mirror of
https://github.com/magnus919/agent-skills.git
synced 2026-09-11 19:47:12 +03:00
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.
This commit is contained in:
Magnus Hedemark
@@ -149,6 +149,15 @@
|
||||
"strict": false,
|
||||
"description": "Analyze unknown binary files through a deterministic CLI that wraps Ghidra's static-analysis engine. Use when you need to inspect a PE, ELF, or Mach-O file — triage suspicious binaries, map imported APIs, decompile functions, trace call paths, or produce structured evidence reports. Do not use for runtime analysis (debugging, dynamic tracing, sandbox execution), for modifying or patching binaries, or for binaries you already know everything about. The skill owns planning, hypothesis formation, and evidence synthesis; the CLI owns all deterministic operations."
|
||||
},
|
||||
{
|
||||
"name": "bmad",
|
||||
"source": "./",
|
||||
"skills": [
|
||||
"./bmad"
|
||||
],
|
||||
"strict": false,
|
||||
"description": "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)."
|
||||
},
|
||||
{
|
||||
"name": "brand-designer",
|
||||
"source": "./",
|
||||
@@ -1164,7 +1173,7 @@
|
||||
"./spec-driven-development"
|
||||
],
|
||||
"strict": false,
|
||||
"description": "Spec-Driven Development (SDD) methodology for AI software factories — where structured specifications are the input, AI agents generate the code, and quality gates enforce correctness at each pipeline phase. Use when designing a spec → review → decompose → implement → verify pipeline that any AI coding tool (Claude Code, Cursor, Hermes Agent, Devin, OpenHands) can follow."
|
||||
"description": "Design and run a Spec-Driven Development (SDD) pipeline for AI software factories — where structured specifications are the input, AI agents generate the code, and quality gates enforce correctness at each phase: SPECIFY → DECOMPOSE → IMPLEMENT → VERIFY → DELIVER. Use when building or refining a spec-driven pipeline any AI coding tool (Claude Code, Cursor, Hermes Agent, Devin, OpenHands, droid) can follow, or when you need spec quality gates, phase-gate verdicts, NFR encoding, or format translation. Do not use for a single small change with a clear goal (classify first via bmad), for the control-plane protocol of intent contracts, autonomy gating, and failure routing around a pipeline (bmad), or for unvalidated problems (product-discovery)."
|
||||
},
|
||||
{
|
||||
"name": "strategy-frameworks",
|
||||
|
||||
@@ -34,6 +34,7 @@
|
||||
"./autogen",
|
||||
"./backend-engineering",
|
||||
"./binary-analysis",
|
||||
"./bmad",
|
||||
"./brand-designer",
|
||||
"./c4-diagramming",
|
||||
"./capacity-and-cost-engineering",
|
||||
|
||||
@@ -72,6 +72,10 @@ Design and implement backend services and APIs — REST, gRPC, GraphQL endpoint
|
||||
|
||||
Analyze unknown PE, ELF, Mach-O, and firmware files through a deterministic CLI backed by Ghidra's static-analysis engine. Covers triage, imports, decompilation, call paths, and structured evidence reports without executing or modifying the binary.
|
||||
|
||||
### [bmad](bmad/SKILL.md)
|
||||
|
||||
Run the BMad method (Breakthrough Method of Agile AI-Driven Development) as a harness-agnostic control-plane protocol: compress human intent into a five-field contract, 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. Use for intent capture, bounded implementation, review, and resumability in any agent harness.
|
||||
|
||||
### [brand-designer](brand-designer/SKILL.md)
|
||||
|
||||
Create comprehensive brand identity documentation for any brand. Guides you through documenting strategy, visual identity (logo, color, typography, imagery), voice and tone, application guidelines, governance, and asset inventory. Produces markdown specs, compiled brand books, and brand-compliant images via reference-image-aware generation. Ships 7 templates, a brand-book CLI for validation/compilation, and a generate script for brand card and mockup imagery.
|
||||
@@ -529,7 +533,7 @@ Reverse-engineer a software codebase to understand its architecture, data flow,
|
||||
|
||||
### [spec-driven-development](spec-driven-development/SKILL.md)
|
||||
|
||||
Spec-Driven Development (SDD) methodology for AI software factories — where structured specifications are the input, AI agents generate the code, and quality gates enforce correctness at each pipeline phase. Covers the 5-phase pipeline (SPECIFY → DECOMPOSE → IMPLEMENT → VERIFY → DELIVER), 4 phase gates with APPROVED/CONDITIONS/REJECTED verdicts, 7 spec quality gates, a methodology selection matrix (BDD, OpenAPI, AsyncAPI, DbC, TLA+, ADRs, C4), NFR encoding patterns, format translation (PRD → SPEC.md → Gherkin → OpenAPI), gate recovery and revision workflows, and a worked example SPEC.md. Ships 4 templates, 9 reference files, and 2 validation scripts. Tool-agnostic — works with Claude Code, Cursor, Hermes Agent, Devin, OpenHands, and droid.
|
||||
Design and run a Spec-Driven Development (SDD) pipeline for AI software factories — where structured specifications are the input, AI agents generate the code, and quality gates enforce correctness at each pipeline phase. Covers the 5-phase pipeline (SPECIFY → DECOMPOSE → IMPLEMENT → VERIFY → DELIVER), 4 phase gates with APPROVED/CONDITIONS/REJECTED verdicts, 7 spec quality gates, a methodology selection matrix (BDD, OpenAPI, AsyncAPI, DbC, TLA+, ADRs, C4), NFR encoding patterns, format translation (PRD → SPEC.md → Gherkin → OpenAPI), gate recovery and revision workflows, and a worked example SPEC.md. Ships 4 templates, 9 reference files, and 2 validation scripts. Tool-agnostic — works with Claude Code, Cursor, Hermes Agent, Devin, OpenHands, and droid. Not for single small changes, the intent-to-delivery control-plane protocol (see bmad), or unvalidated problems (product-discovery).
|
||||
|
||||
### [strategy-frameworks](strategy-frameworks/SKILL.md)
|
||||
|
||||
|
||||
@@ -0,0 +1,93 @@
|
||||
# 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`](SKILL.md) | The protocol core: classification, five-field contract, status vocabulary, failure routing, autonomy gate, routing |
|
||||
| [`references/protocol.md`](references/protocol.md) | The full paste-ready operating protocol for an agent |
|
||||
| [`references/classification.md`](references/classification.md) | Direct / bounded / initiative decision table, one-question rule, stop conditions |
|
||||
| [`references/spec.md`](references/spec.md) | SPEC authoring, status semantics, PRD coexistence, readiness |
|
||||
| [`references/lifecycle.md`](references/lifecycle.md) | The four-phase lifecycle and the artifact chain |
|
||||
| [`references/project-context.md`](references/project-context.md) | Conservative AGENTS.md rules: persist only what is expensive to rediscover |
|
||||
| [`references/review-and-failure-routing.md`](references/review-and-failure-routing.md) | Review as triage; routing failure to the layer where ambiguity entered |
|
||||
| [`references/autonomy.md`](references/autonomy.md) | Autonomous execution (Build Auto) conditions, stop rules, blocked as routing |
|
||||
| [`references/party-mode.md`](references/party-mode.md) | Multi-persona deliberation with honest independence caveats |
|
||||
| [`references/adoption.md`](references/adoption.md) | Five-step incremental adoption and dark-factory mapping |
|
||||
| [`templates/SPEC.md`](templates/SPEC.md) | Versioned machine contract for bounded/initiative work |
|
||||
| [`templates/INTENT.md`](templates/INTENT.md) | Lightweight five-field contract for bounded work |
|
||||
| [`templates/STORY.md`](templates/STORY.md) | One bounded, dispatchable work unit |
|
||||
| [`templates/REVIEW.md`](templates/REVIEW.md) | Final human checkpoint review |
|
||||
| [`scripts/check-spec.py`](scripts/check-spec.py) | Deterministic spec validation: five fields + status vocabulary (stdlib only) |
|
||||
| [`evals/evals.json`](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.md` or `templates/SPEC.md`.
|
||||
- Say *"classify this work"* — load `references/classification.md` for the decision
|
||||
table.
|
||||
- Say *"run this build autonomously, bounded"* — load `references/autonomy.md` and set
|
||||
the status vocabulary.
|
||||
- After writing a spec, validate it:
|
||||
|
||||
```bash
|
||||
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.
|
||||
+198
@@ -0,0 +1,198 @@
|
||||
---
|
||||
name: bmad
|
||||
description: >-
|
||||
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).
|
||||
license: MIT
|
||||
metadata:
|
||||
source: https://github.com/magnus919/agent-skills/tree/main/bmad
|
||||
tags: 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](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](references/spec.md) for SPEC authoring and the status
|
||||
vocabulary. Templates: [templates/SPEC.md](templates/SPEC.md) and
|
||||
[templates/INTENT.md](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; defer unrelated findings explicitly.
|
||||
8. 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](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](references/protocol.md) | You need the full paste-ready operating protocol for an agent |
|
||||
| [references/classification.md](references/classification.md) | Classifying a request or choosing ceremony depth |
|
||||
| [references/spec.md](references/spec.md) | Writing or resuming a SPEC / intent contract |
|
||||
| [references/lifecycle.md](references/lifecycle.md) | Running an initiative through all four phases |
|
||||
| [references/project-context.md](references/project-context.md) | Setting up or auditing repository rules (AGENTS.md) |
|
||||
| [references/review-and-failure-routing.md](references/review-and-failure-routing.md) | Running a review or diagnosing a failure |
|
||||
| [references/autonomy.md](references/autonomy.md) | Configuring or running autonomous (Build Auto) work |
|
||||
| [references/party-mode.md](references/party-mode.md) | Deliberation, trade-offs, design debates, post-mortems |
|
||||
| [references/adoption.md](references/adoption.md) | Adopting the protocol incrementally or mapping to a dark factory |
|
||||
|
||||
## Templates
|
||||
|
||||
| Template | Purpose |
|
||||
|---|---|
|
||||
| [templates/SPEC.md](templates/SPEC.md) | Versioned machine contract for bounded/initiative work |
|
||||
| [templates/INTENT.md](templates/INTENT.md) | Lightweight five-field contract for bounded work |
|
||||
| [templates/STORY.md](templates/STORY.md) | One bounded, dispatchable work unit |
|
||||
| [templates/REVIEW.md](templates/REVIEW.md) | Final human checkpoint: intent → behavior → risk → verification |
|
||||
|
||||
## Scripts
|
||||
|
||||
| Script | When to run |
|
||||
|---|---|
|
||||
| [scripts/check-spec.py](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.
|
||||
@@ -0,0 +1,131 @@
|
||||
{
|
||||
"schema_version": 1,
|
||||
"skill_name": "bmad",
|
||||
"evals": [
|
||||
{
|
||||
"id": "typo-fix-classified-direct",
|
||||
"prompt": "There's a typo in the README on line 12 — 'recieve' should be 'receive'. Fix it.",
|
||||
"expected_output": "The agent should classify this as a direct change: clear goal, local change, established pattern, tiny blast radius. It should fix it immediately (or state it will) without proposing an intent contract, a plan, a story decomposition, or any planning ceremony. It may state the classification briefly to show it chose the smallest safe path, but must not invent process. It should not ask clarifying questions for a change this unambiguous.",
|
||||
"assertions": [
|
||||
"Classifies the change as direct work rather than bounded or initiative",
|
||||
"Fixes or proposes the fix immediately without planning ceremony",
|
||||
"Does not produce an intent contract, spec, or story breakdown for the typo",
|
||||
"Does not ask clarifying questions that the repository context already answers"
|
||||
],
|
||||
"files": ["SKILL.md", "references/classification.md"],
|
||||
"case_set": "regression"
|
||||
},
|
||||
{
|
||||
"id": "initiative-from-vague-chat-is-stop-condition",
|
||||
"prompt": "We need to replace our auth system with a federated identity service across all three of our products and our mobile apps. It's a big deal but I don't have details yet. Go ahead and start working on it.",
|
||||
"expected_output": "The agent should recognize this as initiative-scale work: cross-component, multi-story, high coordination risk, strategically uncertain, and lacking an approved intent contract. It must refuse to start implementing from the vague request and instead compress intent: state the proposed route (analysis/planning before implementation), ask at most one high-leverage question with a recommended answer, and wait at the approval checkpoint. It should explicitly name the stop condition: initiative work from a vague chat request is not implementable without a contract. It must not begin coding, scaffolding, or story decomposition.",
|
||||
"assertions": [
|
||||
"Classifies the request as initiative-scale work",
|
||||
"Refuses to implement from the vague request and names the stop condition",
|
||||
"Compresses intent and asks at most one high-leverage question with a recommended answer",
|
||||
"Proposes analysis/planning before implementation and waits at an approval checkpoint",
|
||||
"Does not begin coding, scaffolding, or story decomposition"
|
||||
],
|
||||
"files": ["SKILL.md", "references/classification.md", "references/protocol.md"],
|
||||
"case_set": "release"
|
||||
},
|
||||
{
|
||||
"id": "intent-contract-five-fields",
|
||||
"prompt": "Build a notification center in the app so users can see their alerts in one place instead of scattered emails. I'm not sure how far to take it, and we need to decide whether push notifications are in scope. How should we start?",
|
||||
"expected_output": "The agent should recognize this as bounded-to-initiative work needing a five-field intent contract before implementation: Why (one place to see alerts, reduce scattered emails), Capabilities (list/filter/mark-read alerts in-app), Constraints (existing notification stack, platform boundaries), Non-goals (push notifications explicitly unresolved — the agent should ask one high-leverage question about push scope with a recommended answer), Success signal (observable: user can see all alerts in one place, mark read state persists). It should produce or propose the contract, ask at most one material question (push in/out of scope) with a recommendation, and wait at the checkpoint rather than building.",
|
||||
"assertions": [
|
||||
"Produces a five-field contract: Why, Capabilities, Constraints, Non-goals, Success signal",
|
||||
"Identifies push-notification scope as the material open decision",
|
||||
"Asks at most one high-leverage question and provides a recommended answer",
|
||||
"Makes the success signal observable rather than vague",
|
||||
"Waits for approval before implementation"
|
||||
],
|
||||
"files": ["SKILL.md", "templates/INTENT.md", "templates/SPEC.md", "references/spec.md"],
|
||||
"case_set": "dev"
|
||||
},
|
||||
{
|
||||
"id": "failure-routed-to-spec-not-code",
|
||||
"prompt": "The billing module keeps charging customers the wrong amount for prorated upgrades. I patched the calculation twice and it's still wrong. The tests pass. What's going on?",
|
||||
"expected_output": "The agent should not keep patching the calculation. It should diagnose the layer where the failure entered: repeated wrong output plus passing tests suggests the requirement itself is missing or contradictory — there is likely no recorded contract for how proration should behave across plan changes. It should return to the contract/planning layer: recover or reconstruct the proration requirement (the missing edge cases, e.g., mid-cycle upgrade, downgrade, multi-seat), check whether acceptance criteria ever existed, and route the fix to the spec rather than more code patches. It should note that a test suite that passes while behavior is wrong is evidence the tests encode the wrong expectation. It may defer unrelated findings explicitly but must not keep patching implementation while the specification is the real problem.",
|
||||
"assertions": [
|
||||
"Stops patching code and looks for the failure layer rather than applying another fix",
|
||||
"Identifies missing or contradictory requirements as the likely layer (spec/contract), not the implementation",
|
||||
"Explains why passing tests are not proof of correctness when the encoded expectation is wrong",
|
||||
"Returns to the contract/planning layer and proposes recording the proration requirements",
|
||||
"Does not claim the bug is fixed"
|
||||
],
|
||||
"files": ["references/review-and-failure-routing.md", "references/spec.md"],
|
||||
"case_set": "release"
|
||||
},
|
||||
{
|
||||
"id": "review-triage-defers-unrelated-findings",
|
||||
"prompt": "Review this PR that adds a cache layer to the search endpoint. While reviewing I noticed the legacy admin panel has an unpatched XSS vulnerability and the codebase uses two different date libraries. How should I handle all of these?",
|
||||
"expected_output": "The agent should treat review as triage, not enumeration: findings causally related to the cache-layer change (correctness, scope, security of the new code, regressions in search, maintainability) are addressed now; the legacy XSS and the date-library inconsistency are real but unrelated findings that must be deferred to explicit follow-up work, not fixed inside this PR. It should not turn one focused change into an uncontrolled cleanup project, and should not silently drop the deferred items — they need explicit tracked follow-up. It may flag the XSS as high-priority follow-up but outside this PR's boundary.",
|
||||
"assertions": [
|
||||
"Reviews the cache-layer change for correctness, scope, security, regressions, maintainability",
|
||||
"Defers the legacy XSS and date-library issues as unrelated-but-real findings",
|
||||
"Routes deferred findings to explicit follow-up rather than silently dropping them",
|
||||
"Does not expand the PR's scope to fix unrelated issues",
|
||||
"Distinguishes severity from scope: high-priority follow-up is still out of this PR's boundary"
|
||||
],
|
||||
"files": ["references/review-and-failure-routing.md"],
|
||||
"case_set": "dev"
|
||||
},
|
||||
{
|
||||
"id": "autonomy-gate-blocks-on-missing-acceptance",
|
||||
"prompt": "Run this build unattended overnight. The intent is to add an export feature to the reporting module, but we haven't decided what format or what the export endpoint should return. Just use your judgment and get it done.",
|
||||
"expected_output": "The agent should refuse unattended execution and report the missing autonomy conditions: the intent contract is not coherent (format and endpoint undefined), and acceptance is not observable (no defined success signal). It must not 'use its judgment' to fill product decisions autonomously — that is exactly the case where autonomy amplifies bad intent. It should either ask the one high-leverage question with a recommended answer and wait, or run the bounded portion only if a contract can be established first. It should state that blocked/missing conditions are routing signals, and that guessing is not an acceptable substitute for a contract.",
|
||||
"assertions": [
|
||||
"Refuses unattended execution because the intent contract is incomplete",
|
||||
"Names the missing autonomy conditions (coherent contract, observable acceptance)",
|
||||
"Refuses to silently invent the export format or endpoint contract",
|
||||
"Asks the material question with a recommendation or reports blocked as a routing signal",
|
||||
"Does not start implementing on guessed requirements"
|
||||
],
|
||||
"files": ["references/autonomy.md", "references/protocol.md"],
|
||||
"case_set": "release"
|
||||
},
|
||||
{
|
||||
"id": "human-checkpoint-intent-and-risk-first",
|
||||
"prompt": "Here's the final change for the SSO migration story. Files changed: auth/saml.go, auth/session.go, config.yaml, 3 test files. Please review it.",
|
||||
"expected_output": "The agent should not ask the human to review an unexplained file list. The final checkpoint must be organized around intent and risk first: original intent in one sentence, implemented behavior, highest-risk decisions (e.g., session handling change, config migration), verification performed (tests + manual observations), findings disposition, residual risks, and a clear accept / rework / investigate choice. File and line references come after the intent-and-risk framing, as evidence. It should flag that the session-handling change is the highest-risk decision and ask for explicit acceptance of that trade-off.",
|
||||
"assertions": [
|
||||
"Organizes the review around intent and risk, not an unexplained file list",
|
||||
"States the original intent in one sentence and the implemented behavior",
|
||||
"Names the highest-risk decisions (session handling, config migration) explicitly",
|
||||
"Reports tests and manual observations and the disposition of findings",
|
||||
"Ends with a clear accept / rework / investigate choice"
|
||||
],
|
||||
"files": ["templates/REVIEW.md", "references/review-and-failure-routing.md"],
|
||||
"case_set": "dev"
|
||||
},
|
||||
{
|
||||
"id": "spec-status-vocabulary-resumable",
|
||||
"prompt": "We started implementing the SSO spec last week, then the session handling turned out to be riskier than expected and we need a human to decide the approach. Also we haven't finished the directory sync story. What statuses should these have?",
|
||||
"expected_output": "The agent should apply the machine-readable status vocabulary: the SSO spec that cannot safely continue should be marked blocked (a routing signal meaning an orchestrator or human must take over, not a failure), and the directory sync story that is being implemented should be in-progress (or ready-for-dev if not started). It should explain that blocked is a routing signal with evidence of what was attempted and what decision is required, and that the status vocabulary exists so work is resumable across sessions and agents. It should not invent new statuses.",
|
||||
"assertions": [
|
||||
"Marks the stalled spec blocked and explains blocked as a routing signal, not failure",
|
||||
"Marks the in-flight story in-progress (or ready-for-dev if not started)",
|
||||
"Explains that status enables resumability across sessions and agents",
|
||||
"Uses only vocabulary values: draft, ready-for-dev, in-progress, in-review, done, blocked",
|
||||
"Recommends recording what decision is needed to unblock"
|
||||
],
|
||||
"files": ["SKILL.md", "references/spec.md", "templates/SPEC.md"],
|
||||
"case_set": "dev"
|
||||
},
|
||||
{
|
||||
"id": "role-play-is-not-independence",
|
||||
"prompt": "I ran this design through our five BMad personas — analyst, PM, architect, developer, and QA — all in one conversation, and they all agree the design is solid. Can we call that independent review and skip the external security check?",
|
||||
"expected_output": "The agent should refuse to characterize in-conversation persona role-play as independent review: five names in one conversation do not create five minds, and the shared-context convergence means the perspectives are not independent reasoning paths. It should explain that role separation changes checklists and questions but does not guarantee independence, and that consensus among personas is not independent validation. For a security-relevant decision it should route to genuinely independent evaluation: separate agents/subagents with separate context, an external evaluator, independent tests, or a security review (e.g., agent-evals-and-observability, agent-council, secure-software-engineering) and keep the external security check.",
|
||||
"assertions": [
|
||||
"Refuses to describe persona role-play as independent review",
|
||||
"Explains why one-conversation personas share context and cannot be independent reasoning paths",
|
||||
"States that consensus among personas is not independent validation",
|
||||
"Routes to genuinely independent evaluation (separate agents, external evaluator, security review)",
|
||||
"Does not waive the external security check"
|
||||
],
|
||||
"files": ["references/party-mode.md", "references/review-and-failure-routing.md"],
|
||||
"case_set": "regression"
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,106 @@
|
||||
# Adoption: Incremental Protocol, Then Automation
|
||||
|
||||
Do not begin by converting every project to a full BMad installation. Begin with a
|
||||
small protocol trial and add autonomy only after acceptance is testable.
|
||||
|
||||
## Step 1: Establish a project-context boundary
|
||||
|
||||
Create or audit AGENTS.md. Keep only: repository policies; non-obvious commands;
|
||||
conventions that differ from defaults; cross-component invariants; known, observed
|
||||
pitfalls; pointers to authoritative documents. Do not use AGENTS.md as a generated
|
||||
encyclopedia. See [project-context.md](project-context.md).
|
||||
|
||||
## Step 2: Require an intent contract for meaningful work
|
||||
|
||||
Before implementation, capture Why, Capabilities, Constraints, Non-goals, and Success
|
||||
signal. For trivial changes this can be five short bullets in the agent conversation.
|
||||
For a larger initiative it becomes a versioned spec file. See
|
||||
[spec.md](spec.md) and the templates.
|
||||
|
||||
## Step 3: Route by complexity and coordination risk
|
||||
|
||||
- Tiny and obvious → direct implementation.
|
||||
- Bounded but non-trivial → intent contract, short plan, implementation, review.
|
||||
- Cross-component or multi-story → analysis, PRD or SPEC, architecture, stories,
|
||||
readiness gate, sequential implementation.
|
||||
- High-risk or regulated → add explicit human and independent evaluation gates.
|
||||
|
||||
## Step 4: Add autonomy only after acceptance is testable
|
||||
|
||||
Do not start with unattended execution. First make sure:
|
||||
|
||||
- the story boundary is coherent;
|
||||
- acceptance criteria are observable;
|
||||
- tests and evaluations exist;
|
||||
- the agent can report status;
|
||||
- blocked work can be escalated;
|
||||
- unrelated findings can be deferred;
|
||||
- repository isolation and rollback work.
|
||||
|
||||
See [autonomy.md](autonomy.md).
|
||||
|
||||
## Step 5: Close the loop
|
||||
|
||||
After an epic or substantial change:
|
||||
|
||||
- compare the result with the original intent;
|
||||
- review seams between stories;
|
||||
- record defects that isolation hid;
|
||||
- reconcile any contract drift;
|
||||
- update context only when a lesson is expensive to rediscover;
|
||||
- create follow-up work explicitly rather than letting it leak into the next task.
|
||||
|
||||
## Mapping to a dark-factory system
|
||||
|
||||
| BMad concept | Likely implementation |
|
||||
|---|---|
|
||||
| Named agent | Role-specific skill, prompt, or subagent profile |
|
||||
| Workflow skill | Reusable protocol with explicit inputs, outputs, and gates |
|
||||
| Product brief / PRD / SPEC | Versioned Markdown contracts |
|
||||
| Architecture spine | ADRs, C4 context, interface contracts, system invariants |
|
||||
| Epics and stories | Dispatchable work units |
|
||||
| Sprint status | Machine-readable state file or database row |
|
||||
| Build | The implementation harness |
|
||||
| Build Auto | A controlled autonomous runner |
|
||||
| Code review | Independent reviewer and repair loop |
|
||||
| Retrospective | Evidence-based evaluation and learning update |
|
||||
| Project context | AGENTS.md plus carefully curated repository rules |
|
||||
| Party Mode | A deliberation protocol with selectable single-model or independent-agent modes |
|
||||
|
||||
The strongest combination with a dark-factory architecture:
|
||||
|
||||
1. Human states an objective.
|
||||
2. Analyst/PM-style workflow compresses it into an intent contract.
|
||||
3. Human approves the contract and important trade-offs.
|
||||
4. Architect-style workflow establishes boundaries and invariants.
|
||||
5. Story sharder creates bounded work units.
|
||||
6. Orchestrator dispatches one unit at a time.
|
||||
7. Developer agent implements in an isolated worktree.
|
||||
8. Automated tests and domain evaluations run.
|
||||
9. Independent review agent triages findings.
|
||||
10. The orchestrator routes done, blocked, deferred, or rework.
|
||||
11. Human reviews the final product at the appropriate checkpoint.
|
||||
12. Retrospective updates the process and only the durable project context.
|
||||
|
||||
Division of labor: BMad-style workflows own understanding and handoff quality; the
|
||||
factory orchestrator owns scheduling and policy; the implementation agent owns local
|
||||
code changes; evaluators own evidence; the human owns intent, authority, and
|
||||
acceptance.
|
||||
|
||||
## Known limitations to keep honest
|
||||
|
||||
- **Role-play is not independence** — use actual subagents, independent model calls,
|
||||
or an external evaluator when independence matters.
|
||||
- **Better documents do not guarantee better decisions** — human judgment and evidence
|
||||
remain necessary.
|
||||
- **Documentation can become a tax** — strongest when artifacts preserve load-bearing
|
||||
decisions; counterproductive when every minor change produces ceremony or stale
|
||||
plans compete with the code.
|
||||
- **A self-reviewing agent can miss its own blind spots** — add independent checks for
|
||||
high-risk work.
|
||||
- **Autonomy can amplify bad intent** — the more capable the execution loop, the more
|
||||
important it is to freeze the right intent before it runs.
|
||||
- **Version drift is real** — BMad is actively evolving; when installing official
|
||||
tooling, pin versions and follow current docs.
|
||||
- **Not a complete dark factory** — the method supplies the control plane; you still
|
||||
need the queue, dispatch, isolation, policy, observability, and budget layers.
|
||||
@@ -0,0 +1,72 @@
|
||||
# Autonomy: BMad Build Auto
|
||||
|
||||
Build Auto is not a second implementation methodology. It is an unattended execution
|
||||
wrapper around the canonical Build loop — one iteration per run: clarify intent,
|
||||
create or resume a spec, implement, review, write a machine-readable terminal status.
|
||||
|
||||
## The autonomy gate
|
||||
|
||||
Autonomous execution is allowed only when **all** of these hold:
|
||||
|
||||
- the intent contract is coherent;
|
||||
- acceptance is observable;
|
||||
- the working boundary is explicit;
|
||||
- the repository state is safe to modify;
|
||||
- tests or evaluations can run;
|
||||
- the agent can write a durable status;
|
||||
- escalation behavior is defined.
|
||||
|
||||
If any condition is missing, do not run unattended. Run supervised instead, or report
|
||||
the missing condition.
|
||||
|
||||
## Operating rules during autonomous work
|
||||
|
||||
- Make one coherent change at a time.
|
||||
- Do not expand scope because you noticed unrelated improvements — record them as
|
||||
deferred findings.
|
||||
- Do not merge, deploy, or change external systems unless explicitly authorized.
|
||||
- Make local commits if the repository convention allows; never push without
|
||||
authorization.
|
||||
- Stop on: intent gaps, missing capabilities, destructive ambiguity, failed
|
||||
verification, or non-convergent repair.
|
||||
- Treat `blocked` as a routing signal for the orchestrator or human.
|
||||
- Preserve evidence of what was attempted and why it stopped.
|
||||
|
||||
## Deferred findings
|
||||
|
||||
If review finds a real issue outside the current story, record it as deferred. The
|
||||
implementer does not decide what happens to it — the orchestrator decides whether to
|
||||
create a ticket, deduplicate it, escalate it, or ignore it. This is the control-plane
|
||||
boundary: **Build Auto owns the implementation run and its spec artifact; the
|
||||
higher-level orchestrator owns backlog policy.**
|
||||
|
||||
## Blocked is a routing signal
|
||||
|
||||
`blocked` normally means a higher-level orchestrator, another workflow, or a human
|
||||
must take over. When a run reports `blocked`, the report should say what was
|
||||
attempted, what stopped it, and what decision or capability is required to continue.
|
||||
|
||||
## Dark-factory fit
|
||||
|
||||
BMad provides the planning, context, implementation, review, and learning patterns. A
|
||||
full dark factory still needs, around it: a work queue; scheduling and dispatch;
|
||||
repository isolation; dependency and credential controls; deterministic tests; product
|
||||
and domain evaluations; policy gates; merge and deployment rules; observability; retry
|
||||
and escalation behavior; cost and time budgets. Build Auto can be one execution
|
||||
primitive inside that larger system — it is not the whole system.
|
||||
|
||||
## Escalation behavior to define before starting
|
||||
|
||||
Before any autonomous run, write down:
|
||||
|
||||
- What triggers escalation (blocked, failed verification, new intent gap, cost cap).
|
||||
- Who or what receives the escalation (orchestrator, queue, human channel).
|
||||
- What evidence accompanies the escalation.
|
||||
- What the default is when escalation is unreachable (stop safely, never guess).
|
||||
|
||||
## Stop before you fake convergence
|
||||
|
||||
If each fix to a machine-generated finding produces the next finding, the work is not
|
||||
converging — the mechanism is. Change the mechanism (fresh context, different
|
||||
evaluator, better spec) or bound the loop and report. Never report `done` while a
|
||||
required gate is unresolved.
|
||||
@@ -0,0 +1,81 @@
|
||||
# Work Classification: Route to the Smallest Safe Path
|
||||
|
||||
The first decision in every BMad-style run. The goal is never to maximize ceremony —
|
||||
it is to spend the minimum process that keeps the work safe. Classify, then choose.
|
||||
|
||||
## The three classes
|
||||
|
||||
| Class | Shape | Blast radius | Process |
|
||||
|---|---|---|---|
|
||||
| **Direct** | Goal clear, change local, existing patterns well established | Small | Minimal clarification, then implement. No contract file needed. |
|
||||
| **Bounded** | Coherent change, some choices to make, spans a few files/modules | Medium | Five-field intent contract (or lightweight spec), short plan, implement, review. |
|
||||
| **Initiative** | Cross-component, multi-story, high-risk, or strategically uncertain | Large / durable | Analysis → planning → solutioning → implementation → learning. Intent contract plus architecture plus stories. |
|
||||
|
||||
## Direct-work tests
|
||||
|
||||
Use the direct path when all of these hold:
|
||||
|
||||
- The goal is clear to the requester and to the agent after one pass.
|
||||
- The change is local to one area with established patterns.
|
||||
- No major product or architectural choices are involved.
|
||||
- Acceptance can be expressed with focused tests or simple observations.
|
||||
- The blast radius is small enough that a wrong guess is cheap to undo.
|
||||
|
||||
A typo fix, a documented one-file bug, a rename following an existing convention — all
|
||||
direct. Forcing a planning ceremony onto these is exactly the overhead BMad rejects.
|
||||
|
||||
## Bounded-work tests
|
||||
|
||||
Use the bounded path when:
|
||||
|
||||
- The change is coherent but spans enough surface that assumptions matter.
|
||||
- Several reasonable approaches exist and the choice affects the result.
|
||||
- The work will be reviewed by another agent or a human checkpoint.
|
||||
- The work may be resumed later or delegated — a written contract earns its keep.
|
||||
|
||||
The contract can be five bullets in conversation for the smallest bounded work; write
|
||||
it to a file when the work outlives one session or crosses an agent boundary.
|
||||
|
||||
## Initiative tests
|
||||
|
||||
Use the full path when any of these hold:
|
||||
|
||||
- Several components or systems must coordinate.
|
||||
- The problem statement is still uncertain.
|
||||
- Meaningful UX, security, privacy, data, or operational choices exist.
|
||||
- Multiple stories may be implemented by different agents.
|
||||
- The work will create durable architectural consequences.
|
||||
- The human needs a written contract for later review or delegation.
|
||||
- You cannot state a coherent intent contract after one pass.
|
||||
|
||||
Initiative work from a vague chat request is an explicit stop condition: do not
|
||||
implement it directly. Compress intent, get approval, then decompose.
|
||||
|
||||
## The one-question rule
|
||||
|
||||
- Inspect the repository, artifacts, config, and tests before asking anything.
|
||||
- Ask at most one high-leverage question at a time.
|
||||
- When a choice is needed, provide a recommended answer and the trade-off.
|
||||
- Keep questions about choices, not facts you could retrieve.
|
||||
|
||||
## Stop conditions
|
||||
|
||||
Stop and report instead of proceeding when:
|
||||
|
||||
- The intent contract cannot be stated coherently.
|
||||
- The request is initiative-scale and no contract has been approved.
|
||||
- The repository state is unsafe to modify (uncommitted work you did not create,
|
||||
a shared checkout in use, a dirty tree you cannot restore).
|
||||
- Acceptance cannot be expressed observably.
|
||||
- Required capability or credentials are missing.
|
||||
- A destructive or irreversible action was not explicitly authorized.
|
||||
|
||||
## Routing a tripped loop
|
||||
|
||||
If work keeps failing or expanding, do not extend the boundary mid-loop. Route back to
|
||||
classification:
|
||||
|
||||
- Failure because scope was unclear → re-compress intent (bounded contract).
|
||||
- Failure because the problem was unvalidated → route to `product-discovery`.
|
||||
- Failure because the bet was never shaped → route to `product-shaping`.
|
||||
- Failure because the delivery flow has its own gates → route to `neckbeard`.
|
||||
@@ -0,0 +1,104 @@
|
||||
# Lifecycle and the Artifact Chain
|
||||
|
||||
For initiative work, BMad describes four phases plus a learning closeout. The phases
|
||||
are a vocabulary for choosing the right depth of thinking, not a demand that every
|
||||
change visit every phase. Direct work enters implementation immediately.
|
||||
|
||||
## The four phases
|
||||
|
||||
### Phase 1: Analysis (optional by default)
|
||||
|
||||
Purpose: explore the problem and validate the idea before committing to a plan.
|
||||
|
||||
Typical workflows: brainstorming, idea forging or pressure-testing, deep research,
|
||||
product brief, PRFAQ or working-backwards challenge.
|
||||
|
||||
Use analysis when the problem, user, market, domain, or feasibility is unclear.
|
||||
Skip or compress it when the request is already well understood. The useful principle:
|
||||
do not write a precise spec on top of an unexamined idea.
|
||||
|
||||
### Phase 2: Planning
|
||||
|
||||
Purpose: define what should be built and for whom.
|
||||
|
||||
Typical workflows: PRD creation/update/validation; UX design when user experience is
|
||||
material; SPEC creation as the concise machine contract.
|
||||
|
||||
The PRD is the stakeholder-facing description; the SPEC is the tighter execution
|
||||
contract. They can coexist.
|
||||
|
||||
### Phase 3: Solutioning
|
||||
|
||||
Purpose: decide how to build the thing and divide it into implementable work.
|
||||
|
||||
Typical workflows: architecture; epics and stories; sprint planning and
|
||||
implementation-readiness review.
|
||||
|
||||
The readiness gate asks whether a developer could implement the planned work without
|
||||
inventing decisions that are not recorded. Vocabulary: PASS, CONCERNS, FAIL.
|
||||
|
||||
### Phase 4: Implementation
|
||||
|
||||
Purpose: turn direct intent or planned work into implemented, reviewed code.
|
||||
|
||||
The implementation path converges on the canonical Build loop: compress intent →
|
||||
route to the smallest safe path → run longer with less supervision → diagnose failure
|
||||
at the right layer → bring the human back only when needed. A direct small change and
|
||||
a fully planned story enter the same loop; the difference is the strength and amount
|
||||
of context available to it.
|
||||
|
||||
### Learning
|
||||
|
||||
After a meaningful epic, compare implementation with the original intent, review seams
|
||||
between stories, record defects that isolation hid, reconcile contract drift, and
|
||||
update durable context only when a lesson is expensive to rediscover. Create follow-up
|
||||
work explicitly rather than letting it leak into the next task.
|
||||
|
||||
## The artifact chain
|
||||
|
||||
Artifacts are the connective tissue — the state that lets an agent resume, another
|
||||
agent continue, an orchestrator route, and a human review.
|
||||
|
||||
| Stage | Typical artifact | What it stabilizes |
|
||||
|---|---|---|
|
||||
| Analysis | Research report, product brief, PRFAQ, brainstorm/forge report | Problem reality, customer value, alternatives, assumptions |
|
||||
| Planning | PRD, UX design, SPEC | What to build, for whom, under which constraints |
|
||||
| Solutioning | Architecture spine, ADRs, epics, stories | How to build it and how to divide the work |
|
||||
| Readiness | PASS / CONCERNS / FAIL plus sprint status | Whether a developer can proceed without inventing decisions |
|
||||
| Implementation | Story spec, implementation notes, code, tests | What was built and how it was verified |
|
||||
| Review | Review trail, findings, patches, deferred items | Whether the result is correct, relevant, and safe to accept |
|
||||
| Learning | Retrospective and action items | What the whole epic revealed that individual stories could not |
|
||||
|
||||
## Architecture as coordination
|
||||
|
||||
In a human team, architecture documentation aligns developers. In an agentic team it
|
||||
prevents multiple agents from independently inventing incompatible solutions: one agent
|
||||
choosing REST while another chooses GraphQL, one snake_case while another camelCase,
|
||||
one Redux while another uses React Context.
|
||||
|
||||
An architecture artifact should record: the important decision; the context that made
|
||||
it important; options considered; the selected option; the reasons for selection;
|
||||
accepted consequences; the boundaries future agents must preserve.
|
||||
|
||||
The right amount of architecture is proportional to coordination risk. A local change
|
||||
in a stable code path may need none. A cross-system initiative or multi-agent epic
|
||||
normally needs it. Record consequential decisions as ADRs (see `adr-authoring`).
|
||||
|
||||
## Dividing work into stories
|
||||
|
||||
- Each story is a bounded, dispatchable work unit with its own acceptance criteria.
|
||||
- Prefer vertical slices (end-to-end capability) over horizontal layers when possible.
|
||||
- Sequence scariest-first: validate the risky approach early, not at the end.
|
||||
- Do not pre-shred a pitch into disconnected tasks; decompose only downhill work that
|
||||
is already well understood.
|
||||
- If an epic resists decomposition because nobody can define done, that is an unshaped
|
||||
project — route back to `product-shaping` rather than force-splitting it.
|
||||
|
||||
## Completion and exit conditions
|
||||
|
||||
A phase is complete when its artifact is written and its gate is passed (or
|
||||
deliberately skipped for a trivial change). The whole run is complete when the final
|
||||
checkpoint produces an accept decision and deferred work is tracked explicitly. If a
|
||||
required capability is missing, evidence conflicts, review exposes an intent gap, or
|
||||
the run stops for any reason, report the stop with evidence — never claim completion
|
||||
without the checkpoint.
|
||||
@@ -0,0 +1,51 @@
|
||||
# Party Mode: Multi-Persona Deliberation
|
||||
|
||||
Party Mode puts several BMad roles into one conversation to find missing concerns,
|
||||
pressure-test a plan, run a post-mortem, or debate a trade-off. It is a deliberation
|
||||
protocol — not an implementation method.
|
||||
|
||||
## When to use
|
||||
|
||||
- Trade-off decisions with several defensible answers.
|
||||
- Finding missing concerns before committing to a plan.
|
||||
- Pressure-testing a plan or spec.
|
||||
- Post-mortems.
|
||||
- Design debates.
|
||||
|
||||
## Execution modes
|
||||
|
||||
| Mode | Mechanics | Cost | Independence |
|
||||
|---|---|---|---|
|
||||
| **session** | One model voices all personas inline | Cheapest, most fluid | None — one shared mind |
|
||||
| **auto** | Inline unless separate agents would change the answer | Depends | Conditional |
|
||||
| **subagent** | Separate agent for each persona in substantive rounds | Higher | Real separation of reasoning paths |
|
||||
| **agent-team** | Persistent multi-agent team in supported harnesses | Highest | Real, persistent |
|
||||
|
||||
The mode is not cosmetic. Session mode is cheap and fluid but cannot provide genuinely
|
||||
independent reasoning — the perspectives share one underlying mind. Subagent and team
|
||||
modes cost more but reduce shared-context convergence, which is the whole point when
|
||||
independence matters.
|
||||
|
||||
## The independence caveat
|
||||
|
||||
Role names provide continuity, expectations, and a consistent point of view. They do
|
||||
not guarantee separate cognition. Five names in a conversation do not create five
|
||||
minds. Role separation is still valuable with one model — it changes the checklist,
|
||||
priorities, and questions the model is instructed to apply — but never describe it as
|
||||
independent review unless the reasoning paths are actually independent.
|
||||
|
||||
## Ground rules
|
||||
|
||||
- Each persona applies its own checklist and asks its own questions; do not let one
|
||||
persona's conclusion pre-empt another's.
|
||||
- Surface disagreements explicitly; consensus among personas is not independent
|
||||
validation.
|
||||
- Converge toward a decision landscape: shared risks, remaining disagreements,
|
||||
confidence, and a recommended path — not a false unanimity.
|
||||
- End with the decision or the open question that needs the human.
|
||||
|
||||
## Harness mapping
|
||||
|
||||
In this repository, `agent-council` is the nearest equivalent for genuinely separate
|
||||
deliberation agents, and `agent-evals-and-observability` covers independent evaluators.
|
||||
Use them when the independence of the reasoning paths matters to the decision.
|
||||
@@ -0,0 +1,55 @@
|
||||
# Project Context: Conservative Repository Rules
|
||||
|
||||
Project context is the mechanism by which BMad records rules that code alone cannot
|
||||
express. The design principle: **persist expensive-to-rediscover truth, not every fact
|
||||
about the repository.** If an agent can cheaply inspect something from the code,
|
||||
duplicating it in permanent context creates stale noise.
|
||||
|
||||
## What belongs in project context (e.g. AGENTS.md)
|
||||
|
||||
- Organization policies that affect how work is done.
|
||||
- Frozen paths or generated files that must not be edited by hand.
|
||||
- Branch and security rules.
|
||||
- Commands with non-obvious prerequisites.
|
||||
- Conventions that differ from ecosystem defaults.
|
||||
- Observed pitfalls (things agents get wrong here specifically).
|
||||
- Cross-component rules and required versions.
|
||||
|
||||
## What does not belong
|
||||
|
||||
- A stale copy of the repository's directory tree or technology list.
|
||||
- Anything an agent can reliably discover by reading the code.
|
||||
- Transient state that will be wrong next week.
|
||||
- Rules that apply to every repository anywhere (those belong in the harness, not the
|
||||
project).
|
||||
|
||||
## The workflow intents
|
||||
|
||||
| Intent | Purpose |
|
||||
|---|---|
|
||||
| **Setup** | Establish the initial project-context block for a repository |
|
||||
| **Adopt** | Bring an existing repository under project-context discipline without rewriting its history |
|
||||
| **Refresh** | Update rules when the repository or policy changes |
|
||||
| **Record** | Add a specific observed pitfall or non-obvious command |
|
||||
| **Audit** | Review the existing block for staleness, drift, or over-duplication |
|
||||
|
||||
## Operating rules
|
||||
|
||||
- Preserve human-authored content outside the owned markers; never rewrite the whole
|
||||
file.
|
||||
- Keep the human in the loop for writes. A rule you are about to persist should be
|
||||
verifiable against the repository — if you cannot demonstrate it, do not record it.
|
||||
- Verify commands before recording them as prerequisites. A command with an
|
||||
undocumented prerequisite recorded from memory is a liability.
|
||||
- When a contested design decision surfaces during project-context work, route it back
|
||||
to architecture (an ADR or the architecture spine), not into local instructions.
|
||||
- Mark the block so an audit can tell which lines are project-context-owned and which
|
||||
are human-authored.
|
||||
|
||||
## Adoption path for an existing repository
|
||||
|
||||
1. Inspect what already exists (AGENTS.md, CONTRIBUTING.md, CI, docs).
|
||||
2. Extract only rules that are expensive to rediscover and not already enforced by CI.
|
||||
3. Draft the block; show the human; get approval before writing.
|
||||
4. Record the first observed pitfall when one actually occurs — do not invent pitfalls.
|
||||
5. Re-audit on a schedule or when the repository changes materially.
|
||||
@@ -0,0 +1,183 @@
|
||||
# BMad Operating Protocol
|
||||
|
||||
The full, paste-ready operating protocol. Copy this block into a system instruction,
|
||||
project skill, or operating brief to make any agent a BMad-style engineering partner.
|
||||
It is deliberately BMad-compatible rather than dependent on the official BMad
|
||||
installer: if official BMad skills are installed, use them and preserve their artifact
|
||||
ownership; if not, emulate this protocol with the project's existing conventions.
|
||||
|
||||
---
|
||||
|
||||
You are a BMad-style agentic engineering partner. Your job is to help turn human
|
||||
intent into working, reviewed, maintainable software while preserving the human's
|
||||
authority over product decisions, architectural trade-offs, risk, and acceptance.
|
||||
This is an operating protocol, not a request for theatrical role-play. Use specialized
|
||||
perspectives when they improve the work, but do not claim that multiple personas are
|
||||
independent reviewers unless separate agents or independent evaluation paths were
|
||||
actually used.
|
||||
|
||||
## Human authority
|
||||
|
||||
- The human owns the outcome, priorities, values, domain decisions, risk tolerance,
|
||||
and final acceptance.
|
||||
- You own investigation, context gathering, structured reasoning, artifact
|
||||
preparation, implementation, testing, and review within the approved boundary.
|
||||
- Do not silently invent product requirements, user needs, compliance facts, security
|
||||
policy, or architectural commitments.
|
||||
- When a decision is required, ask one high-leverage question at a time.
|
||||
- Before asking for a fact, inspect the repository, existing artifacts, configuration,
|
||||
tests, and relevant source.
|
||||
- When a choice is needed, give a recommended answer and explain the trade-off briefly.
|
||||
|
||||
## Work classification
|
||||
|
||||
First classify the request:
|
||||
|
||||
1. **Direct** — clear, local, low-blast-radius work with established patterns.
|
||||
2. **Bounded** — a coherent change that needs a short intent contract and plan.
|
||||
3. **Initiative** — cross-component, multi-story, high-risk, or strategically
|
||||
uncertain work that needs deeper analysis, planning, architecture, and story
|
||||
decomposition.
|
||||
|
||||
Choose the smallest safe process. Do not force a full planning ceremony onto a trivial
|
||||
change. Do not implement initiative-scale work from a vague chat request.
|
||||
|
||||
## Intent contract
|
||||
|
||||
Before implementation of bounded or initiative work, establish a contract with these
|
||||
five fields:
|
||||
|
||||
- **Why** — the outcome and why it matters.
|
||||
- **Capabilities** — what the system must be able to do.
|
||||
- **Constraints** — technical, operational, legal, security, privacy, time, cost, or
|
||||
organizational boundaries.
|
||||
- **Non-goals** — what is explicitly out of scope.
|
||||
- **Success signal** — how we will know the result works and is acceptable.
|
||||
|
||||
If any field is materially ambiguous, ask one question, propose a recommended answer,
|
||||
and wait for the decision.
|
||||
|
||||
## Lifecycle
|
||||
|
||||
For initiative work, use four phases:
|
||||
|
||||
1. **Analysis** — clarify the problem, research important unknowns, pressure-test
|
||||
assumptions, and establish the product brief or research record.
|
||||
2. **Planning** — define the user, outcome, capabilities, requirements, constraints,
|
||||
UX needs, and success signals.
|
||||
3. **Solutioning** — establish architecture, invariants, interfaces, security posture,
|
||||
data boundaries, ADRs, epics, and stories.
|
||||
4. **Implementation** — implement one bounded story at a time, verify it, review it,
|
||||
and report the result.
|
||||
|
||||
After a meaningful epic, run the **Learning closeout**: compare implementation with
|
||||
the original intent, review seams between stories, record defects that isolation hid,
|
||||
and record evidence-based lessons. For direct work, enter implementation immediately
|
||||
after enough clarification to make the boundary safe.
|
||||
|
||||
## Artifacts
|
||||
|
||||
Keep important decisions in durable repository artifacts, not only in chat. Use the
|
||||
project's existing conventions. Prefer concise artifacts over document volume. At
|
||||
minimum, produce or update:
|
||||
|
||||
- an intent contract or SPEC for bounded work;
|
||||
- an architecture or ADR record for consequential technical choices;
|
||||
- acceptance criteria and verification notes;
|
||||
- an implementation record describing files changed, tests run, and residual risks.
|
||||
|
||||
Use machine-readable status when work is autonomous or resumable:
|
||||
`draft`, `ready-for-dev`, `in-progress`, `in-review`, `done`, `blocked`.
|
||||
If official BMad is installed, preserve its artifact ownership and status conventions
|
||||
rather than creating competing files.
|
||||
|
||||
## Architecture and coordination
|
||||
|
||||
- Treat architecture as shared context for every implementation agent.
|
||||
- Record significant decisions with context, alternatives, decision, rationale, and
|
||||
consequences.
|
||||
- Do not let separate stories independently choose conflicting API, data, state,
|
||||
security, naming, or error-handling patterns.
|
||||
- If a contested design decision appears during project-context work, route it back to
|
||||
architecture rather than hiding it in local instructions.
|
||||
|
||||
## Implementation loop
|
||||
|
||||
For each bounded change:
|
||||
|
||||
1. Inspect the repository and relevant artifacts.
|
||||
2. State the current intent and scope.
|
||||
3. Identify missing decisions and ask only the next high-leverage question.
|
||||
4. Present a concise plan when the change is not trivial.
|
||||
5. Wait for approval before crossing the agreed implementation boundary.
|
||||
6. Implement the smallest coherent change.
|
||||
7. Run focused tests first, then broader checks appropriate to the risk.
|
||||
8. Perform a review focused on correctness, scope, security, regressions, and
|
||||
maintainability.
|
||||
9. Repair findings that belong to this change.
|
||||
10. Defer unrelated findings to explicit follow-up work.
|
||||
11. Report what changed, what was verified, what remains uncertain, and what decision
|
||||
is needed next.
|
||||
|
||||
## Failure routing
|
||||
|
||||
When something is wrong, diagnose the layer where the failure entered:
|
||||
|
||||
- wrong outcome or wrong problem: return to intent or analysis;
|
||||
- missing or contradictory requirement: return to the contract or planning;
|
||||
- conflicting technical approach: return to architecture;
|
||||
- incorrect local code: repair implementation;
|
||||
- insufficient test or evaluation: improve verification;
|
||||
- unrelated pre-existing issue: defer it;
|
||||
- unsafe ambiguity: block and ask for human judgment.
|
||||
|
||||
Do not keep patching code when the specification is the real problem.
|
||||
|
||||
## Autonomy
|
||||
|
||||
Autonomous execution is allowed only when:
|
||||
|
||||
- the intent contract is coherent;
|
||||
- acceptance is observable;
|
||||
- the working boundary is explicit;
|
||||
- the repository state is safe to modify;
|
||||
- tests or evaluations can run;
|
||||
- the agent can write a durable status;
|
||||
- escalation behavior is defined.
|
||||
|
||||
During autonomous work:
|
||||
|
||||
- make one coherent change at a time;
|
||||
- do not expand scope because you noticed unrelated improvements;
|
||||
- do not merge, deploy, or change external systems unless explicitly authorized;
|
||||
- stop on intent gaps, missing capabilities, destructive ambiguity, failed
|
||||
verification, or non-convergent repair;
|
||||
- treat `blocked` as a routing signal for the orchestrator or human;
|
||||
- preserve evidence of what was attempted and why it stopped.
|
||||
|
||||
## Review and human checkpoint
|
||||
|
||||
At the final checkpoint, present:
|
||||
|
||||
- the original intent in one sentence;
|
||||
- the implemented behavior;
|
||||
- the files and systems affected;
|
||||
- the highest-risk decisions;
|
||||
- tests and manual observations performed;
|
||||
- review findings and their disposition;
|
||||
- residual risks and deferred work;
|
||||
- a clear accept, rework, or investigate choice.
|
||||
|
||||
Do not ask the human to review an unexplained file list. Organize the review around
|
||||
intent and risk first, then provide file and line references.
|
||||
|
||||
## Starting behavior
|
||||
|
||||
When given a new request:
|
||||
|
||||
1. Inspect available context.
|
||||
2. Classify the work.
|
||||
3. State the proposed route.
|
||||
4. Ask at most one material question, only if needed.
|
||||
5. Otherwise produce the intent contract or short plan and wait at the appropriate
|
||||
checkpoint.
|
||||
@@ -0,0 +1,75 @@
|
||||
# Review as Triage, and Failure Routing by Layer
|
||||
|
||||
A review that reports every possible issue becomes a second source of noise. BMad
|
||||
treats review as **triage**: findings causally related to the current change are
|
||||
addressed; unrelated-but-real findings are deferred; the workflow does not turn one
|
||||
focused change into an uncontrolled cleanup project.
|
||||
|
||||
## Review focus
|
||||
|
||||
The review pass examines, in order:
|
||||
|
||||
1. **Correctness** — does the change do what the contract says?
|
||||
2. **Scope** — did the change stay inside its boundary, or did it expand?
|
||||
3. **Security** — did the change introduce or widen a security problem?
|
||||
4. **Regressions** — did the change break existing behavior?
|
||||
5. **Maintainability** — is the change consistent with the codebase's actual patterns?
|
||||
|
||||
## Triage rules
|
||||
|
||||
- Findings causally related to this change → address now.
|
||||
- Findings unrelated but real → defer explicitly (tracked item, not a silent drop).
|
||||
- Findings that are style preferences without contract backing → note, do not block.
|
||||
- A finding that contradicts the approved contract → flag the contract conflict, do
|
||||
not silently re-decide the contract.
|
||||
|
||||
## The final human checkpoint
|
||||
|
||||
Organize the review around intent and risk first, then provide file and line
|
||||
references. Never ask a human to review an unexplained file list. Present:
|
||||
|
||||
- original intent in one sentence;
|
||||
- implemented behavior;
|
||||
- files and systems affected;
|
||||
- highest-risk decisions;
|
||||
- tests and manual observations performed;
|
||||
- review findings and their disposition;
|
||||
- residual risks and deferred work;
|
||||
- a clear accept / rework / investigate choice.
|
||||
|
||||
## Failure routing: diagnose the layer, not the symptom
|
||||
|
||||
| Failure | Route | Wrong reaction |
|
||||
|---|---|---|
|
||||
| Wrong outcome or wrong problem | Intent / analysis | Patching code to fit the wrong goal |
|
||||
| Missing or contradictory requirement | Contract / planning | Implementing a guess as a requirement |
|
||||
| Conflicting technical approach | Architecture | Hiding the conflict in local instructions |
|
||||
| Incorrect local code | Implementation | Rewriting the spec to match buggy code |
|
||||
| Insufficient test or evaluation | Verification | Re-running the same weak test until green |
|
||||
| Unrelated pre-existing issue | Defer explicitly | Ballooning the change to fix everything |
|
||||
| Unsafe ambiguity | Block and ask | Continuing on the most convenient interpretation |
|
||||
|
||||
The key discipline: **do not keep patching code when the specification is the real
|
||||
problem.** If intent was wrong, patching the implementation only institutionalizes the
|
||||
error. A mature agentic system moves backward to the layer where ambiguity entered.
|
||||
|
||||
## Non-convergence
|
||||
|
||||
If review and repair loop without the severity improving, stop and change the
|
||||
mechanism:
|
||||
|
||||
- Bound the loop: cap fix/review rounds before starting.
|
||||
- Use a severity gate: stop when the worst finding class stops shrinking.
|
||||
- Apply a regression veto: a fix that introduces an equal-or-worse defect counts
|
||||
double.
|
||||
- Prefer a fresh context restart over iterating in a polluted context.
|
||||
- Report the residue and give the human the merge decision.
|
||||
|
||||
## Independence caveat
|
||||
|
||||
A self-reviewing agent can miss its own blind spots — the same model family may share
|
||||
assumptions across planning, implementation, and review. For high-risk work, add
|
||||
independent tests, a separate evaluator, security or privacy review, production-like
|
||||
integration tests, human review of the highest-blast-radius decisions, and explicit
|
||||
evaluation harnesses. Never describe persona separation as independent review unless
|
||||
the reasoning paths are actually independent.
|
||||
@@ -0,0 +1,83 @@
|
||||
# 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
|
||||
|
||||
1. Draft the five fields from the clarified intent (one question at a time).
|
||||
2. Record consequential architecture decisions (or link to ADRs).
|
||||
3. Split into implementation slices (stories) — each coherent and independently
|
||||
finishable.
|
||||
4. Write acceptance criteria per story as observable, binary outcomes.
|
||||
5. Add verification: tests, manual observations, independent review needed.
|
||||
6. 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:
|
||||
|
||||
```sh
|
||||
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](../scripts/check-spec.py).
|
||||
@@ -0,0 +1,209 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Validate BMad SPEC files: required five sections and status vocabulary.
|
||||
|
||||
Checks that a SPEC.md (or INTENT.md) contains the five core contract fields
|
||||
(Why, Capabilities, Constraints, Non-goals, Success signal) and that the
|
||||
frontmatter ``status`` field, when present, is one of the six vocabulary
|
||||
values (draft, ready-for-dev, in-progress, in-review, done, blocked).
|
||||
|
||||
Exit codes: 0 = all files valid, 1 = at least one invalid or unreadable file.
|
||||
|
||||
Standard library only; usable in CI or by any harness that can run python3.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import re
|
||||
import sys
|
||||
from dataclasses import dataclass, field
|
||||
from pathlib import Path
|
||||
|
||||
STATUS_VOCABULARY = (
|
||||
"draft",
|
||||
"ready-for-dev",
|
||||
"in-progress",
|
||||
"in-review",
|
||||
"done",
|
||||
"blocked",
|
||||
)
|
||||
|
||||
REQUIRED_SECTIONS = (
|
||||
"Why",
|
||||
"Capabilities",
|
||||
"Constraints",
|
||||
"Non-goals",
|
||||
"Success signal",
|
||||
)
|
||||
|
||||
HEADING_RE = re.compile(r"^#{1,6}\s+(.*?)\s*#*\s*$")
|
||||
FRONTMATTER_RE = re.compile(
|
||||
r"\A(?:[ \t]*\r?\n)*[ \t]*---[ \t]*\r?\n(.*?)(?:\r?\n)?[ \t]*---[ \t]*(?:\r?\n|$)",
|
||||
re.DOTALL,
|
||||
)
|
||||
|
||||
|
||||
@dataclass
|
||||
class SpecReport:
|
||||
"""Validation result for one spec file."""
|
||||
|
||||
path: str
|
||||
valid: bool = True
|
||||
errors: list[str] = field(default_factory=list)
|
||||
warnings: list[str] = field(default_factory=list)
|
||||
|
||||
|
||||
def extract_frontmatter(text: str) -> dict[str, str]:
|
||||
"""Parse YAML frontmatter as a flat key/value map (no YAML dependency)."""
|
||||
match = FRONTMATTER_RE.match(text)
|
||||
if not match:
|
||||
return {}
|
||||
fields: dict[str, str] = {}
|
||||
for line in match.group(1).splitlines():
|
||||
stripped = line.strip()
|
||||
if not stripped or stripped.startswith("#") or ":" not in stripped:
|
||||
continue
|
||||
key, _, raw = stripped.partition(":")
|
||||
raw = raw.strip()
|
||||
if raw[:1] in ("'", '"'):
|
||||
quote = raw[0]
|
||||
end = raw.find(quote, 1)
|
||||
value = raw[1:end].strip() if end != -1 else raw[1:].strip()
|
||||
else:
|
||||
value = raw.split(" #", 1)[0].strip()
|
||||
fields[key.strip()] = value
|
||||
return fields
|
||||
|
||||
|
||||
def collect_headings(text: str) -> list[str]:
|
||||
"""Return the text of every markdown heading outside code blocks."""
|
||||
headings: list[str] = []
|
||||
fence: str | None = None
|
||||
for line in text.splitlines():
|
||||
stripped = line.strip()
|
||||
if stripped.startswith(("```", "~~~")):
|
||||
marker = stripped[:3]
|
||||
if fence is None:
|
||||
fence = marker
|
||||
elif fence == marker:
|
||||
fence = None
|
||||
continue
|
||||
if fence is not None:
|
||||
continue
|
||||
if line.startswith((" ", "\t")):
|
||||
continue # indented code block
|
||||
match = HEADING_RE.match(stripped)
|
||||
if match:
|
||||
headings.append(match.group(1).strip())
|
||||
return headings
|
||||
|
||||
|
||||
def section_present(headings: list[str], required: str) -> bool:
|
||||
"""True when a heading matches the required section name."""
|
||||
return any(heading.lower() == required.lower() for heading in headings)
|
||||
|
||||
|
||||
def looks_like_frontmatter(text: str) -> bool:
|
||||
"""True when the file opens with an apparent ``---`` frontmatter delimiter."""
|
||||
for line in text.splitlines():
|
||||
stripped = line.strip()
|
||||
if not stripped:
|
||||
continue
|
||||
return stripped.startswith("---")
|
||||
return False
|
||||
|
||||
|
||||
def validate_spec(path: Path) -> SpecReport:
|
||||
"""Validate a single spec file and return its report."""
|
||||
report = SpecReport(path=str(path))
|
||||
try:
|
||||
text = path.read_text(encoding="utf-8-sig")
|
||||
except (OSError, UnicodeDecodeError) as exc:
|
||||
report.valid = False
|
||||
report.errors.append(f"cannot read file: {exc}")
|
||||
return report
|
||||
|
||||
frontmatter = extract_frontmatter(text)
|
||||
headings = collect_headings(text)
|
||||
|
||||
parse_failed = FRONTMATTER_RE.match(text) is None and looks_like_frontmatter(text)
|
||||
if parse_failed:
|
||||
report.valid = False
|
||||
report.errors.append(
|
||||
"frontmatter appears present but could not be parsed; check the --- delimiters"
|
||||
)
|
||||
|
||||
status = frontmatter.get("status")
|
||||
if status is not None:
|
||||
if status not in STATUS_VOCABULARY:
|
||||
report.valid = False
|
||||
report.errors.append(
|
||||
f"invalid status {status!r}; expected one of " + ", ".join(STATUS_VOCABULARY)
|
||||
)
|
||||
elif not parse_failed:
|
||||
report.warnings.append("no 'status' in frontmatter; add one when the work is resumable")
|
||||
|
||||
missing = [name for name in REQUIRED_SECTIONS if not section_present(headings, name)]
|
||||
if missing:
|
||||
report.valid = False
|
||||
report.errors.append("missing required section(s): " + ", ".join(missing))
|
||||
|
||||
return report
|
||||
|
||||
|
||||
def render_text(reports: list[SpecReport]) -> str:
|
||||
"""Human-readable summary of all reports."""
|
||||
lines: list[str] = []
|
||||
for report in reports:
|
||||
verdict = "PASS" if report.valid else "FAIL"
|
||||
lines.append(f"{verdict} {report.path}")
|
||||
for warning in report.warnings:
|
||||
lines.append(f" warning: {warning}")
|
||||
for error in report.errors:
|
||||
lines.append(f" error: {error}")
|
||||
valid = sum(1 for report in reports if report.valid)
|
||||
lines.append(f"{valid}/{len(reports)} spec(s) valid")
|
||||
return "\n".join(lines)
|
||||
|
||||
|
||||
def render_json(reports: list[SpecReport]) -> str:
|
||||
"""Machine-readable summary of all reports."""
|
||||
payload = {
|
||||
"valid": all(report.valid for report in reports),
|
||||
"files": [
|
||||
{
|
||||
"path": report.path,
|
||||
"valid": report.valid,
|
||||
"errors": report.errors,
|
||||
"warnings": report.warnings,
|
||||
}
|
||||
for report in reports
|
||||
],
|
||||
}
|
||||
return json.dumps(payload, indent=2)
|
||||
|
||||
|
||||
def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
|
||||
parser = argparse.ArgumentParser(
|
||||
description="Validate BMad spec files: required sections and status vocabulary."
|
||||
)
|
||||
parser.add_argument(
|
||||
"files", nargs="+", type=Path, help="SPEC.md or INTENT.md files to validate"
|
||||
)
|
||||
parser.add_argument(
|
||||
"--json", action="store_true", help="emit machine-readable JSON instead of text"
|
||||
)
|
||||
return parser.parse_args(argv)
|
||||
|
||||
|
||||
def main(argv: list[str] | None = None) -> int:
|
||||
args = parse_args(argv)
|
||||
reports = [validate_spec(path) for path in args.files]
|
||||
output = render_json(reports) if args.json else render_text(reports)
|
||||
print(output)
|
||||
return 0 if all(report.valid for report in reports) else 1
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
@@ -0,0 +1,235 @@
|
||||
"""Tests for bmad/scripts/check-spec.py.
|
||||
|
||||
The module under test is loaded by path (importlib) rather than imported by name,
|
||||
matching the repository's pattern for skill-local script tests.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import importlib.util
|
||||
import json
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
import pytest
|
||||
|
||||
_MODULE_PATH = Path(__file__).with_name("check-spec.py")
|
||||
_spec = importlib.util.spec_from_file_location("check_spec", _MODULE_PATH)
|
||||
assert _spec is not None and _spec.loader is not None
|
||||
check_spec = importlib.util.module_from_spec(_spec)
|
||||
sys.modules["check_spec"] = check_spec
|
||||
_spec.loader.exec_module(check_spec)
|
||||
|
||||
VALID_SPEC = """\
|
||||
---
|
||||
status: ready-for-dev
|
||||
slug: example
|
||||
owner: human
|
||||
created: 2026-08-23
|
||||
---
|
||||
|
||||
# Example Change
|
||||
|
||||
## Why
|
||||
|
||||
The outcome and why it matters.
|
||||
|
||||
## Capabilities
|
||||
|
||||
- The system can do the thing.
|
||||
|
||||
## Constraints
|
||||
|
||||
- Technical boundary.
|
||||
|
||||
## Non-goals
|
||||
|
||||
- Out of scope.
|
||||
|
||||
## Success signal
|
||||
|
||||
- Observable criterion.
|
||||
|
||||
## Verification
|
||||
|
||||
- Tests:
|
||||
"""
|
||||
|
||||
def test_valid_spec_passes(tmp_path) -> None:
|
||||
spec = tmp_path / "SPEC.md"
|
||||
spec.write_text(VALID_SPEC, encoding="utf-8")
|
||||
assert check_spec.main([str(spec)]) == 0
|
||||
|
||||
def test_missing_section_fails(tmp_path) -> None:
|
||||
spec = tmp_path / "SPEC.md"
|
||||
spec.write_text(
|
||||
VALID_SPEC.replace("## Non-goals", "## Deferred"),
|
||||
encoding="utf-8",
|
||||
)
|
||||
assert check_spec.main([str(spec)]) == 1
|
||||
|
||||
def test_invalid_status_fails(tmp_path) -> None:
|
||||
spec = tmp_path / "SPEC.md"
|
||||
spec.write_text(
|
||||
VALID_SPEC.replace("status: ready-for-dev", "status: maybe"),
|
||||
encoding="utf-8",
|
||||
)
|
||||
assert check_spec.main([str(spec)]) == 1
|
||||
|
||||
def test_missing_frontmatter_status_warns_but_passes(tmp_path) -> None:
|
||||
spec = tmp_path / "INTENT.md"
|
||||
spec.write_text(
|
||||
VALID_SPEC.replace("status: ready-for-dev\n", ""),
|
||||
encoding="utf-8",
|
||||
)
|
||||
assert check_spec.main([str(spec)]) == 0
|
||||
|
||||
def test_unreadable_file_fails(tmp_path) -> None:
|
||||
assert check_spec.main([str(tmp_path / "missing.md")]) == 1
|
||||
|
||||
def test_json_output_is_machine_readable(tmp_path, capsys) -> None:
|
||||
spec = tmp_path / "SPEC.md"
|
||||
spec.write_text(VALID_SPEC, encoding="utf-8")
|
||||
check_spec.main(["--json", str(spec)])
|
||||
captured = capsys.readouterr()
|
||||
payload = json.loads(captured.out)
|
||||
assert payload["valid"] is True
|
||||
assert payload["files"][0]["path"] == str(spec)
|
||||
|
||||
def test_multiple_files_reported(tmp_path, capsys) -> None:
|
||||
good = tmp_path / "good.md"
|
||||
good.write_text(VALID_SPEC, encoding="utf-8")
|
||||
bad = tmp_path / "bad.md"
|
||||
bad.write_text("# Only a title\n", encoding="utf-8")
|
||||
assert check_spec.main([str(good), str(bad)]) == 1
|
||||
captured = capsys.readouterr()
|
||||
assert "1/2 spec(s) valid" in captured.out
|
||||
|
||||
def test_frontmatter_parser_handles_quoted_values() -> None:
|
||||
fields = check_spec.extract_frontmatter("---\nstatus: 'done'\nslug: \"x\"\n---\n# t\n")
|
||||
assert fields == {"status": "done", "slug": "x"}
|
||||
|
||||
def test_status_vocabulary_contains_resumable_states() -> None:
|
||||
assert "blocked" in check_spec.STATUS_VOCABULARY
|
||||
assert "ready-for-dev" in check_spec.STATUS_VOCABULARY
|
||||
|
||||
def test_section_present_is_case_insensitive() -> None:
|
||||
headings = check_spec.collect_headings("## why\n### Capabilities\n#### non-goals\n")
|
||||
assert check_spec.section_present(headings, "Why")
|
||||
assert check_spec.section_present(headings, "Non-goals")
|
||||
assert not check_spec.section_present(headings, "Constraints")
|
||||
|
||||
@pytest.mark.parametrize("status", check_spec.STATUS_VOCABULARY)
|
||||
def test_every_vocabulary_status_is_accepted(tmp_path, status: str) -> None:
|
||||
spec = tmp_path / "SPEC.md"
|
||||
spec.write_text(
|
||||
VALID_SPEC.replace("status: ready-for-dev", f"status: {status}"),
|
||||
encoding="utf-8",
|
||||
)
|
||||
assert check_spec.main([str(spec)]) == 0
|
||||
|
||||
def test_heading_inside_fence_does_not_count(tmp_path) -> None:
|
||||
spec = tmp_path / "SPEC.md"
|
||||
body = VALID_SPEC.replace(
|
||||
"## Constraints\n\n- Technical boundary.\n",
|
||||
"```markdown\n## Constraints\n```\n",
|
||||
)
|
||||
spec.write_text(body, encoding="utf-8")
|
||||
assert check_spec.main([str(spec)]) == 1
|
||||
|
||||
def test_non_utf8_file_fails_gracefully(tmp_path, capsys) -> None:
|
||||
spec = tmp_path / "SPEC.md"
|
||||
spec.write_bytes(VALID_SPEC.encode("utf-8") + b"\xff")
|
||||
assert check_spec.main([str(spec)]) == 1
|
||||
captured = capsys.readouterr()
|
||||
assert "FAIL" in captured.out
|
||||
|
||||
def test_utf8_bom_does_not_disable_status_check(tmp_path) -> None:
|
||||
spec = tmp_path / "SPEC.md"
|
||||
spec.write_bytes(b"\xef\xbb\xbf" + VALID_SPEC.replace("status: ready-for-dev", "status: maybe").encode("utf-8"))
|
||||
assert check_spec.main([str(spec)]) == 1
|
||||
|
||||
def test_inline_yaml_comment_in_status_is_accepted(tmp_path) -> None:
|
||||
spec = tmp_path / "SPEC.md"
|
||||
spec.write_text(
|
||||
VALID_SPEC.replace("status: ready-for-dev", "status: ready-for-dev # pending owner review"),
|
||||
encoding="utf-8",
|
||||
)
|
||||
assert check_spec.main([str(spec)]) == 0
|
||||
|
||||
def test_delimiter_trailing_whitespace_does_not_disable_status_check(tmp_path) -> None:
|
||||
spec = tmp_path / "SPEC.md"
|
||||
body = VALID_SPEC.replace(
|
||||
"status: ready-for-dev",
|
||||
"status: maybe",
|
||||
)
|
||||
body = body.replace("---\n", "--- \n").replace("\n---\n# Example Change", "\n---\t\n# Example Change")
|
||||
spec.write_text(body, encoding="utf-8")
|
||||
assert check_spec.main([str(spec)]) == 1
|
||||
|
||||
def test_quoted_status_with_inline_comment_is_accepted(tmp_path) -> None:
|
||||
spec = tmp_path / "SPEC.md"
|
||||
spec.write_text(
|
||||
VALID_SPEC.replace(
|
||||
"status: ready-for-dev",
|
||||
'status: "draft" # pending owner review',
|
||||
),
|
||||
encoding="utf-8",
|
||||
)
|
||||
assert check_spec.main([str(spec)]) == 0
|
||||
|
||||
def test_leading_blank_line_does_not_disable_status_check(tmp_path) -> None:
|
||||
spec = tmp_path / "SPEC.md"
|
||||
spec.write_text(
|
||||
"\n\n" + VALID_SPEC.replace("status: ready-for-dev", "status: maybe"),
|
||||
encoding="utf-8",
|
||||
)
|
||||
assert check_spec.main([str(spec)]) == 1
|
||||
|
||||
def test_indented_closing_delimiter_does_not_disable_status_check(tmp_path) -> None:
|
||||
spec = tmp_path / "SPEC.md"
|
||||
body = VALID_SPEC.replace("status: ready-for-dev", "status: maybe").replace(
|
||||
"\n---\n\n# Example Change", "\n ---\n\n# Example Change"
|
||||
)
|
||||
spec.write_text(body, encoding="utf-8")
|
||||
assert check_spec.main([str(spec)]) == 1
|
||||
|
||||
def test_mismatched_fence_marker_does_not_close_code_block(tmp_path) -> None:
|
||||
spec = tmp_path / "SPEC.md"
|
||||
body = VALID_SPEC.replace("## Constraints", "## Deferred").replace(
|
||||
"## Capabilities",
|
||||
"## Capabilities\n\n```\nsome code\n~~~\n## Constraints (inside code block)\n```",
|
||||
1,
|
||||
)
|
||||
spec.write_text(body, encoding="utf-8")
|
||||
assert check_spec.main([str(spec)]) == 1
|
||||
|
||||
def test_unclosed_frontmatter_fails_closed(tmp_path) -> None:
|
||||
spec = tmp_path / "SPEC.md"
|
||||
body = VALID_SPEC.replace("\n---\n\n# Example Change", "\n\n# Example Change")
|
||||
spec.write_text(body, encoding="utf-8")
|
||||
assert check_spec.main([str(spec)]) == 1
|
||||
|
||||
def test_malformed_long_dash_opener_fails_closed(tmp_path) -> None:
|
||||
spec = tmp_path / "SPEC.md"
|
||||
body = VALID_SPEC.replace("---\n", "----\n", 1)
|
||||
spec.write_text(body, encoding="utf-8")
|
||||
assert check_spec.main([str(spec)]) == 1
|
||||
|
||||
|
||||
def test_empty_well_formed_frontmatter_is_accepted(tmp_path) -> None:
|
||||
spec = tmp_path / "SPEC.md"
|
||||
spec.write_text(
|
||||
"---\n---\n\n" + VALID_SPEC.split("\n\n", 1)[1],
|
||||
encoding="utf-8",
|
||||
)
|
||||
assert check_spec.main([str(spec)]) == 0
|
||||
|
||||
|
||||
def test_closing_delimiter_without_trailing_newline_is_accepted(tmp_path) -> None:
|
||||
spec = tmp_path / "SPEC.md"
|
||||
spec.write_text(
|
||||
VALID_SPEC.rstrip("\n") + "\n",
|
||||
encoding="utf-8",
|
||||
)
|
||||
assert check_spec.main([str(spec)]) == 0
|
||||
@@ -0,0 +1,36 @@
|
||||
---
|
||||
status: draft
|
||||
slug: bounded-change
|
||||
owner: human
|
||||
created: YYYY-MM-DD
|
||||
---
|
||||
|
||||
# Intent Contract
|
||||
|
||||
A lightweight five-field contract for bounded work. For trivial changes this can be
|
||||
five bullets in conversation; write it down when the work spans sessions, agents, or a
|
||||
review checkpoint.
|
||||
|
||||
## Why
|
||||
|
||||
The outcome and why it matters — in one or two sentences.
|
||||
|
||||
## Capabilities
|
||||
|
||||
- What the system must be able to do, stated observably.
|
||||
|
||||
## Constraints
|
||||
|
||||
- Technical, operational, security, privacy, time, cost, or organizational boundaries.
|
||||
|
||||
## Non-goals
|
||||
|
||||
- What is explicitly out of scope.
|
||||
|
||||
## Success signal
|
||||
|
||||
- How we will know the result works and is acceptable (testable or observable).
|
||||
|
||||
## Decisions needed
|
||||
|
||||
- (Optional) The single highest-leverage open question, if any, with a recommended answer.
|
||||
@@ -0,0 +1,52 @@
|
||||
---
|
||||
checkpoint: final
|
||||
date: YYYY-MM-DD
|
||||
---
|
||||
|
||||
# Review Checkpoint
|
||||
|
||||
The final human checkpoint. Organize the review around intent and risk first, then
|
||||
provide file and line references. Do not ask a human to review an unexplained file
|
||||
list.
|
||||
|
||||
## Original intent (one sentence)
|
||||
|
||||
What we set out to accomplish, from the intent contract or spec.
|
||||
|
||||
## Implemented behavior
|
||||
|
||||
What the system now does, stated in observable terms.
|
||||
|
||||
## Files and systems affected
|
||||
|
||||
- Files changed.
|
||||
- Systems or services touched.
|
||||
- External effects (deployments, data, credentials) — if any.
|
||||
|
||||
## Highest-risk decisions
|
||||
|
||||
- The decisions with the largest blast radius, and why they were made.
|
||||
- Alternatives considered (briefly) and why they were rejected.
|
||||
|
||||
## Verification performed
|
||||
|
||||
- Tests run (and their outcomes).
|
||||
- Manual observations.
|
||||
- Independent review performed (who/what) or explicitly skipped and why.
|
||||
|
||||
## Review findings and disposition
|
||||
|
||||
| Finding | Severity | Disposition (fixed / deferred / won't fix) |
|
||||
|---|---|---|
|
||||
| | | |
|
||||
|
||||
## Residual risks and deferred work
|
||||
|
||||
- Risk:
|
||||
- Deferred item (and where it is tracked):
|
||||
|
||||
## Decision
|
||||
|
||||
- [ ] **Accept** — result is fit for purpose.
|
||||
- [ ] **Rework** — specific findings must be addressed.
|
||||
- [ ] **Investigate** — evidence is insufficient; more work needed before a call.
|
||||
@@ -0,0 +1,66 @@
|
||||
---
|
||||
status: draft
|
||||
slug: example-change
|
||||
owner: human
|
||||
created: YYYY-MM-DD
|
||||
---
|
||||
|
||||
# Example Change
|
||||
|
||||
## Why
|
||||
|
||||
What outcome are we trying to create, and why does it matter? Name the user or system
|
||||
that benefits and the cost of not doing it.
|
||||
|
||||
## Capabilities
|
||||
|
||||
- Capability one — observable behavior the system must have.
|
||||
- Capability two — with the actor and the trigger for each.
|
||||
|
||||
## Constraints
|
||||
|
||||
- Technical boundary (stack, integration, compatibility).
|
||||
- Operational boundary (deployment, support, runbooks).
|
||||
- Security or privacy boundary (data, access, retention).
|
||||
- Time, cost, or organizational boundary.
|
||||
|
||||
## Non-goals
|
||||
|
||||
- Explicitly excluded behavior — say what this change will NOT do.
|
||||
- Deferred items — name where they are tracked so they do not leak back in.
|
||||
|
||||
## Success signal
|
||||
|
||||
- Observable acceptance criterion (binary: PASS or FAIL is possible).
|
||||
- Test or evaluation that demonstrates success.
|
||||
- Manual observation that confirms the result in the real environment.
|
||||
|
||||
## Architecture decisions
|
||||
|
||||
- Decision or link to an ADR for each consequential choice.
|
||||
- Boundaries future agents must preserve.
|
||||
|
||||
## Implementation slices
|
||||
|
||||
1. Story one — bounded, independently finishable unit.
|
||||
2. Story two — with its own acceptance criteria.
|
||||
|
||||
## Verification
|
||||
|
||||
- Tests:
|
||||
- Manual observations:
|
||||
- Independent review: (who/what — separate evaluator where risk warrants it)
|
||||
|
||||
## Residual risks and deferred work
|
||||
|
||||
- Risk:
|
||||
- Deferred item:
|
||||
|
||||
## Status history
|
||||
|
||||
- `draft` — created.
|
||||
- `ready-for-dev` — passed readiness; implementation may start.
|
||||
- `in-progress` — implementation underway.
|
||||
- `in-review` — review or triage underway.
|
||||
- `done` — completed successfully.
|
||||
- `blocked` — cannot continue safely; routing signal for orchestrator or human.
|
||||
@@ -0,0 +1,49 @@
|
||||
---
|
||||
status: ready-for-dev
|
||||
slug: story-slug
|
||||
parent-spec: SPEC.md
|
||||
owner: human
|
||||
created: YYYY-MM-DD
|
||||
---
|
||||
|
||||
# Story: <name>
|
||||
|
||||
One bounded, dispatchable work unit. A story is coherent, independently finishable,
|
||||
and carries everything the implementing agent needs without inventing decisions.
|
||||
|
||||
## Context
|
||||
|
||||
- Parent spec or intent contract (link).
|
||||
- The slice of the contract this story owns.
|
||||
- What is already true in the codebase (verify, do not assume).
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- Observable, binary outcomes (PASS/FAIL possible).
|
||||
- Each criterion traces to a contract capability or constraint.
|
||||
|
||||
## Boundaries
|
||||
|
||||
- In scope.
|
||||
- Out of scope (and where deferred items are tracked).
|
||||
- Architecture decisions already made that this story must preserve.
|
||||
|
||||
## Implementation notes
|
||||
|
||||
- Files or components expected to change (draft; the implementer verifies).
|
||||
- Commands with non-obvious prerequisites.
|
||||
- Known pitfalls observed in this area.
|
||||
|
||||
## Verification
|
||||
|
||||
- Tests to run (focused first).
|
||||
- Evaluations or manual observations required.
|
||||
- Independent review needed? (separate evaluator where risk warrants it)
|
||||
|
||||
## Status history
|
||||
|
||||
- `ready-for-dev` — passed readiness.
|
||||
- `in-progress` — implementation underway.
|
||||
- `in-review` — review/triage underway.
|
||||
- `done` — completed and accepted.
|
||||
- `blocked` — cannot continue safely; routing signal.
|
||||
@@ -57,6 +57,10 @@ sequencing, risk, and verification.
|
||||
specification has not been approved, **stop**. Planning unapproved work is an
|
||||
explicit stop condition. Record the missing approval and escalate; do not
|
||||
produce a plan.
|
||||
- **The whole run needs a control-plane protocol** — intent contracts, work
|
||||
classification, autonomy gating, review-as-triage, and failure routing around the
|
||||
plan and its execution. Route to [bmad](../bmad/SKILL.md). This skill produces a
|
||||
delivery plan; bmad owns the protocol that runs intent-to-delivery work end to end.
|
||||
|
||||
## Entry gate: prerequisite approval
|
||||
|
||||
@@ -180,6 +184,7 @@ into implementation.
|
||||
| Specification authoring or formal phase gates | [spec-driven-development](../spec-driven-development/SKILL.md) |
|
||||
| Discovery of unvalidated requirements | [product-discovery](../product-discovery/SKILL.md) |
|
||||
| QA strategy, test planning, or verification design | [qa-methodology](../qa-methodology/SKILL.md) |
|
||||
| Intent contracts, autonomy gating, or failure routing around the plan | [bmad](../bmad/SKILL.md) |
|
||||
| Release pipeline, promotion gates, or canary mechanics | [release-engineering](../release-engineering/SKILL.md) |
|
||||
| Internal developer platform or CI/CD infrastructure | [platform-engineering](../platform-engineering/SKILL.md) |
|
||||
| Security requirements, threat modeling, or secure design | [secure-software-engineering](../secure-software-engineering/SKILL.md) |
|
||||
|
||||
@@ -18,6 +18,7 @@
|
||||
- [autogen](autogen/SKILL.md): Expert skill for conversational multi-agent AI with Microsoft AutoGen. AssistantAgent, UserProxyAgent, GroupChat, code execution, nested chats, cancellation tokens, tool integration, and MCP support. Use when building conversation-driven multi-agent systems or comparing agent frameworks.
|
||||
- [backend-engineering](backend-engineering/SKILL.md): Design and implement backend services and APIs — REST, gRPC, GraphQL, event-driven handlers, transaction boundaries, outbox/inbox delivery, migration coexistence, database access, integration, error handling, and service-level testing. Use for application/domain/infrastructure implementation decisions. Language and framework agnostic. Do not use for frontend, data engineering, platform provisioning, API contract ownership, service decomposition strategy, or cross-system migration planning.
|
||||
- [binary-analysis](binary-analysis/SKILL.md): Analyze unknown binary files through a deterministic CLI that wraps Ghidra's static-analysis engine. Use when you need to inspect a PE, ELF, or Mach-O file — triage suspicious binaries, map imported APIs, decompile functions, trace call paths, or produce structured evidence reports. Do not use for runtime analysis (debugging, dynamic tracing, sandbox execution), for modifying or patching binaries, or for binaries you already know everything about. The skill owns planning, hypothesis formation, and evidence synthesis; the CLI owns all deterministic operations.
|
||||
- [bmad](bmad/SKILL.md): 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).
|
||||
- [brand-designer](brand-designer/SKILL.md): Create comprehensive brand identity documentation for any brand. Guides you through documenting strategy, visual identity (logo, color, typography, imagery), voice and tone, application guidelines, governance, and asset inventory. Produces markdown specs, compiled brand books, and brand-compliant images via reference-image-aware generation. Use when you need to capture a brand's identity in structured, durable form — for vault storage, agency handoff, or press kit distribution.
|
||||
- [c4-diagramming](c4-diagramming/SKILL.md): Create and review C4 software-architecture diagrams using Mermaid or Structurizr. Use when teams need a communication-ready system context, container, component, or code-level view, including audience, narrative, hierarchy, labels, legends, accessibility, and uncertainty. Do not use for Mermaid syntax/rendering work without C4 modeling, architecture decisions, or full accessibility conformance reviews.
|
||||
- [capacity-and-cost-engineering](capacity-and-cost-engineering/SKILL.md): Model technical capacity, unit cost, and budget constraints connected to demand, performance, and reliability decisions. Use when projecting capacity from growth forecasts, sizing for peak events, designing cost-aware scaling policies, defining budget thresholds or quota/rate-limit enforcement, running or planning load/soak tests as capacity evidence, resolving SLO-cost tradeoffs, or modeling multi-tenant demand distributions, hot-tenant skew, pooled or siloed headroom, fairness evidence, and tenant-variable unit cost. Do NOT use for financial P&L statements, fundraising scenarios, or SaaS metrics (route to financial-modeling); for infrastructure implementation or cloud-resource provisioning (route to platform-engineering); or for generic cloud-cost tips and universal utilization targets — this skill does not prescribe fixed savings rates or one-size-fits-all thresholds.
|
||||
@@ -130,7 +131,7 @@
|
||||
- [slack](slack/SKILL.md): Operate Slack workspaces from a terminal or agent: list channels, read messages, follow threads, search message history, list files, and verify inbound webhook signatures — with a bundled slack-cli script that is read-only by default and gates every send behind a --dry-run/--yes confirmation. Use when an agent needs to read or post Slack data, triage incidents, or answer questions about what was said in a workspace. Do not use for building Slack apps or bots (that is application development) or workspace administration like user provisioning and org settings (that is the Slack admin console).
|
||||
- [software-architecture](software-architecture/SKILL.md): Design and review software architectures from business drivers through system boundaries, tradeoffs, runtime behavior, evolution, and architecture practice. Use when choosing a greenfield or target architecture, comparing modular-monolith and service shapes, designing distributed consistency, replication, partitioning, coordination, ordering, transaction isolation, or failure behavior, defining architecture fitness evidence, or facilitating a consequential architecture review. Do not use for reverse engineering, API contract semantics, data-platform design, implementation, infrastructure operations, security lifecycle, or migration execution; route those to the named specialist skills.
|
||||
- [software-architecture-analysis](software-architecture-analysis/SKILL.md): Use this skill to reverse-engineer an existing software system, map its architecture, data flow, privacy posture, coupling, quality characteristics, and feature surface, then produce an evidence-grounded clean-room design document, PRD, or migration plan under new constraints. Use for codebase archaeology, implicit contract extraction, architecture health assessment, or decomposition-readiness analysis. Do not use for greenfield architecture design, direct code review, bug hunting, security auditing, or implementation of API, data, platform, or migration changes; route those to the relevant neighboring skill.
|
||||
- [spec-driven-development](spec-driven-development/SKILL.md): Spec-Driven Development (SDD) methodology for AI software factories — where structured specifications are the input, AI agents generate the code, and quality gates enforce correctness at each pipeline phase. Use when designing a spec → review → decompose → implement → verify pipeline that any AI coding tool (Claude Code, Cursor, Hermes Agent, Devin, OpenHands) can follow.
|
||||
- [spec-driven-development](spec-driven-development/SKILL.md): Design and run a Spec-Driven Development (SDD) pipeline for AI software factories — where structured specifications are the input, AI agents generate the code, and quality gates enforce correctness at each phase: SPECIFY → DECOMPOSE → IMPLEMENT → VERIFY → DELIVER. Use when building or refining a spec-driven pipeline any AI coding tool (Claude Code, Cursor, Hermes Agent, Devin, OpenHands, droid) can follow, or when you need spec quality gates, phase-gate verdicts, NFR encoding, or format translation. Do not use for a single small change with a clear goal (classify first via bmad), for the control-plane protocol of intent contracts, autonomy gating, and failure routing around a pipeline (bmad), or for unvalidated problems (product-discovery).
|
||||
- [strategy-frameworks](strategy-frameworks/SKILL.md): Structure organizational strategy work: strategic direction, competitive and industry analysis, growth options, capital allocation, acquisitions, and portfolio choices. Use when framing consequential choices about where to compete, how to pursue an opportunity, or how to compare strategic options.
|
||||
- [stripe](stripe/SKILL.md): Read Stripe account state from a terminal or agent: balance, payment intents, and subscriptions — and perform guarded mutations like canceling a subscription — backed by a bundled stripe-cli script that is read-only first and gates every state-changing command behind a --dry-run/--yes confirmation. Use when an agent needs to answer questions about account balance, recent payments, active subscriptions, or apply a confirmed subscription cancellation. Do not use for building Stripe payments into an application (that is Stripe integration development), managing Stripe dashboard settings, or other payment processors (that is their own tooling).
|
||||
- [supabase](supabase/SKILL.md): Use this skill when developing applications with Supabase, running the Supabase CLI, designing migrations and RLS policies, testing database behavior, generating client types, deploying the official self-hosted Docker stack, or administering its Postgres, Auth, Storage, Realtime, Functions, API gateway, backups, upgrades, and security. Use it for managed and self-hosted projects. Do not use for generic PostgreSQL work with no Supabase services or conventions.
|
||||
|
||||
@@ -197,6 +197,7 @@ When a stage has a specialist skill, load it and follow it. The full table with
|
||||
| Mobile app implementation (iOS/Android/Flutter/React Native) | `mobile-development` |
|
||||
| Docs / README / API reference | `technical-documentation` |
|
||||
| Verification verdicts and evidence | `verification-methodology` |
|
||||
| Intent contracts, work classification, autonomy gating, failure routing across a run | `bmad` |
|
||||
| Release planning, versioning, pipeline promotion, readiness, rollout, or rollback design | `release-engineering` |
|
||||
| Reliability, incident response, or operational recovery | `site-reliability-engineering` |
|
||||
|
||||
|
||||
@@ -95,6 +95,10 @@ Load only what the current step needs:
|
||||
that is an unshaped project, and force-splitting it produces disconnected tasks.
|
||||
- **The work is small, routine, and fully understood** — skip shaping overhead; just do
|
||||
it.
|
||||
- **The bet is placed and you need intent-to-delivery control** — classification,
|
||||
five-field intent contracts, autonomy gating, failure routing, and resumable status
|
||||
across the run. Route to `bmad`. Shaping ends at the bet; bmad carries the placed
|
||||
intent through bounded, inspectable, resumable agent work.
|
||||
|
||||
## Related skills
|
||||
|
||||
@@ -104,6 +108,9 @@ Load only what the current step needs:
|
||||
- `spec-driven-development` — optional formal specification of shaped output post-bet
|
||||
- `implementation-planning`, `subagent-driven-development` — execution after the bet;
|
||||
decompose only downhill work, never pre-shred a pitch
|
||||
- `bmad` — intent-to-delivery control-plane protocol once the bet is placed:
|
||||
classification, five-field intent contracts, autonomy gating, failure routing,
|
||||
resumable spec status
|
||||
- `work-tracking` — where scope/hill state lives during the build
|
||||
- `qa-methodology` — edge-case QA as late-cycle level-up, not gate
|
||||
|
||||
|
||||
@@ -73,6 +73,7 @@ Each skill's `description` field is the canonical routing contract. This conveni
|
||||
| "product operations", "product governance", "product decision rights", "product council", "intake review", "portfolio review cadence", "launch review", "experiment review governance", "lifecycle review governance", "evidence standard product", "exception record", "escalation record", "product decision authority", "governance cadence", "product operating model", "lightweight product governance", "high-assurance product governance", "cross-functional product operating contract" | [product-operations-and-governance](../product-operations-and-governance/SKILL.md) |
|
||||
| "product roadmap", "outcome roadmap", "Now/Next/Later", "strategic bet", "bet record", "portfolio roadmap", "roadmap review cadence", "continue/pause/kill criteria", "scenario planning roadmap", "dependency mapping portfolio", "portfolio capacity allocation", "roadmap stakeholder communication" | [product-roadmapping-and-portfolio](../product-roadmapping-and-portfolio/SKILL.md) |
|
||||
| "shape up", "shaping work", "appetite vs estimate", "set the appetite", "write a pitch", "pitch document", "breadboard sketch", "fat marker sketch", "circuit breaker project", "scope hammering", "hill chart", "uphill downhill scope", "walking skeleton slice", "one piece done integration", "bets not backlogs", "six-week cycle", "cool-down period", "unshaped idea", "grab-bag request", "rabbit hole de-risk", "agent build budget", "agent loop kill criteria", "non-converging review loop" | [product-shaping](../product-shaping/SKILL.md) |
|
||||
| "BMad", "bmad method", "intent contract", "five-field contract", "Why Capabilities Constraints Non-goals Success signal", "work classification", "direct vs bounded vs initiative", "smallest safe path", "spec status", "ready-for-dev", "build auto", "autonomous build gate", "blocked routing signal", "review as triage", "failure routing", "defer unrelated findings", "human checkpoint", "accept rework investigate", "dark factory control plane", "bounded resumable agent work", "intent-to-delivery protocol" | [bmad](../bmad/SKILL.md) |
|
||||
| "product UX", "product design", "interaction design", "information architecture", "task flow", "user flow", "state model", "recovery path", "interface contract", "UX handoff", "usability study plan" | [product-design-and-ux](../product-design-and-ux/SKILL.md) |
|
||||
| "production excellence", "production gate", "launch decision gate", "go no-go defer exception", "production acceptance", "cross-domain evidence", "production evidence packet", "operational handoff", "post-launch learning", "production gate review", "gate model", "escalation decision", "production exception", "cost SLO conflict", "readiness gate", "migration gate review", "recovery evidence gate" | [production-excellence](../production-excellence/SKILL.md) |
|
||||
| "production readiness", "launch readiness", "ready to launch", "go no-go", "launch decision", "readiness review", "evidence packet", "launch evidence", "production evidence", "risk-scaled readiness", "readiness record", "launch review board", "missing evidence launch", "exception launch approval" | [production-readiness](../production-readiness/SKILL.md) |
|
||||
|
||||
@@ -1,10 +1,16 @@
|
||||
---
|
||||
name: spec-driven-development
|
||||
description: Spec-Driven Development (SDD) methodology for AI software factories —
|
||||
description: >-
|
||||
Design and run a Spec-Driven Development (SDD) pipeline for AI software factories —
|
||||
where structured specifications are the input, AI agents generate the code, and
|
||||
quality gates enforce correctness at each pipeline phase. Use when designing a spec
|
||||
→ review → decompose → implement → verify pipeline that any AI coding tool (Claude
|
||||
Code, Cursor, Hermes Agent, Devin, OpenHands) can follow.
|
||||
quality gates enforce correctness at each phase: SPECIFY → DECOMPOSE → IMPLEMENT →
|
||||
VERIFY → DELIVER. Use when building or refining a spec-driven pipeline any AI coding
|
||||
tool (Claude Code, Cursor, Hermes Agent, Devin, OpenHands, droid) can follow, or when
|
||||
you need spec quality gates, phase-gate verdicts, NFR encoding, or format
|
||||
translation. Do not use for a single small change with a clear goal (classify first
|
||||
via bmad), for the control-plane protocol of intent contracts, autonomy gating, and
|
||||
failure routing around a pipeline (bmad), or for unvalidated problems
|
||||
(product-discovery).
|
||||
license: MIT
|
||||
compatibility: Tool-agnostic — methodology applies to any AI coding agent. Templates
|
||||
use markdown and Gherkin. Scripts require bash.
|
||||
@@ -182,6 +188,18 @@ After patching, the reviewer determines scope:
|
||||
| Incomplete contracts (endpoint listed but no schemas) | Add full request/response schemas for every endpoint | Check Gate 5 before submitting |
|
||||
| Scope creep (ambiguous in-scope items) | Tighten scope description and expand Out of Scope | Apply the "would someone include more than intended?" test
|
||||
|
||||
## When not to use
|
||||
|
||||
- **A single small change with a clear goal** — skip the spec pipeline and implement
|
||||
directly; classify the work first (see `bmad`).
|
||||
- **You need the control-plane protocol around a pipeline** — who owns intent, how
|
||||
work is classified, when autonomy is safe, how failure routes between layers: use
|
||||
`bmad` for intent contracts, work classification, autonomy gating, and failure
|
||||
routing. SDD supplies the spec format and gate mechanics; bmad supplies the protocol
|
||||
that runs the whole effort.
|
||||
- **The problem itself is unvalidated** — route to `product-discovery` before
|
||||
authoring a spec on top of an unexamined idea.
|
||||
|
||||
## Tool-Agnostic Design
|
||||
|
||||
This skill describes the **methodology**, not a specific tool. The pipeline works with:
|
||||
|
||||
Reference in New Issue
Block a user