Spec Driven Dev

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 | Create spec from "I want to build/add X" | Feature description | | /spec.refine [section] | Improve spec with research/Gemini | Optional section focus | | /spec.clarify | 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 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

1. 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

1. Generate spec file:

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

1. Fill initial sections:

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

1. 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/

1. 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

1. 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

1. Update spec:

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

1. 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 or /spec.clarify Q1: answer, Q2: answer

Workflow

1. Load active spec with open questions

1. Parse user response:

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

1. Update spec:

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

1. 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. ``

1. Mark spec as APPROVED

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

1. 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

1. Add task metadata:

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

1. 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#)

1. Load context:

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

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

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

1. Update task file:

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

1. 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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mauromedda
• Source: mauromedda/agent-toolkit
• License: MIT

Install and usage instructions live in the source repository linked above.