Tutorial: build Blockfall

This tutorial follows one small browser game from a human intention to a reviewed, merged batch. You are the human. Your agent does the implementation.

You will practise the whole collaboration: spark, refine, pitch, accept, estimate, roadmap, breakdown, clarification, start, handover, review, rework, complete and merge.

::: tip What you will learn How to talk to a agent, what the agent does in mdBoard, when you must decide, and how the board changes. The commands are shown in collapsible sections; you do not need to run them. :::

1. Set up the project

mkdir blockfall
cd blockfall
git init
git commit --allow-empty -m "Start Blockfall"
mdboard init --upstream main \
  --subscription "DeepSeek-V4.1-Flash (off-peak)" \
  --eur-per-million-tokens 0.21
git add .
git commit -m "Initialize mdBoard"

Connect the agent:

Human: Read AGENTS.md, then run `mdboard runbook` and `mdboard context`.
       You are the agent for Blockfall. Follow the runbook.
       Never self-approve or merge. Introduce yourself and brief me.

Agent: mdBoard is ready. No upstream iteration is open. Roadmap 0 of 5.
          I can start a iteration or help you shape the first idea.

2. Start the iteration

Human: Start the upstream iteration.

Agent: Iteration 1 is open from main. I hold the writer lease.
          The board is ready.

::: details What the agent runs mdboard upstream start :::

3. Spark the game

Human: I want a minimal falling-block game in the browser. One piece
       falls; arrow keys move and rotate; game over is clear.

Agent: Created #0001 as a spark with exactly that intent. Do you want
          to refine it now?

The card is an idea in spark. It is one sentence, not a specification.

4. Refine it

Human: Yes. Ask me the decisions that matter, then write acceptance criteria.

Agent: Four decisions:
          1. Grid size and cell size?
          2. Which tetrominoes and rotation rule?
          3. Gravity speed and lock behaviour?
          4. What happens on game over and restart?

Human: 10x20, 30px cells. All seven pieces, simple rotation, one row per
       0.8s. Game over overlay with R to restart.

Agent: I wrote the decisions and acceptance criteria. The content is
          editable only while #0001 is in refine.

5. Pitch it

Human: That is the intent. Pitch it at the consortium review.

Agent: #0001 is in pitch and the content is frozen. It is on the
          consortium agenda.

The human consortium now decides.

6. Accept and estimate

Human: The consortium accepts #0001. Promote it and estimate it.

Agent: Recorded with you as authoriser. #0001 is accepted and is now
          a batch. Estimate: 12,667 weighted tokens, 1.0 agent hour,
          about €0.0027 at the current rate.

The estimate is required before the roadmap.

7. Roadmap it

Human: Put it on the roadmap.

Agent: #0001 is on the roadmap, slot 1 of 5. Estimated total €0.0027.
          Next gate: breakdown.

8. Break it down

Human: Break it down. Ask me everything before starting.

Agent: I moved #0001 to breakdown. Tasks:
          #0001-01 playable falling piece and controls
          #0001-02 locked pieces and game over
          #0001-03 keyboard restart and smoke test
          One clarification meeting is pending: two questions.

Clarification

Agent: 1. Should rotation near a wall be refused, or should it wall-kick?
          2. Should the game-over overlay block arrow keys?

Human: Refuse rotation; no wall kicks. Block arrow keys, allow R.

Agent: Answers recorded and the clarification gate is accepted.
          Say “start #0001” when you want implementation.

9. Start and execute

Human: Start #0001.

Agent: #0001 is doing. #0001-01 is working. I will commit each task
          and keep one task working at a time.

A few minutes later:

Agent: #0001-01 done and committed. #0001-02 is working.
          No blockers.

The agent is autonomous inside the batch. You do not approve each task.

10. Handover

Agent: #0001 is in handover. All tasks done. The report draft is
          .mdboard/reports/R0001.md. I opened the handover review.

The batch now needs a human.

11. Review and request changes

Human: I reviewed it. Locked pieces are drawn, but the game-over overlay
       still lets ArrowLeft move the piece. Request changes.

Agent: Recorded a changes-required review from you, returned #0001 to
          doing, and created #0001-04 from finding F1.

The batch is doing again; only the rework task is pending. The completed tasks stay done.

Agent: #0001-04 done. #0001 is in handover round 2.

12. Accept and complete

Human: I accept #0001. Complete it.

Agent: Owner accept recorded. I wrote the final report and appended
          the changelog entry. #0001 is completed.

The report is at .mdboard/reports/R0001.md; the changelog has one dated bullet.

13. Merge

Human: Prepare the merge for iteration 1.

Agent: The worktree is clean, no active batch, the merge check passes.
          Only you can merge.

Human: I merged it into nightly.

Agent: Iteration 1 is merged. I will open the next iteration when you are ready.

At a release point, the owner merges nightly into stable on the release train.

What you practised

You expressed intent and made the human decisions.
The agent translated each intent into a legal mdBoard action.
The board moved through spark, refine, pitch, accepted, roadmap, breakdown, doing, handover and completed.
Review found a real issue; rework was a task, not a reopened completed card.
You merged; the agent never did.

Try next

Add a second small idea and take it through pitch and rejection.
Raise the roadmap limit temporarily and watch the expiry check.
Add a second reviewer and review a batch in parallel.