git:20260319.d4659ca to git:20260327.17e6b46

8 added, 97 removed. Audit A to A.

---

name: sdd-methodology

description: "Guides agents through the Spec-Driven Development (SDD) lifecycle: specification authoring, technical planning, task decomposition, and implementation execution. Use when working on features that follow a structured development process, when creating specs, plans, or tasks, when the user mentions SDD, spec-driven, specification workflow, or when gating rules between phases need enforcement."

---

# Spec-Driven Development Methodology

- ## Project Bootstrap

- Before feature delivery begins, a project can establish shared Project Context Specs and Workspace Control Plane governance:

- 1. **Product Strategist** *(optional)* — Create or refine `specs/prd.md` and register it as the canonical Product Document. Output: `specs/prd.md`, `.github/sddp-config.md` update

- 2. **Solution Architect** *(optional)* — Create or refine `specs/sad.md` and register it as the canonical Technical Context Document. Output: `specs/sad.md`, `.github/sddp-config.md` update

- 3. **Init** — Establish or amend `project-instructions.md` and preserve or adopt Project Context Specs references in `.github/sddp-config.md`. Output: `project-instructions.md`, `.github/sddp-config.md` updates

- Project bootstrap does **not** change the strict feature delivery order below.

- ## Feature Delivery Lifecycle

- SDD enforces a strict phase order. Each phase produces artifacts that gate the next:

- 1. **Specify** — Capture WHAT users, systems, or operators need and WHY. Output: `spec.md`

- 2. **Clarify** — Reduce ambiguity via targeted questions. Output: updated `spec.md`

- 3. **Plan** — Design HOW to build it. Output: `plan.md`, `research.md`, `data-model.md`, `contracts/`

- 4. **Tasks** — Decompose into actionable work items. Output: `tasks.md`

- 5. **Implement** — Execute tasks phase-by-phase. Output: source code + marked tasks + `.completed` marker

- 6. **Quality Control** — Verify implementation against spec, run tests, static analysis, and security audit. Output: `qc-report.md`, `.qc-passed` marker

- ### Phase Gating Rules

- - **Specify → Clarify**: `spec.md` must exist

- - **Clarify → Plan**: `spec.md` must exist (clarify is optional but recommended)

- - **Plan → Tasks**: `spec.md` + `plan.md` must exist

- - **Tasks → Implement**: `spec.md` + `plan.md` + `tasks.md` must exist

- - **Implement**: All checklists in `checklists/` must pass (or user explicitly overrides)

- - **Implement → QC**: `.completed` marker must exist in `FEATURE_DIR`

- - **Checklist**: After generation, the `TestEvaluator` auto-evaluates items against artifacts, resolves gaps, and asks the user about ambiguous items

- If a required artifact is missing, stop and direct the user to the correct prior phase.

- ### Gate Failure Error Template

- When reporting a gate failure to the user, always include all three elements:

- 1. **What is missing and where**: Name the missing artifact and its expected full path — e.g., "Missing `spec.md` at `specs/00001-user-auth/spec.md`"

- 2. **Most likely cause**: Brief explanation — e.g., "This file is created by `/sddp-specify`. It does not exist yet in your feature directory."

- 3. **Copy-pasteable fix command**: Include context from the branch/feature name — e.g., "`/sddp-specify Users can register and log in with email and password`"

- Never output a bare "Cannot proceed without [artifact]" without these three elements.

- ## Feature Workspace Convention

- Every feature's artifacts live at `specs/<feature-folder>/`.

- - If the current branch matches `#####-feature-name`, agents use the branch name.

- - If a git repo is active but the branch does not match, full-mode agents prompt for a folder name and validate new names in `00001-feature-name` format.

- - If no git repo is active, full-mode agents derive a suggested folder name from the feature description and validate new names in `00001-feature-name` format.

- - If git is in detached HEAD or branch resolution fails for another reason, full-mode agents halt and tell the user to fix the repository state and re-run the workflow.

- - Existing non-prefixed Feature Workspaces are grandfathered and remain usable when already present.

- Detect the branch via: `git rev-parse --abbrev-ref HEAD`

- Standard layout:

- ```

- specs/prd.md # Project Context Specs: Product Requirements Document (optional but preferred)

- specs/sad.md # Project Context Specs: Software Architecture Document (optional but preferred)

- project-instructions.md # Workspace Control Plane: project governance managed by /sddp-init

- .github/sddp-config.md # Workspace Control Plane: shared context and document registration

+ > **Lifecycle, phase gates, conventions, task format, and markers** are defined in `AGENTS.md` (injected into every conversation context). Do not duplicate those rules here.

- specs/<feature-folder>/

- ├── spec.md, plan.md, tasks.md

- ├── research.md, data-model.md

- ├── contracts/

- ├── checklists/

- ├── qc-report.md # Generated by /sddp-qc

- ├── manual-test.md # Generated by /sddp-qc when manual verification needed

- ├── .completed # Set by /sddp-implement

- └── .qc-passed # Set by /sddp-qc on success

- ```

+ ## Project Bootstrap

- ## Project Instructions

+ Before feature delivery, a project can establish shared context:

- The file `project-instructions.md` contains non-negotiable project principles.

+ 1. **Product Strategist** *(optional)* — `specs/prd.md` + `.github/sddp-config.md`

+ 2. **Solution Architect** *(optional)* — `specs/sad.md` + `.github/sddp-config.md`

+ 3. **Init** — `project-instructions.md` + `.github/sddp-config.md`

- - **During Planning**: Run an Instructions Check — verify the plan aligns with every principle

- - **During Analysis**: Project instructions violations are always CRITICAL severity

- - **Project instructions changes**: Must go through `/sddp-init` with semantic versioning

- - Project instructions supersede all other practices

+ Bootstrap does **not** change the strict feature delivery order in `AGENTS.md`.

## Quality Philosophy: "Unit Tests for English"

Checklists validate the QUALITY of requirements, not implementation behavior:

- ✅ "Are error handling requirements defined for all API failure modes?"

- ❌ "Verify the API returns proper error codes"

- The full quality framework is in [references/quality-dimensions.md](references/quality-dimensions.md) — read it only when performing quality analysis, checklist generation, or evaluating requirements quality. Not needed for general phase gating or directory convention lookups.

- ## Priority System

- Product specs use user stories; technical and operational specs use objectives. All use priorities P1 (most critical) through P3+:

- - Each story or objective must be **independently testable/verifiable** — implementing just P1 yields a viable MVP

- - Prioritize clarifications by impact: scope > security/privacy > UX or operator flow > technical details

- - Maximum 3 `[NEEDS CLARIFICATION]` markers in any spec

- ## Task Format

- ```

- - [ ] T### [P?] [US#|OBJ#?] {(FR|TR|OR|RR)-###?} Description with file path

- ```

- - `[P]` = parallelizable (different files, no dependencies)

- - `[US#]` = product user story reference

- - `[OBJ#]` = technical or operational objective reference

- - `{(FR|TR|OR|RR)-###}` = links task to requirement(s) from spec

- - Phases: optional Setup → optional Foundational (cross-work-item blockers) → Delivery Work Items (by priority) → optional Polish

- - Mark completed: `- [ ]` → `- [X]`

+ The full quality framework is in [references/quality-dimensions.md](references/quality-dimensions.md) — read it only when performing quality analysis, checklist generation, or evaluating requirements quality.