SpecKit Generator

Project-focused specification management with 1 bootstrap command (/speckit.init) that installs 8 project-local commands to transform specifications into executed implementations with git checkpoint safety.

Table of Contents

• •Critical Workflow Rules
• •Overview
• •Commands
• •Command: init
• •Command: plan
• •Command: tasks
• •Command: analyze
• •Command: clarify
• •Command: implement
• •Command: revert
• •Memory File System
• •Idempotency

Critical Workflow Rules

MANDATORY: Commands must NOT be chained automatically.

Each command produces artifacts that require user review and approval before proceeding to the next phase. This is not optional.

Required Gates

Recommended Workflow

/speckit.init
    ↓ [User reviews structure]
/speckit.plan
    ↓ [User reviews plan]
/speckit.analyze ← Run BEFORE approving plan
    ↓ [Address any CRITICAL/HIGH findings]
/speckit.clarify ← Run if [TBD] items exist
    ↓ [User approves final plan]
/speckit.tasks
    ↓ [User reviews tasks]
/speckit.implement

What NOT To Do

• •❌ Run /speckit.plan then immediately /speckit.tasks without user approval
• •❌ Generate all artifacts in one session without checkpoints
• •❌ Skip /speckit.analyze before plan approval
• •❌ Proceed past a GATE without explicit user confirmation

Gate Response Format

After completing a command, present results in this format:

## [Command] Complete

[Summary of what was created/modified]

### Artifacts Created
- [list of files]

### Recommended Next Steps
1. Review the [artifacts] above
2. Run `/speckit.analyze` to check compliance (if applicable)
3. Run `/speckit.clarify` to resolve any [TBD] items (if applicable)

**Awaiting your approval before proceeding.**

Overview

SpecKit provides a complete workflow for specification-driven development:

init → plan → tasks → implement
  ↑      ↑      ↑         ↑
  └──────┴──────┴─────────┘
         analyze/clarify (anytime)

Core Principles

1. •Separation of Concerns: Plans define WHAT, tasks define HOW
2. •Memory-Driven Compliance: All execution references constitution.md and relevant memory files
3. •Idempotent Operations: All commands safe to run repeatedly
4. •Deterministic Analysis: analyze produces identical output for identical input

Commands

Plugin Command (Global)

Project Commands (Installed by /speckit.init)

Command: init

Establish the .claude/ foundation with appropriate memory files for the project.

Trigger

• •Explicit: /speckit.init
• •Automatic: Other commands detect missing setup

Workflow

1. •Check existing state - Detect if .claude/ exists
2. •Detect tech stack - Analyze project for languages/frameworks
3. •Present detection - Show detected stack and recommended memory files
4. •Create structure - Build directory structure
5. •Copy memory files - Select and copy based on tech stack
6. •Generate project context - Create project-context.md

Directory Structure Created

.claude/
├── commands/      # Custom project commands
├── memory/        # constitution.md + tech-specific files
│   └── MANIFEST.md
├── templates/     # Output templates
└── scripts/       # Project scripts

speckit/           # SpecKit artifacts (specs, plans, tasks, designs)
├── spec.md
├── plan.md
├── tasks.md
├── plans/         # Multi-domain plans (if complex)
└── designs/       # Design documents

Memory File Selection

Options

Options:
1. Accept recommended selection
2. Add additional memory files
3. Remove memory files from selection
4. Override detected stack manually

See references/command-workflows/init-workflow.md for detailed workflow.

Command: plan

Create implementation plans from specification files. Hierarchical for complex/multi-domain specs.

Trigger

• •/speckit.plan
• •/speckit.plan spec.md
• •/speckit.plan --all

Workflow

1. •Locate specs - Find spec files in speckit/
2. •Assess complexity - Single domain vs multi-domain
3. •Generate plans - Create plan.md (and domain plans if complex)
4. •Validate - Check plan completeness and consistency

Output Structure

Simple (single domain):

speckit/
├── spec.md
└── plan.md

Complex (multi-domain):

