speckit-generator

What this skill does

# 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](#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)
- [Command: revert](#command-revert)
- [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

### Plugin Command (Global)

| Command | Purpose | When to Use |
|---------|---------|-------------|
| `/speckit.init` | Establish .claude/ foundation with git, install project commands | New projects or incomplete setup |

### Project Commands (Installed by /speckit.init)

| Command | Purpose | When to Use |
|---------|---------|-------------|
| `/plan` | Create plans from specifications | After specs exist in speckit/ |
| `/tasks` | Generate tasks from plans | After plans are approved |
| `/design` | Generate detailed task designs | Before implementing complex tasks |
| `/analyze` | Audit project consistency | Anytime for health check |
| `/clarify` | Resolve ambiguities | When specs have open questions |
| `/implement` | Execute tasks with git checkpoint | When ready to implement |
| `/revert` | Revert to checkpoint with analysis | When implementation fails |
| `/lint` | Scan code for anti-patterns | Before code review or after implementation |

---

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

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

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