Spec Skill

Specification Driven Development

TRIGGER when: starting a new project from scratch; managing complex multi-phase work that needs structured plan→execute→verify loops; ensuring a verification closure (must_haves + UAT) before marking work done; onboarding a brownfield codebase (/spec-map-codebase); running an ad-hoc task that still wants atomic commits and optional verification (/spec-quick).

Overview

Spec-driven-dev is a structured development system that transforms vague ideas into executable plans through systematic questioning, domain/use-case discovery when humans interact with the system, research, planning, and verification. Inspired by get-shit-done (GSD), it provides templates and workflows for managing software projects from conception to completion.

CRITICAL RULE: You must STOP and WAIT for user confirmation at specific checkpoints. Do not rush from planning to execution in a single turn.

Commands

All commands are invoked as /spec-<name> (e.g., /spec-new, /spec-plan 1). Commands automatically load the relevant workflow docs.

Core Workflow Commands

Utility Commands

Command Workflow Mapping

Quick Usage Examples

/spec-new                          # Start fresh project
/spec-plan 1                       # Plan phase 1
/spec-execute 1                    # Execute phase 1
/spec-verify 1                     # Verify phase 1
/spec-transition                   # Move to phase 2
/spec-health --repair              # Fix missing planning files
/spec-quick "Add dark mode toggle" # Ad-hoc task
/spec-map-codebase api             # Analyze API layer

Configuration

Project settings are stored in .planning/config.json. Key settings:

See templates/config.json for the full schema with all workflow toggles, gates, safety settings, and parallelization controls.

Core Workflow

1. Project Initialization

Start by creating the foundational project context:

# Create project planning structure
mkdir -p .planning/phases

Key documents created:

• .planning/PROJECT.md - Project vision and context
• .planning/DOMAIN.md - Business vocabulary and domain concepts when people interact with the system
• .planning/USE_CASES.md - Actors, roles, and role-to-domain operations when people interact with the system
• .planning/REQUIREMENTS.md - Scoped feature requirements
• .planning/ROADMAP.md - Phase decomposition
• .planning/STATE.md - Project memory and decisions
• .planning/config.json - Workflow preferences

2. Discovery Discussion (Interactive - BLOCKING)

Goal: Fully understand the user's intent before generating any files. You MUST engage in a dialogue.

Resources:

• Refer to references/questioning.md for questioning strategies and mental models.

Actions:

1. Start Open: Ask "Tell me about what you want to build."
2. Loop (Ask -> Wait -> Ask):
   • Ask clarifying questions about goals, constraints, domain boundaries, actors, and tech stack.
   • WAIT for the user's answer.
   • Challenge vagueness and clarify boundaries based on the answer.
   • REPEAT until you have a clear mental model.
3. Summarize: Present a summary of requirements and scope.
4. STOP: Ask "Do we have enough details to proceed to planning? Or should we discuss more?"
5. WAIT: Do not generate any Roadmap or Plan files until the user explicitly says "Proceed to Plan".

3. Domain & Use-Case Gate

Only proceed here after user confirmation.

Before writing REQUIREMENTS.md or ROADMAP.md, decide whether humans interact with the system.

The gate is REQUIRED when:

• The system has a UI, app, dashboard, form, human-facing CLI, chat flow, or workflow.
• The user asks to "build a system/app/tool/page/feature" where a person will create, view, edit, review, configure, approve, learn, buy, search, or operate something.
• Different people may use the product differently.
• There are roles, derived access differences, ownership, collaboration, review, approval, learning, commerce, or administration.
• The project has business objects whose meaning, state, ownership, or lifecycle affects behavior.

The gate can be LIGHTWEIGHT/SKIPPED when:

• The work is a pure library, internal refactor, infrastructure change, CI/build task, or machine-only integration.
• The phase changes implementation only and does not introduce or alter human-facing behavior.

Actions when required:

