Agent recipes

These are command sequences the agent runs. You normally ask for the outcome in chat; the agent translates it into these commands.

The complete flag reference is in CLI for the agent.

Open a session

mdboard runbook
mdboard context
mdboard actions '#0007'

runbook is the rulebook; context is the board state; actions answers what is legal for a card.

Spark and refine

mdboard --actor agent spark "CSV export for the report table"
mdboard --actor agent refine '#0007'

refine opens the only state in which the agent may edit the idea content. Pitching is a human decision; the agent executes it only after authorisation.

mdboard --actor agent pitch '#0007' \
  --authorised-by owner --authorization "Pitch it at the next review."

Accept and estimate

mdboard --actor agent accept-idea '#0007' \
  --authorised-by owner --authorization "The consortium accepts."

mdboard --actor agent estimate '#0007' \
  --tokens-optimistic 8000 --tokens-realistic 12000 --tokens-pessimistic 20000 \
  --agent-hours-optimistic 0.5 --agent-hours-realistic 1.0 --agent-hours-pessimistic 1.5

Roadmap

mdboard --actor agent roadmap '#0007' \
  --authorised-by owner --authorization "Put it on the roadmap."

The command fails if the estimate is missing, the roadmap is full or another batch is active.

Breakdown

mdboard --actor agent breakdown '#0007' \
  --authorised-by owner --authorization "Break it down."
mdboard --actor agent task new '#0007' "Streamed endpoint"
mdboard --actor agent task new '#0007' "Permission tests"
mdboard --actor agent meeting open breakdown-clarification --batch '#0007'
mdboard --actor agent meeting question add M-0007-01 "Include headers when empty?"

Start and execute

mdboard --actor agent start '#0007' \
  --authorised-by owner --authorization "Start the batch."

mdboard --actor agent work '#0007-01'
# implement, test, commit
mdboard --actor agent done '#0007-01' --commit <sha>

Only one task may be working. If a task fails:

mdboard --actor agent fail '#0007-01' --reason "Missing fixture"

Handover

mdboard --actor agent handover '#0007'

This fails unless all tasks are done and no task is in error. It opens the handover review gate.

Review and changes

The human review is transcribed with provenance:

mdboard --actor agent review '#0007' \
  --reviewer reviewer \
  --authored-by reviewer \
  --transcribed-by agent \
  --verdict changes-required \
  --finding F1:"The stream closes before the final row."

Requesting changes returns the batch to doing:

mdboard --actor owner request-changes '#0007' \
  --reason "Streaming boundary is wrong."

Complete

mdboard --actor agent complete '#0007' \
  --authorised-by owner --authorization "I accept the batch."

Completion requires an independent review, the owner accept, a report and a changelog bullet.

Commit

mdboard --actor agent commit -m "#0007 complete CSV export"

This stages the working tree, commits it and prints the SHA. It enforces the open iteration and writer lease. Merge and release refuse a dirty tree.

Meetings

mdboard meeting list
mdboard meeting accept M-0007-01
mdboard meeting defer M-0007-01 --until 2026-10-30
mdboard meeting dismiss M-0007-01 --reason "Not doing this batch."

Branch operations

The agent prepares; the owner executes:

# agent
mdboard upstream status
mdboard commit -m "iteration ready"
mdboard check --git
mdboard render --check

# owner
mdboard upstream merge
mdboard release

The owner runs both commands; the agent prepares the checks, report and summary.

Exceptions

mdboard --actor agent block '#0007' --reason "Waiting for credentials."
mdboard --actor owner unblock '#0007'
mdboard --actor owner cancel '#0007' --reason "Superseded by #0012."

Verify

mdboard check --json
mdboard render --check

A red check is a stop, not a suggestion. The agent fixes the facts and regenerates the views; it never hand-edits a generated view.