mirror of https://github.com/magnus919/agent-skills.git synced 2026-09-11 19:47:12 +03:00

Files

T

Magnus HedemarkandGitHub e10508b034 feat(bmad): add BMad control-plane protocol skill (#400 )

* 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.

2026-08-24 08:05:43 -04:00

10 KiB

Raw Blame History

name, description, license, metadata

name

description

license

metadata

bmad

Use this skill to run BMad (Breakthrough Method of Agile AI-Driven Development) as a harness-agnostic control-plane protocol that turns human intent into bounded, inspectable, resumable agent work. Compress intent into a five-field contract (Why, Capabilities, Constraints, Non-goals, Success signal); classify work as direct/bounded/initiative and route to the smallest safe path; carry decisions in durable artifacts; review as triage; route failure to the layer where ambiguity entered; and gate autonomy on observable acceptance with machine-readable status (draft/ready-for-dev/in-progress/in-review/done/blocked). Use when a change request, feature, delegated build, or multi-agent epic needs intent capture, bounded implementation, review, and resumability in any agent harness. Do not use for validating whether a problem is real (product-discovery), shaping bets before planning (product-shaping), formal spec/gate pipelines (spec-driven-development), or the issue-to-PR delivery flow (neckbeard).

MIT

source	tags
https://github.com/magnus919/agent-skills/tree/main/bmad	bmad, bmad-method, agentic-engineering, intent-contract, spec, work-classification, review-triage, autonomy, dark-factory, control-plane, bounded-work, human-in-the-loop

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)

Class	Shape	Process
Direct	clear goal, local change, established patterns, small blast radius	implement immediately after minimal clarification
Bounded	coherent change needing a short contract and plan	intent contract → plan → implement → review
Initiative	cross-component, multi-story, high-risk, or strategically uncertain	analysis → planning → solutioning → implementation → learning

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:

Why — the outcome and why it matters.
Capabilities — what the system must be able to do.
Constraints — technical, operational, legal, security, privacy, time, cost, organizational boundaries.
Non-goals — what is explicitly out of scope.
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

Inspect the repository and available context before asking anything.
Classify the work; state the proposed route.
Establish or resume the intent contract; ask at most one material question.
Present a plan for non-trivial work; wait at the approval checkpoint.
Implement the smallest coherent change; run focused tests first, then broader checks.
Review for correctness, scope, security, regressions, maintainability.
Repair findings that belong to this change; defer unrelated findings explicitly.
Report intent, behavior, files, risk, verification, findings disposition, and an accept / rework / investigate choice.

Spec status vocabulary

Machine-readable status for resumable work:

Status	Meaning
`draft`	Spec exists but is not ready
`ready-for-dev`	Passed readiness; ready to implement
`in-progress`	Implementation underway
`in-review`	Review or triage underway
`done`	Workflow completed successfully
`blocked`	Cannot safely continue unattended

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:

Failure	Route
Wrong outcome or wrong problem	intent / analysis
Missing or contradictory requirement	contract / planning
Conflicting technical approach	architecture
Incorrect local code	implementation
Insufficient test or evaluation	verification
Unrelated pre-existing issue	defer explicitly
Unsafe ambiguity	block and ask

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

Reference	Load when
references/protocol.md	You need the full paste-ready operating protocol for an agent
references/classification.md	Classifying a request or choosing ceremony depth
references/spec.md	Writing or resuming a SPEC / intent contract
references/lifecycle.md	Running an initiative through all four phases
references/project-context.md	Setting up or auditing repository rules (AGENTS.md)
references/review-and-failure-routing.md	Running a review or diagnosing a failure
references/autonomy.md	Configuring or running autonomous (Build Auto) work
references/party-mode.md	Deliberation, trade-offs, design debates, post-mortems
references/adoption.md	Adopting the protocol incrementally or mapping to a dark factory

Templates

Template	Purpose
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: intent → behavior → risk → verification

Scripts

Script	When to run
scripts/check-spec.py	After writing or editing a spec: validate five fields + status vocabulary (stdlib only, `--json` output)

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.

10 KiB Raw Blame History