sk-spec-driven-development

name	sk-spec-driven-development
description	Establishes a formal spec→plan→tasks→implement contract for multi-step feature work. Use when authoring multi-step pipelines, building new features, refactoring systems, or when a request is too ambiguous for direct execution and a verified specification must precede implementation.
user-invocable	false

Spec-Driven Development (SDD) — Workflow Reference

The canonical contract defining WHAT and WHY, focusing on user journeys and success criteria. The technical architecture document defining HOW, including stack, API contracts, and risk mitigations. A decomposition of the plan into small, independent, and verifiable units of work (T-1, T-2, etc.).

The Four Phases

### 1. SPECIFY (`/specify`) - **Goal**: Define the outcome without implementation details. - User journeys, success criteria (AC), non-goals, and constraints are captured. - **Invariant**: The spec must be readable without code; it must answer "What does done look like?"

2. PLAN (/plan)

• Goal: Design the technical implementation.
• Tech stack, architecture (contracts/schemas), dependency matrix, and risks are defined.
• Ambiguities surfaced in the spec are resolved via /clarify.

3. TASKS (/tasks)

• Goal: Decompose the plan into chunks (5–30 min per agent session).
• Each task requires a stable ID, description, file list, and verifiable AC.
• Validation: Implementation is blocked if any spec AC lacks a corresponding task.

4. IMPLEMENT (/implement)

• Goal: Execute tasks in parallel where dependencies allow.
• Each task runs through an isolated RPI loop (Research, Plan, Implement).
• pipeline-state.json is reconciled upon completion or failure of each task.

**MANDATORY HUMAN APPROVAL**: Before dispatching parallel implementation, `spec.md` and `tasks.md` are presented to the user. Execution waits for explicit `APPROVE`. A misunderstood spec at this stage will cause all parallel workers to fail simultaneously.

Artifact Skeletons

### `spec.md` - **Context**: Motivation for the change. - **User Journeys**: Scenarios and expected outcomes. - **Success Criteria**: Numbered list of verifiable ACs. - **Non-Goals**: Explicit out-of-scope items.

plan.md

• Architecture: Layer diagrams and data flow.
• API Contracts: Schemas and signatures.
• Dependency Matrix: Upstream/downstream component mapping.

tasks.md

• ID: T-1, T-2, etc.
• Acceptance: A concrete command or check that returns pass/fail.
• Depends On: Upstream task IDs.

Pattern Mapping

<mapping_table>

SDD Command	Pattern 5 Phase	Outcome
/specify	Phase 1	spec.md
/plan	Phase 2	plan.md
/tasks	Phase 3	tasks.md
/analyze	Phase 4	Pre-gate validation
Approval	Phase 4b	Human authorization
/implement	Phase 5	Parallel execution
</mapping_table>

- Every acceptance criterion in `spec.md` MUST be mapped to at least one task in `tasks.md`. - Tasks must be small enough for a single agent session (avoiding context bloat). - Strict write/review isolation is maintained during the implementation phase.

Reference Files

• sk-4d-method/SKILL.md — Per-invocation wrapper.
• sk-pipeline-patterns/SKILL.md — Pattern 5 definition.
• sk-write-review-isolation/SKILL.md — Implementation review loop.
• sk-pipeline-state/SKILL.md — State reconciliation rules.