mdBoard

Why mdBoard

mdBoard is a collaboration protocol for a human team and one coding agent. The human sets intent and keeps authority; the agent implements and operates mdBoard; Git keeps the record.

It is not an issue tracker, a chat workspace or an agent runtime. It is the small, strict layer that keeps an agent’s speed from outrunning human understanding.

The shift

A capable coding agent can produce a feature-sized change in the time a human needs to read the diff. That changes the bottleneck:

  • implementation is not the scarce step;
  • human review and intent alignment are;
  • parallel feature branches add coordination cost without adding useful speed;
  • the risk is not “the agent cannot code”, it is “the codebase evolves faster than the team can understand.”

The default answer is more developers and more parallel features. The better answer is one agent, one active batch, and human review at semantic boundaries.

Two failure modes

Without a protocol, agentic development fails in two opposite ways:

  1. Unbounded autonomy. The agent ships a large, plausible change. The human cannot reconstruct the intent, the decisions or the tests, and the codebase drifts.
  2. Constant supervision. The human reviews every step. The agent waits for permission, and the human becomes a slow approval queue.

mdBoard takes the middle path: human authority at a few gates, agent autonomy inside a batch.

What mdBoard does

It makes five things explicit:

Concern mdBoard’s answer
Who decides? Owner and members at defined gates; the agent never self-approves.
What is being worked on? One active batch, one working task, one writer lease.
Where does the truth live? The open upstream branch; nightly and stable receive accepted work.
What does the human see? A chat with the agent, the HTML board, BOARD.md and ROADMAP.md.
What counts as done? A reviewed batch with a report and a changelog entry.

How it is different

Typical issue tracker Agent orchestration mdBoard
Primary user Humans Agents The agent operates; humans decide
Source of truth Hosted database Runtime state A Git branch and its records
Work unit Ticket Task Idea → batch → tasks
Human role Assignee, commenter Prompt author Intent, review, merge, release
Agent role Tool Autonomous worker Agent with bounded autonomy
Review Comments and approvals Model output Human review artifact at batch level
Parallelism Many assignees Many agents One active batch; review in parallel

This is a trade-off. mdBoard gives up hosted convenience, rich portfolio planning and unlimited parallel feature work in exchange for human comprehension, Git-native truth and deterministic agent coordination.

Who it is for

mdBoard fits:

  • a product owner or small consortium with a clear product vision;
  • one strong coding agent working against one repository;
  • humans who want to review outcomes, not supervise keystrokes;
  • teams willing to accept a review bottleneck and manage it explicitly;
  • projects where code evolution must remain understandable.

It is probably a poor fit for:

  • many independent feature teams;
  • a workflow that needs a hosted multi-tenant board;
  • agents that cannot follow a stable runbook;
  • projects where no human can review the work.

What 1.0 alpha includes

  • the spark → refine → pitch → accepted idea flow;
  • batch planning with estimated roadmap entries;
  • breakdown into ordered tasks;
  • a single agent writer with a review-first completion gate;
  • parent-level review artifacts and rework tasks;
  • the permanent upstream / nightly / stable branch model;
  • meeting gates for consortium review, breakdown clarification, handover review, release readiness and recovery;
  • BOARD.md and ROADMAP.md, plus the HTML review surface;
  • event history and a agent runbook.

What it does not try to do

  • replace code review or tests;
  • prove that a human really approved something in a chat-only workflow;
  • schedule calendars;
  • run multiple agents against the same upstream;
  • hide the process behind a web app.

A reasonable first pilot

  1. Install mdBoard and connect one agent.
  2. Pick one real idea and take it through spark, refine and pitch.
  3. Let the agent estimate it and put it on the roadmap.
  4. Break it into three to five tasks and review the clarification questions.
  5. Let the agent implement the batch.
  6. Review the batch as a human, request changes once, then accept it.
  7. Merge upstream into nightly yourself.

If that feels controlled, repeat. If it feels heavy, reduce the batch size before adding more process.

How collaboration works →