How collaboration works

mdBoard is built around one relationship:

You talk to your agent. Your agent uses mdBoard. mdBoard keeps both of you aligned.

The human is the authority. The agent is the operator. Git is the record. The board is the shared view.

The three participants

Git holds the truth. BOARD.md, ROADMAP.md and the HTML board are projections of the facts; they are generated because generated views are easier to read, not because they are authoritative.

The loop

Human intent
    │  chat: "I want…"
    ▼
Agent ── uses ──► mdBoard ── writes ──► Git
    │                  │                     │
    │                  ├─ state + event      │
    │                  ├─ review artifact    │
    │                  └─ meeting gate       │
    ▼                                        │
Brief + board view ◄── generated views ◄─────┘

The agent is not a passive tool. It is the actor that translates your intent into legal mdBoard actions. mdBoard is not a chatbot. It is the protocol that makes the agent’s actions inspectable and bounded.

The conversation contract

Every meaningful exchange has the same shape:

1. You state an intent. “I want CSV export.” “Review this batch.” “Put it on the roadmap.”
2. The agent restates and checks authority. It says what will change, which human gate it needs and what it will not do.
3. The agent acts through mdBoard. It uses a named action, not a free-form file edit.
4. The agent briefs you. It reports the new state, what changed, what needs you and what happens next.

A good agent never silently “just does it.” A good human does not need to know the state machine; the agent translates.

One writer, one batch

This model is deliberately not parallel at the implementation layer:

• one active batch in breakdown or doing;
• one task working at a time;
• one agent writer holding the upstream lease;
• one human review queue that can grow, and can be parallelised with more reviewers.

The point is to make the human review the bottleneck, not the merge mechanics. If the review queue grows, add reviewers. Do not add parallel feature branches.

Chat first, records always

You can work entirely in chat:

Human: Spark an idea for CSV export.
Agent: Created #0007 as a spark. Do you want to refine it now?

The agent records the corresponding mdBoard action. Later, the board and the event history let you answer:

• what was intended;
• what state the card is in;
• who authorised the move;
• what was reviewed;
• what evidence exists;
• what is waiting for a human.

Chat is not the record. Chat is how you steer. mdBoard records the decisions and the state.

What you do not need to do

• You do not edit cards in Git by hand.
• You do not manage branches or worktrees yourself.
• You do not merge upstream through the agent.

You can use the CLI if you want to inspect or recover, but it is not required for the collaboration. See Chat, board and tools for the surface comparison.

The trust boundary

The current model uses chat-only authorisation. When a human gate is reached, the agent records the human’s statement, the authoriser and the time. This is auditable, but it is not cryptographic proof: a misbehaving agent with write access could forge the statement. The model assumes a well-behaved agent and a human who reads the brief.

Branch merges and releases are stricter: only a human executes them. The agent may prepare the merge check, report and release notes.

See Roles and authority and Security.

Common misconceptions

Next

• Roles and authority
• Chat patterns
• The board
• Work lifecycle