mdBoardTechnical documentation
This is the technical track: how mdBoard works as a tool, how its state machine is enforced, and how a human or agent drives it through the CLI.
The Guide is the user journey — installation, collaboration, concepts and working through the agent. This track is the deeper reference for commands, states, storage, events, security and extension points.
Start with the CLI
- CLI reference — commands, global options, actors and authority flags.
- Command overview — the command surface grouped by lifecycle stage.
- The runbook — the normative agent instructions.
- Configuration —
mdboard.toml, actors, branches and limits. - Card format — every card field and its meaning.
How the tool thinks
| Concept | Technical reference |
|---|---|
| State machine and transitions | Process model |
| Cards, kinds and lifecycle | Card format |
| Board projections and facts | The board in depth |
| Events, history and evidence | Checks and guarantees |
| Context budgets and handover | Context handover |
| HTTP API | API reference |
| Security model | Security |
| Plugin surface | Plugin API |
The operating loop
An agent normally runs:
mdboard runbook
mdboard context
mdboard actions <ID>
It mutates state only through named actions, records human authorisation with --authorised-by and --authorization, and commits at task and batch boundaries. Human-only gates — merge and release — are never delegated to the agent.
What this track covers
- the full CLI action surface and its authority rules;
- process states, transitions and illegal actions;
- card fields, event records and validation;
- branches, writer leases, iterations and roadmap limits;
- governance, meetings, rotations and standing orders;
- reports, mirroring, migrations and release operations;
- the HTTP API, security boundaries and plugin API.
Technical pages are written for humans who need to understand the tool and for agents that must operate it correctly. Commands are shown verbatim; authority and failure modes are explicit.