mdBoard

Truth, facts and views

mdBoard is easier to trust if you separate three things: truth, facts and views. The collaboration works because the human and the agent agree on that separation.

1. Truth is the open upstream branch

The upstream branch is the working truth while a iteration is open. nightly is the integration train; stable is released truth.

stable   ← released
nightly  ← accepted upstream iterations
upstream ← one active iteration; the agent writes, humans review

Chat is not truth. The HTML board is not truth. A stash or a local worktree is not truth. When they disagree, the branch wins.

2. Facts are written

A fact is durable, reviewable content in Git:

  • a card;
  • a state transition event;
  • a review artifact;
  • a meeting gate and its decision;
  • a report;
  • a changelog entry.

Facts are small and mostly per-file. The agent writes them through mdBoard, not by hand-editing generated output.

3. Views are generated

A view is a projection of the facts:

  • BOARD.md — the state overview;
  • ROADMAP.md — committed batches, estimates and total cost;
  • the HTML board — review, consortium and meeting views;
  • JSON output from the CLI or API.

Never hand-edit a generated view. If a view is stale, ask the agent to regenerate it. If the view and the facts disagree, the facts win.

4. Chat is how you steer

Chat is the human interface. It is not the record.

  • You say what you want.
  • The agent translates it into a named mdBoard action.
  • mdBoard records the action and the human authorisation.
  • The agent briefs you on the new state.

This is why the documentation leads with collaboration and samples of dialogue: the CLI is the agent’s machinery, not the human’s primary experience.

5. Cards are the unit of intent and work

There are three card kinds:

Kind Purpose
Idea A spark, a refinement or a pitch.
Batch An accepted idea promoted to delivery; the parent of tasks.
Task One unit of implementation under a batch.

A review artifact is not a card; it is the human verdict on a batch round. Rework becomes a task.

6. The state machine is a contract

The states are not decoration. They encode when a human gate applies:

  • spark and refine are for shaping;
  • pitch is frozen for the consortium;
  • accepted and roadmap are the commitment;
  • breakdown is where the agent asks questions;
  • doing is autonomy inside the batch;
  • handover is where the human takes over;
  • completed requires a review, a report and an owner accept.

The full model is in Process model and the repository’s formal spec.

7. The agent is a participant, not a view

The agent is the primary operator of mdBoard. It reads the runbook, uses named actions, writes events and briefs you. It is not a passive renderer, and it is not the authority.

Next