On to the next BMAD task: 1.5 - console I/O primitives

In this sprint, we’ll be building:

  • output primitives EMIT, CR, SPACE and SPACES
  • input primitives KEY and KEY?

These should all be trivial wrappers around BDOS calls to do the actual work. These functions will be essential when it comes to building the full outer interpreter that will make AntForth interactive!

To get started we /bmad-bmm-create-story 1-5 and review the story. Straight away Claude has flagged that KEY and KEY? can’t be tested automatically, which is fair, but I asked for a separate test executable to be provided so I can test them nmanually:

please make sure that a separate manual test executable is provided so that 
I can test KEY and KEY? - just a prog that echos what I type is fine, ctrl-c to exit.

With the updated plan in place we can /bmad-bmm-dev-story 1-5, followed by /bmad-bmm-code-review 1-5.

Code review found some minor test coverage gaps, which were quickly fixed.

io.asm

All the new console stuff, unsurprisingly, is in io.asm. The output routines are all variations on the same basic theme:

console output

Similarly the input routines:

console input

Testing

make test passes, although the hard-coded test-thread in antforth.asm is starting to get a bit wild and overgrown - the sooner we have a proper interpreter the better!

Claude did make us a manual test key_test.com which we have to run ourselves:

typing test

Although, now I look at the source code:

; ================================================
; test_key.asm — Manual test for KEY / KEY? primitives
; Echoes typed characters. Ctrl-C to exit.
; Part of antforth — ANS Forth for MicroBeast Z80
; ================================================

        INCLUDE "constants.asm"

        ORG     TPA_START       ; 0x0100

echo_loop:
        LD      C, C_READ       ; BDOS function 1: read console (blocking, echoes)
        CALL    BDOS_ENTRY      ; A = character typed
        CP      0x03            ; Ctrl-C?
        JR      NZ, echo_loop   ; No — keep looping (char already echoed by BDOS)
        LD      C, P_TERMCPM    ; BDOS function 0: exit to CP/M
        JP      BDOS_ENTRY

That just tests BDOS and doesn’t test any of our stuff at all!

Back to Claude then:

❯ test_key.asm does not test our KEY or KEY? implementations, it calls the BDOS routine directly.
as a test therefore, it is entirely useless. Write a proper test that actually exercises the code-under-test!!

● You're absolutely right — test_key.asm just calls BDOS directly and doesn't exercise our KEY or KEY?
code words at all. I need to build a proper Forth-threaded test program. Let me check what infrastructure is needed.

This kind of thing is unfortunately far too commmon, even BMAD couldn’t save us this time. It’s the perfect example of what the human responsibilities are in this partnership!

Here’s Claude making amends:

typing test amends

Checking the source code, this time we have got something more substantial:

typing test 2 code

This is what it looks like when you run it:

typing test 2

This would be a great topic to raise in a sprint retrospective, and as we’ve just finished Epic 1 you’ll see that the next step in sprint-status.yaml is an optional retrospective. Let’s take that option!

First /reset claude code and then /bmad-bmm-retrospective epic 1. This kicks off a long, interactive session where the LLM adopts several personas (developer, architect, tester) simultaneously. You get to ask them challenging questions, and they bicker about whose fault it is. Stay alert, sometimes they’ll conclude that it’s your fault. It is a frankly hilarious experience, eerily reminiscent of a real-world retro. The end result is that your PRD and architecture documents will get updated with the lessons learned. In extreme cases a “course change” may be scheduled, which is usually a single extra story, but can in theory be a whole new emergency epic if the wheels have really come off.

The whole chat is too long to include here, but this was what I kicked off with:

❯ It's a solid foundation, and it's exciting to see the functionality coming together. But let's not pat ourselves on the back about testing. The single test thread in antforth.asm is becoming unwieldy and we urgently need to replace it with something more modular - I guess we'll have to wait for the outer
interpreter to be available. MORE CONCERNING for me is that I asked for a manual test harness for `KEY` and `KEY?` and was given code that didn't excercise *any* of the code under test - it just called some BDOS routines directly. This is an unforgiveable oversight, and it must not happen again.

And you can see the resulting document with the conclusions they came to.

Which all seems sensible. On to epic 2!