# Spec-Kit Workflow

How to take a feature from spec to working code.

## The Loop

```
clarify → plan → tasks → analyze → implement
```

Every step produces files in `specs/NNN-feature-name/`. Review after each step before moving on.

## Steps

### 1. Clarify the spec (optional)

```
/speckit.clarify
```

Asks up to 5 targeted questions about gaps or ambiguities in the spec. Answers get folded back into `spec.md`. Skip this if the spec is already solid.

### 2. Create the implementation plan

```
/speckit.plan
```

Reads `spec.md`, checks it against the constitution, and produces:

| File | Content |
|------|---------|
| `plan.md` | Technical design, architecture decisions, contracts |
| `research.md` | Background research (if needed) |
| `data-model.md` | Entity definitions (if new entities are involved) |
| `contracts/` | API contracts (if applicable) |

**Review this carefully.** The plan shapes everything downstream.

### 3. Generate the task list

```
/speckit.tasks
```

Reads the plan and generates `tasks.md` — an ordered, dependency-aware task list. Tasks marked `[P]` can run in parallel.

### 4. Check consistency (optional)

```
/speckit.analyze
```

Cross-checks spec, plan, and tasks for contradictions, gaps, or drift. Non-destructive — only reports, doesn't change files.

### 5. Implement

```
/speckit.implement
```

Executes the tasks from `tasks.md` phase by phase. Follows TDD: writes tests first, then implementation. Stops at checkpoints so you can verify.

## File structure

Each feature lives in its own directory:

```
specs/
  007-view-event/
    spec.md              # What and why (from /speckit.specify or migration)
    plan.md              # How (from /speckit.plan)
    research.md          # Background research (from /speckit.plan)
    data-model.md        # Entity definitions (from /speckit.plan)
    contracts/           # API contracts (from /speckit.plan)
    tasks.md             # Ordered task list (from /speckit.tasks)
```

## Starting a brand new feature

If the feature doesn't have a spec yet:

```
/speckit.specify
```

Describe what you want in plain language. This creates the spec directory and `spec.md` from the template. Then continue with the loop above.

## Tips

- **Don't skip the review.** Each step builds on the previous one. Garbage in, garbage out.
- **The spec is the source of truth.** If something in the plan contradicts the spec, fix the spec first.
- **You can re-run steps.** Changed the spec after planning? Run `/speckit.plan` again.
- **Constitution governs everything.** Principles in `.specify/memory/constitution.md` override ad-hoc decisions.