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