mdBoard

Roles and authority

mdBoard works only if the human and the agent have different jobs. This page defines who decides, who executes and who must stay out of the way.

The roles

Role Who Authority
Guardian A human Final veto, tie-break and guardian transfer. Exactly one.
Co-guardian A human Shares veto, tie-break and transfer authority with the guardian. Zero or more.
Stakeholder A human Holds one or more seats and votes on pitched proposals.
Owner A human Final authority: accept ideas, accept batches, override the roadmap limit, merge upstream into nightly, release nightly into stable, reopen rejected ideas.
Member A human Spark ideas, refine, pitch, review peers’ batches, attend the consortium.
Consortium The owner and members The human decision body for pitches, roadmap selection and review.
Agent The coding agent The single writer: refine content, estimate, break down, implement tasks, commit, report, transcribe reviews and remind humans.
mdBoard The tool Records, checks and generates views. It has no authority to decide.

Any member may review a batch they do not own. A separate reviewer role is not needed.

Who decides what

Action Agent alone Agent after human authorisation Human executes
Create a spark no yes, on instruction —
Refine content only in refine — yes
Pitch no yes yes
Accept/reject an idea no yes, on the consortium decision yes
Park/reopen no yes yes
Estimate/re-estimate estimate; re-estimate needs authorisation yes yes
Put on / remove from roadmap no yes yes
Break down a batch no yes yes
Start implementation no yes yes
Work a task, mark done, fail yes — —
Handover yes — —
Request changes no yes yes
Complete no yes, on the owner’s accept yes
Block/unblock propose yes yes
Cancel no yes yes
Merge/release no no yes, owner
Override roadmap limit no yes, owner yes
Transcribe a review yes, with provenance — yes

The agent never claims the owner role. It may execute a card-level action after an explicit human decision, recording who authorised it. Branch merges and releases are different: the agent prepares them, the owner executes them.

The agent’s autonomy

The agent acts alone in these places:

  • refining content while a card is in refine;
  • estimating a batch;
  • creating tasks during breakdown;
  • working the pending tasks after start;
  • committing each completed task;
  • moving the batch to handover when all tasks are done;
  • writing the report draft and transcribing human review findings;
  • reminding you about pending meetings;
  • preparing a merge check and release notes.

Everything outside this list is a human gate. The agent may propose it, but it may not decide it.

The human gates

These are the moments where the human must be in the loop:

  1. Idea acceptance — the consortium accepts, rejects or sends the pitch back.
  2. Roadmap commitment — a batch is chosen and estimated; the roadmap limit applies.
  3. Start — the human authorises implementation after clarification.
  4. Review acceptance — the owner accepts the batch after independent review.
  5. Merge and release — the owner merges upstream → nightly and nightly → stable.

If you remove these gates, mdBoard is just a task tracker with extra steps. They are the product.

Review independence

  • The reviewer must not be the intent owner.
  • Multiple reviewers can work in parallel; their review artifacts are independent.
  • The owner makes the final acceptance decision.
  • If a reviewer says “changes required”, the owner either requests changes or records an override reason.
  • In a one-human project, the owner may self-review with an explicit override reason in the event.

Review is discussed in Review and acceptance.

The refusal protocol

A agent must refuse an illegal request and offer the legal alternatives. This is a feature, not stubbornness.

You say The agent should say
“Delete this card.” “Cards are not deleted. I can leave it rejected, reopen it as a spark, or cancel it with a reason.”
“Move it straight to completed.” “Completion requires handover, an independent review and your accept.”
“Merge it.” “Only you can merge. I can prepare the check, the report and the summary.”
“Just edit the pitch.” “Pitch content is frozen for the consortium. I can request changes and move it back to refine.”
“Approve it for me.” “I cannot authorise your accept. I can prepare the batch and record your explicit decision.”
“Run two batches at once.” “Only one batch can be in breakdown or doing. We can finish this one or block it.”

If the agent does not refuse an illegal action, it is not following the runbook.

The primary user

The agent is the primary operator of mdBoard. It runs the CLI, writes the records and maintains the board.

The humans are the primary authority and beneficiary. The product exists to keep you in control without asking you to operate the machinery.

That is why the guide leads with collaboration, not commands. The CLI reference is deep, but it is written for the agent and for the human who needs to recover or inspect.

Trust and provenance

Chat-only authorisation is an audit convention, not proof. The event journal records:

  • the action;
  • the executor;
  • the human who authorised it;
  • the human’s statement;
  • the time.

A misbehaving agent with filesystem access could forge this record. mdBoard is a coordination protocol, not a sandbox. The Security page states the boundary plainly.

Review artifacts record authored_by and transcribed_by. When the agent transcribes your chat, the artifact says so. If independence matters more than convenience, write the review yourself in the HTML board.

Next