1. Define top-level concepts first: Create .planning/DOMAIN.md from templates/DOMAIN.md. Start with the largest meaningful modules/entities, then recursively decompose only as far as requirements, data, behavior, and verification need.
2. Keep domain discovery continuous: Do not treat DOMAIN.md/USE_CASES.md as a separate detour. Their concepts and use cases must flow directly into REQUIREMENTS.md, ROADMAP.md, phase CONTEXT.md, PLAN.md must_haves, and UAT.
3. Define actors/roles: Create .planning/USE_CASES.md from templates/USE_CASES.md. Identify roles and their goals.
4. Map role operations: For each role, map what they can do to domain concepts and what outcome results.
5. Derive access rules from behavior: Do not invent permissions as a separate design layer. If only Parent can set word-card scope and Student is not given that use case, then scope-setting is Parent-only until the user says otherwise.
6. Resolve unstable terms: If a term like "card", "project", "account", "record", or "workspace" is ambiguous, clarify it before requirements.
7. STOP if unstable: Do not decompose roadmap while core concepts, actors, or actor-to-concept operations remain ambiguous.

Actions when not required:

1. Record Interaction Gate: Not required and the reason in DOMAIN.md/USE_CASES.md if the files are being generated.
2. Proceed directly to requirements and roadmap.

4. Requirements Extraction

Convert confirmed discovery into scoped, traceable requirements.

Rules:

• For human-interaction systems, every v1 user-facing requirement must trace to at least one use case and at least one domain concept.
• Avoid generic "User can..." when roles differ. Prefer "[Role] can [operation] [domain concept] so that [outcome]."
• Access control is derived from the use-case matrix and explicit boundaries. Missing role-operation pairs are unconfirmed: do not implement or expose them silently, and ask or defer until the user expands the use case.
• Requirements are the continuation of the use-case model, not a new feature list. Preserve actor, operation, domain concept, and outcome through requirement IDs.
• Implementation-only work can still be tracked as technical requirements, but must not replace the role/use-case model for product behavior.

5. Roadmap Planning

Only proceed here after user confirmation. Decompose the confirmed requirements into a phased roadmap:

Phase structure:

• Integer phases (1, 2, 3): Planned milestone work
• Decimal phases (2.1, 2.2): Urgent insertions
• Dependency tracking: Clear phase dependencies
• Success criteria: Observable behaviors for verification

6. Per-Phase Analysis & Discussion (BLOCKING)

Before planning every phase, re-analyze context and run a focused discussion loop.

Resources:

• Refer to references/questioning.md for phase-level clarification patterns.

Actions:

1. Analyze Phase Context: Review .planning/PROJECT.md, .planning/DOMAIN.md, .planning/USE_CASES.md, .planning/ROADMAP.md, .planning/STATE.md, and dependency phases.
2. Loop (Ask -> Wait -> Ask):
   • Ask phase-specific clarifying questions about scope, constraints, interfaces, and acceptance criteria.
   • If the phase introduces or changes human interaction, roles, derived access rules, or domain operations, update DOMAIN.md/USE_CASES.md before PLAN.md.
   • If the phase only implements previously modeled behavior, keep the use-case trace and continue into implementation planning without redoing discovery.
   • WAIT for the user's answer.
   • Refine unclear assumptions and identify missing decisions.
   • REPEAT until phase boundaries are unambiguous.
3. Summarize: Present phase scope, risks, decisions, and success criteria.
4. STOP: Ask "Do we have enough details for this phase plan?"
5. WAIT: Do not create/update this phase's PLAN.md until the user explicitly says "Proceed to Phase Plan".

7. Phase Planning & Review (BLOCKING)

Create the detailed execution plan for the current phase, but do not execute yet. This step repeats for each phase.

Resources:

• Refer to references/verification-patterns.md to define goal-backward verification criteria.

Actions:

1. Create/Update .planning/phases/XX-phase/XX-PLAN.md.
2. Define Verification (must_haves): In the YAML frontmatter, define must_haves (truths, artifacts, key_links) based on the phase goal.
3. Carry Domain Trace Into Codegen: For human-interaction/business plans, define domain_trace in frontmatter and task-level <domain_trace> blocks. Include use cases, actors, domain concepts/modules/entities, and derived access rules that implementation must satisfy.
4. Plan Tasks: Break down implementation steps to satisfy verification criteria. For business systems, each task must explain how the use case becomes concrete code: data/entity shape, UI/CLI/API/service behavior, derived access checks, tests, and UAT evidence. Use <read_first> tags in tasks to define files that must be read before execution, and <acceptance_criteria> for grep-verifiable conditions.
5. Review: Check plan against the "Plan Verification Checklist".
6. STOP: Present the full plan content to the user.
7. ASK: "Here is the detailed plan. Does this look correct? Shall I proceed with execution?"
8. WAIT: Do not write any code until the user explicitly says "Yes" or "Proceed".

