feat: spec-driven-development v1.2.0 — SDD methodology for AI software factories

2026-09-11 19:47:12 +03:00 · 2026-07-06 00:09:07 -04:00
parent 920c496cc5
commit 980f87050d
18 changed files with 1794 additions and 0 deletions
@@ -54,6 +54,7 @@ When the user mentions these keywords, load the corresponding skill:
 | User says... | Load skill |
 |---|---|
 | "build a CLI", "make a CLI tool", "agent-friendly CLI", "add --json flag" | [cli-builder](cli-builder/SKILL.md) |
 | "SDD", "spec-driven development", "specification driven", "software factory", "spec first", "spec as code", "SPEC.md template", "write a spec for AI", "AI code generation pipeline", "acceptance criteria", "quality gates", "phase gate review", "BDD for AI", "OpenAPI first", "executable specification" | [spec-driven-development](spec-driven-development/SKILL.md) |
 | "debug this", "root cause", "why is this broken", "fix this bug" | [systematic-debugging](systematic-debugging/SKILL.md) |
 | "epub", "ebook", "EPUB file", "ebook format", "read epub", "write epub", "create ebook", "extract from epub", "epub to text", "edit epub", "repair epub", "convert epub2", "epub images", "batch epub", "ebook metadata" | [epub](epub/SKILL.md) |
 | "gutenberg", "public domain", "download a book", "classic literature", "free ebook", "gutenberg.org", "project gutenberg", "PG", "gutendex" | [gutenberg](gutenberg/SKILL.md) |
