ABOUTME: Spec-driven development orchestrator with subcommand interface

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

Spec-Driven Development

Quick Reference

/spec.plan <intent>

/spec.refine [section]

/spec.clarify <response>

/spec.tasks

/spec.run [task#]

Core Principle

Phase 1:

/spec.plan

- Create Specification

/spec.plan <description>

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

/spec.refine [section]

/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

/spec.clarify <response>

/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

/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

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

/spec.run

Phase 5:

/spec.run

- Execute Tasks

/spec.run [task#]

/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

# 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

.py

/python

.go

/golang

.sh

/bash

Makefile

/make

.tf

/terraform

/design-patterns

gemini -m gemini-3-pro-preview ...

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

/spec.tasks

/spec.clarify

/spec.run

/spec.tasks

/spec.clarify

/spec.plan

/spec.run

/spec.refine

Templates

references/templates.md

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