Speckit Generator

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