The runbook

The runbook is the agent’s stable, normative instruction set. It is shipped with mdBoard rather than copied into AGENTS.md, so every installation gives the agent the same baseline behaviour.

Why it exists

A vague AGENTS.md produces vague agent behaviour. The runbook makes the collaboration explicit:

who decides and who executes;
what the agent may do alone;
which actions require human authorisation;
what is forbidden even with instruction;
how to brief the human after a change;
how to handle meetings, reviews, branches and conflicts.

AGENTS.md is deliberately short: it tells the agent to read the runbook. The runbook is the contract.

How to onboard a agent

Read AGENTS.md, then run `mdboard runbook` and `mdboard context`.
You are the agent for this repository. Follow the runbook.
You never self-approve, never merge, and never change state without the
authorisation the runbook requires.

The agent should run mdboard runbook at the start of each session. mdboard context supplies the current board state; the runbook supplies the rules.

What the runbook covers

Section	Content
Identity	You are the agent, one writer, the human is the authority.
Truth	The open `upstream` branch is the working truth.
States	The idea, batch and task machines.
Actions	Named actions and their guards.
Authority	Agent autonomy, human gates, human-executed merges.
Review	Parent-level review, artifacts, changes and rework.
Meetings	Fixed and on-demand gates, reminders and decisions.
Branches	One iteration, writer lease, merge and release boundaries.
Briefings	What to report after every transition.
Refusals	Illegal requests and the legal alternatives.
Conflicts	Stop, reconstruct, ask a human.

The runbook is not a prompt

A prompt is per-conversation and easy to drift. The runbook is versioned with the binary and referenced by AGENTS.md. It is the same across installations, which makes agent behaviour predictable.

The runbook is not a security sandbox. A agent with write access can still ignore it. mdBoard makes the expected behaviour explicit and the events inspectable; it does not prove obedience.

Example excerpt

If the human asks you to accept a batch:
1. Check that the batch is in handover.
2. Check that at least one independent review artifact exists.
3. Restate the effect and ask for the owner's explicit accept.
4. Record authorised_by and the human's statement.
5. Run the complete action.
6. Brief the board and the remaining human gates.

If the human asks you to merge:
1. Explain that only the owner executes the merge.
2. Prepare the merge check, report and summary.
3. Wait for the owner to run the merge.

Runbook versus context

Command	Answers
`mdboard runbook`	What am I allowed to do, and how?
`mdboard context`	What is the board state now?
`mdboard actions <card>`	What can I do from this card’s state?
`mdboard history <card>`	What happened to this card?
`mdboard brief`	What should I tell the human now?

The agent should use all of them, in that spirit: rules, state, legal actions, history, summary.

Updating the runbook

The runbook is tied to the mdBoard version. When the binary changes, the agent should read the new runbook before acting. The docs describe the intent; the runbook is the operational text.

If your team needs a project-specific rule, put it in the project’s AGENTS.md or configuration rather than editing the runbook output. Project policy should be visible and versioned with the project.