8. Phase Execution

Only proceed here after user confirmation of the PLAN. Execute the approved plan step-by-step.

Resources:

• Refer to workflows/execute-plan.md for the complete execution workflow including pre-execution checks, task execution order, verification rules, atomic commit strategy, and error recovery.
• Refer to templates/continue-here.md for session handoff when pausing mid-execution.

Plan components:

• Tasks: Specific, actionable implementation steps with concrete values
• Dependencies: Plan-to-plan dependency graphs managed via wave groups
• Waves: Parallel execution groups — independent plans run together
• Verification: Executing the defined verification and acceptance criteria
• Checkpoints: User interaction points (decisions, visual verification)
• user_setup: External service configuration the user must complete

9. Verification & Summary

Ensure quality and document outcomes:

Resources:

• Refer to workflows/verify-work.md for the complete verification workflow: automated checks, must-haves verification, UAT generation, and gap handling.
• Refer to workflows/transition.md for phase completion and transition to the next phase.
• Refer to workflows/health.md for planning directory integrity checks and auto-repair.
• Refer to references/verification-patterns.md for verification types and workflows.
• Refer to templates/verification-report.md for the verification report template.
• Refer to templates/UAT.md for user acceptance testing documentation.

Verification types:

• Automated: Tests, linting, build checks
• Manual: User verification of UI/UX via checkpoint tasks
• Must-Haves: Goal-backward verification (truths, artifacts, key_links)
• Integration: System integration testing
• Documentation: Update project context

After verification, refer to workflows/transition.md for the phase completion checklist and preparation for the next phase.

Templates & Patterns

All templates are in the templates/ directory. See templates/README.md for the canonical artifact registry — the authoritative index of all .planning/ artifacts.

Core Planning Templates

• templates/PROJECT.md — Project vision, requirements, constraints, key decisions
• templates/DOMAIN.md — Domain concepts, attributes, relationships, lifecycles, invariants; required when humans interact with the system
• templates/USE_CASES.md — Actors/roles, role relationships, use-case matrix, role-to-domain operations
• templates/ROADMAP.md — Phase decomposition with success criteria and progress tracking
• templates/STATE.md — Cross-session memory: position, decisions, blockers, performance, Deferred Items
• templates/REQUIREMENTS.md — Scoped functional requirements with traceability
• templates/config.json — Workflow configuration (gates, parallelization, quality, ship.pr_body_sections, git.create_tag)

Phase Execution Templates

• templates/PLAN.md — Executable phase plan with XML task structure, must_haves, user_setup
• templates/SUMMARY.md — Post-execution summary with frontmatter for context assembly
• templates/discovery.md — Phase discussion decisions and context capture
• templates/research.md — Phase ecosystem research (NN-RESEARCH.md): libraries, patterns, expert approaches, locked constraints from discovery
• templates/VALIDATION.md — Validation architecture with Given/When/Then scenarios
• templates/UAT.md — User acceptance testing results with issue tracking (five-state model: pass/skipped/blocked + severity inference)
• templates/verification-report.md — Post-execution verification against must_haves (three-state: passed/gaps_found/human_needed + Anti-Patterns Found)
• templates/user-setup.md — USER-SETUP.md: human-required external config (API keys, dashboards) Claude cannot automate
• templates/continue-here.md — Session handoff for paused work

Brownfield Analysis Templates

• templates/codebase/structure.md — Directory organization and key modules
• templates/codebase/architecture.md — Design patterns and component relationships
• templates/codebase/stack.md — Technology stack with versions
• templates/codebase/conventions.md — Coding conventions and patterns
• templates/codebase/integrations.md — External services and dependencies
• templates/codebase/testing.md — Testing approach and coverage
• templates/codebase/concerns.md — Known issues and technical debt

Quality, Security & Operations Templates

• templates/SECURITY.md — Security contract: threat register, trust boundaries, accepted risks, audit trail (ASVS-leveled)
• templates/DEBUG.md — Active debug session tracker (.planning/debug/[slug].md): hypothesis/test/next-action loop with status state machine
• templates/retrospective.md — Living project retrospective: what was built, what worked, inefficiencies, patterns to persist
• templates/user-profile.md — Developer profile with behavioral directives and confidence ratings, generated from session analysis

Workflow Documentation

