The BMAD pack: what we ship to your coding agent

When a SpecGraph project crosses the seal-the-spec threshold, we compose what we call a BMAD pack: a stamped, immutable bundle of markdown and YAML that the coding agent reads as its single source of truth. Not a wiki link. Not a search query. A pack. Versioned. Signed. Served over MCP.

We get asked the same question three times a week: why eight files?Why this shape and not, say, one big PRD? Or, alternatively, fifty small ones? The answer matters because the shape of the artefact dictates the shape of the agent's attention — and the agent's attention is the most expensive thing on your roadmap.

Why eight, exactly

Each file in the pack corresponds to a question the agent has to answer before it can write a line of code. We've resisted the urge to combine, because combining files makes the agent re-read context it has already loaded. We've resisted the urge to split, because splitting makes the agent misscontext it should have loaded. Eight is what survived.

• product-brief.md — the why, in two paragraphs. The agent reads this on every turn.
• prd.md — the what. Sections numbered §1 → §N. Stable references for self-citation.
• architecture.md — the how. Stack, boundaries, decisions. Includes the “not chosen” column.
• ux-design.md — the surface. Design tokens at the top, components by name.
• epics.md — the work, by epic and story. Each story has a stable key (1.1, 1.2) and references PRD sections.
• qa-test-plan.md — the proof. What “done” looks like, by feature.
• project-context.md — the operational context. Repo layout, branch policy, deploy targets.
• CLAUDE.md — the agent's constitution. Voice, style, what not to invent. The agent reads this first.

Plus, alongside the planning files: a sprint-status.yamlregistry and one markdown file per story under impl/ . The implementation files are the ones the agent actually writes against. The planning files are the ones it reads to know what to write.

Specs come from people. Packs go to agents. The job of SpecGraph is to make those two artefacts the same thing — without either party having to compromise.

Why immutable

Every pack is stamped with a semver version, a timestamp, and a signature. The signature is the boring kind — HMAC over the canonical JSON of the pack contents — but it's not boring in practice. It means the agent can't accidentally execute a pack from someone's WIP branch. It means the audit trail can replay which pack versiona given commit was written against. It means a regulator asking “why did the system do that?” gets a one-line answer:“It was acting on pack v1.0.0, sealed on April 29 by these four approvers, and here's the diff to v1.0.1.”

Why MCP and not a webhook

MCP is a streaming, capability-typed protocol designed for agents. It lets us do three things webhooks can't:

• Hand the agent tools alongside the documents — the same pack also exposes open_story, cite_section, post_question.
• Stream long-context payloads without the agent having to chunk them itself.
• Authorise per-token. The agent reads only the project the token is bound to. No cross-project leakage, no shared-secret pain.

What the agent does with it

The interesting part is what the agent does back. Every commit it produces references the section of the PRD that justified it. Every PR description starts with the story key. Every QA event closes the loop on a test plan item. The pack isn't just an input — it's a citation graph that the agent populates as it works. Reviewers read commits the way a researcher reads a paper. That is the work product.

What you can do this week

• Open the BMAD pack we ship as part of the playground. Read CLAUDE.md first. Notice what we tell the agent not to do.
• Write the equivalent of CLAUDE.md for your own codebase. Even if you never adopt SpecGraph, the act of writing it will remove half the drift in your next sprint.
• If you're running an agent today, ask it to cite a PRD section in its next commit. Most can. Almost none do — by default.

We didn't invent BMAD. We made it executable. The pack is what the executable artefact looks like.