@@ -120,6 +120,10 @@ Query, search, and download public datasets from the City of Raleigh Open Data p
 Reverse-engineer a software codebase to understand its architecture, data flow, privacy posture, and feature surface — then produce a clean-room design document, PRD, or migration plan under new constraints (local-first, privacy-first, self-hosted). Includes an interface extraction pattern for designing swappable storage provider abstractions.
 ### [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.
 ### [systematic-debugging](systematic-debugging/SKILL.md)
 4-phase root cause debugging protocol: understand bugs before fixing. Covers schema/environment divergence, exception type specificity in fallback chains, progressive characterization grids for API/retrieval failures, dependency source detection (editable dev forks), macOS sandboxed application debugging, and the Rule of Three for recognizing architectural problems. Adapted from [obra/superpowers](https://github.com/obra/superpowers) (MIT) with significant expansion from real-world use.
@@ -0,0 +1,197 @@
 ---
 name: spec-driven-development
 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.
 license: MIT
 compatibility: Tool-agnostic — methodology applies to any AI coding agent. Templates use markdown and Gherkin. Scripts require bash.
 metadata:
  source: https://github.com/magnus919/agent-skills/spec-driven-development
  spec-version: "1.2.0"
  hermes:
    tags: [sdd, specifications, ai-code-generation, software-factory, bdd, gherkin, quality-gates, phase-gates]
    related_skills: [sdd-authoring, sdd-review, sdd-verification, sdd-work-decomposition]
 ---
 # 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.
 > **SDD Core Principles**
 > 1. **Precision over clarity.** A precise-but-dense spec is better than a readable-but-ambiguous one. The AI cannot ask for clarification — it implements one interpretation at random.
 > 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.
 > 3. **Testability over descriptiveness.** An AC that cannot produce CLEAR PASS or CLEAR FAIL is not an AC — it's a hope.
 > 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.
 > 5. **Spec is the single source of truth.** Every downstream artifact traces back to the spec. Deviations are defects unless explicitly documented.
 > 6. **Spec IS the test (when possible).** Gherkin-style ACs serve double duty as test cases. No separate test writing required.
 ## 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` |
 | 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` |
 | 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` |
 | 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 | Write SPEC.md from template — problem, scope, stories, ACs, edge cases, NFRs | `references/spec-quality-gates.md` (validate before Gate 1) | `SPEC.md` |
 | 2 | Run **spec-quality-check.sh** on SPEC.md | — | 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 implementation against spec (not code style) | `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` |
 | A clear, approved specification | **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.
 ## 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
 ## 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.
@@ -0,0 +1,114 @@
 # The AI Software Factory Pipeline
 The canonical 5-phase pipeline for spec-driven code generation. Each phase produces an artifact that passes through a gate before the next phase begins.
 ## Pipeline Diagram
 ```
 INCEPTION → [SPECIFY] → GATE 1 → [DECOMPOSE] → GATE 2 → [IMPLEMENT] → GATE 3 → [VERIFY] → GATE 4 → DELIVER
                │                      │               │              │
          Produces:              Produces:        Produces:       Produces:
          SPEC.md                TASK-PLAN.md     Code/PRs        VERIFICATION.md
 ```
 ## Phase 1: Spec Authoring (SPECIFY)
 **Input:** Raw requirements — conversation, ticket, PRD, user research, competitive analysis
 **Output:** SPEC.md
 **Who writes it:** A human domain expert, an AI spec-authoring agent guided by a human, or both in collaboration
 **What SPEC.md contains:**
 1. Problem statement — what problem this solves and why it matters
 2. Success criteria — measurable outcomes that define success
 3. Scope boundary — explicit in-scope and out-of-scope
 4. User stories — prioritized, each with acceptance criteria
 5. Acceptance criteria — per-story, Given/When/Then or bulleted pass/fail
 6. Edge cases — explicit boundary conditions, error states, invalid inputs
 7. Non-functional requirements — performance, security, observability, compliance
 8. Data contracts / interfaces — schemas, APIs, events
 9. Assumptions & open questions — documented for resolution planning
 **Gate 1: Spec Review** — Is the spec complete, unambiguous, and testable enough for decomposition? Pass quality gates first.
 ## Phase 2: Work Decomposition (DECOMPOSE)
 **Input:** Reviewed, approved SPEC.md
 **Output:** TASK-PLAN.md
 **Principle:** The spec IS the plan. This phase does not invent work — it extracts an execution sequence from the spec's defined behaviors.
 **Rules:**
 - Every spec requirement maps to at least one task
 - Each task is independently implementable and verifiable
 - No task exceeds one session of AI agent work (30-120 minutes)
 - Dependencies are real and spec-derived (not invented)
 - Each task body includes a `Spec: -- section X` reference back to SPEC.md
 **Gate 2: Plan Review** — Does every spec requirement have a covering task? Are dependencies honest? Is each task independently implementable?
 ## Phase 3: Implementation (IMPLEMENT)
 **Input:** TASK-PLAN.md per-task directives
 **Output:** Code, configs, documentation changes (typically as a PR)
 **Who implements:** AI coding agents, each working on one task at a time
 **Rules:**
 - Each task is implemented as an independent unit
 - Contract interfaces defined in the spec are the coordination mechanism between parallel tasks
 - Deviations from the spec are explicitly documented, not silently introduced
 - The spec is the ground truth — implementation must satisfy all ACs
 **Gate 3: Implementation Review** — Does the implementation satisfy all acceptance criteria for completed tasks? This is NOT a general code review — it checks spec compliance only.
 ## Phase 4: Verification (VERIFY)
 **Input:** Implementation artifacts, SPEC.md acceptance criteria
 **Output:** VERIFICATION.md with pass/fail matrix
 **Method:** Every acceptance criterion from the spec is tested against the implementation. Verification covers:
 - Functional correctness — does output match expected for each input?
 - Behavioral completeness — are all scenarios handled (including edge cases)?
 - Contract compliance — do interfaces match spec definitions?
 - Non-functional requirements — do performance/security thresholds pass?
 - Negative testing — are invalid inputs correctly rejected?
 **Severity classification:**
 | Severity | Definition | Gate Impact |
 |----------|-----------|-------------|
 | BLOCKING | AC failed, no workaround — core requirement unmet | Gate does not pass |
 | CRITICAL | AC failed but feasible workaround exists | Gate does not pass without documented exception |
 | MINOR | AC passes suboptimally | Gate can pass with remediation plan |
 | INFO | Observation, no pass/fail impact | Informational |
 **Gate 4: Acceptance Review** — All BLOCKING failures resolved? CRITICAL failures documented? Compliance score adequate?
 ## Phase 5: Delivery (DELIVER)
 **Input:** Approved VERIFICATION.md, implementation artifacts
 **Output:** Merged PR, deployed feature
 **Gate:** Only passed if verification report shows no BLOCKING failures and all CRITICAL failures have documented exceptions.
 ## Parallel Task Execution
 When the spec has independent features with no dependency chain, multiple AI agents can implement tasks in parallel. The coordination mechanism:
 1. **Contracts first:** Shared interfaces (API schemas, data contracts) are defined in the spec and are the first tasks implemented
 2. **Independent tasks:** Tasks with no interdependencies run in parallel
 3. **Dependent tasks:** Sequential execution with contract verification at each handoff
 ## The Pipeline Template
 The pipeline is a template, not a straitjacket. Common variations:
 - **Greenfield project:** Full 5-phase pipeline from INCEPTION to DELIVER
 - **Feature addition:** Phases 1-4 (spec through verify) against an existing codebase
 - **Bug fix:** Compressed pipeline — spec-only for the fix scope, implement, verify
 - **Refactor:** No new spec — spec is inferred from existing behavior, verified after refactor
@@ -0,0 +1,120 @@
 # Critiques & Tradeoffs
 SDD is not a silver bullet. This reference covers when it fails, the hard tradeoffs, and how to mitigate them.
 ## 1. Spec as Bottleneck
 **The problem:** SDD creates a serial dependency at the spec phase — no code can be written until the spec is approved. In fast-moving projects, this causes:
 - Developer/agent idle time while waiting for spec approval
 - Pressure to deliver specs faster, reducing quality
 - Specs that pass the gate check but aren't actually good enough
 **Mitigation:**
 - Write specs iteratively — one feature at a time, not the entire system
 - Use AI-assisted spec authoring to accelerate spec writing
 - Tighten the spec scope to what's necessary for the next implementation phase
 - Distinguish between "specs that drive the factory" vs "light specs for prototypes"
 **Truth:** SDD shifts the bottleneck from debugging code to writing specs. Depending on your team's skills, this may or may not be a net improvement.
 ## 2. Garbage In, Garbage Out (GIGO)
 **The hardest problem in AI code generation:** Spec quality is the most difficult engineering problem. It's easy to verify code against a spec. It's hard to verify a spec against stakeholder intent.
 **Root cause:** AI agents cannot ask clarifying questions. A vague spec produces working-but-wrong code. An ambiguous term produces code implementing the wrong interpretation. A missing edge case produces code that crashes in production.
 **Mitigation:**
 - The 7 quality gates in this skill exist specifically to catch GIGO before code generation
 - Spec quality checks should be automated (see `spec-quality-check.sh`)
 - Spec review should have the same rigor as code review
 - Invest in spec templates and spec quality infrastructure before scaling the factory
 ## 3. Spec Drift vs Code Drift
 Two failure modes that compound over time:
 | Failure Mode | Description | Prevention |
 |-------------|-------------|-----------|
 | **Spec drift** | Spec changes but code doesn't → spec becomes outdated, verification passes wrong things | Spec-as-code discipline: spec changes follow the same PR process as code changes |
 | **Code drift** | Code changes but spec doesn't → spec no longer reflects the actual system | Living documentation: when spec IS the test, drift is impossible (for behavioral specs) |
 **The hard truth:** Even with living documentation, only behavioral specs stay synced. Architecture specs, NFR specs, and design decision docs will drift without active maintenance.
 ## 4. The Precision-Clarity Tradeoff
 This is the defining tension of SDD:
 **For human developers:** clarity > precision. Some ambiguity is acceptable because humans clarify through conversation.
 **For AI agents:** precision > clarity. The spec must be exact even if it's dense. The agent cannot ask for clarification.
 The result: **specs optimized for AI consumption are harder for humans to write and review.** Business stakeholders may struggle to validate dense, technical specs. Spec reviewers need a different skill set than traditional requirements review.
 **Mitigation:**
 - Dual-format specs: AI-precise format for the agent, human-readable summary for stakeholders
 - AI-assisted spec authoring (AI produces the dense spec, human reviews for intent)
 ## 5. Over-Specification
 Specs that are too rigid cause:
 - AI agents produce suboptimal code because the spec constrains the implementation unnecessarily
 - False precision — specifying things that should be implementation details
 - Spec maintenance burden for decisions that could have been left open
 **The threshold:** A good spec specifies WHAT but not HOW — except when the HOW matters (performance, security, compliance, maintainability). Determining this boundary is a judgment call.
 **Anti-pattern:** Specifying the algorithm, data structure, or UI framework in the spec when it's an implementation detail.
 ## 6. Under-Specification
 The opposite problem — specs too vague for AI agents:
 - Agents fill gaps with random interpretations
 - Different agents produce incompatible implementations from the same spec
 - Reviewers cannot assess completeness
 - Edge cases are discovered in production, not in specification
 **The trap:** "Good enough to be understood by a human" is not "good enough for an AI agent." Human readers correct for ambiguity unconsciously; agents propagate it faithfully.
 ## 7. The "Formal Methods Tax"
 TLA+, Alloy, and formal verification provide the strongest guarantees but at high cost:
 - Requires specialized mathematical training
 - Slow to write (hours for what a paragraph describes in minutes)
 - Covers specific properties only (safety/liveness), not full system behavior
 - Model checking is limited by scope size (Alloy's "small scope hypothesis")
 **Verdict:** Use formal methods only for critical subsystems where the cost of failure exceeds the cost of formal specification. Not for entire codebases.
 ## 8. Maintenance Burden
 Every requirement change requires:
 - Spec update (same effort as updating code)
 - Re-review through the SDD gate
 - Re-verification of existing functionality
 - Version management across multiple spec iterations
 **When this hurts most:** Rapidly changing requirements during early exploration. If requirements change faster than you can write specs, SDD is the wrong approach.
 ## 9. When NOT to Use SDD
 | Context | Why SDD Fails | Better Approach |
 |---------|--------------|-----------------|
 | Throwaway prototypes | Spec cost > bug-fix cost | Just code it |
 | Genuinely unknown requirements | You can't specify what you don't know | Exploration-first, spec later |
 | Rapid exploration phase | Requirements change faster than spec updates | Agile/iterative, no formal gate |
 | Single-developer greenfield | Overhead of gates slows velocity | Lightweight spec only |
 | UI-heavy with dynamic requirements | Spec for visual/interaction behavior is fragile | Click-through prototypes, spec only core logic |
 | Team won't maintain specs | Spec becomes shelf-ware within weeks | Don't start — the drift will be worse than no spec |
 ## The SDD Paradox
 The fundamental tension that every SDD practitioner must accept:
 > The more valuable a spec is for AI code generation (precise, structured, testable), the harder it is for humans to write, maintain, and validate.
 This creates the market for:
 - **AI-assisted spec authoring** — AI writes the structured spec from natural language, human reviews
 - **Spec quality automation** — linting, validation, gap detection
 - **Spec inference from code** — reverse-engineering specs from existing systems
 The paradox doesn't invalidate SDD. It defines where SDD is worth the investment and where it isn't.
@@ -0,0 +1,198 @@
 # Specification: Password Reset Flow
 ## Status
 - **Author:** SDD Skill Example
 - **Version:** 1.0.0 (example)
 - **Status:** Example — shown for calibration
 ## Problem Statement
 Users who forget their passwords currently have no self-service recovery path. When locked out, they must contact support to regain access, creating delays and support costs. A self-service password reset flow reduces support tickets and improves user experience.
 ## Success Criteria
 - Reduce password-related support tickets by 80% within 30 days of launch
 - Password reset completes in under 2 minutes for 95% of users (from "Forgot Password" click to new password confirmed)
 ## Scope
 ### In Scope
 - Email-based password reset with time-limited token
 - Password strength validation (minimum 8 chars, mixed case, digit)
 - Rate limiting on reset requests (max 3 per email per hour)
 - Confirmation email on successful reset
 - Session invalidation after password change
 ### Out of Scope (Explicit)
 - SMS-based reset (no phone number required)
 - Security questions backup
 - Admin-initiated password reset
 - Passwordless authentication (magic links)
 - Account recovery via alternate email
 - Remember-me across sessions after reset
 ## User Stories
 ### US-001: Initiate Password Reset
 **Priority:** P0
 **Description:** As a registered user who forgot their password, I want to request a password reset so that I can regain access to my account.
 **Acceptance Criteria:**
 1. [AC-001.1] Given I am on the login page, When I click "Forgot Password", Then I see an email input field with a submit button labeled "Send Reset Link"
 2. [AC-001.2] Given I enter my registered email address, When I submit the form, Then I receive a password reset email within 30 seconds
 3. [AC-001.3] Given I enter an unregistered email address, When I submit the form, Then I see "If that email is registered, a reset link has been sent" (same message as success — no email enumeration)
 4. [AC-001.4] Given I have submitted 3 reset requests in the last hour, When I try to submit a 4th, Then I see "Too many requests. Try again later."
 **Edge Cases:**
 - Unregistered email: show generic success message, no email enumeration (covered in AC-001.3)
 - Rate limit exceeded: show retry-after message (covered in AC-001.4)
 - Malformed email format: show validation error before submission
 - Network failure on send: show "Something went wrong. Please try again."
 - Email provider returns permanent failure (bounce): log and alert, no user-facing error
 - Concurrent reset requests: each request generates a new token; only the most recent token is valid
 ### US-002: Complete Password Reset
 **Priority:** P0
 **Description:** As a user with a valid reset token, I want to set a new password so that I can log in with my new credentials.
 **Acceptance Criteria:**
 1. [AC-002.1] Given I click the reset link in the email, When the token is valid and unexpired, Then I see a password creation form
 2. [AC-002.2] Given I enter a new password meeting all strength requirements, When I submit, Then my password is updated and I see "Password updated successfully. Please log in."
 3. [AC-002.3] Given I enter a weak password (under 8 characters), When I submit, Then I see specific guidance: "Password must be at least 8 characters"
 4. [AC-002.4] Given I click a reset link with an expired token (older than 15 minutes), When the page loads, Then I see "This reset link has expired. Please request a new one."
 5. [AC-002.5] Given I click a reset link that has already been used, When the page loads, Then I see "This reset link has already been used. Please request a new one."
 6. [AC-002.6] Given my password is successfully reset, When I attempt to log in with my old password, Then authentication is rejected (old credentials invalidated)
 **Edge Cases:**
 - Expired token: show expiration message, prompt new request (covered in AC-002.4)
 - Reused token: show already-used message, prompt new request (covered in AC-002.5)
 - Weak password: show specific strength guidance per failure (covered in AC-002.3)
 - Token tampering (invalid format, wrong user ID): show generic "Invalid reset link"
 - Browser closes mid-reset: token remains valid until expiry
 - Password update fails due to database error: show "Something went wrong. Please try again." with retry
 ## Non-Functional Requirements
 | ID | Requirement | Threshold | Verification Method |
 |----|-------------|-----------|-------------------|
 | NFR-001 | Reset email delivery | Email sent within 30s at P95 under 100 concurrent requests | Load test with email provider mock |
 | NFR-002 | Reset token expiry | Tokens expire after exactly 15 minutes | Unit test with time mocking |
 | NFR-003 | Rate limiting | Max 3 requests per email per hour | Integration test with repeated requests |
 | NFR-004 | Password strength | Minimum 8 chars, at least 1 uppercase, 1 lowercase, 1 digit | Unit test with password validator |
 | NFR-005 | Session invalidation | All active sessions invalidated within 5s of password change | Integration test with session store |
 | NFR-006 | Audit logging | Every reset request and completion produces an audit log entry | Log inspection test |
 | NFR-007 | API response time | All endpoints respond within 500ms at P95 under normal load | Load test |
 ## Data Contracts & Interfaces
 ### POST /api/auth/forgot-password
 **Request:**
 ```json
 {
  "email": "user@example.com"
 }
 ```
 **Response 200:**
 ```json
 {
  "message": "If that email is registered, a reset link has been sent"
 }
 ```
 **Response 429 (rate limited):**
 ```json
 {
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Try again later.",
  "retry_after_seconds": 1800
 }
 ```
 ### GET /api/auth/reset-password?token={token}
 **Response 200:**
 ```json
 {
  "valid": true,
  "expires_at": "2026-07-05T12:00:00Z"
 }
 ```
 **Response 410 (expired or used):**
 ```json
 {
  "valid": false,
  "reason": "expired" | "already_used",
  "message": "This reset link has {expired|already been used}. Please request a new one."
 }
 ```
 ### POST /api/auth/reset-password
 **Request:**
 ```json
 {
  "token": "abc123...",
  "password": "NewSecurePass1"
 }
 ```
 **Response 200:**
 ```json
 {
  "status": "success",
  "message": "Password updated successfully. Please log in."
 }
 ```
 **Response 400 (validation failure):**
 ```json
 {
  "status": "error",
  "errors": [
    { "field": "password", "message": "Password must be at least 8 characters" }
  ]
 }
 ```
 ### Token Schema
 ```json
 {
  "token": "string (64-char hex)",
  "user_id": "uuid",
  "email": "string (email format)",
  "created_at": "datetime (ISO 8601)",
  "expires_at": "datetime (created_at + 15 minutes)",
  "used_at": "datetime | null",
  "status": "active | expired | used"
 }
 ```
 ## Assumptions & Open Questions
 | # | Assumption / Question | Impact if Wrong | Resolution |
 |---|----------------------|----------------|------------|
 | 1 | Email provider delivers within 30s for 95% of requests | If slower, users perceive reset as broken | Verify with email provider SLA; add fallback message |
 | 2 | Users check email within 15 minutes | If users take longer, they hit expired token | Monitor token expiry rate; consider extending to 30 min |
 | 3 | Rate limiting per email is sufficient for abuse prevention | Distributed attacks across many emails bypasses per-email limit | Add IP-based rate limiting as a second layer |
 | 4 | No existing sessions need to be preserved | Users may lose unsaved work in other sessions | Confirm with product — may need grace period |
 | 5 | Password strength requirements match user expectations | Complex requirements increase support tickets | Test with user sample; adjust if >10% fail |
 | 6 | What is the expected peak concurrent reset volume? | Affects NFR-001 and NFR-007 thresholds | Load test with range; document assumptions |
 ## Revision History
 | Version | Date | Author | Change |
 |---------|------|--------|--------|
 | 1.0.0 | 2026-07-05 | SDD Skill Example | Initial example spec for calibration |
@@ -0,0 +1,159 @@
 # Format Translation
 Specifications in an AI software factory come in multiple formats. This reference covers how to translate between formats, when to use each, and the conversion loss risks.
 ## Translation Map
 ```
                    ┌─────────────────┐
                    │   Human PRD     │ (natural language)
                    └────────┬────────┘
                             │ (lossy — interpretation required)
                             ▼
                    ┌─────────────────┐
                    │   SPEC.md       │ (structured markdown)
                    └───┬──────┬──────┘
                        │      │
               ┌────────┘      └────────┐
               ▼                         ▼
     ┌──────────────────┐     ┌──────────────────┐
     │  Gherkin .feature│     │  OpenAPI YAML     │
     │  (behavior)      │     │  (API contracts)  │
     └────────┬─────────┘     └────────┬─────────┘
              │                        │
              ▼                        ▼
     ┌──────────────────┐     ┌──────────────────┐
     │  Step definitions│     │  Server stubs    │
     │  + test cases    │     │  + client SDKs   │
     └──────────────────┘     └──────────────────┘
 ```
 ## Directional Conversions
 ### Human PRD → SPEC.md
 **Loss:** HIGH. A PRD is narrative, opinionated, and assumes shared context. Converting to structured SPEC.md requires:
 1. Extract explicit requirements from narrative prose
 2. Identify implicit assumptions and make them explicit
 3. Decompose vague statements into testable ACs
 4. Add edge cases the PRD author didn't consider
 5. Define measurable NFR thresholds from qualitative descriptions
 **Risk:** Interpretation loss. The PRD author's intent may not survive the translation. **Solution:** Send the SPEC.md to the PRD author for Gate 1 review.
 ### SPEC.md → Gherkin Feature Files
 **Loss:** LOW (for behavioral sections). Gherkin maps directly to the user stories and ACs in SPEC.md.
 **Mapping:**
 ```
 SPEC.md user story → Gherkin Feature (with narrative)
 SPEC.md acceptance criteria → Gherkin Scenario (Given/When/Then)
 SPEC.md edge cases → Additional Scenarios or Scenario Outline
 ```
 **Translation example:**
 | SPEC.md | Gherkin |
 |---------|---------|
 | "US-001: As a user, I want to reset my password" | `Feature: Password Reset` |
 | "AC-001.1: Given I'm on the login page, When I click 'Forgot Password', Then I see an email input field" | `Scenario: Initiate password reset` with Given/When/Then |
 | "Edge case: email not found" | `Scenario: Reset with unregistered email` |
 ### SPEC.md → OpenAPI YAML
 **Loss:** LOW-MEDIUM. The Data Contracts & Interfaces section of SPEC.md maps directly to OpenAPI paths, schemas, and responses.
 **Mapping:**
 ```
 SPEC.md "Data Contracts" API spec → OpenAPI paths
 SPEC.md request/response schemas → OpenAPI components/schemas
 SPEC.md auth requirements → OpenAPI securitySchemes
 SPEC.md error formats → OpenAPI responses with examples
 ```
 **Translation example:**
 ```markdown
 ## Data Contracts
 ### POST /api/users
 - Request: { name: string, email: string }
 - Response 201: { id: uuid, name: string, email: string, created_at: datetime }
 - Error 409: { error: "email_taken", message: "..." }
 ```
 → OpenAPI YAML with the path, requestBody schema, and response schemas for 201 and 409.
 ### Gherkin ↔ OpenAPI (cross-format verification)
 Gherkin scenarios can validate OpenAPI contracts and vice versa:
 - An OpenAPI `400` response definition implies a Gherkin scenario: "When I send an invalid request, Then I receive 400"
 - A Gherkin scenario about successful creation implies an OpenAPI `201` response with a specific schema
 **Trick:** Generate Gherkin scenarios directly from OpenAPI response codes and schemas. Every documented error code should have a corresponding negative test scenario.
 ### SPEC.md → TASK-PLAN.md tasks
 **Loss:** MINIMAL (intentional). Each AC in SPEC.md becomes one or more tasks in TASK-PLAN.md. This is not a lossy conversion — it's a decomposition.
 **Rule:** Every AC must appear in at least one task. The `spec-to-tasks.sh` script validates this coverage.
 ### SPEC.md → JSON Schema (data contracts)
 **Loss:** NONE for structural types. JSON Schema losslessly represents the type constraints in SPEC.md data contracts.
 **Mapping:**
 ```
 SPEC.md field type constraints → JSON Schema type/format/enum
 SPEC.md required fields → JSON Schema required array
 SPEC.md validation rules → JSON Schema pattern/minLength/maxLength
 ```
 ## Conversion Ordering
 For a new feature, the recommended conversion sequence:
 ```
 1. Human conversation → SPEC.md (structured markdown)
 2. SPEC.md behavioral ACs → Gherkin .feature files (spec-as-tests)
 3. SPEC.md data contracts → OpenAPI YAML + JSON Schema (for code gen)
 4. SPEC.md → TASK-PLAN.md (for implementation sequencing)
 ```
 Steps 2 and 3 can happen in parallel since they target different concerns.
 ## Format Selection Guide
 | Format | Best For | Worst For |
 |--------|----------|-----------|
 | SPEC.md (markdown) | Complete spec with all concerns | Machine automation without human review |
 | Gherkin | Behavioral requirements, executable tests | Architecture, NFRs, data contracts |
 | OpenAPI | REST API contracts, client/server code gen | Internal business logic, UI, async events |
 | AsyncAPI | Event-driven systems, message queues | Request/response APIs |
 | JSON Schema | Data validation, type safety | Behavior, orchestration, side effects |
 | Protocol Buffers | High-performance RPC, cross-language schemas | Human readability, quick iteration |
 | TLA+ | Distributed systems, protocol verification | Full-system specification, non-critical code |
 ## Translation Risks
 | Conversion | Risk | Mitigation |
 |------------|------|-----------|
 | Human prose → structured spec | Intent loss | Review Gate 1 with domain expert |
 | SPEC.md → Gherkin | ACs that don't map to scenarios | Cover every AC in at least one scenario |
 | SPEC.md → OpenAPI | Missing error paths | Derive error responses from edge cases, not just happy path |
 | Gherkin → step definitions | Brittle UI-coupled steps | Implement at the API/domain layer, not UI layer |
 | OpenAPI → client stubs | Stale SDKs when API changes | Regenerate stubs from spec, keep generation in CI |
 ## Brownfield: Reverse-Engineering Specs from Code
 When working with existing codebases that have no specs, the conversion direction reverses:
 ```
 Code → API surface (OpenAPI from routes/swagger/middleware)
 Code → Behavioral spec (Gherkin from tests or observed behavior)
 Code → Architecture decisions (ADRs from code review & commit history)
 ```
 This is never lossless. The resulting spec captures **what the code does**, not **what it should do**. Treat reverse-engineered specs as starting points for refinement, not ground truth. See `ai-factory-pipeline.md` for brownfield feature additions.
@@ -0,0 +1,139 @@
 # Methodology Selection Matrix
 Different specification methodologies serve different purposes. This guide helps select the right methodology (or combination) for your AI code generation context.
 ## Methodology Spectrum
 ```
 Human-oriented (conversational) ─────────────────────────── Machine-oriented (formal)
        |              |                |                      |               |
    User Stories    BDD/Gherkin    OpenAPI-first          DbC/Contracts   Formal Methods
    (Agile)         (Cucumber)     (Swagger/OpenAPI)       (Eiffel)        (TLA+, Alloy)
        |              |                |                      |               |
    Too vague       Executable      Machine-readable       Machine-        Provably
    for AI          & human-        API contracts           verifiable      correct
 ```
 ## Methodology Descriptions
 ### User Stories (Agile)
 **Format:** "As a [role], I want [capability] so that [benefit]"
 **AI-readiness:** LOW. User stories express intent but lack the precision AI agents need. They work as conversation starters with humans but fail as executable specs for AI.
 **When to use:** As the starting point for spec authoring (Phase 0), but they must be refined into structured acceptance criteria before entering the SDD pipeline.
 ### Behavior-Driven Development (BDD) — Gherkin / Cucumber
 **Format:**
 ```gherkin
 Feature: Title
  Scenario: Description
    Given <precondition>
    When <action>
    Then <expected outcome>
 ```
 **AI-readiness:** HIGH. Gherkin is the most AI-friendly spec format for behavioral requirements.
 **Why:**
 - Fixed syntax with defined keywords — agents parse it deterministically
 - Scenarios map directly to test cases — spec IS the test
 - Each scenario produces a binary PASS/FAIL verdict
 - Language-agnostic — works with any tech stack
 - Tools exist to execute scenarios directly (Cucumber, SpecFlow, Behave)
 **When to use:** Any behavioral requirement where the user can describe preconditions, actions, and expected outcomes.
 **Limitations:** Does not cover non-functional requirements well. Step definitions require maintenance. Complex state setup can make scenarios brittle.
 ### OpenAPI-First
 **Format:** YAML/JSON specification following the OpenAPI 3.x standard
 **AI-readiness:** VERY HIGH for API definitions. Directly machine-parseable.
 **Why:**
 - Declarative YAML/JSON — agents parse without interpretation
 - Can generate server stubs, client libraries, and test harnesses
 - GitHub Copilot, Cursor, Claude Code all consume OpenAPI natively
 - Enables mock-server testing before implementation exists
 **When to use:** Any system with REST APIs, microservices, or client-server interfaces.
 **Limitations:** REST-only. Does not cover internal logic, async events, or architectural decisions.
 ### AsyncAPI
 **Format:** YAML/JSON for event-driven and message-based APIs
 **AI-readiness:** HIGH. Same YAML/JSON structure as OpenAPI but for async channels.
 **When to use:** Event-driven architectures, message queues (Kafka, RabbitMQ), WebSocket APIs.
 ### Design by Contract (DbC)
 **Format:** Preconditions, postconditions, and invariants expressed as assertions
 **AI-readiness:** VERY HIGH. Contracts:
 - Are machine-verifiable
 - Translate directly to assertions in generated code
 - Define clear success/failure boundaries
 - Enable fuzz testing and property-based verification
 **When to use:** Interface boundaries between components, library/API contracts, systems where correctness guarantees matter. Works alongside any other methodology — contracts complement rather than replace behavioral specs.
 ### Formal Methods — TLA+, Alloy
 **Format:** Mathematical models of system behavior, verified by model checkers
 **AI-readiness:** VERY HIGH for specific use cases (distributed systems, protocols, safety-critical components). The model checker provides provable guarantees.
 **When to use:**
 - Distributed/concurrent systems (race conditions, deadlocks, consensus)
 - Critical infrastructure where correctness is paramount
 - Protocol design (network, consensus, replication)
 - Systems where a bug costs >$1M
 **Tradeoff:** The "formal methods tax" — requires specialized expertise, is slow to write, and covers only specific properties (safety/liveness), not full system behavior. Use only for critical subsystems, not the entire codebase.
 ### Architecture Decision Records (ADRs)
 **Format:** Structured markdown with Context → Decision → Consequences
 **AI-readiness:** MEDIUM. ADRs are narrative documents, not executable. They provide context that informs AI code generation but do not directly drive it.
 **When to use:** Alongside behavioral specs. ADRs provide architectural context (why a decision was made, what alternatives were considered) that helps AI agents make consistent implementation choices.
 ### C4 Model
 **Format:** Hierarchical diagrams at 4 levels (Context → Container → Component → Code)
 **AI-readiness:** MEDIUM-HIGH for architecture. The structured hierarchy maps well to AI consumption when expressed as structured markdown or PlantUML, but the diagrams themselves require human interpretation.
 **When to use:** Defining system boundaries and component decomposition before AI agents implement individual containers/components.
 ### arc42
 **Format:** Structured template for software architecture documentation
 **AI-readiness:** MEDIUM. arc42 provides a comprehensive template (constraints, building block view, runtime view, deployment, cross-cutting concepts) that can feed into AI agents as architectural constraints, but it's prose-heavy.
 **When to use:** As the architectural companion to a behavioral SPEC.md, especially for complex systems with multiple quality concerns.
 ## Selecting a Methodology
 The AI software factory typically needs a **composite** approach — not a single methodology:
 | Concern | Best Methodology | AI-Readiness |
 |---------|-----------------|--------------|
 | What the system does (behavior) | BDD / Gherkin | HIGH |
 | How components communicate | OpenAPI / AsyncAPI | VERY HIGH |
 | Interface contracts | Design by Contract | VERY HIGH |
 | Architecture decisions | ADRs | MEDIUM |
 | System structure | C4 / arc42 | MEDIUM |
 | Critical correctness | TLA+ / Alloy | VERY HIGH (narrow scope) |
 | Business intent | User Stories | LOW (needs refinement) |
 The SPEC.md template in this skill's templates/ directory combines multiple approaches: structured Gherkin-like ACs for behavior, OpenAPI/YAML for interfaces, and prose sections for architecture context.
@@ -0,0 +1,113 @@
 # NFR Encoding for AI Specs
 Non-functional requirements (NFRs) are the hardest spec dimension for AI code generation. AI agents naturally optimize for functional correctness; NFRs are often the last thing they consider. This guide covers how to encode NFRs in machine-readable formats so AI agents treat them as first-class constraints.
 ## The Problem
 AI agents, given a behavioral spec, will produce working code that:
 - Works correctly for 1 user but fails at 1000
 - Handles the happy path but logs nothing
 - Is functionally correct but has a SQL injection vulnerability
 - Uses the correct algorithm but is 100x slower than required
 These are NFR failures. The agent didn't know the constraints because they weren't specified in a machine-actionable way.
 ## General Pattern
 Every NFR must include three things:
 1. **Dimension** — what is being measured (latency, availability, concurrency, etc.)
 2. **Threshold** — the specific, measurable boundary
 3. **Verification method** — how compliance is checked
 | Dimension | Threshold Format | Example |
 |-----------|-----------------|---------|
 | Latency | `X units at Y percentile under Z load` | `200ms at P95 under 1000 concurrent users` |
 | Throughput | `X operations per Y time unit` | `5000 requests/second sustained` |
 | Availability | `X% over Y time period` | `99.9% uptime measured monthly` |
 | Concurrency | `X simultaneous users/connections` | `5000 simultaneous WebSocket connections` |
 | Storage | `X units per Y` | `1TB data, 30-day retention` |
 | Recovery | `X time to recover from Y failure` | `<5 min RTO for AZ failure` |
 | Accuracy | `X% correct under Y conditions` | `99.5% classification accuracy on test set` |
 ## Encoding NFRs in SPEC.md
 Within the SPEC.md template, NFRs are specified as a table:
 ```markdown
 ## Non-Functional Requirements
 | ID | Requirement | Threshold | Verification Method |
 |----|-------------|-----------|-------------------|
 | NFR-001 | API response time | <200ms at P95 under 1000 concurrent requests | k6 load test with p95 assertion |
 | NFR-002 | Uptime | 99.9% availability | Prometheus alerting + SLO tracking |
 | NFR-003 | Auth security | OWASP ASVS Level 2 | Semgrep SAST + dependency audit |
 | NFR-004 | Write audit log | All writes to user data produce audit event | Audit log must exist and be immutable |
 | NFR-005 | Max memory per request | <256MB heap | Memory profiling in staging |
 ```
 The key insight: **each NFR must produce a PASS/FAIL verdict**, just like behavioral ACs. If you can't write a test for it, it's not an NFR — it's a hope.
 ## NFR by Category
 ### Performance
 | Dimension | How to Specify | Common Pitfall |
 |-----------|---------------|----------------|
 | Latency | Xms at Y percentile | Forgetting load conditions — "fast" is meaningless without concurrency |
 | Throughput | X operations/period | Mixing peak vs sustained — specify both |
 | Resource usage | X CPU, X memory, X storage | Not specifying units or measurement method |
 **Example:** "The search endpoint must respond within 500ms at P99 under 2000 req/s sustained load, measured by k6 on the staging environment. The API gateway must queue or reject requests exceeding this threshold, not crash."
 ### Security
 Security NFRs are unique: specifying them in the spec is itself a security best practice (shift-left security).
 | Concern | How to Specify |
 |---------|---------------|
 | Authentication | AuthN method (OAuth2, SAML, API keys), token format, expiry, scopes |
 | Authorization | AuthZ model (RBAC, ABAC), permission model, admin boundaries |
 | Input validation | Validation rules per field, injection prevention |
 | Secrets | Encryption at rest, in transit; secrets management approach |
 **Example:** "All API endpoints must validate JWTs from the OAuth2 provider before processing. Scopes are checked per RBAC matrix in docs/rbac.md. Input validation uses a whitelist approach — reject known-bad patterns at the API gateway level."
 ### Observability
 | Concern | How to Specify |
 |---------|---------------|
 | Logging | What events produce logs, log format (structured JSON), retention |
 | Metrics | What metrics are exposed (RED metrics for services: Rate, Errors, Duration) |
 | Tracing | Distributed tracing headers, span context propagation |
 **Example:** "Every API request produces a structured JSON log entry with: timestamp, request_id, method, path, status_code, duration_ms, user_id. The /metrics endpoint exposes Prometheus-formatted counters for request count, error count, and P50/P95/P99 latency."
 ### Reliability
 | Concern | How to Specify |
 |---------|---------------|
 | Fault tolerance | What failures the system survives without data loss |
 | Retry strategy | Backoff algorithm, max retries, circuit breaker thresholds |
 | Graceful degradation | What features degrade and how |
 **Example:** "The checkout service must survive any single downstream dependency failure without losing orders. Payments may queue for retry, but user session and cart data must persist. Circuit breakers open after 5 failures in 30 seconds."
 ## Encoding NFRs for Autonomous Agents
 For fully autonomous AI agents, NFRs need additional structure:
 ```markdown
 ### NFR Constraints for Implementation Agent
 The following constraints MUST be reflected in code architecture and dependencies, not just tested after implementation:
 1. **Database:** Use PostgreSQL 16. Read replicas for reporting queries. Connection pooling via PgBouncer.
 2. **Caching:** Redis for session cache (TTL: 30 min). No caching of user financial data.
 3. **Async:** Background jobs via RabbitMQ. No long-running processes in request handlers.
 4. **Observability:** OpenTelemetry instrumentation in every service. Export traces to Tempo.
 Implementation choices that violate these constraints without explicit spec amendment will be rejected at Gate 3.
 ```
 This gives the agent architectural guardrails before it makes technology choices that are expensive to undo.
@@ -0,0 +1,96 @@
 # Phase Gate Methodology
 The four gates that enforce quality at each SDD phase transition. Every gate asks the same question: **"Is the artifact for this phase complete, correct, and unambiguous enough for the next phase to proceed safely?"**
 ## The Four Gates
 ```
 SPECIFY → [GATE 1] → DECOMPOSE → [GATE 2] → IMPLEMENT → [GATE 3] → VERIFY → [GATE 4] → DELIVER
  Spec Review       Plan Review      Impl Review          Acceptance Review
 ```
 ## Gate 1: Spec Review
 **Reviews:** SPEC.md
 **Question:** Is the spec complete, unambiguous, and testable enough for work decomposition?
 **Checklist:**
 - [ ] Every acceptance criterion is testable (binary PASS/FAIL)
 - [ ] Edge cases are explicitly enumerated, not implied
 - [ ] Non-functional requirements have measurable thresholds
 - [ ] Scope boundary is clear (explicit in-scope AND out-of-scope)
 - [ ] Data contracts and interface definitions are sufficiently precise
 - [ ] No section leaves room for the agent to make an unguided assumption
 - [ ] Assumptions and open questions are documented
 ## Gate 2: Plan Review
 **Reviews:** TASK-PLAN.md
 **Question:** Does every spec requirement map to a task? Are dependencies real?
 **Checklist:**
 - [ ] Every specification requirement maps to at least one task
 - [ ] Dependencies are real and spec-derived (not invented)
 - [ ] Each task is independently implementable and verifiable
 - [ ] Task sizes are appropriate for a single implementation session (30-120 min)
 - [ ] The implementation handoff (CLAUDE.md, .cursorrules, AGENTS.md) accurately represents the spec and plan
 - [ ] No task exceeds the scope of any single spec section
 ## Gate 3: Implementation Review
 **Reviews:** Implementation output (code, config, docs) against TASK-PLAN.md
 **Question:** Does the implementation satisfy all acceptance criteria for completed tasks?
 This is NOT a general code review. It does not assess code style, test coverage, or architectural elegance. It checks only spec compliance.
 **Checklist:**
 - [ ] All task acceptance criteria are satisfied
 - [ ] Any deviations from the spec are documented (not silently introduced)
 - [ ] Implementation produces correct results for all specified inputs
 - [ ] Error states are handled per the spec
 - [ ] Interface contracts are honored (return types, error formats, status codes)
 ## Gate 4: Acceptance Review
 **Reviews:** VERIFICATION.md
 **Question:** Is the overall compliance score sufficient for delivery?
 **Checklist:**
 - [ ] All spec ACs are accounted for in the verification matrix
 - [ ] BLOCKING failures are resolved (none remain open)
 - [ ] CRITICAL failures have documented remediation plans or exceptions
 - [ ] Compliance score meets the project threshold (typically >90%)
 - [ ] Any exceptions are documented with owner and due date
 ## Gate Decision Format
 Every gate produces one of three verdicts:
 | Verdict | Meaning | What happens next |
 |---------|---------|-------------------|
 | APPROVED | Artifact passes all criteria. Next phase may proceed. | Deliver artifact to next phase |
 | CONDITIONS | Artifact passes subject to specific remediations that don't require full re-review | Deliver artifact + conditions list; next phase may proceed while conditions are resolved |
 | REJECTED | Artifact fails one or more criteria. Current phase must produce a revised artifact. | Return artifact to current phase; no downstream work starts |
 ## Finding Severity
 | Severity | Definition | Disposition |
 |----------|-----------|-------------|
 | BLOCKING | Issue makes the next phase impossible or produces guaranteed-defective output | Gate cannot pass |
 | CRITICAL | Issue significantly impacts quality but next phase can proceed with documented exception | Gate passes with conditions |
 | MINOR | Issue should be fixed but doesn't block the phase | Gate can pass with remediation plan |
 | INFO | Observation or suggestion, no correctness impact | Informational |
 ## Escalation
 When the reviewer and artifact author disagree on a finding:
 1. Document the disagreement — what the artifact says, what the reviewer found, why the author disagrees
 2. Escalate to the human orchestrator if the finding is BLOCKING or CRITICAL
 3. MINOR and INFO disagreements are resolved by the reviewer's determination — the gate is not delayed for editorial preferences
 ## The Gate Philosophy
 In SDD, quality is not enforced by code review — that's too late. Quality is enforced by the phase gate. A defect caught at Gate 1 (spec review) costs minutes to fix. The same defect caught at Gate 4 (acceptance review) costs hours — the implementation may need to be discarded and rewritten against a corrected spec.
 This is the fundamental insight: **shift quality left.** The cheapest defect is the one caught before a single line of code is written.
@@ -0,0 +1,75 @@
 # SDD Overview & Philosophy
 ## What Is Spec-Driven Development?
 Spec-Driven Development (SDD) is a methodology for building software where **the specification is the executable input** to a code generation pipeline. It synthesizes practices from Behavior-Driven Development (BDD), Design by Contract (DbC), Formal Methods (TLA+/Alloy), OpenAPI-first design, and lean phase-gate project management — organized around a central insight relevant to AI code generation.
 ## The Core Distinction
 Traditional requirements engineering produces documents that **describe** what the system should do. SDD produces specifications that **drive** what the system does.
 | Aspect | Traditional Requirements | SDD Spec |
 |--------|------------------------|----------|
 | Primary consumer | Humans | AI agents (also readable by humans) |
 | Purpose | Communication and alignment | Executable input to code generation |
 | Ambiguity tolerance | High — humans can ask questions | Zero — agents implement one interpretation |
 | Verification | Manual review | Automated acceptance criteria |
 | Format | Prose-heavy documents | Structured markdown + machine-readable formats |
 ## The Software Factory Metaphor
 SDD adopts the factory model for software development:
 | Factory Element | SDD Equivalent |
 |----------------|----------------|
 | Blueprints | Specification (SPEC.md) |
 | Routing plan | Work decomposition (TASK-PLAN.md) |
 | Work orders | Individual tasks with acceptance criteria |
 | Assembly line | AI code generation agents |
 | Quality control | Verification against spec |
 | Rework loop | Failed AC → spec review → regenerate |
 The metaphor is precise: a factory doesn't design products on the assembly line. The design (spec) is completed, reviewed, and approved before any fabrication (code generation) begins. Changes to the design go back through the design process, not through ad-hoc patches on the factory floor.
 ## The Feedback Loop
 When verification fails, the root cause can be in two places:
 | Failure Type | Root Cause | Response |
 |-------------|-----------|----------|
 | Implementation bug | Code doesn't meet spec | Regenerate code for affected task |
 | Spec ambiguity | Spec is unclear | Revise spec, regenerate code |
 | Missing edge case | Spec didn't enumerate | Add edge case to spec, regenerate |
 | NFR failure | Implementation choices | Revise task plan with NFR constraints |
 | Contract violation | Interface mismatch | Fix contract alignment across tasks |
 The feedback loop routes failures to their correct root cause. A spec defect should not be fixed by patching code — it should be fixed in the spec, and the code regenerated.
 ## Key Principles
 1. **Precision over clarity.** The AI cannot ask for clarification. A precise-but-dense spec is better than a readable-but-ambiguous one.
 2. **Completeness over brevity.** Every missing acceptance criterion is a missing feature. The cost of specifying an edge case up front is minutes; discovering it in production is hours or days.
 3. **Testability over descriptiveness.** An AC that cannot produce a CLEAR PASS or CLEAR FAIL is not an AC — it's a hope.
 4. **Gates catch defects early.** A defect caught at Gate 1 (spec review) costs minutes to fix. The same defect caught at Gate 4 (acceptance review) costs hours — the entire implementation may need to be discarded.
 5. **Spec is the single source of truth.** Every downstream artifact — task plan, architecture, implementation, tests — derives from and traces back to the spec. Deviations are defects unless explicitly documented.
 6. **Spec IS the test (when possible).** Acceptance criteria expressed in Gherkin (Given/When/Then) serve double duty as test cases. No separate test writing required.
 ## When to Use SDD
 SDD excels when:
 - AI agents are generating the code and cannot ask clarifying questions
 - The system has defined interfaces, contracts, or behavioral boundaries
 - Multiple AI agents work in parallel and need consistent guidance
 - Quality requirements justify spec investment (not throwaway prototypes)
 - The team can maintain spec discipline (spec + code are both versioned)
 SDD is overkill when:
 - The implementation is a throwaway prototype or spike
 - Requirements are genuinely unknown and emerge through exploration
 - The team lacks the discipline to maintain specs alongside code
 - The cost of writing a spec exceeds the cost of fixing bugs in production
@@ -0,0 +1,95 @@
 # Spec Quality Gates
 Seven gates every SPEC.md must pass before entering the code generation pipeline. These are validation checks, not editorial preferences — a failing gate means the spec is not executable by an AI agent.
 ## Gate 1: Testability
 Every acceptance criterion must produce a CLEAR PASS or CLEAR FAIL.
 **Test:** Read each AC aloud. Can you check "yes or no" against it? If the check requires interpretation ("what counts as responsive?" "what counts as efficient?"), the AC fails.
 **Wrong:** "The system should handle errors gracefully"
 **Right:** "When the payment API returns HTTP 503, the system displays 'Service temporarily unavailable' and retries automatically after 5 seconds"
 ## Gate 2: Edge Case Completeness
 Edge cases must be explicitly enumerated, not implied by "normal case" examples.
 **Test:** For each user story, list five things that could go wrong. If the spec doesn't address at least three, edge cases are underspecified.
 **Wrong:** "User uploads a profile photo" — no mention of what happens with empty files, wrong formats, oversized images
 **Right:** "User uploads a profile photo" with explicit ACs for: empty/corrupt file, wrong format, >5MB, non-image file
 Common edge case categories:
 - Empty/null inputs
 - Maximum/minimum boundary values
 - Invalid formats (wrong type, wrong encoding)
 - Concurrent access / race conditions
 - Network failures / timeouts
 - Authorization failures
 - Data that no longer exists (tombstones, soft deletes)
 ## Gate 3: Scope Boundary Clarity
 Out-of-scope must be as explicit as in-scope. Ambiguous scope boundaries are the most common source of drift — the implementation agent cannot distinguish "out of scope" from "the spec forgot to mention this."
 **Test:** Read the in-scope list. For each item, ask: "Could someone reasonably include broader functionality under this description?" If yes, the scope boundary is not tight enough.
 **Wrong:** "In scope: user authentication" — does this include password reset? social login? MFA? session management? API tokens?
 **Right:** "In scope: email/password authentication, password reset flow, session token management. Out of scope: social login (Google/GitHub OAuth), MFA/TOTP, API key authentication"
 ## Gate 4: Non-Functional Requirement Measurability
 NFRs must state a specific, measurable threshold and a verification method.
 **Test:** For each NFR, ask: "Can I write a test that fails if this threshold is not met?" If no, the NFR is not measurable.
 **Wrong:** "The system should be fast"
 **Right:** "Search responses must complete within 200ms at P95 under 1000 concurrent requests, verified by k6 load test with 95th percentile assertion"
 | NFR Type | Measurable Format | Verification Method |
 |----------|------------------|-------------------|
 | Performance | X units under Y load at Z percentile | Load test (k6, Locust) |
 | Availability | X% uptime over Y period | Monitoring + SLO |
 | Security | X controls, Y compliance standard | SAST scan, pen test |
 | Observability | X metrics + Y logging + Z tracing | Integration test |
 ## Gate 5: Data Contract Sufficiency
 Any interface between components must be specified at a level of detail enabling independent implementation of both sides.
 **Test:** Could two implementation agents build the producer and consumer independently using only this spec and their shared contracts? If they'd need to coordinate in real time, the data contracts are insufficient.
 **Wrong:** "API endpoint: POST /orders"
 **Right:** "POST /orders accepts JSON body {customerId, items[], shippingAddress}. Returns 201 with {orderId, status}. Error responses: 400 for validation failures, 422 for out-of-stock items."
 Data contract minimum:
 - All request/response schemas (field names, types, required/optional, constraints)
 - Status codes and error formats for every endpoint
 - Event/stream schemas if applicable
 - Auth requirements (method, scopes, token format)
 ## Gate 6: Assumption Inventory
 Every assumption made during specification must be documented with an impact assessment.
 **Test:** Count the undocumented assumptions. If you can find any not in the Assumptions section, the inventory is incomplete. Ask "what would have to be true for this spec to be wrong?" for each section.
 **Wrong:** No Assumptions section at all
 **Right:** "Assumption: Users have stable internet connectivity. Impact if wrong: offline mode is not specified, retry logic may be insufficient."
 Common undocumented assumptions:
 - Network reliability assumptions
 - User behavior assumptions (will users follow the happy path?)
 - Data quality assumptions (will input data be clean?)
 - Environment assumptions (hardware, OS, dependencies)
 - Third-party service assumptions (availability, latency, rate limits)
 ## Gate 7: AI Agent Readiness
 The spec must be consumable by an AI coding agent without requiring clarification.
 **Test:** Read the spec as if you cannot ask a single follow-up question. Mark every phrase that could be interpreted in more than one way. Each marked phrase is a spec defect.
 **Wrong:** "The system should handle common file formats" — the agent must guess what "common" means
 **Right:** "The system must accept CSV (RFC 4180), JSON, and XML files. Reject all other formats with error code 400 and message 'Unsupported format: {format}'"
@@ -0,0 +1,116 @@
 #!/usr/bin/env bash
 # spec-quality-check.sh - Validates that a SPEC.md has all required sections.
 # Usage: spec-quality-check.sh [path/to/SPEC.md]
 # Returns 0 if all required sections are present, 1 if any are missing.
 set -euo pipefail
 SPEC="${1:-SPEC.md}"
 if [ ! -f "$SPEC" ]; then
  echo "ERROR: $SPEC not found"
  exit 1
 fi
 MISSING=0
 # Helper: check if a section exists as a heading
 section_exists() {
  local section="$1"
  grep -qi "^##\s*$section\|^###\s*$section" "$SPEC" && return 0
  return 1
 }
 # Helper: check if "Acceptance Criteria" appears under "User Stories"
 # by looking for AC patterns ([AC-XXX] or "### Acceptance Criteria")
 acceptance_criteria_under_stories() {
  # Check for [AC-XXX.YY] references under a User Stories heading
  grep -qi "\[AC-\d" "$SPEC" && return 0
  # Check for ### Acceptance Criteria sub-headings
  grep -qi "^###\s*Acceptance Criteria" "$SPEC" && return 0
  return 1
 }
 echo "Checking: $SPEC"
 echo ""
 # Problem Statement
 if section_exists "Problem Statement"; then
  echo "  ✓ Problem Statement"
 else
  echo "  ✗ Problem Statement"
  MISSING=$((MISSING + 1))
 fi
 # Success Criteria
 if section_exists "Success Criteria"; then
  echo "  ✓ Success Criteria"
 else
  echo "  ✗ Success Criteria"
  MISSING=$((MISSING + 1))
 fi
 # Scope (In Scope or Out of Scope)
 if section_exists "In Scope"; then
  echo "  ✓ In Scope"
 else
  echo "  ✗ In Scope"
  MISSING=$((MISSING + 1))
 fi
 if section_exists "Out of Scope"; then
  echo "  ✓ Out of Scope"
 else
  echo "  ✗ Out of Scope"
  MISSING=$((MISSING + 1))
 fi
 # User Stories
 if section_exists "User Stories"; then
  echo "  ✓ User Stories"
 else
  echo "  ✗ User Stories"
  MISSING=$((MISSING + 1))
 fi
 # Acceptance Criteria — checks top-level section OR inline under user stories
 if section_exists "Acceptance Criteria" || acceptance_criteria_under_stories; then
  echo "  ✓ Acceptance Criteria (found: $(grep -c '\[AC-\|Acceptance Criteria' "$SPEC" || true) references)"
 else
  echo "  ✗ Acceptance Criteria"
  MISSING=$((MISSING + 1))
 fi
 # Edge Cases — check top-level section OR inline per-user-story
 if section_exists "Edge Cases"; then
  echo "  ✓ Edge Cases (top-level section)"
 elif grep -qi "Edge Cases" "$SPEC"; then
  echo "  ✓ Edge Cases (inline per user story)"
 else
  echo "  ✗ Edge Cases"
  MISSING=$((MISSING + 1))
 fi
 # Non-Functional Requirements
 if section_exists "Non-Functional Requirements" || section_exists "NFR"; then
  echo "  ✓ Non-Functional Requirements"
 else
  echo "  ✗ Non-Functional Requirements"
  MISSING=$((MISSING + 1))
 fi
 # Assumptions
 if section_exists "Assumptions"; then
  echo "  ✓ Assumptions & Open Questions"
 else
  echo "  ✗ Assumptions & Open Questions"
  MISSING=$((MISSING + 1))
 fi
 echo ""
 if [ "$MISSING" -eq 0 ]; then
  echo "PASS: All required sections present in $SPEC"
  exit 0
 else
  echo "FAIL: $MISSING required section(s) missing from $SPEC"
  exit 1
 fi
@@ -0,0 +1,79 @@
 #!/usr/bin/env bash
 # spec-to-tasks.sh - Validates that every spec AC has a covering task.
 # Usage: spec-to-tasks.sh [path/to/TASK-PLAN.md] [path/to/SPEC.md]
 # Returns 0 if all spec ACs are covered, 1 if any are uncovered.
 set -euo pipefail
 TASK_PLAN="${1:-TASK-PLAN.md}"
 SPEC="${2:-SPEC.md}"
 if [ ! -f "$TASK_PLAN" ]; then
  echo "ERROR: $TASK_PLAN not found"
  exit 1
 fi
 if [ ! -f "$SPEC" ]; then
  echo "WARNING: $SPEC not found — checking task self-consistency only"
  SPEC=""
 fi
 echo "Checking task coverage in: $TASK_PLAN"
 echo ""
 # Extract AC references from the task plan
 # Matches patterns like: AC-001.1, AC-002.x, etc.
 AC_REFS=$(grep -oE 'AC-[0-9]+(\.[0-9]+)?' "$TASK_PLAN" 2>/dev/null || true)
 if [ -z "$AC_REFS" ]; then
  echo "WARNING: No AC references found in task plan"
  echo "  Expected format: AC-NNN.MMM (e.g., AC-001.1, AC-002.1)"
  echo ""
  echo "PASS: Task coverage check skipped (no ACs to match)"
  exit 0
 fi
 UNIQUE_ACS=$(echo "$AC_REFS" | sort -u)
 AC_COUNT=$(echo "$UNIQUE_ACS" | wc -l | tr -d ' ')
 echo "Unique ACs referenced in tasks: $AC_COUNT"
 echo ""
 # If spec is provided, check that key ACs appear in the task plan
 if [ -n "$SPEC" ]; then
  EXTRACTED_ACS=$(grep -oE '\[AC-[0-9]+(\.[0-9]+)?\]' "$SPEC" 2>/dev/null | tr -d '[]' | sort -u || true)
  if [ -z "$EXTRACTED_ACS" ]; then
    echo "No structured AC tags ([AC-XXX]) found in SPEC.md"
    echo "  Try checking inline AC patterns..."
    EXTRACTED_ACS=$(grep -oE 'AC-[0-9]+(\.[0-9]+)?' "$SPEC" 2>/dev/null | sort -u || true)
  fi
  if [ -n "$EXTRACTED_ACS" ]; then
    SPEC_AC_COUNT=$(echo "$EXTRACTED_ACS" | wc -l | tr -d ' ')
    echo "ACs found in spec: $SPEC_AC_COUNT"
    MISSING_ACS=0
    COVERED_ACS=0
    for ac in $EXTRACTED_ACS; do
      if echo "$AC_REFS" | grep -qF "$ac"; then
        COVERED_ACS=$((COVERED_ACS + 1))
      else
        echo "  UNCOVERED: $ac in spec but not referenced in task plan"
        MISSING_ACS=$((MISSING_ACS + 1))
      fi
    done
    echo ""
    echo "Coverage: $COVERED_ACS / $SPEC_AC_COUNT ACs covered"
    if [ "$MISSING_ACS" -gt 0 ]; then
      echo "FAIL: $MISSING_ACS AC(s) from spec not covered by tasks"
      exit 1
    fi
  else
    echo "No AC patterns found in SPEC.md (checked both [AC-XXX] and AC-XXX formats)"
  fi
 fi
 echo ""
 echo "PASS: Task coverage validation complete"
 exit 0
@@ -0,0 +1,41 @@
 # Gate Decision: <Project / Phase>
 ## Verdict
 **APPROVED** / **CONDITIONS** / **REJECTED**
 **Gate:** Gate 1 (Spec Review) / Gate 2 (Plan Review) / Gate 3 (Implementation Review) / Gate 4 (Acceptance Review)
 **Artifact under review:** <path to artifact>
 **Reviewer:** <name>
 **Date:** <date>
 ## Summary
 <One-paragraph summary: what was evaluated, the key finding, and why the verdict was reached.>
 ## Findings
 ### Finding 1: <Title>
 - **Severity:** BLOCKING / CRITICAL / MINOR / INFO
 - **Location:** <artifact> — <section>
 - **Description:** <what was found>
 - **Recommendation:** <what should change>
 ### Finding 2: <Title>
 ...
 ## Conditions (if verdict is CONDITIONS)
 | # | Condition | Owner | Due By |
 |---|-----------|-------|--------|
 | 1 | <remediation required> | <name> | <date/gate> |
 ## Revision History
 | Version | Date | Verdict | Author |
 |---------|------|---------|--------|
 | 1.0 | <date> | <verdict> | <name> |
@@ -0,0 +1,81 @@
 # Specification: <Project / Feature Name>
 ## Status
 - **Author:** <name>
 - **Version:** 0.1.0 (draft)
 - **Status:** Draft / Under Review / Approved
 - **Reviewed by:** <reviewer>
 - **Gate verdict:** Pending / Approved / Conditions / Rejected
 ## Problem Statement
 <One to three sentences describing the problem this specification addresses. What gap exists in the current system? What user need is unmet? Why is this worth building?>
 ## Success Criteria
 <Measurable outcomes that define success. These are NOT acceptance criteria for individual features — they are the overall outcomes justifying the investment. Example: "Reduce account creation time from 90s to under 30s.">
 ## Scope
 ### In Scope
 - <Capability or behavior included>
 - <Capability or behavior included>
 ### Out of Scope (Explicit)
 - <Capability explicitly excluded — prevents scope creep>
 - <Capability explicitly excluded>
 ## User Stories
 ### US-001: <Story Title>
 **Priority:** P0 / P1 / P2 / P3
 **Description:** As a <role>, I want <capability> so that <benefit>.
 **Acceptance Criteria:**
 1. [AC-001.1] Given/When/Then or pass/fail condition
 2. [AC-001.2] Given/When/Then or pass/fail condition
 **Edge Cases:**
 - <Edge case description — what happens when>
 - <Edge case description>
 ### US-002: <Story Title>
 ...
 ## Non-Functional Requirements
 | ID | Requirement | Threshold | Verification Method |
 |----|-------------|-----------|-------------------|
 | NFR-001 | Response time | < 200ms at P95 | Load test |
 | NFR-002 | Availability | 99.9% uptime | Monitoring |
 | NFR-003 | Security | <describe requirement> | <describe how verified> |
 ## Data Contracts & Interfaces
 <Schemas, API signatures, event definitions. Stubs are acceptable at this phase — identify what contracts exist even if refined later.>
 ### <Interface Name>
 ```
 <Schema or signature>
 ```
 ## Assumptions & Open Questions
 | # | Assumption / Question | Impact if Wrong | Resolution |
 |---|----------------------|----------------|------------|
 | 1 | <assumption> | <what breaks> | <how/when resolved> |
 | 2 | <open question> | <what blocks> | <how/when resolved> |
 ## Revision History
 | Version | Date | Author | Change |
 |---------|------|--------|--------|
 | 0.1.0 | <date> | <name> | Initial draft |
@@ -0,0 +1,82 @@
 # Task Plan: <Project / Feature Name>
 ## Source Specification
 - **Spec:** `SPEC.md` (version <x.y.z>)
 - **Spec review gate:** Approved / Conditions
 - **Plan author:** <name>
 - **Plan version:** 0.1.0
 ## Phase Overview
 | Metric | Value |
 |--------|-------|
 | Total tasks | <N> |
 | Task groups | <N> |
 | Critical path | <N> tasks |
 | Estimated total effort | <estimate> |
 | Dependencies | <N> real dependencies |
 ## Execution Order
 <Recommended execution order. Start with foundational tasks (contracts, schemas, interfaces), then core logic, then integration, then edge cases and error handling.>
 ## Task Groups
 ### Group 1: <Name>
 **Spec reference:** `SPEC.md` — Section <X>
 **Preconditions:** <none or reference to prerequisite groups>
 **Dependencies:** <none or list of prerequisite tasks>
 | ID | Task | Spec Ref | Est. Size | Preconditions |
 |----|------|----------|-----------|---------------|
 | T-001 | <task name> | AC-001.x | S/M/L | <none or T-XXX> |
 | T-002 | <task name> | AC-001.x | S/M/L | T-001 |
 ### Group 2: <Name>
 ...
 ## Critical Path
 <Chain of dependent tasks determining overall timeline. Tasks on the critical path have zero float — delay in any one delays the entire plan.>
 ## Task Cards
 Copy this structure for each task.
 ---
 ### T-001: <Task Name>
 - **Type:** feature / refactor / test / docs / config
 - **Spec reference:** `SPEC.md` — US-001, AC-001.1, AC-001.2
 - **Dependencies:** <none or T-XXX>
 - **Estimated size:** Small (<1h) / Medium (1-2h) / Large (2-4h)
 - **Preconditions:** <what must exist before this task starts>
 **Description:**
 <What this task implements, derived from the spec.>
 **Acceptance Criteria:**
 - [ ] AC-001.1: <condition — directly from SPEC.md>
 - [ ] AC-001.2: <condition — directly from SPEC.md>
 **Implementation Agent Directives:**
 <This section becomes the context file (CLAUDE.md / .cursorrules / AGENTS.md) for the implementation agent running this task.>
 - Load SPEC.md section <X> for behavioral requirements
 - Load the interface contract from SPEC.md section <Y>
 - Implement in this scope: <commit scope>
 - Do NOT implement: <explicit out-of-scope for this task>
 ---
 ## Revision History
 | Version | Date | Author | Change |
 |---------|------|--------|--------|
 | 0.1.0 | <date> | <name> | Initial plan from SPEC.md v0.x |
@@ -0,0 +1,84 @@
 # Verification Report: <Project / Feature Name>
 ## Source Specification
 - **Spec:** `SPEC.md` (version <x.y.z>)
 - **Spec review gate:** Approved / Conditions
 - **Plan reference:** `TASK-PLAN.md` (version <x.y.z>)
 - **Verification author:** <name>
 - **Verification date:** <date>
 - **Verification mode:** automated / manual / interactive
 ## L1: Summary
 | Metric | Value |
 |--------|-------|
 | Total ACs tested | <N> |
 | Pass | <N> |
 | Fail | <N> |
 | Blocking | <N> |
 | Critical | <N> |
 | Minor | <N> |
 | Compliance score | <XX.X%> |
 | **Gate Verdict** | **APPROVED / CONDITIONS / REJECTED** |
 ### Gate Verdict Rationale
 <One paragraph explaining the verdict based on severity rules: 0 BLOCKING + 0 CRITICAL = APPROVED; 0 BLOCKING + <=2 CRITICAL with remediation plans = CONDITIONS; any BLOCKING = REJECTED; <90% pass rate without exception = REJECTED.>
 ## L2: Verification Matrix
 ### Per-Story Results
 | Story / Feature | ACs | Pass | Fail | Blocking | Verdict |
 |-----------------|-----|------|------|----------|---------|
 | <US-001> | <N> | <N> | <N> | <N> | PASS / FAIL |
 | <US-002> | <N> | <N> | <N> | <N> | PASS / FAIL |
 ### Verification Dimensions Coverage
 | Dimension | Score | Notes |
 |-----------|-------|-------|
 | Functional Correctness | <N/N> | |
 | Behavioral Completeness | <N/N> | |
 | Contract Compliance | <N/N> | |
 | Non-Functional Requirements | <N/N> | |
 | Negative Testing | <N/N> | |
 ## L3: Failure Dossiers
 ### <AC-ID>: <Description>
 - **Severity:** BLOCKING / CRITICAL / MINOR / INFO
 - **Story:** <US-00X>
 - **Verification dimension:** <Functional / Behavioral / Contract / NFR / Negative>
 **Expected behavior (from spec):**
 <What the acceptance criterion says should happen>
 **Actual behavior (from implementation):**
 <What actually happens>
 **Evidence:**
 <Test output, code inspection, observation>
 **Remediation recommendation:**
 <What to fix, why this severity, how to verify the fix passes the AC>
 ---
 ### <AC-ID>: <Description>
 ...
 ## SOURCES
 | Reference | Description |
 |-----------|-------------|
 | `SPEC.md` | Source specification document |
 | <AC-specific ref> | Section X — user story for this AC |
 ## Revision History
 | Version | Date | Author | Change |
 |---------|------|--------|--------|
 | 1.0 | <date> | <name> | Initial verification |