• workflows/execute-plan.md — Step-by-step plan execution with verification and error recovery
• workflows/verify-work.md — Phase completion verification including must_haves checking
• workflows/transition.md — Phase completion, context updates, and next phase preparation
• workflows/health.md — Planning directory integrity validation and auto-repair

Project Template (PROJECT.md)

See templates/PROJECT.md for the full template with guidelines, evolution rules, and brownfield support.

Phase Plan Template (PLAN.md)

See templates/PLAN.md for the full template with frontmatter fields, XML task structure, must_haves verification, user_setup for external services, TDD plans, and parallel execution patterns.

Roadmap Template (ROADMAP.md)

See templates/ROADMAP.md for the full template with phase numbering, decimal insertions, milestone grouping, and progress tracking.

Implementation Examples

Example 1: New Web Application

User: "I want to build a todo app with user authentication"

Workflow:
1. Initialize project: Create PROJECT.md with core value "Simple, reliable todo management"
2. Domain & Use-Case Gate: Required because people use the app. Define Todo, List, Account, Session; define roles such as Owner or Collaborator if collaboration exists
3. Requirements Discussion: Clarify "user authentication" (Email/Password? OAuth? JWT?) and trace requirements to use cases
4. Roadmap: Phase 1 (Auth), Phase 2 (Todo CRUD), Phase 3 (Advanced features)
5. Per-Phase Discussion (Phase 1): Reconfirm auth boundaries and constraints
6. Plan Review (Phase 1): Present Phase 1 plan for user approval
7. Execution (Phase 1): Implement auth with verification tests
8. Repeat steps 5-7 for each subsequent phase

Example 2: API Service

User: "Build a REST API for inventory management"

Workflow:
1. Initialize: PROJECT.md with value "Reliable inventory tracking API"
2. Domain & Use-Case Gate: Required if humans/operators/admins use or govern inventory. Define Product, SKU, Stock Movement, Warehouse, Adjustment; define Clerk, Manager, Admin if roles differ
3. Requirements Discussion: Define API surface, database choice, auth strategy, and use-case traceability
4. Roadmap: Phase 1 (Basic CRUD), Phase 2 (Search), Phase 3 (Auth), Phase 4 (Reporting)
5. Per-Phase Discussion (Phase 1): Confirm endpoint scope and data model details
6. Plan Review (Phase 1): Confirm endpoints and data models
7. Execution (Phase 1): Implement endpoints with tests
8. Repeat steps 5-7 for each subsequent phase

Best Practices

1. Context Management

• Discuss before planning: Ensure alignment on requirements via workflows/transition.md and templates/discovery.md
• Model people before features when people interact: For UI/app/CLI/business workflows, define DOMAIN.md and USE_CASES.md before REQUIREMENTS.md and ROADMAP.md
• Confirm before executing: User must approve the plan
• Keep STATE.md updated with all key decisions
• Use SUMMARY.md for each completed plan with full frontmatter for automatic context assembly
• Reference dependencies explicitly in phase plans via depends_on and wave fields
• Maintain clean separation between planning and execution
• Session continuity: Use templates/continue-here.md when pausing mid-work

2. Verification Strategy

• Goal-backward verification: Define must_haves (truths, artifacts, key_links) in the plan frontmatter before implementation. See templates/PLAN.md for the full structure.
• Task-level verification: Define grep-verifiable acceptance_criteria for each <task>
• Automated checks: Tests, linting, type checking — see workflows/verify-work.md
• User verification: Checkpoints for UI/UX validation via checkpoint:human-verify tasks
• Integration testing: End-to-end workflow validation
• Verification reporting: Use templates/verification-report.md to document results

3. Phase Design

• Small, focused phases: 2-3 plans per phase (~50% context max per plan)
• Clear dependencies: Explicit phase-to-phase and plan-to-plan dependencies via wave groups
• Measurable outcomes: Each phase delivers testable functionality with success criteria
• Progressive disclosure: Build complexity gradually
• Parallel execution: Independent plans run in same wave — see templates/PLAN.md for parallel patterns
• External services: Declare in user_setup frontmatter — AI can't create API keys or configure dashboards

Resources

This skill includes resource directories for commands, templates, references, and scripts:

commands/

Slash command definitions that trigger specific workflows. Each command file describes the workflow, inputs, outputs, and rules for that operation.

Commands in this skill:

