speckit-workflow

SpecKit Workflow

The SpecKit methodology is a constitution-driven approach to feature development. It ensures consistency across features by grounding all decisions in project principles.

Core Philosophy

Constitution First: Every feature is designed against the project's constitution - a living document of principles, constraints, and standards.

Governance Over Convention: Rather than implicit patterns, SpecKit makes governance explicit through:

• Constitution principles (MUST, SHOULD, MAY)
• Feature specifications tied to principles
• Quality checklists as "unit tests for requirements"
• Consistency analysis across artifacts

Directory Structure

.specify/
├── memory/
│   └── constitution.md       # Project principles and standards
├── .current-feature          # Active feature pointer
├── templates/                # Artifact templates
│   ├── spec-template.md
│   ├── plan-template.md
│   ├── tasks-template.md
│   └── checklist-template.md
└── specs/
    └── <id>-<name>/          # Feature directories
        ├── .speckit-state.json
        ├── .progress.md
        ├── .coordinator-prompt.md
        ├── spec.md           # Feature specification
        ├── plan.md           # Technical design
        ├── tasks.md          # Implementation tasks
        ├── research.md       # Research findings (optional)
        ├── data-model.md     # Entity definitions (optional)
        ├── contracts/        # API contracts (optional)
        └── checklists/       # Quality checklists

Feature ID System

Features use auto-incremented 3-digit IDs:

• 001-user-auth
• 002-payment-gateway
• 003-notification-system

Benefits:

• Natural ordering in filesystem
• Easy reference in commits/PRs
• Prevents naming conflicts

Workflow Phases

Phase 1: Constitution (/speckit:constitution)

Establish or update project-wide principles.

Inputs: Project context, team preferences Outputs: .specify/memory/constitution.md

Constitution sections:

• Identity: Project name, purpose, core domain
• Principles: MUST/SHOULD/MAY rules
• Technology Stack: Languages, frameworks, tools
• Patterns: Architecture, naming, error handling
• Quality Standards: Testing, performance, security

Phase 2: Specify (/speckit:specify)

Define the feature specification against constitution.

Inputs: Feature goal, constitution reference Outputs: spec.md

Specification contains:

• Feature overview and goals
• User stories with acceptance criteria
• Constitution alignment markers
• Out of scope items
• Dependencies and risks

Phase 3: Clarify (/speckit:clarify) - Optional

Resolve ambiguities through structured Q&A.

Inputs: spec.md with ambiguities Outputs: Updated spec.md with clarifications

Rules:

• Maximum 5 clarifying questions per session
• Each question has 2-4 options + "Other"
• Recommendations marked when applicable
• Clarifications appended to spec

Phase 4: Plan (/speckit:plan)

Generate technical design from specification.

Inputs: spec.md, constitution, codebase context Outputs: plan.md, optionally data-model.md, contracts/

Plan contains:

• Architecture overview
• Component breakdown
• Data flow diagrams
• API contracts
• Integration points
• Risk mitigation

Phase 5: Tasks (/speckit:tasks)

Break plan into dependency-ordered implementation tasks.

Inputs: plan.md, spec.md Outputs: tasks.md

Task format:

- [ ] T001 [P] [US1] Task description `path/to/file.ts`

Components:

• T001: Sequential task ID
• [P]: Parallel marker (optional)
• [US1]: User story reference (optional)
• Description with file path

Task phases:

1. Setup: Environment, dependencies, scaffolding
2. Core: Main implementation tasks
3. Integration: Connect components
4. Polish: Error handling, edge cases
5. Verification: Quality checkpoints

Phase 6: Implement (/speckit:implement)

Execute tasks via Ralph Wiggum loop.

Inputs: tasks.md, state file Outputs: Code changes, commits, updated progress

Execution model:

• Coordinator reads state, delegates to executor
• 4-layer verification before advancing
• Parallel execution for [P] marked tasks
• Fresh context per task

State Management

State File (.speckit-state.json)

{
  "featureId": "001",
  "name": "user-auth",
  "basePath": ".specify/specs/001-user-auth",
  "phase": "execution",
  "taskIndex": 0,
  "totalTasks": 15,
  "taskIteration": 1,
  "maxTaskIterations": 5,
  "globalIteration": 1,
  "maxGlobalIterations": 100,
  "awaitingApproval": false
}

Progress File (.progress.md)

Tracks:

• Completed tasks with commit hashes
• Learnings and context for future tasks
• Blockers and resolutions
• Cross-task dependencies

Quality Assurance

Checklists (/speckit:checklist)

Domain-specific quality checklists:

• UX checklist
• API checklist
• Security checklist
• Performance checklist
• Accessibility checklist

Checklists are "unit tests for requirements" - verifiable criteria before implementation.

Analyze (/speckit:analyze)

Cross-artifact consistency analysis:

• Spec ↔ Constitution alignment
• Plan ↔ Spec coverage
• Tasks ↔ Plan traceability
• Identifies gaps, conflicts, ambiguities

Command Reference

| Command | Purpose | Phase | |---------|---------|-------| | /speckit:start <name> | Create or resume feature | Entry | | /speckit:constitution | Create/update project principles | 1 | | /speckit:specify | Define feature specification | 2 | | /speckit:clarify | Resolve spec ambiguities | 3 | | /speckit:plan | Generate technical design | 4 | | /speckit:tasks | Break plan into tasks | 5 | | /speckit:implement | Execute tasks | 6 | | /speckit:analyze | Check consistency | Any | | /speckit:checklist | Generate quality checklist | Any | | /speckit:status | Show current state | Any | | /speckit:switch <id> | Change active feature | Any | | /speckit:cancel | Stop execution, cleanup | Any |

Agent Ecosystem

| Agent | Purpose | Used By | |-------|---------|---------| | constitution-architect | Create/update constitution | constitution | | spec-analyst | Generate specifications | specify | | plan-architect | Technical design | plan | | task-planner | Task breakdown | tasks | | spec-executor | Execute single task | implement | | qa-engineer | Verification tasks | implement |

Constitution Integration

All phases reference the constitution:

1. Specify: Maps features to constitution principles
2. Plan: Architecture follows constitution patterns
3. Tasks: Quality checkpoints enforce constitution
4. Implement: Executor validates against standards

Constitution markers in artifacts:

• [C§3.1]: References constitution section 3.1
• [MUST]: Required by constitution
• [SHOULD]: Recommended by constitution
• [MAY]: Optional per constitution

Best Practices

Starting New Features

1. Ensure constitution exists and is current
2. Use descriptive feature names (kebab-case)
3. Include clear success criteria in spec
4. Reference related features if applicable

During Implementation

1. Follow task order (dependencies matter)
2. Commit after each task
3. Update progress with learnings
4. Run verification checkpoints

Maintaining Constitution

1. Version constitution changes semantically
2. Run sync impact analysis after updates
3. Update affected features if needed
4. Document rationale for changes