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

```text
.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:
```markdown
- [ ] 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`)

```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:can