magnus919/agent-skills/bmad

BMad: Intent-to-Delivery Control-Plane Protocol

BMad is a software-delivery method built on one idea: human intent should be progressively clarified, recorded, reviewed, and handed to agents as durable context rather than improvised in chat. This skill turns that method into a protocol any agent harness can follow — no official BMad installer required.

The loop: classify the request → compress intent into a contract → route to the smallest safe path → implement one bounded unit → review as triage → route failure to the layer where ambiguity entered → gate autonomy on observable acceptance → learn from completed work.

When to use this skill

Load when a change request, feature, bug report, delegated build, or multi-agent epic needs:

• intent capture before implementation — a contract, not a vibe;
• a decision about how much ceremony the work deserves;
• durable artifacts so work is resumable across sessions or agents;
• review that triages findings instead of enumerating noise;
• autonomy that stops safely when the boundary is unsafe.

Work classification (smallest safe path)

Load references/classification.md for the decision table, the one-question rule, and stop conditions.

The intent contract (five fields)

For bounded or initiative work, establish a contract before implementation:

1. Why — the outcome and why it matters.
2. Capabilities — what the system must be able to do.
3. Constraints — technical, operational, legal, security, privacy, time, cost, organizational boundaries.
4. Non-goals — what is explicitly out of scope.
5. Success signal — how we will know the result works and is acceptable.

If a field is materially ambiguous, ask one high-leverage question, propose a recommended answer, and wait for the decision. For trivial changes the contract can be five bullets in conversation; for larger work it becomes a versioned spec file.

Load references/spec.md for SPEC authoring and the status vocabulary. Templates: templates/SPEC.md and templates/INTENT.md.

The canonical loop

1. Inspect the repository and available context before asking anything.
2. Classify the work; state the proposed route.
3. Establish or resume the intent contract; ask at most one material question.
4. Present a plan for non-trivial work; wait at the approval checkpoint.
5. Implement the smallest coherent change; run focused tests first, then broader checks.
6. Review for correctness, scope, security, regressions, maintainability.
7. Repair findings that belong to this change; carry stable IDs, orchestrator dispositions, and receiving-task/closure evidence for deferred findings. A follow-up ticket alone does not resolve a finding.
8. Bind review to the exact candidate/content and acceptance contract, executed checks/environment/results/evidence; invalidate affected approval after relevant changes. Report intent, behavior, risk, finding closure, and an accept / rework / investigate choice. See references/review-and-failure-routing.md.

Spec status vocabulary

Machine-readable status for resumable work:

blocked is a routing signal, not failure: a higher-level orchestrator, another workflow, or a human takes over. Validate a spec deterministically with scripts/check-spec.py.

Failure routing

When something is wrong, diagnose the layer where the failure entered:

Do not keep patching code when the specification is the real problem.

Autonomy gate

Autonomous execution is allowed only when all of these hold: intent contract coherent, acceptance observable, boundary explicit, repository safe to modify, tests or evaluations runnable, durable status writable, escalation defined. During autonomous work: one coherent change at a time; never expand scope on unrelated improvements; never merge, deploy, or change external systems without authorization; stop on intent gaps, missing capability, destructive ambiguity, failed verification, or non-convergent repair.

Reference files

Templates

Scripts

Routing to adjacent skills

• Upstream (before BMad): product-discovery validates whether a problem is real;

product-shaping sets an appetite and produces a pitch; product-strategy and product-roadmapping-and-portfolio frame strategic context.

• Downstream (during BMad): spec-driven-development for formal spec/gate

pipelines; implementation-planning for a dependency-aware delivery plan; adr-authoring for architecture decisions; software-architecture-analysis for reverse-engineering an existing codebase.

• Execution and gates: neckbeard for the issue-to-PR delivery flow;

verification-methodology for acceptance evidence; qa-methodology for test strategy; agent-evals-and-observability for independent evaluators; agent-council for Party-Mode-style multi-agent deliberation; release-engineering for deployment gates; kanban-guru for backlog and dispatch policy.

When not to use

• The problem itself is unvalidated → product-discovery. BMad compresses intent;

it does not establish whether the problem is real.

• No decision yet on how much the work is worth → product-shaping first (appetite,

pitch, bet). BMad starts from a placed intent.

• You need a formal spec format plus phase gates as the factory pipeline →

spec-driven-development owns SPEC format and gate mechanics; BMad provides the control-plane protocol around them.

• You are executing an issue-to-PR delivery flow with its own gates → neckbeard.

BMad complements it; do not run two competing delivery lifecycles.

• You need independent review → role-play is not independence. Use agent-council,

separate evaluators, or agent-evals-and-observability; never claim persona separation as independent review.

• Operating the official BMad installer/tooling → this skill emulates the method;

it does not install or operate bmad-method npm packages.

Version drift and attribution

BMad is actively evolving (official repository: bmadcode/bmad-method; BMAD™ and BMAD-METHOD™ are trademarks of BMad Code, LLC). Older articles differ on name expansion, agents, file names, and commands. When installing the official tooling, treat the official docs and installed source as authoritative. This skill is an original distillation of the method as a harness-agnostic protocol; it does not reproduce official installer content.