• commands/spec/new.md — /spec-new: Initialize a new project
• commands/spec/plan.md — /spec-plan <N>: Plan a phase (flags: --prd <file>, --mvp, --gaps)
• commands/spec/execute.md — /spec-execute <N>: Execute a phase (flags: --wave N, --gaps-only, --interactive)
• commands/spec/verify.md — /spec-verify <N>: Verify phase completion
• commands/spec/transition.md — /spec-transition: Complete and prepare next phase
• commands/spec/next.md — /spec-next: Auto-detect next step
• commands/spec/help.md — /spec-help: Show command reference
• commands/spec/quick.md — /spec-quick: Ad-hoc task (flags: --discuss/--full/--validate/--research; subcmds: list/status/resume)
• commands/spec/health.md — /spec-health [--repair] [--context]: Check directory integrity
• commands/spec/map-codebase.md — /spec-map-codebase: Analyze existing codebase
• commands/spec/config.md — /spec-config: Manage configuration

workflows/

Executable code (Python/Bash/etc.) that can be run directly to perform specific operations.

Scripts in this skill:

• scripts/init_project.py - Initialize a spec-driven project structure from templates.
  • Usage: python scripts/init_project.py <project_name>
  • Run when: Starting a new project or reinitializing missing planning scaffolding.
• scripts/validate_project.py - Validate required planning files, directory structure, and phase artifacts.
  • Usage: python scripts/validate_project.py [project_path]
  • Run when: Before phase execution, after major planning updates, and before handoff.
• scripts/package_skill.py - Package this skill into a distributable zip with manifest metadata.
  • Usage: python scripts/package_skill.py [skill_path]
  • Run when: Releasing or sharing the skill.

Appropriate for: Python scripts, shell scripts, or any executable code that performs automation, data processing, or specific operations.

Note: Scripts may be executed without loading into context, but can still be read for patching or environment adjustments.

workflows/

Step-by-step workflow documentation for each phase of the spec-driven process. Load these into context when executing specific workflows.

Workflows in this skill:

• workflows/execute-plan.md — Task execution, atomic commits, verification, error recovery
• workflows/verify-work.md — Must-haves verification, UAT, gap handling
• workflows/transition.md — Phase completion, context updates, next phase preparation
• workflows/health.md — Directory integrity validation and auto-repair

scripts/

Executable code (Python/Bash/etc.) that can be run directly to perform specific operations.

Scripts in this skill:

• scripts/init_project.py - Initialize a spec-driven project structure from templates
• scripts/validate_project.py - Validate required planning files, directory structure, and phase artifacts
• scripts/package_skill.py - Package this skill into a distributable zip with manifest metadata

Appropriate for: Python scripts, shell scripts, or any executable code that performs automation, data processing, or specific operations.

references/

Documentation and reference material intended to be loaded into context to inform Claude's process and thinking.

References in this skill:

• references/questioning.md — Questioning strategies and mental models for requirements and phase-level discovery
• references/verification-patterns.md — Verification types, workflows, and goal-backward must_haves patterns
• references/checkpoints.md — Checkpoint types (human-verify/decision/action) and golden rules for interaction boundaries
• references/domain-probes.md — Domain-aware follow-up probes (auth, real-time, storage, etc.) for requirement gathering
• references/user-story-template.md — Canonical "As a / I want to / So that" user story format and structural rules
• references/tdd.md — TDD disciplines: red-green-refactor cycle, when TDD improves quality, cycle overhead
• references/debugger-philosophy.md — Evergreen debugging disciplines: user=reporter, Claude=investigator
• references/common-bug-patterns.md — Frequency-ordered bug checklist (~80% of bugs) to scan before hypothesizing
• references/thinking-models-debug.md — Structured reasoning models for debugging (fault tree, hypothesis-driven, Occam's razor)
• references/ai-evals.md — AI evaluation reference: model vs product evals, measurement approaches, rubric design

Appropriate for: In-depth documentation, API references, database schemas, comprehensive guides, or any detailed information that Claude should reference while working.

assets/

Files not intended to be loaded into context, but rather used within the output Claude produces.

Examples from other skills:

• Brand styling: PowerPoint template files (.pptx), logo files
• Frontend builder: HTML/React boilerplate project directories
• Typography: Font files (.ttf, .woff2)

Appropriate for: Templates, boilerplate code, document templates, images, icons, fonts, or any files meant to be copied or used in the final output.

Any unneeded directories can be deleted. Not every skill requires all three types of resources.