speckit/
├── spec.md
├── plan.md              # Master plan with domain references
└── plans/
    ├── domain-a-plan.md
    ├── domain-b-plan.md
    └── domain-c-plan.md

Plan Content

Plans contain:

• •Requirements mapping (which spec sections covered)
• •Architecture decisions
• •Implementation approach (phases, NOT tasks)
• •Verification strategy
• •Notes for task generation

Plans do NOT contain:

• •Individual tasks (that's /speckit.tasks)
• •Implementation code
• •Detailed how-to instructions

Complexity Detection

User can override detection.

See references/command-workflows/plan-workflow.md for detailed workflow.

Command: tasks

Generate implementation tasks from plans + constitution + memory files.

Trigger

• •/speckit.tasks
• •/speckit.tasks plan.md
• •/speckit.tasks --all

Workflow

1. •Load plan(s) - Read plan files
2. •Load constitution - Extract relevant sections
3. •Load memory files - Get tech-specific guidelines
4. •Generate tasks - Create *-tasks.md with phases
5. •Validate - Check task completeness

Output

# [Domain] Tasks

## Phase 1: Foundation

### TASK-001: [Title]
**Status**: PENDING
**Priority**: P1
**Constitution Sections**: §4.1, §4.2
**Memory Files**: typescript.md, git-cicd.md
**Plan Reference**: PLAN-001
**Description**: ...
**Acceptance Criteria**:
- [ ] Criterion 1
- [ ] Criterion 2

Task Statuses

See references/command-workflows/tasks-workflow.md for detailed workflow.

Command: analyze

Deterministic, read-only audit of project artifacts for consistency and completeness.

Trigger

• •/speckit.analyze
• •/speckit.analyze --verbose
• •/speckit.analyze --category gaps

Characteristics

• •Read-only: Never modifies files
• •Deterministic: Same inputs = same outputs
• •Stable IDs: Finding IDs remain stable across runs
• •Quantified: Metrics for coverage, completeness

Analysis Categories

Severity Levels

Output Format

# Analysis Report

Generated: [timestamp]
Artifacts analyzed: [count]

## Summary
| Category | Critical | High | Medium | Low |
|----------|----------|------|--------|-----|
| GAPS     | 2        | 3    | 5      | 1   |
| ...      |          |      |        |     |

## Findings

### GAP-001 [CRITICAL]
**Location**: spec.md:45
**Description**: Missing error handling specification
**Recommendation**: Define error states for API failures

See references/command-workflows/analyze-workflow.md for detailed workflow.

Command: clarify

Structured ambiguity resolution with immediate spec updates.

Trigger

• •/speckit.clarify
• •/speckit.clarify spec.md

Characteristics

• •One question at a time: Focused, manageable
• •Multiple choice or short phrase: Quick answers
• •5-question maximum per session: Avoid fatigue
• •Immediate updates: Specs updated after each answer
• •9-category taxonomy: Structured classification

Ambiguity Categories

Workflow

1. •Scan for ambiguity - Find [TBD], [NEEDS CLARIFICATION], vague language
2. •Prioritize - Rank by impact on implementation
3. •Present question - One at a time with options
4. •Update spec - Apply answer immediately
5. •Log session - Record Q&A for traceability

Question Format

CLARIFY-001 [BEHAVIOR]

The spec mentions "user authentication" but doesn't specify the method.

Which authentication method should be used?
1. OAuth 2.0 with Google/GitHub (Recommended)
2. Email/password with JWT
3. Magic link (passwordless)
4. Other (please specify)

Your choice:

See references/command-workflows/clarify-workflow.md for detailed workflow.

Command: implement

Execute tasks from *-tasks.md with batch+gates execution model.

Trigger

• •/speckit.implement TASK-001
• •/speckit.implement TASK-001..TASK-005
• •/speckit.implement "Phase 1"
• •/speckit.implement @foundation

Task Selection

Execution Model: Batch + Gates

Execute Phase 1 tasks
    ↓
GATE: "Phase 1 complete. Review outputs?"
    ↓
[User confirms]
    ↓
Execute Phase 2 tasks
    ↓
GATE: "Phase 2 complete. Review outputs?"
    ...
    ↓
MANDATORY: Post-Implementation Hooks

Workflow

For each task:

1. •Load context - Read referenced constitution sections + memory files
2. •Present context - Show agent the relevant guidelines
3. •Execute - Perform the task
4. •Update status - PENDING → IN_PROGRESS → COMPLETED
5. •Verify - Check acceptance criteria

Gate Behavior

At phase/group boundaries:

Phase [N] complete.

Tasks completed: [count]
Tasks failed: [count]

Options:
1. Continue to Phase [N+1]
2. Review completed work
3. Re-run failed tasks
4. Stop execution

Context Loading

## Execution Context for TASK-001

### Constitution Requirements (§4.1, §4.2)
[Extracted sections from constitution.md]

### Memory File Guidelines
From typescript.md:
[Relevant sections]

From git-cicd.md:
[Relevant sections]

### Task Details
[Full task content]

MANDATORY: Pre-Implementation Hooks

CRITICAL: These hooks MUST execute BEFORE any task work begins:

If no argument or invalid argument: Show current status and available selectors, then STOP until user provides valid selection.

MANDATORY: Post-Implementation Hooks

CRITICAL: These hooks MUST execute after ANY /speckit.implement run:

The command is NOT COMPLETE until all hooks execute. See references/command-workflows/implement-workflow.md for detailed templates and verification methods.

Command: revert

Revert to a previous git checkpoint with intelligent failure analysis and artifact recommendations.

Trigger

• •/speckit.revert - Most recent checkpoint
• •/speckit.revert [checkpoint-tag] - Specific checkpoint
• •/speckit.revert --list - List available checkpoints

Workflow

1. •List checkpoints - Show available speckit-checkpoint-* tags
2. •Preview revert - Show files and tasks that will be affected
3. •Execute revert - git reset --hard [checkpoint]
4. •Analyze failure - Determine what went wrong
5. •Recommend fixes - Suggest spec/plan/task updates

Failure Analysis Categories

Output

After revert, provides:

• •Summary of what was reverted
• •Root cause analysis
• •Specific recommendations for next steps
• •Updated project-status.md with revert logged
• •Updated tasks.md with failure notes

See commands/speckit.revert.md for detailed workflow.

Memory File System

Memory files provide persistent guidelines that inform all commands.

Universal Files (Always Loaded)

Tech-Specific Files (Loaded by Detection)

Constitution Section References

Tasks reference constitution sections by ID:

• •§1.0 - Chapter reference
• •§1.1 - Section reference
• •§1.1.a - Subsection reference

Example task:

**Constitution Sections**: §4.1 (Error Handling), §4.2 (Logging)

Idempotency

All commands are designed to be safe when run repeatedly.

Init Idempotency

• •Skips existing directories
• •Updates changed memory files only
• •Preserves project customizations

Plan Idempotency

• •Detects existing plans
• •Offers update or regenerate
• •Preserves manual edits with warning

Tasks Idempotency

• •Preserves task statuses
• •Adds new tasks for new plan items
• •Never removes manually added tasks

Analyze Idempotency

• •Read-only, always safe
• •Stable finding IDs across runs

Clarify Idempotency

• •Tracks answered questions
• •Skips already-clarified items
• •Session history preserved

Implement Idempotency

• •Skips COMPLETED tasks
• •Resumes from last position
• •Re-runnable for failed tasks

Catching Up

When running on an existing project:

1. •Init detects state - Finds what exists, what's missing
2. •Commands offer catch-up - "Missing setup. Run init first?"
3. •Incremental updates - Only process what's new
4. •Never destructive - No deletions without explicit request

Related Skills

These skills auto-activate based on context to provide supplementary guidance:

When to Use

• •Before /speckit.plan: Use requirement-patterns to write better specifications
• •During /speckit.plan: Use adr-authoring for architecture decisions
• •With /speckit.analyze: Skills provide context for interpreting findings