Spec-Driven Development for AI Software Factories
A methodology for building software where specifications are the executable input to an AI code generation pipeline. The factory model: specs are blueprints, AI agents are the assembly line, verification is quality control, and gates catch defects before they compound.
Pipeline Overview
INCEPTION → [SPECIFY] → REVIEW → [DECOMPOSE] → REVIEW → [IMPLEMENT] → REVIEW → [VERIFY] → DELIVER
↑ ↑ ↑ ↑ ↑ ↑ ↑ ↓
Phase 1 Gate 1 Phase 2 Gate 2 Phase 3 Gate 3 Phase 4 Gate 4
Each phase passes through a gate before the next begins. A defect caught at Gate 1 costs minutes to fix; the same defect found at Gate 4 costs hours.
Use an existing approved PRD, architecture document or issue set as the specification
when it supplies the minimum handoff in references/factory-review-lanes.md.
Throughout this workflow, SPEC.md denotes that authoritative specification; it need
not be a new file or competing copy. Validate equivalent content and traceability.
Run format-specific scripts only when their expected input format applies; otherwise
record the equivalent content checks and any missing information explicitly.
SDD Core Principles
- Make consequential intent explicit. Keep specifications readable and testable. Agents can ask for clarification; unresolved consequential choices need an owner and must stop dependent work before its decision boundary.
- Completeness over brevity. Every missing acceptance criterion is a missing feature. Specifying an edge case upfront costs minutes; discovering it in production costs hours or days.
- Testability over descriptiveness. An AC that cannot produce CLEAR PASS or CLEAR FAIL is not an AC — it's a hope.
- Gates catch defects early. A Gate 1 (spec review) fix costs minutes. A Gate 4 (acceptance review) fix costs hours — the entire implementation may need to be discarded.
- Spec is the single source of truth. Every downstream artifact traces back to the spec. Deviations are defects unless explicitly documented.
- Specs guide test oracles. Gherkin-style ACs can become executable cases, but still need implementation, coverage and oracle review. Independent and withheld scenarios can reveal gaps in visible examples.
Loading Guide
| Reference |
Load when |
File |
| SDD Overview & Philosophy |
You need to understand the why — the software factory metaphor, how SDD differs from traditional requirements, the core principle that specs are executable inputs not communication artifacts |
references/sdd-overview.md |
| The AI Factory Pipeline |
You need the full 5-phase pipeline with phase inputs, outputs, and transition rules — or you're designing a new pipeline from scratch |
references/ai-factory-pipeline.md |
| Factory review lanes |
Separating behavioral acceptance from maintainability, or adapting existing planning artifacts |
references/factory-review-lanes.md |
| Spec Quality Gates |
You've written a SPEC.md and need to validate it before Gate 1 — the 7 gates that separate a good spec from a vague one |
references/spec-quality-gates.md |
| Review records and assumptions |
Binding verdicts to a candidate, tracking provisional choices, or closing deferred findings |
references/review-records.md |
| Phase Gate Methodology |
You're running a review gate (any of the 4) and need the decision criteria, verdict format, and escalation path |
references/phase-gate-methodology.md |
| Methodology Selection Matrix |
You're deciding which spec methodology (BDD, Formal, DbC, OpenAPI, ADRs) fits your context — when each applies and their AI-readiness ratings |
references/methodology-matrix.md |
| NFR Encoding for AI Specs |
You need to express non-functional requirements (performance, security, observability) in machine-readable format |
references/nfr-encoding.md |
| Format Translation |
You need to map between spec formats — Gherkin ↔ OpenAPI ↔ SPEC.md ↔ JSON Schema — or translate a human PRD into an AI-ready spec |
references/format-translation.md |
| Critiques & Tradeoffs |
You need to decide when not to use SDD — the honest limitations: spec bottleneck, GIGO, drift, over/under-specification, the formal methods tax |
references/critiques-and-tradeoffs.md |
| Worked Example — Complete SPEC.md |
You want to see a fully-realized specification to calibrate your output depth — shows proper AC format, edge case enumeration, NFR thresholds, data contracts, and assumptions for a password reset feature |
references/example-spec.md |
Methodology Quick-Pick
Not sure which spec methodology fits your situation? Use this quick reference table (load references/methodology-matrix.md for full depth):
| Concern |
Reach For |
AI-Readiness |
Format Produces |
| REST API contracts |
OpenAPI |
VERY HIGH |
YAML/JSON specification |
| Event/message schemas (Kafka, RabbitMQ) |
AsyncAPI |
HIGH |
YAML/JSON channel specs |
| Behavioral requirements (what the system does) |
BDD / Gherkin |
HIGH |
.feature files with Given/When/Then |
| Interface correctness (pre/post/invariants) |
Design by Contract |
VERY HIGH |
Assertions in code |
| Distributed system correctness (consensus, protocols) |
TLA+ / Alloy |
VERY HIGH (narrow scope) |
Mathematical model |
| Architecture decisions (why we chose X) |
ADRs |
MEDIUM |
Structured markdown |
| System structure (boxes-and-lines) |
C4 Model |
MEDIUM-HIGH |
PlantUML / structured text |
| Raw stakeholder intent |
User Stories |
LOW (needs refinement) |
"As a... I want..." |
Composite approach: Most systems need 3-4 of these working together. REST APIs get OpenAPI, event streams get AsyncAPI, critical behavior gets Gherkin scenarios, and cross-team interface boundaries get DbC assertions.
Templates
| Template |
Pipeline Phase |
File |
| SPEC.md |
Phase 1 — Spec Authoring (SPECIFY). Write this first: problem, scope, user stories, ACs, edge cases, NFRs, data contracts |
templates/SPEC.md |
| FACTORY-REVIEW.md |
Task integration and release acceptance — distinct behavior/engineering verdicts on the same candidate |
templates/FACTORY-REVIEW.md |
| REVIEW.md |
Gate 1-4 — Phase-Gate Review. Use at every gate transition: spec review, plan review, implementation review, acceptance review |
templates/REVIEW.md |
| TASK-PLAN.md |
Phase 2 — Work Decomposition (DECOMPOSE). Extract from an approved spec: task groups, dependency graph, per-task ACs, implementation directives |
templates/TASK-PLAN.md |
| VERIFICATION.md |
Phase 4 — Verification (VERIFY). After implementation: AC pass/fail matrix, compliance score, failure dossiers with remediation |
templates/VERIFICATION.md |
Scripts
| Script |
When to run |
File |
spec-quality-check.sh |
After writing or editing a SPEC.md — validates all required sections exist (problem statement, scope, ACs, edge cases, NFRs, assumptions) |
scripts/spec-quality-check.sh |
spec-to-tasks.sh |
After writing a TASK-PLAN.md — validates every spec AC has a covering task reference |
scripts/spec-to-tasks.sh |
Trigger Conditions
Load this skill when:
- You're building a software factory — a system where AI agents produce code from structured specifications through a gated pipeline
- You're designing or refining an AI code generation pipeline where specs drive implementation
- You need to write a specification that an AI agent (not just a human) will consume
- You're evaluating spec methodologies (BDD, Formal, OpenAPI-first) for a project
- You need templates for SPEC.md, TASK-PLAN.md, REVIEW.md, or VERIFICATION.md
- You're reviewing or verifying AI-generated code against its specification
Quick Reference: Pipeline Steps
| Step |
Action |
Load This Reference |
Produces |
| 1 |
Reuse an approved equivalent specification or write SPEC.md; fill missing handoff content |
references/spec-quality-gates.md (validate before Gate 1) |
SPEC.md |
| 2 |
Run spec-quality-check.sh for its supported format; otherwise record equivalent content checks |
— |
Validation report |
| 3 |
Gate 1 — Review spec against quality gates, produce REVIEW.md |
references/spec-quality-gates.md, references/phase-gate-methodology.md |
REVIEW.md (APPROVED/CONDITIONS/REJECTED) |
| 4 |
Decompose approved spec into TASK-PLAN.md — each task traces to a spec section |
references/ai-factory-pipeline.md (Decompose phase) |
TASK-PLAN.md |
| 5 |
Gate 2 — Review task plan for dependency honesty, spec coverage |
references/phase-gate-methodology.md |
REVIEW.md |
| 6 |
Implement each task — one task per agent session |
— |
Code/PR |
| 7 |
Gate 3 — Verify spec compliance; record the separate engineering lane before integration |
references/phase-gate-methodology.md |
REVIEW.md |
| 8 |
Run verification against all ACs — produce VERIFICATION.md |
— |
VERIFICATION.md |
| 9 |
Gate 4 — Review verification report, deliver only if no BLOCKING failures |
references/phase-gate-methodology.md |
Final approval |
For deeper methodology context, load references/sdd-overview.md (philosophy) or references/ai-factory-pipeline.md (full pipeline detail with parallel execution).
Pipeline Mode & Entry Points
Where to Enter the Pipeline
You don't always start at SPECIFY. Enter at the phase matching what you already have:
| You Have This |
Enter At |
Start With |
| A vague idea, conversation, or PRD |
Phase 1 — SPECIFY |
templates/SPEC.md + references/format-translation.md |
| Approved product scope with interaction contracts |
Phase 1 — SPECIFY |
product-design-and-ux handoff + templates/SPEC.md |
| A clear, approved specification or equivalent planning artifact |
Phase 2 — DECOMPOSE |
templates/TASK-PLAN.md + references/ai-factory-pipeline.md |
| A spec + approved task plan |
Phase 3 — IMPLEMENT |
Task cards with per-task directives |
| Existing code needing verification |
Phase 4 — VERIFY |
templates/VERIFICATION.md |
Which Pipeline Mode to Use
Not every change needs all 4 gates. Choose your mode:
| Mode |
When to Use |
Gates to Run |
Spec Depth |
| Full |
Greenfield feature, multi-agent work, high-risk change, complex interfaces |
All 4 gates |
Full SPEC.md with ACs, NFRs, data contracts, edge cases |
| Lightweight |
Simple bug fix, well-understood change, single-file edit |
Gate 1 (light) → Implement → Gate 4 (light) |
Single user story, 1-3 ACs, abbreviated NFRs |
| Minimal |
Prototype, spike, exploration, throwaway code |
None — skip formal gates |
Mini-spec: 1 paragraph + 3 ACs. No NFR table, no contracts |
Rule of thumb: If you know the fix in under 60 seconds and it touches one file, use Lightweight mode. If you're not sure what the right solution is, use Full mode — the gates will catch your mistakes early.
Review validity and decisions
Use templates/REVIEW.md for candidate/contract identity and executed evidence;
use the assumptions ledger in templates/SPEC.md and carry its IDs into tasks.
A relevant change supersedes affected approval/evidence. Consequential unresolved
choices block dependent effects before merge/release; low-risk reversible choices
may be batched under existing authority. Stable finding IDs preserve follow-up
ownership and verified closure without turning every suggestion into a ticket.
Read references/review-records.md at these handoffs. BMad owns backlog/authority
routing; harness engineering owns runtime state integrity and enforcement.
Gate Recovery & Revision
What happens when a gate rejects your artifact? The pipeline doesn't stop — it iterates.
The Revision Loop
Artifact submitted → Gate review → REJECTED or CONDITIONS
↓
Return to current phase
↓
Patch specific findings
↓
Resubmit for re-review
↓
APPROVED → next phase
How to Patch, Not Rewrite
Each finding identifies a narrow, fixable defect. Patch at the finding's location:
| Finding Severity |
Action |
Example |
| BLOCKING |
Fix immediately — gate cannot pass until resolved |
Rewrite untestable AC with binary PASS/FAIL condition |
| CRITICAL |
Must fix. Gate may pass with documented exception if ≤2 findings |
Add missing edge cases to User Stories section |
| MINOR |
Fix before next phase if feasible. Gate can pass with remediation plan |
Add request/response schemas to Data Contracts |
| INFO |
Note for future improvement. No action required for gate pass |
Suggestion for alternative field naming |
Re-Review Scope
After patching, the reviewer determines scope:
- Full re-review: Required when REJECTED verdict. The entire artifact is re-evaluated, not just patched sections.
- Targeted re-review: Possible with CONDITIONS verdict. Only the affected findings and surrounding context are reviewed.
Risk of partial fixes: Fixing only BLOCKING findings and ignoring CRITICAL ones guarantees re-rejection at the same gate. The CRITICAL findings that cost minutes to fix at Gate 1 will cost hours if caught at Gate 4.
Common Revision Patterns
| Failure Pattern |
Fix Strategy |
Prevention |
| Untestable ACs (vague language like "should handle", "should be efficient") |
Rewrite each AC with explicit Given/When/Then and binary outcome |
Apply Gate 1 check before submitting |
| Missing edge cases |
Add edge case enumeration per story — 3 minimum per story |
Use the "five things that could go wrong" test from spec-quality-gates |
| Vague NFRs ("should be fast", "should be secure") |
Replace with specific threshold + verification method |
Use the "can I write a test for this?" test from nfr-encoding reference |
| 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:
- Claude Code — use CLAUDE.md as spec context, plan-then-implement mode
- Cursor — Plan Mode + .cursorrules for spec context, Agent Mode for implementation
- Hermes Agent — native SDD pipeline (authoring → review → decomposition → verification)
- Devin / OpenHands — task-based implementation from spec-derived task plans
- GitHub Copilot Workspace — issue-driven with spec as structured issue body
- droid (Factory) — task cards from spec decomposition
The templates are format-agnostic (markdown). Adapt the handoff mechanism (CLAUDE.md, .cursorrules, AGENTS.md) to your tool.
Executable business-policy specifications
When translating business clauses into repeatable eligibility or routing decisions, read the business-policy recipe and use the release contract. Preserve policy-owner authority, independent translation-fidelity evidence, and explicit review lanes. Run python3 scripts/business_policy.py --input evals/loan-request.json from this skill directory for a read-only synthetic demonstration (Python 3.10+, standard library); run python3 -m pytest scripts/test_business_policy.py for its contract tests (pytest required). Deterministic execution is not proof that a generated interpretation is correct.
For business rules, do not invent authoritative clauses or owner approvals. Require complete valid facts (including false/zero distinctions), owner-reviewed precedence, independent source-derived fixtures, and exactly one applicable published version selected by the authoritative event date/scope. Caller-supplied version overrides must not bypass applicability. Missing facts or unresolved interpretation go to review. Positive-day policies must reject zero. Report tests as unrun unless execution evidence exists; passing tests cannot guarantee translation correctness or 100% compliance.
1---2name: spec-driven-development3description: >-4 Design and run a Spec-Driven Development (SDD) pipeline for AI software factories —5 where structured specifications are the input, AI agents generate the code, and6 quality gates enforce correctness at each phase: SPECIFY → DECOMPOSE → IMPLEMENT →7 VERIFY → DELIVER. Use when building or refining a spec-driven pipeline any AI coding8 tool (Claude Code, Cursor, Hermes Agent, Devin, OpenHands, droid) can follow, or when9 you need spec quality gates, phase-gate verdicts, NFR encoding, or format10 translation. Do not use for a single small change with a clear goal (classify first11 via bmad), for the control-plane protocol of intent contracts, autonomy gating, and12 failure routing around a pipeline (bmad), or for unvalidated problems13 (product-discovery).14license: MIT15compatibility: Tool-agnostic — methodology applies to any AI coding agent. Templates16 use markdown and Gherkin. Scripts require bash.17metadata:18 source: https://skillmd.com/skills/magnus919/spec-driven-development19 upstream: https://github.com/magnus919/agent-skills/spec-driven-development20 spec-version: 1.2.021---2223# Spec-Driven Development for AI Software Factories2425A methodology for building software where **specifications are the executable input** to an AI code generation pipeline. The factory model: specs are blueprints, AI agents are the assembly line, verification is quality control, and gates catch defects before they compound.2627## Pipeline Overview2829```30INCEPTION → [SPECIFY] → REVIEW → [DECOMPOSE] → REVIEW → [IMPLEMENT] → REVIEW → [VERIFY] → DELIVER31 ↑ ↑ ↑ ↑ ↑ ↑ ↑ ↓32 Phase 1 Gate 1 Phase 2 Gate 2 Phase 3 Gate 3 Phase 4 Gate 433```3435Each phase passes through a gate before the next begins. A defect caught at Gate 1 costs minutes to fix; the same defect found at Gate 4 costs hours.3637Use an existing approved PRD, architecture document or issue set as the specification38when it supplies the minimum handoff in `references/factory-review-lanes.md`.39Throughout this workflow, SPEC.md denotes that authoritative specification; it need40not be a new file or competing copy. Validate equivalent content and traceability.41Run format-specific scripts only when their expected input format applies; otherwise42record the equivalent content checks and any missing information explicitly.4344> **SDD Core Principles**45> 1. **Make consequential intent explicit.** Keep specifications readable and testable. Agents can ask for clarification; unresolved consequential choices need an owner and must stop dependent work before its decision boundary.46> 2. **Completeness over brevity.** Every missing acceptance criterion is a missing feature. Specifying an edge case upfront costs minutes; discovering it in production costs hours or days.47> 3. **Testability over descriptiveness.** An AC that cannot produce CLEAR PASS or CLEAR FAIL is not an AC — it's a hope.48> 4. **Gates catch defects early.** A Gate 1 (spec review) fix costs minutes. A Gate 4 (acceptance review) fix costs hours — the entire implementation may need to be discarded.49> 5. **Spec is the single source of truth.** Every downstream artifact traces back to the spec. Deviations are defects unless explicitly documented.50> 6. **Specs guide test oracles.** Gherkin-style ACs can become executable cases, but still need implementation, coverage and oracle review. Independent and withheld scenarios can reveal gaps in visible examples.5152## Loading Guide5354| Reference | Load when | File |55|-----------|-----------|------|56| SDD Overview & Philosophy | You need to understand the *why* — the software factory metaphor, how SDD differs from traditional requirements, the core principle that specs are executable inputs not communication artifacts | `references/sdd-overview.md` |57| The AI Factory Pipeline | You need the full 5-phase pipeline with phase inputs, outputs, and transition rules — or you're designing a new pipeline from scratch | `references/ai-factory-pipeline.md` |58| Factory review lanes | Separating behavioral acceptance from maintainability, or adapting existing planning artifacts | `references/factory-review-lanes.md` |59| Spec Quality Gates | You've written a SPEC.md and need to validate it before Gate 1 — the 7 gates that separate a good spec from a vague one | `references/spec-quality-gates.md` |60| Review records and assumptions | Binding verdicts to a candidate, tracking provisional choices, or closing deferred findings | `references/review-records.md` |61| Phase Gate Methodology | You're running a review gate (any of the 4) and need the decision criteria, verdict format, and escalation path | `references/phase-gate-methodology.md` |62| Methodology Selection Matrix | You're deciding which spec methodology (BDD, Formal, DbC, OpenAPI, ADRs) fits your context — when each applies and their AI-readiness ratings | `references/methodology-matrix.md` |63| NFR Encoding for AI Specs | You need to express non-functional requirements (performance, security, observability) in machine-readable format | `references/nfr-encoding.md` |64| Format Translation | You need to map between spec formats — Gherkin ↔ OpenAPI ↔ SPEC.md ↔ JSON Schema — or translate a human PRD into an AI-ready spec | `references/format-translation.md` |65| Critiques & Tradeoffs | You need to decide *when not* to use SDD — the honest limitations: spec bottleneck, GIGO, drift, over/under-specification, the formal methods tax | `references/critiques-and-tradeoffs.md` |66| Worked Example — Complete SPEC.md | You want to see a fully-realized specification to calibrate your output depth — shows proper AC format, edge case enumeration, NFR thresholds, data contracts, and assumptions for a password reset feature | `references/example-spec.md` |6768## Methodology Quick-Pick6970Not sure which spec methodology fits your situation? Use this quick reference table (load `references/methodology-matrix.md` for full depth):7172| Concern | Reach For | AI-Readiness | Format Produces |73|---------|-----------|-------------|-----------------|74| REST API contracts | OpenAPI | VERY HIGH | YAML/JSON specification |75| Event/message schemas (Kafka, RabbitMQ) | AsyncAPI | HIGH | YAML/JSON channel specs |76| Behavioral requirements (what the system does) | BDD / Gherkin | HIGH | `.feature` files with Given/When/Then |77| Interface correctness (pre/post/invariants) | Design by Contract | VERY HIGH | Assertions in code |78| Distributed system correctness (consensus, protocols) | TLA+ / Alloy | VERY HIGH (narrow scope) | Mathematical model |79| Architecture decisions (why we chose X) | ADRs | MEDIUM | Structured markdown |80| System structure (boxes-and-lines) | C4 Model | MEDIUM-HIGH | PlantUML / structured text |81| Raw stakeholder intent | User Stories | LOW (needs refinement) | "As a... I want..." |8283**Composite approach:** Most systems need 3-4 of these working together. REST APIs get OpenAPI, event streams get AsyncAPI, critical behavior gets Gherkin scenarios, and cross-team interface boundaries get DbC assertions.8485## Templates8687| Template | Pipeline Phase | File |88|----------|---------------|------|89| SPEC.md | **Phase 1** — Spec Authoring (SPECIFY). Write this first: problem, scope, user stories, ACs, edge cases, NFRs, data contracts | `templates/SPEC.md` |90| FACTORY-REVIEW.md | Task integration and release acceptance — distinct behavior/engineering verdicts on the same candidate | `templates/FACTORY-REVIEW.md` |91| REVIEW.md | **Gate 1-4** — Phase-Gate Review. Use at every gate transition: spec review, plan review, implementation review, acceptance review | `templates/REVIEW.md` |92| TASK-PLAN.md | **Phase 2** — Work Decomposition (DECOMPOSE). Extract from an approved spec: task groups, dependency graph, per-task ACs, implementation directives | `templates/TASK-PLAN.md` |93| VERIFICATION.md | **Phase 4** — Verification (VERIFY). After implementation: AC pass/fail matrix, compliance score, failure dossiers with remediation | `templates/VERIFICATION.md` |9495## Scripts9697| Script | When to run | File |98|--------|-------------|------|99| `spec-quality-check.sh` | After writing or editing a SPEC.md — validates all required sections exist (problem statement, scope, ACs, edge cases, NFRs, assumptions) | `scripts/spec-quality-check.sh` |100| `spec-to-tasks.sh` | After writing a TASK-PLAN.md — validates every spec AC has a covering task reference | `scripts/spec-to-tasks.sh` |101102## Trigger Conditions103104Load this skill when:105106- **You're building a software factory** — a system where AI agents produce code from structured specifications through a gated pipeline107- You're designing or refining an AI code generation pipeline where specs drive implementation108- You need to write a specification that an AI agent (not just a human) will consume109- You're evaluating spec methodologies (BDD, Formal, OpenAPI-first) for a project110- You need templates for SPEC.md, TASK-PLAN.md, REVIEW.md, or VERIFICATION.md111- You're reviewing or verifying AI-generated code against its specification112113## Quick Reference: Pipeline Steps114115| Step | Action | Load This Reference | Produces |116|------|--------|-------------------|----------|117| 1 | Reuse an approved equivalent specification or write SPEC.md; fill missing handoff content | `references/spec-quality-gates.md` (validate before Gate 1) | `SPEC.md` |118| 2 | Run **spec-quality-check.sh** for its supported format; otherwise record equivalent content checks | — | Validation report |119| 3 | **Gate 1** — Review spec against quality gates, produce REVIEW.md | `references/spec-quality-gates.md`, `references/phase-gate-methodology.md` | `REVIEW.md` (APPROVED/CONDITIONS/REJECTED) |120| 4 | Decompose approved spec into TASK-PLAN.md — each task traces to a spec section | `references/ai-factory-pipeline.md` (Decompose phase) | `TASK-PLAN.md` |121| 5 | **Gate 2** — Review task plan for dependency honesty, spec coverage | `references/phase-gate-methodology.md` | `REVIEW.md` |122| 6 | Implement each task — one task per agent session | — | Code/PR |123| 7 | **Gate 3** — Verify spec compliance; record the separate engineering lane before integration | `references/phase-gate-methodology.md` | `REVIEW.md` |124| 8 | Run verification against all ACs — produce VERIFICATION.md | — | `VERIFICATION.md` |125| 9 | **Gate 4** — Review verification report, deliver only if no BLOCKING failures | `references/phase-gate-methodology.md` | Final approval |126127For deeper methodology context, load `references/sdd-overview.md` (philosophy) or `references/ai-factory-pipeline.md` (full pipeline detail with parallel execution).128129## Pipeline Mode & Entry Points130131### Where to Enter the Pipeline132133You don't always start at SPECIFY. Enter at the phase matching what you already have:134135| You Have This | Enter At | Start With |136|-------------|----------|------------|137| A vague idea, conversation, or PRD | **Phase 1 — SPECIFY** | `templates/SPEC.md` + `references/format-translation.md` |138| Approved product scope with interaction contracts | **Phase 1 — SPECIFY** | [product-design-and-ux](../product-design-and-ux/SKILL.md) handoff + `templates/SPEC.md` |139| A clear, approved specification or equivalent planning artifact | **Phase 2 — DECOMPOSE** | `templates/TASK-PLAN.md` + `references/ai-factory-pipeline.md` |140| A spec + approved task plan | **Phase 3 — IMPLEMENT** | Task cards with per-task directives |141| Existing code needing verification | **Phase 4 — VERIFY** | `templates/VERIFICATION.md` |142143### Which Pipeline Mode to Use144145Not every change needs all 4 gates. Choose your mode:146147| Mode | When to Use | Gates to Run | Spec Depth |148|------|-------------|-------------|------------|149| **Full** | Greenfield feature, multi-agent work, high-risk change, complex interfaces | All 4 gates | Full SPEC.md with ACs, NFRs, data contracts, edge cases |150| **Lightweight** | Simple bug fix, well-understood change, single-file edit | Gate 1 (light) → Implement → Gate 4 (light) | Single user story, 1-3 ACs, abbreviated NFRs |151| **Minimal** | Prototype, spike, exploration, throwaway code | None — skip formal gates | Mini-spec: 1 paragraph + 3 ACs. No NFR table, no contracts |152153> **Rule of thumb:** If you know the fix in under 60 seconds and it touches one file, use Lightweight mode. If you're not sure what the right solution is, use Full mode — the gates will catch your mistakes early.154155## Review validity and decisions156157Use `templates/REVIEW.md` for candidate/contract identity and executed evidence;158use the assumptions ledger in `templates/SPEC.md` and carry its IDs into tasks.159A relevant change supersedes affected approval/evidence. Consequential unresolved160choices block dependent effects before merge/release; low-risk reversible choices161may be batched under existing authority. Stable finding IDs preserve follow-up162ownership and verified closure without turning every suggestion into a ticket.163Read `references/review-records.md` at these handoffs. BMad owns backlog/authority164routing; harness engineering owns runtime state integrity and enforcement.165166## Gate Recovery & Revision167168What happens when a gate rejects your artifact? The pipeline doesn't stop — it iterates.169170### The Revision Loop171172```173Artifact submitted → Gate review → REJECTED or CONDITIONS174 ↓175 Return to current phase176 ↓177 Patch specific findings178 ↓179 Resubmit for re-review180 ↓181 APPROVED → next phase182```183184### How to Patch, Not Rewrite185186Each finding identifies a narrow, fixable defect. Patch at the finding's location:187188| Finding Severity | Action | Example |189|-----------------|--------|---------|190| **BLOCKING** | Fix immediately — gate cannot pass until resolved | Rewrite untestable AC with binary PASS/FAIL condition |191| **CRITICAL** | Must fix. Gate may pass with documented exception if ≤2 findings | Add missing edge cases to User Stories section |192| **MINOR** | Fix before next phase if feasible. Gate can pass with remediation plan | Add request/response schemas to Data Contracts |193| **INFO** | Note for future improvement. No action required for gate pass | Suggestion for alternative field naming |194195### Re-Review Scope196197After patching, the reviewer determines scope:198- **Full re-review:** Required when REJECTED verdict. The entire artifact is re-evaluated, not just patched sections.199- **Targeted re-review:** Possible with CONDITIONS verdict. Only the affected findings and surrounding context are reviewed.200201**Risk of partial fixes:** Fixing only BLOCKING findings and ignoring CRITICAL ones guarantees re-rejection at the same gate. The CRITICAL findings that cost minutes to fix at Gate 1 will cost hours if caught at Gate 4.202203### Common Revision Patterns204205| Failure Pattern | Fix Strategy | Prevention |206|----------------|-------------|------------|207| Untestable ACs (vague language like "should handle", "should be efficient") | Rewrite each AC with explicit Given/When/Then and binary outcome | Apply Gate 1 check before submitting |208| Missing edge cases | Add edge case enumeration per story — 3 minimum per story | Use the "five things that could go wrong" test from spec-quality-gates |209| Vague NFRs ("should be fast", "should be secure") | Replace with specific threshold + verification method | Use the "can I write a test for this?" test from nfr-encoding reference |210| Incomplete contracts (endpoint listed but no schemas) | Add full request/response schemas for every endpoint | Check Gate 5 before submitting |211| Scope creep (ambiguous in-scope items) | Tighten scope description and expand Out of Scope | Apply the "would someone include more than intended?" test212213## When not to use214215- **A single small change with a clear goal** — skip the spec pipeline and implement216 directly; classify the work first (see `bmad`).217- **You need the control-plane protocol around a pipeline** — who owns intent, how218 work is classified, when autonomy is safe, how failure routes between layers: use219 `bmad` for intent contracts, work classification, autonomy gating, and failure220 routing. SDD supplies the spec format and gate mechanics; bmad supplies the protocol221 that runs the whole effort.222- **The problem itself is unvalidated** — route to `product-discovery` before223 authoring a spec on top of an unexamined idea.224225## Tool-Agnostic Design226227This skill describes the **methodology**, not a specific tool. The pipeline works with:228- **Claude Code** — use CLAUDE.md as spec context, plan-then-implement mode229- **Cursor** — Plan Mode + .cursorrules for spec context, Agent Mode for implementation230- **Hermes Agent** — native SDD pipeline (authoring → review → decomposition → verification)231- **Devin / OpenHands** — task-based implementation from spec-derived task plans232- **GitHub Copilot Workspace** — issue-driven with spec as structured issue body233- **droid (Factory)** — task cards from spec decomposition234235The templates are format-agnostic (markdown). Adapt the handoff mechanism (CLAUDE.md, .cursorrules, AGENTS.md) to your tool.236237## Executable business-policy specifications238239When translating business clauses into repeatable eligibility or routing decisions, read [the business-policy recipe](references/executable-business-policy.md) and use [the release contract](templates/BUSINESS-POLICY.md). Preserve policy-owner authority, independent translation-fidelity evidence, and explicit review lanes. Run `python3 scripts/business_policy.py --input evals/loan-request.json` from this skill directory for a read-only synthetic demonstration (Python 3.10+, standard library); run `python3 -m pytest scripts/test_business_policy.py` for its contract tests (pytest required). Deterministic execution is not proof that a generated interpretation is correct.240241For business rules, do not invent authoritative clauses or owner approvals. Require complete valid facts (including false/zero distinctions), owner-reviewed precedence, independent source-derived fixtures, and exactly one applicable published version selected by the authoritative event date/scope. Caller-supplied version overrides must not bypass applicability. Missing facts or unresolved interpretation go to review. Positive-day policies must reject zero. Report tests as unrun unless execution evidence exists; passing tests cannot guarantee translation correctness or 100% compliance.