Chat patterns

You do not need to learn the state machine. You need to say what you want, and your agent translates it into legal mdBoard actions.

This page collects the common dialogues. They are examples, not scripts; the agent should adapt to your wording.

Before the first card action, the agent opens the upstream iteration:

Human: Open the working iteration.

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

The response contract

For any action that changes the project, a good agent response has four parts:

1. Restate what it understood.
2. Name the authority it needs.
3. Act through mdBoard and report the new state.
4. Brief you: what changed, what needs you, what happens next.

Example:

Human: Put #0007 on the roadmap.

Agent: This will move #0007 from accepted to roadmap and reserve
          1 of 5 roadmap slots. The estimate is 12,667 tokens and
          1.0 agent hour. You are the owner; confirm the roadmap move.

Human: Yes.

Agent: Done. #0007 is on the roadmap. Total roadmap: 2 of 5 batches,
          estimated €0.13. Next human gate: breakdown clarification.

Status check

You can ask at any time:

Human: Where are we? What needs me?

Agent: Upstream iteration 3 is open. One batch is doing: #0009.
          #0009-02 is working; #0009-01 is done.
          Handover review for #0008 is pending — you and one reviewer.
          Roadmap: 4 of 5. No blocked cards.
          The next decision for you is the handover review of #0008.

The agent gets this from mdboard context. It should not reconstruct state from memory.

What can you do with this card?

You can ask for the legal actions at any time:

Human: What can you do with #0007 right now?

Agent: #0007 is a batch in handover, round 1.
          I can transcribe a review artifact, request changes with your
          authorisation, or block it with a reason.
          I cannot complete it without an independent review and your
          owner accept. I cannot merge it.

The agent derives the answer from mdboard actions #0007, not from improvisation. If the answer sounds vague, ask it to run the command.

Spark an idea

Human: Spark an idea: add CSV export to the report table. Keep it
       small — current filters only, streamed response, owner-only.

Agent: Created #0007 as a spark. Intent owner: you. No scope added
          beyond your sentence. Do you want to refine it now?

The card is an idea in spark. The agent may create it on your instruction, but it should not silently invent a design.

Refine

Human: Yes. Ask me the open questions, then write acceptance criteria.

Agent: Three questions:
          1. Hidden columns — include or exclude?
          2. Maximum rows before streaming?
          3. Owner-only, or any member with report access?

Human: Exclude hidden. Stream after 1,000 rows. Owner-only for now.

Agent: I updated #0007 only while it is in refine.
          Acceptance criteria now cover filters, streaming boundary,
          owner-only access, and a regression test.

The agent is allowed to edit content only in refine. In other idea states it may move the card and record decisions, but not rewrite the intent.

Pitch

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

Agent: #0007 is now in pitch; the content is frozen.
          I added it to the consortium review agenda.

pitch is a request for a human decision. The agent does not accept it.

Consortium decision

Human: The consortium accepts #0007. Please promote it.

Agent: I will record the accept decision with you as authoriser and
          promote #0007 to a batch. This does not put it on the roadmap;
          the estimate and the roadmap slot come next. Confirm?

Human: Confirmed.

Agent: #0007 is accepted. It is a batch now. Shall I estimate it?

Rejection and change requests look similar:

Human: The consortium rejects #0003. Reason: too close to the billing
       roadmap, revisit next quarter.

Agent: #0003 is rejected and the reason is recorded. It can be reopened
          as a spark by you or its creator.

Estimate and roadmap

Human: Estimate #0007 and show me the roadmap.

Agent: Estimate: 12,667 weighted tokens; 1.0 weighted agent hour.
          At the current blended rate of €0.21/1M, about €0.0027.
          Roadmap is 2 of 5 batches; adding #0007 makes it 3 of 5,
          about €0.11 estimated total. Do you want me to commit it?

Human: Yes.

Agent: #0007 is on the roadmap. Next gate: breakdown.

The estimate is required before roadmap. The roadmap total is the sum of batch estimates. If the scope changes, the agent asks for a re-estimate rather than silently changing the number.

