| name | speckit-generator |
| description | Project-focused specification and task management system with 6 individual commands. Each command MUST be invoked separately and requires user approval before proceeding. Commands: /speckit.init, /speckit.plan, /speckit.tasks, /speckit.analyze, /speckit.clarify, /speckit.implement. NEVER chain commands automatically - each produces output that requires user review. Use /speckit.plan when user wants to create plans from specs. Use /speckit.tasks only AFTER user has approved plans.
|
SpecKit Generator
Project-focused specification management with 6 commands that work together to transform specifications into executed implementations.
Table of Contents
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
| After Command | MUST DO | Before Proceeding To |
|---|
/speckit.init | Present created structure, confirm memory files | Any other command |
/speckit.plan | Present plan summary, wait for explicit approval | /speckit.tasks |
/speckit.tasks | Present task summary, wait for explicit approval | /speckit.implement |
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
- Separation of Concerns: Plans define WHAT, tasks define HOW
- Memory-Driven Compliance: All execution references constitution.md and relevant memory files
- Idempotent Operations: All commands safe to run repeatedly
- Deterministic Analysis: analyze produces identical output for identical input
Commands
| Command | Purpose | When to Use |
|---|
/speckit.init | Establish .claude/ foundation | New projects or incomplete setup |
/speckit.plan | Create plans from specifications | After specs exist in resources/ |
/speckit.tasks | Generate tasks from plans | After plans are approved |
/speckit.analyze | Audit project consistency | Anytime for health check |
/speckit.clarify | Resolve ambiguities | When specs have open questions |
/speckit.implement | Execute tasks | When ready to implement |
Command: init
Establish the .claude/ foundation with appropriate memory files for the project.
Trigger
- Explicit:
/speckit.init
- Automatic: Other commands detect missing setup
Workflow
- Check existing state - Detect if .claude/ exists
- Detect tech stack - Analyze project for languages/frameworks
- Present detection - Show detected stack and recommended memory files
- Create structure - Build directory structure
- Copy memory files - Select and copy based on tech stack
- Generate project context - Create project-context.md
Directory Structure Created
.claude/
├── commands/ # Custom project commands
├── memory/ # constitution.md + tech-specific files
│ └── MANIFEST.md
├── resources/ # Specifications, designs
├── templates/ # Output templates
└── scripts/ # Project scripts
Memory File Selection
| Category | Files | Selection |
|---|
| Universal | constitution.md, documentation.md, git-cicd.md, security.md, testing.md | Always |
| TypeScript/JS | typescript.md | If TS/JS detected |
| React/Next.js | react-nextjs.md | If React/Next detected |
| Tailwind | tailwind-shadcn.md | If Tailwind detected |
| Python | python.md | If Python detected |
| Rust | rust.md | If Rust detected |
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
- Locate specs - Find spec files in .claude/resources/
- Assess complexity - Single domain vs multi-domain
- Generate plans - Create plan.md (and domain plans if complex)
- Validate - Check plan completeness and consistency
Output Structure
Simple (single domain):
.claude/resources/
├── spec.md
└── plan.md
Complex (multi-domain):
.claude/resources/
├── 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
| Indicator | Simple | Complex |
|---|
| Domains | Single | Multiple distinct |
| Page count | <10 pages | >10 pages |
| Stakeholder count | 1-2 | 3+ |
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
- Load plan(s) - Read plan files
- Load constitution - Extract relevant sections
- Load memory files - Get tech-specific guidelines
- Generate tasks - Create *-tasks.md with phases
- 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
| Status | Meaning |
|---|
| PENDING | Not started |
| IN_PROGRESS | Currently being worked |
| BLOCKED | Waiting on dependency |
| COMPLETED | Done and verified |
| SKIPPED | Intentionally not done |
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
| Category | Description |
|---|
| GAPS | Missing required elements |
| INCONSISTENCIES | Contradictions between artifacts |
| AMBIGUITIES | Unclear or undefined items |
| ORPHANS | Unreferenced elements |
| ASSUMPTIONS | Untracked/unvalidated assumptions |
Severity Levels
| Level | Meaning |
|---|
| CRITICAL | Blocks progress, must fix |
| HIGH | Significant risk, should fix |
| MEDIUM | Notable issue, plan to fix |
| LOW | Minor concern |
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
| Category | Example Question |
|---|
| SCOPE | "Should X include Y functionality?" |
| BEHAVIOR | "What happens when user does X?" |
| DATA | "What format should X be stored in?" |
| ERROR | "How should X error be handled?" |
| SEQUENCE | "Does X happen before or after Y?" |
| CONSTRAINT | "What are the limits for X?" |
| INTERFACE | "How does X communicate with Y?" |
| AUTHORITY | "Who approves X?" |
| TEMPORAL | "How long should X take?" |
Workflow
- Scan for ambiguity - Find [TBD], [NEEDS CLARIFICATION], vague language
- Prioritize - Rank by impact on implementation
- Present question - One at a time with options
- Update spec - Apply answer immediately
- 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
| Selector | Meaning |
|---|
TASK-001 | Single task |
TASK-001..TASK-005 | Range of tasks |
"Phase 1" | All tasks in phase |
@foundation | All tasks with @foundation group |
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?"
...
Workflow
For each task:
- Load context - Read referenced constitution sections + memory files
- Present context - Show agent the relevant guidelines
- Execute - Perform the task
- Update status - PENDING → IN_PROGRESS → COMPLETED
- 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]
See references/command-workflows/implement-workflow.md for detailed workflow.
Memory File System
Memory files provide persistent guidelines that inform all commands.
Universal Files (Always Loaded)
| File | Purpose |
|---|
| constitution.md | Core principles, mandatory constraints |
| documentation.md | Documentation standards |
| git-cicd.md | Git workflow, CI/CD practices |
| security.md | Security requirements |
| testing.md | Testing strategies |
Tech-Specific Files (Loaded by Detection)
| File | Triggers |
|---|
| typescript.md | TypeScript, JavaScript, Node.js |
| react-nextjs.md | React, Next.js |
| tailwind-shadcn.md | Tailwind CSS, shadcn/ui |
| python.md | Python, Django, Flask, FastAPI |
| rust.md | Rust |
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:
- Init detects state - Finds what exists, what's missing
- Commands offer catch-up - "Missing setup. Run init first?"
- Incremental updates - Only process what's new
- Never destructive - No deletions without explicit request
