Guide

mdBoard is a collaboration protocol for a human team and one coding agent. You talk to your agent; the agent uses mdBoard; mdBoard keeps your intent, the review gates and the Git-backed record aligned.

This guide is written for the human first. The CLI is documented in depth, but you do not need to drive it yourself: your agent is the primary operator.

::: tip The one-paragraph model You describe an intention. The agent helps you refine it, and the consortium accepts or rejects it. An accepted idea becomes a batch on the roadmap, with an estimate. The agent breaks it into tasks, asks you clarifying questions, and implements the batch after you say start. When the tasks are done, the batch enters handover; you review it, request changes or accept it. Completion writes a report and a changelog entry. Only a human merges upstream into nightly and releases nightly into stable. :::

Start here

Your first conversation

Install mdBoard, connect a agent, and shape one idea into a reviewed batch.

How collaboration works

Who talks to whom, what mdBoard records, and where human authority sits.

Chat patterns

The common prompts and agent responses for every part of the lifecycle.

Stakeholder governance

Seats, quorum, voting, expiry, veto and the guardian role.

Standing orders

Persistent project rules the agent must remember and follow.

SSH authentication

Optional signed guardian gates for roadmap commitments.

Mirroring to public

Publish a sanitized snapshot without private board data or secrets.

Card kinds

Proposal, defect, research, batch and task — and the draft lifecycle.

Choose a path

I want to…	Read
Try the collaboration model	Your first conversation
Build a complete example	Blockfall tutorial
Understand who decides what	Roles and authority
Run a stakeholder vote	Stakeholder governance
Store a persistent project rule	Standing orders
Harden the guardian gate	SSH authentication
Publish a public mirror	Mirroring to public
Understand the five card kinds	Card kinds
Know what to say to my agent	Chat patterns
Read the board	The board
See the full lifecycle	Work lifecycle
Review and accept work	Review and acceptance
Run the human meetings	Meetings
Understand branches and merges	Branches and releases
Estimate cost	Estimation and cost
Onboard or align a agent	The runbook
Look up a command	CLI for the agent
Look up a card field	Card format

Three participants

Participant	Role
You and the consortium	Set intent, accept ideas, review batches, merge and release.
Your agent	Refines, estimates, breaks down, implements, commits, reports and reminds. It operates mdBoard.
mdBoard	Records the state, enforces the gates, coordinates the meetings and generates the views.

Git holds the truth. The HTML board and the Markdown views are projections; they are useful because they are generated from the facts, not because they are a second truth.

What is different here

You do not run a feature-branch per idea. There is one active upstream branch and one writer.
You do not review every task. You review the batch at handover.
You do not manage a shared queue. The agent works one task at a time.
You do not need a hosted tracker. The roadmap is small and human-selected.
You do not need to operate the CLI. You instruct the agent in chat; the agent uses mdBoard.

Alpha status

This guide describes the 1.0 collaboration model. The named CLI actions, the runbook, the new board records, the generated Markdown views, the HTML board and the branch merge/release gates are implemented. The process model and the repository’s formal spec are the normative source when prose and code disagree.

Conventions

“You” means the human reader; “agent” means the coding agent.
Human: and Agent: mark chat examples.
Collapsible sections contain the mdBoard commands the agent runs; you do not need to memorize them.
“Upstream” means the one active working branch, not necessarily main.
“Batch” is the accepted implementation unit; “task” is a child work item.