Breakdown

Human: Break #0007 down. Ask me everything you need before starting.

Agent: I moved #0007 to breakdown. Proposed tasks:
          #0007-01 streamed endpoint
          #0007-02 permission and filter tests
          #0007-03 API and operator docs
          I have two clarification questions in the breakdown meeting.
          I will not start until you accept that meeting.

breakdown is a parent-only state. The child tasks are created in pending; the agent asks questions through a meeting gate instead of starting implementation.

Clarification

Agent: Breakdown clarification for #0007:
          1. Should the stream include a header row when no data matches?
          2. Should the 1,000-row boundary be configurable?

Human: Include headers when there is at least one row; no, do not make
       the boundary configurable in this batch.

Agent: I recorded both answers and accepted the clarification gate.
          The tasks are still pending. Say “start #0007” when you want
          implementation to begin.

The clarification meeting is the human gate before start. The agent may keep asking; it may not start without the human decision.

Start

Human: Start #0007.

Agent: #0007 is doing. I will work the tasks in order and commit each
          one. Only one task will be working at a time. I will not start
          another batch.

Execution updates

You do not need to poll. A good agent briefs on meaningful changes:

Agent: #0007-01 is done and committed. #0007-02 is working now.
          No blockers. One task remains after this.

If you ask for status, you get the board state, not a vague “in progress.”

Handover and review

Agent: #0007 has entered handover. All three tasks are done.
          The report draft is .mdboard/reports/R0007.md.
          I opened the handover review meeting.
          Two reviewers are expected. Please review the batch as a whole.

You can discuss findings in chat, but the review artifact should name who authored the verdict and who transcribed it.

Request changes

Human: I reviewed #0007. The stream closes before the final row.
       Request changes and create a rework task.

Agent: I recorded your changes-required review artifact, returned
          #0007 to doing, and created #0007-04 from finding F1.
          The other tasks remain done. I will hand over again when
          #0007-04 is done.

The batch goes handover → doing; rework is a new task, not a reopened completed task.

Complete

Human: I accept #0007. Complete it.

Agent: I recorded your owner accept, wrote the final report,
          appended the changelog entry, and closed #0007 as completed.
          The next human gate is the upstream merge.

Completion requires an independent review artifact and the owner’s accept. The agent writes the report and changelog, but it does not merge.

Merge and release

Human: Prepare the merge for iteration 3.

Agent: The pending batch is complete, the worktree is clean,
          and the merge check passes. Summary and report are ready.
          Only you can merge.

Human: I merged it.

Agent: Iteration 3 is merged into nightly. I will open the next upstream
          iteration when you are ready. The release train is separate.

Branch merges and releases are human-executed. The agent can prepare and verify, never execute.

Block and recover

Agent: #0009 is blocked. The deployment credential is missing.
          Return state: doing. The task #0009-02 is still working.

Human: The credential is in the vault now.

Agent: I unblocked #0009 back to doing. #0009-02 continues.

A task failure uses error:

Agent: #0009-02 failed: the test fixture is missing. It is in error.
          Options: recover it to pending, or cancel it. I recommend recover.

Refuse an illegal request

Human: Delete card #0004.

Agent: Cards are not deleted. #0004 is rejected; I can reopen it as a
          spark, leave it rejected, or cancel it with a reason. Which one?

Other refusals:

What makes a good prompt

• Say the goal and the scope, not the command.
• Say the constraint (“owner-only”, “no schema change”, “keep it small”).
• Say the decision when the agent asks (“accept”, “request changes”, “start”).
• Ask for a brief after a meaningful change.

What not to ask

• Do not ask the agent to edit a card directly in Git.
• Do not ask it to delete a card.
• Do not ask it to merge or release.
• Do not ask it to accept its own work.
• Do not ask it to skip a clarification or review gate.

The agent should refuse these and tell you what is possible instead.

Next

• The board
• Review and acceptance
• Meetings
• Roles and authority