mdBoard

The board

The board is how you see the collaboration without reading Git. It is a projection of the facts, not a second source of truth.

Three human views

View Best for Generated from
BOARD.md A quick state overview in your editor or code review Cards and their states
ROADMAP.md Committed batches, estimates and the roadmap total Roadmap batches and estimates
HTML board Review, consortium decisions, meetings and drill-down Cards, review artifacts, meetings, reports

The agent regenerates the Markdown views after meaningful changes. The HTML board reads the same records and is served locally by mdboard serve.

What you should see at a glance

A useful board answers five questions:

  1. What is moving? — the active batch and its working task.
  2. What needs me? — handover reviews, clarification gates, consortium decisions.
  3. What is committed? — the roadmap and its estimated cost.
  4. What is stuck? — blocked batches and error tasks.
  5. What is done? — completed batches with reports and changelog links.

If a board view cannot answer these, it is not doing its job.

The state map

Cards are one of three kinds:

Kind States you will see
Idea spark, refine, pitch, rejected, canceled
Batch accepted, roadmap, breakdown, doing, handover, completed, blocked, canceled
Task pending, working, done, error, canceled

You do not need to memorize the map. The important human-facing states are:

  • pitch — waiting for the consortium;
  • roadmap — committed and estimated;
  • breakdown — the agent is decomposing and has questions;
  • doing — implementation is underway;
  • handover — waiting for human review;
  • blocked — waiting for a human or external decision.

A 30-second daily check

Ask your agent for a brief, or read the board:

Human: Give me the board brief.

Agent: Active: #0009 doing, #0009-02 working.
          Needs you: handover review for #0008; breakdown clarification
          for #0010.
          Roadmap: 4 of 5, estimated €0.42.
          Stuck: none.

A brief should end with what needs you now, not a wall of history.

Reading a batch

The batch is the parent. Its detail view contains:

  • the intent and acceptance criteria;
  • its estimate and roadmap slot;
  • the task list and each task’s state;
  • the review rounds and artifacts;
  • the report draft;
  • the event timeline;
  • the meeting gates connected to it.

The tasks are the agent’s work units. You review the batch, not every task.

Review and consortium views

The HTML board is designed for the human side:

  • handover review — read the batch, the evidence and the report draft; accept or request changes;
  • consortium — see the pitch queue and the accepted backlog;
  • meetings — see pending on-demand gates, their questions and their due dates;
  • roadmap — see committed batches, estimates and total cost.

If you prefer chat, ask the agent to bring the detail to you. The board is a convenience, not a requirement.

What is not on the board

The board is intentionally small: one active batch, a short human-selected roadmap, and a review queue. Work is sequential by default, so the board should feel quieter than a tracker.

Truth versus view

  • The open upstream branch is truth.
  • Cards, review artifacts, meeting records, reports and events are facts in Git.
  • BOARD.md, ROADMAP.md and the HTML board are generated views.
  • Never hand-edit a generated view. Ask the agent to regenerate it.

If the view and the facts disagree, the facts win. The agent should explain the difference and rebuild the view.

Asking for a board brief

Human: What changed since yesterday, and what needs me?

Agent: #0007 completed and the report is in .mdboard/reports/R0007.md.
          #0009 is doing. #0008 is waiting for handover review.
          The next consortium review has one pitch on the agenda.
          Nothing is blocked.

Next