# Speckit Generator

> 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.

- Skill: `majiayu000/speckit-generator-2` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add majiayu000/speckit-generator-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/speckit-generator-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/majiayu000/speckit-generator-2

---


# SpecKit Generator

Project-focused specification management with 6 commands that work together to transform specifications into executed implementations.

## Table of Contents
- [Critical Workflow Rules](#critical-workflow-rules)
- [Overview](#overview)
- [Commands](#commands)
- [Command: init](#command-init)
- [Command: plan](#command-plan)
- [Command: tasks](#command-tasks)
- [Command: analyze](#command-analyze)
- [Command: clarify](#command-clarify)
- [Command: implement](#command-implement)
- [Memory File System](#memory-file-system)
- [Idempotency](#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

| 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

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

| 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

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
├── 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

1. **Locate specs** - Find spec files in .claude/resources/
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)**:
```
.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

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

```markdown
# [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

```markdown
# 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

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

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

```markdown
## 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:
```markdown
**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