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