Magnus HedemarkandGitHub
e10508b034
* feat(bmad): add BMad control-plane protocol skill New standalone methodology skill that lets any agent run the BMad method (Breakthrough Method of Agile AI-Driven Development) as a harness-agnostic control-plane protocol: five-field intent contracts, direct/bounded/initiative classification, review-as-triage, failure routing by layer, and autonomy gating with machine-readable spec status. - SKILL.md protocol core with progressive disclosure + When not to use - README.md human-facing install guide - 9 references: protocol, classification, spec, lifecycle, project-context, review-and-failure-routing, autonomy, party-mode, adoption - 4 templates: SPEC, INTENT, STORY, REVIEW - scripts/check-spec.py + 16 tests (stdlib, deterministic spec validation) - evals/evals.json: 9 output-quality cases - Routing seams from bmad to adjacent skills and back from spec-driven-development, product-shaping, implementation-planning, neckbeard - Catalog updates: root README, skill-triggers, marketplace/plugin/llms.txt Closes #399 * fix(bmad): address droid-review findings - check-spec.py: skip headings inside fenced/indented code blocks so a spec cannot PASS on section text that only appears in a code sample - check-spec.py: catch UnicodeDecodeError on non-UTF-8 files and report FAIL instead of crashing - STORY.md template: add created key for resumability/traceability parity - SPEC.md template: split in-progress and in-review status bullets - add 2 regression tests (heading-in-fence, non-UTF-8) * fix(bmad): address droid-review round 2 - check-spec.py: read specs with utf-8-sig so a UTF-8 BOM cannot silently disable the frontmatter status check - check-spec.py: handle standard YAML inline comments after status values (status: draft # pending review) without a false FAIL - references/protocol.md: make lifecycle phrasing consistent with lifecycle.md — four phases plus a learning closeout - add 2 regression tests (BOM, inline comment) * fix(bmad): tolerate trailing whitespace on frontmatter delimiters A spec whose --- delimiter lines carry trailing spaces or tabs would silently disable the status check and let an invalid status PASS. Relax the delimiter pattern and add a regression test. * fix(bmad): ignore inline comments in quoted status values * fix(bmad): tolerate leading blank lines before frontmatter * fix(bmad): fail closed on unparseable frontmatter, matching fence markers Address droid-review round 5 and 6 findings as a single closed class: - Fail closed when a file opens with a --- delimiter that cannot be parsed, so no whitespace/frontmatter permutation can silently disable the status check (previously: unparseable frontmatter was treated as 'no status' warning, letting an invalid status PASS). - Track fence opener markers in collect_headings so a mismatched fence no longer closes a code block early (false-PASS on missing sections) and an unclosed fence no longer swallows real headings. - Accept empty well-formed frontmatter (---\n---) and closing delimiters without a trailing newline. - STORY.md template: parent-spec points at the sibling SPEC.md. - README: status vocabulary is not a strict linear chain; blocked is a resumable routing signal. Whitespace/frontmatter mutation sweep: 9 formatting variants x valid/invalid status all verdict correctly; malformed delimiters fail closed. 29 tests.
5.5 KiB
bmad
Turn human intent into bounded, inspectable, resumable agent work — the BMad method (Breakthrough Method of Agile AI-Driven Development) as a protocol any agent harness can follow, no official installer required.
Why Install This Skill
Most agent failures are not coding failures. The agent implemented the wrong thing because intent was never compressed into a contract; it re-asked questions it could have answered by reading the repository; a review produced a wall of noise instead of a triage; or an autonomous run kept going past the point where the boundary stopped being safe. BMad was built to fix exactly these problems: clarify intent first, route each piece of work to the smallest process it deserves, carry decisions in durable artifacts, and make autonomy conditional on observable acceptance.
This skill installs that discipline as a harness-agnostic protocol. You do not
need the BMad npm installer, a specific IDE, or a particular agent brand. Any agent —
Claude Code, Cursor, Hermes, Devin, OpenHands, or your own harness — can follow the
protocol with plain Markdown contracts, a five-field intent contract, and a
machine-readable status vocabulary (draft → ready-for-dev → in-progress → in-review → done, with blocked as a resumable routing signal and rework paths back to earlier states).
After installing, an agent can take a vague change request and return a one-paragraph
intent contract instead of guessing; take a cross-system initiative and sequence it
through analysis, planning, and solutioning before a single line of code; run a review
that defers unrelated findings instead of ballooning scope; and run unattended builds
that stop safely and report blocked when a human decision is genuinely required.
What You Get
| Directory | What it provides |
|---|---|
SKILL.md |
The protocol core: classification, five-field contract, status vocabulary, failure routing, autonomy gate, routing |
references/protocol.md |
The full paste-ready operating protocol for an agent |
references/classification.md |
Direct / bounded / initiative decision table, one-question rule, stop conditions |
references/spec.md |
SPEC authoring, status semantics, PRD coexistence, readiness |
references/lifecycle.md |
The four-phase lifecycle and the artifact chain |
references/project-context.md |
Conservative AGENTS.md rules: persist only what is expensive to rediscover |
references/review-and-failure-routing.md |
Review as triage; routing failure to the layer where ambiguity entered |
references/autonomy.md |
Autonomous execution (Build Auto) conditions, stop rules, blocked as routing |
references/party-mode.md |
Multi-persona deliberation with honest independence caveats |
references/adoption.md |
Five-step incremental adoption and dark-factory mapping |
templates/SPEC.md |
Versioned machine contract for bounded/initiative work |
templates/INTENT.md |
Lightweight five-field contract for bounded work |
templates/STORY.md |
One bounded, dispatchable work unit |
templates/REVIEW.md |
Final human checkpoint review |
scripts/check-spec.py |
Deterministic spec validation: five fields + status vocabulary (stdlib only) |
evals/evals.json |
Output-quality evaluation cases |
Quick Start
No setup needed. The protocol works with plain Markdown files in your repository.
- Say "this request needs an intent contract before implementation" — fill in
templates/INTENT.mdortemplates/SPEC.md. - Say "classify this work" — load
references/classification.mdfor the decision table. - Say "run this build autonomously, bounded" — load
references/autonomy.mdand set the status vocabulary. - After writing a spec, validate it:
python3 bmad/scripts/check-spec.py path/to/SPEC.md
It prints PASS/FAIL per file and exits non-zero on invalid specs; add --json for
machine-readable output.
Triggers
Load this skill when:
- A change request, feature, or bug report needs intent capture before implementation
- You must decide how much planning ceremony a piece of work deserves
- Delegating a build to an agent: boundary, acceptance, and stop conditions
- Work must be resumable across sessions or agents (durable artifacts, status)
- A review is producing noise instead of triage
- An autonomous run needs to know when to stop and escalate (
blocked) - A multi-agent epic needs shared architecture and story decomposition
- You are standing up a dark-factory-style delivery system and need the control plane
Requirements
No software dependencies or credentials. scripts/check-spec.py uses the Python
standard library only (Python 3.8+). The method is agent-harness-agnostic; templates
and status files are plain Markdown.
Attribution
Method adapted from BMad / BMAD-METHOD™ (trademarks of BMad Code, LLC; official repository: bmadcode/bmad-method), distilled from official documentation and an independent research synthesis into an original harness-agnostic operating protocol. This skill is not the official BMad tooling and does not include its installer.