spec-driven-dev

name	spec-driven-dev
description	Spec-driven development framework with iterative refinement. Orchestrates feature development from intent to implementation via structured specs and task breakdown. Triggers on "/spec.plan", "/spec.refine", "/spec.clarify", "/spec.tasks", "/spec.run", "I want to build", "I want to add", "create spec", "spec-driven", "feature spec".
allowed-tools	Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion, TodoWrite, Task

ABOUTME: Spec-driven development orchestrator with subcommand interface

ABOUTME: Manages lifecycle: /spec.plan -> /spec.refine -> /spec.clarify -> /spec.tasks -> /spec.run

Spec-Driven Development

Iterative feature development framework ensuring zero ambiguity before execution.

Quick Reference

Command	Purpose	Input
/spec.plan <intent>	Create spec from "I want to build/add X"	Feature description
/spec.refine [section]	Improve spec with research/Gemini	Optional section focus
/spec.clarify <response>	Answer clarification questions	Your response
/spec.tasks	Break spec into executable tasks	None (uses active spec)
/spec.run [task#]	Execute tasks with TDD	Optional task number

Core Principle

Iterate until clarity: No task execution begins until ALL questions are resolved and the spec is unambiguous. Claude must be able to execute without interruptions.

---

Phase 1: /spec.plan - Create Specification

Trigger: /spec.plan <description> or "I want to build/add X"

Workflow

1. Check specs/ folder:

   • If missing: Create specs/ and specs/README.md
   • If exists: Read specs/README.md for project overrides

2. Detect project context:

   • Scan repo for language indicators (go.mod, pyproject.toml, package.json, etc.)
   • Note primary language(s) for later skill invocation
   • Check specs/README.md for language overrides

3. Generate spec file:

   • Filename: specs/{feature-slug}.md (kebab-case)
   • Use template from references/templates.md

4. Fill initial sections:

   • Parse user intent into Objective
   • List initial requirements (functional/non-functional)
   • Mark status as DRAFT

5. Generate clarifying questions:

   • Identify ambiguities, edge cases, unknowns
   • List as numbered questions in "Open Questions" section
   • STOP and present questions to user

Output

Created: specs/feature-name.md (DRAFT)

Questions requiring clarification:
1. [Question about scope]
2. [Question about behavior]
3. [Question about constraints]

Use `/spec.clarify` to answer, or `/spec.refine` to research solutions.

---

Phase 2: /spec.refine - Research & Improve

Trigger: /spec.refine [section] (e.g., /spec.refine solution, /spec.refine requirements)

Workflow

1. Load active spec: Find most recent DRAFT spec in specs/

2. Check project conventions:

   • Read specs/README.md for behavior overrides
   • Load relevant language skill (auto-detected or overridden)
   • Load design-patterns skill for architectural guidance

3. Research phase:

   • If user requests Gemini: gemini -m gemini-3-pro-preview "Analyze spec..." .
   • Search codebase for similar patterns
   • Check skill references for best practices

4. Update spec:

   • Fill "Technical Strategy" with concrete approach
   • Add architecture decisions with rationale
   • Update requirements based on findings

5. Re-evaluate clarity:

   • Are there new questions?
   • Are existing questions resolved?
   • If questions remain: STOP and present them

Gemini Integration (User-Invoked)

# For design validation
/spec.refine --gemini "Review architecture approach"

# For alternative exploration
/spec.refine --gemini "What are alternatives to this solution?"

---

Phase 3: /spec.clarify - Answer Questions

Trigger: /spec.clarify <response> or /spec.clarify Q1: answer, Q2: answer

Workflow

1. Load active spec with open questions

2. Parse user response:

   • Match answers to numbered questions
   • Accept free-form responses for single questions

3. Update spec:

   • Move answered questions to relevant sections
   • Add decisions/constraints to Requirements or Strategy
   • Remove resolved questions from "Open Questions"

4. Check for new questions:

   • Does the answer introduce new ambiguities?
   • If questions remain: present them
   • If no questions: announce spec is ready for /spec.tasks

Example

User: /spec.clarify Q1: We need OAuth2 with Google provider only. Q2: No, admin can also delete.

Updated specs/auth-system.md:
- Added OAuth2/Google to Technical Strategy
- Updated permissions: admin can delete

Remaining questions: None
Spec is ready. Use `/spec.tasks` to create task breakdown.

---

Phase 4: /spec.tasks - Task Breakdown

Trigger: /spec.tasks

Prerequisites

• Active spec must have status DRAFT or APPROVED
• "Open Questions" section must be empty
• If questions exist: STOP and redirect to /spec.clarify

Workflow

1. Validate spec readiness:

   If open_questions > 0:
       ERROR: Spec has unresolved questions. Use /spec.clarify first.
   

2. Mark spec as APPROVED

3. Generate task file: specs/{feature-slug}.tasks.md

4. Break down by component:

   • Group tasks by logical component/module
   • Each task = one logical unit (not TDD-granular)
   • TDD practice enforced during /run, not here

5. Add task metadata:

   • Link back to spec
   • Context summary
   • Acceptance criteria per task

6. Final review:

   • Present task list to user
   • Ask: "Any tasks missing or need splitting?"

Task Granularity

Tasks should be high-level logical units:

• "Implement authentication middleware"
• "Create user model and repository"
• "Add API endpoints for user CRUD"

TDD cycle (Red-Green-Refactor) happens WITHIN each task during /spec.run.

---

Phase 5: /spec.run - Execute Tasks

Trigger: /spec.run [task#] (e.g., /spec.run, /spec.run 3)

Prerequisites

• Task file must exist: specs/{feature}.tasks.md
• If no task file: STOP and redirect to /spec.tasks

Workflow

1. Load task file and find next unchecked task (or specified task#)

2. Load context:

   • Read linked spec for requirements
   • Read specs/README.md for project overrides
   • Invoke appropriate language skill

3. Execute with TDD (per CLAUDE.md rules):

   • RED: Write failing test first
   • GREEN: Minimal code to pass
   • REFACTOR: Clean up
   • COMMIT: After each phase

4. Update task file:

   • Mark task as [x] complete
   • Add notes if needed

5. Continue or pause:

   • If more tasks: Ask "Continue to next task?"
   • If blocked: Document blocker, ask for input
   • If all done: Mark spec as COMPLETED

Execution Rules

• No interruptions: If questions arise during execution, the spec was not ready
• Invoke skills: Auto-invoke /python, /golang, etc. based on file type
• Respect hooks: Pre-commit hooks must pass before marking complete
• Gemini review: Follow CLAUDE.md thresholds (>100 lines or >3 files)

---

Project Configuration: specs/README.md

Override default behaviors per-project:

# Spec Configuration

## Language Override
Primary: golang
Secondary: python

## Conventions
- All specs require security section
- Tasks must include rollback plan
- Use feature branches: feature/{spec-name}

## Templates
Use custom templates from: ./templates/

## Auto-invoke
- Always run /trivy before marking complete
- Require /gemini-review for all specs

---

State Management

Spec Status Flow

DRAFT -> APPROVED -> IN_PROGRESS -> COMPLETED
          |              |
          v              v
       (questions?)   (blocked?)
          |              |
          v              v
        DRAFT      IN_PROGRESS

File Structure

project/
└── specs/
    ├── README.md           # Project overrides
    ├── auth-system.md      # Spec (APPROVED)
    ├── auth-system.tasks.md # Task breakdown
    ├── user-dashboard.md   # Spec (DRAFT)
    └── ...

---

Cross-Skill Integration

When	Invoke
Writing .py files	/python skill
Writing .go files	/golang skill
Writing .sh files	/bash skill
Writing Makefile	/make skill
Writing .tf files	/terraform skill
Architecture decisions	/design-patterns skill
User-requested review	gemini -m gemini-3-pro-preview ...

---

Session Resume

On context compaction or session resume:

1. Check specs/ for files with status IN_PROGRESS
2. Check .tasks.md files for unchecked items
3. Report: "Found in-progress spec: X with Y tasks remaining"
4. Ask: "Continue with /spec.run?"

---

Error Handling

Situation	Response
/spec.tasks with open questions	"Spec has N unresolved questions. Use /spec.clarify first."
/spec.run without task file	"No task file found. Use /spec.tasks first."
/spec.clarify without active spec	"No active spec. Use /spec.plan to create one."
Ambiguity during /spec.run	"Execution blocked: [issue]. Spec needs refinement. Use /spec.refine."

---

Templates

See references/templates.md for:

• Spec file template
• Task file template
• README.md template