mirror of
https://github.com/magnus919/agent-skills.git
synced 2026-09-12 12:06:29 +03:00
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.
3.9 KiB
3.9 KiB
SPEC Authoring and the Status Vocabulary
The SPEC is the machine contract of a BMad-style run: the artifact that lets an agent resume, another agent continue, an orchestrator route, and a human review. It is deliberately concise — five core fields plus verification sections.
The five core fields
| Field | What it stabilizes | Common failure if missing |
|---|---|---|
| Why | The outcome and why it matters; the reason the work exists | Agents optimize for a plausible-but-wrong goal |
| Capabilities | What the system must be able to do, observably | Vague scope; every implementer guesses differently |
| Constraints | Technical, operational, legal, security, privacy, time, cost, organizational boundaries | Implementations violate boundaries nobody wrote down |
| Non-goals | What is explicitly out of scope | Scope creep; "while I'm here" expansion |
| Success signal | How we know the result works and is acceptable | No definition of done; endless review |
A good test for each field: could another agent or a fresh session continue from this file alone without inventing a material decision? If not, the field is under-specified.
SPEC versus PRD
- The PRD is the stakeholder-facing description of the problem and desired behavior — richer product context, audience, and rationale.
- The SPEC is a tighter execution contract — the boundary within which implementation is allowed to act.
- They coexist: the PRD holds the why-for-humans; the SPEC holds the what-and-within-what-bounds for implementation. Do not collapse one into the other when both audiences exist.
Status vocabulary
| Status | Meaning | Allowed next |
|---|---|---|
draft |
Spec exists but is not ready | ready-for-dev, blocked, draft |
ready-for-dev |
Passed readiness; ready to implement | in-progress |
in-progress |
Implementation is underway | in-review, blocked |
in-review |
Review or triage is underway | done, in-progress (rework), blocked |
done |
The workflow completed successfully | — |
blocked |
Cannot safely continue unattended | ready-for-dev, in-progress, draft |
blocked is not failure. It is a routing signal meaning a higher-level orchestrator,
another workflow, or a human must take over. A run that reports blocked with evidence
of what was attempted and why is a successful handoff, not a failed run.
Readiness
Before a spec moves to ready-for-dev, ask: could a developer implement the planned
work without inventing decisions that are not recorded?
- PASS — proceed.
- CONCERNS — proceed with named conditions or questions attached to specific stories.
- FAIL — do not proceed; the missing decisions must be recorded first.
Missing documentation is not automatically a problem. It matters only if the stories depend on that information. A local, well-understood change may pass readiness with a very thin spec; a cross-system initiative will not.
Writing order and depth
- Draft the five fields from the clarified intent (one question at a time).
- Record consequential architecture decisions (or link to ADRs).
- Split into implementation slices (stories) — each coherent and independently finishable.
- Write acceptance criteria per story as observable, binary outcomes.
- Add verification: tests, manual observations, independent review needed.
- List residual risks and deferred work explicitly.
For trivial changes, this entire process is five bullets in conversation and the spec file may never exist. For initiative work, the spec file is the contract the whole run revolves around.
Deterministic validation
After writing or editing a spec, run the bundled checker:
python3 bmad/scripts/check-spec.py path/to/SPEC.md
python3 bmad/scripts/check-spec.py --json path/to/SPEC.md # machine-readable
It verifies the five required sections are present and the frontmatter status is in
the vocabulary. See scripts/check-spec.py.