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:

• Setup: Environment, dependencies, scaffolding
• Core: Main implementation tasks
• Integration: Connect components
• Polish: Error handling, edge cases
• 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:

• Specify: Maps features to constitution principles
• Plan: Architecture follows constitution patterns
• Tasks: Quality checkpoints enforce constitution
• 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

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

During Implementation

• Follow task order (dependencies matter)
• Commit after each task
• Update progress with learnings
• Run verification checkpoints

Maintaining Constitution

• Version constitution changes semantically
• Run sync impact analysis after updates
• Update affected features if needed
• Document rationale for changes