---
name: spec-driven
description: >
  Spec-driven product workflow: requirements → spec.md → plan.md → small task.md files
  with explicit inputs/outputs (≈100–200 line changes each). Use when the user wants to
  restart cleanly, write requirements, draft a product spec, break a plan into tasks,
  run /spec-driven, or says 重新開始 / 需求文件 / 拆 task / 從需求做到 task.
---

# Spec-Driven Workflow

Freeze **what we want**, then **how it behaves**, then **how we deliver**, then **one-step tasks**. Never invent code while a phase is unapproved.

## Artifact root

```text
docs/product/<slug>/
  README.md           # phase status
  requirements.md
  spec.md             # after requirements approved
  plan.md             # after spec approved
  tasks/
    INDEX.md
    T001-short-slug.md
```

Templates live in this skill:

```text
references/templates/{requirements,spec,plan,task}.md
references/workflow.md
```

Optional scaffold:

```bash
bash .grok/skills/spec-driven/scripts/init-run.sh <slug> "<one-line goal>"
```

## Invocation

| Form | Behavior |
|------|----------|
| `/spec-driven` | Ask slug + goal if missing; continue current phase |
| `/spec-driven <slug>` | Work on that run |
| `/spec-driven <slug> --status` | Report phase + file presence only |
| `/spec-driven <slug> --phase N` | Only if prior artifacts exist; still require user OK for *this* phase output |

Phases: `0=init`, `1=requirements`, `2=spec`, `3=plan`, `4=tasks`, `5=ready-to-implement`.

## Hard gates

1. **One phase per turn cycle.** Write the current phase document(s), summarize for the user, **stop**.
2. Advance only when the user clearly approves (e.g. 「需求 OK」「spec 通過」「可以拆 task」).
3. Do **not** implement product code until:
   - `plan.md` approved, **and**
   - `tasks/INDEX.md` exists with at least one `todo` task, **and**
   - user says to implement a specific `T###` (or all).
4. Do **not** skip templates' required sections.
5. If prior phase file is missing → stop and say which file is needed.

## Step 0 — Init

1. Resolve `slug` (kebab-case, e.g. `haixun-console`).
2. If `docs/product/<slug>/` missing → run `init-run.sh` or create the same structure.
3. Write/update `README.md` with goal, phase=`requirements`, dates.
4. Ask user to confirm scope in one sentence if ambiguous.

## Step 1 — Requirements

1. Read templates + existing product context (`docs/architecture.md`, related plans, `AGENTS.md` constraints).
2. Write `requirements.md` using the template (product language only).
3. **Forbidden in requirements:** API paths, Go package paths, PR lists, implementation steps.
4. Present: In/Out scope, P0 vs later, success criteria, open questions.
5. Set README phase note: `awaiting-requirements-approval`.
6. **STOP.**

## Step 2 — Spec

Preconditions: `requirements.md` exists and user approved.

1. Write `spec.md` from requirements (behavior contracts).
2. Include Retain / Replace / Remove vs current codebase where relevant.
3. Follow project rules when specifying contracts: JSON envelope, `page/pageSize`, unix nanoseconds UTC, job guarded updates, auth header matrix.
4. **Forbidden in spec:** milestone calendars, task IDs, "we'll refactor later" without a concrete behavior.
5. Present summary → README `awaiting-spec-approval` → **STOP.**

## Step 3 — Plan

Preconditions: `spec.md` approved.

1. Write `plan.md` with milestones M0…Mn, dependencies, risks, verification commands.
2. Map each milestone to a **task id range** (e.g. M1 → T010–T019) but do not write full task files yet unless user asked to combine plan+tasks in one approval (default: plan only).
3. Present summary → **STOP.**

## Step 4 — Tasks

Preconditions: `plan.md` approved.

1. Create `tasks/INDEX.md` and one file per task from `references/templates/task.md`.
2. **Task size rule:** estimate **100–200 lines** of production code change. If larger, split. If smaller and independent, still OK but avoid micro-noise (<~30 lines unless critical fix).
3. Every task MUST have: Goal, Inputs, Outputs (paths + behavior), Out of scope, Acceptance checks (commands), Depends on.
4. No vague tasks ("improve UX", "cleanup backend").
5. Present INDEX + count → **STOP** until user approves task breakdown.
6. On approval: README phase=`ready-to-implement`.

## Step 5 — Implement (only when asked)

1. Pick exactly one `T###` (or user-specified set).
2. Mark INDEX `doing` → implement only that task's Outputs → acceptance → `done`.
3. Do not pull in neighbor tasks "while you're there" unless user expands scope.
4. Prefer `make test` / `go test ./...` / `make web-build` as listed in the task.

## Status reporting (`--status`)

Print:

- slug, goal, phase
- which of requirements/spec/plan/tasks exist
- task counts by status from INDEX

## Style

- Chinese or English matching the user; product docs for this repo default to **繁體中文**.
- Complete sentences in requirements/spec; tasks can be tighter checklists.
- Link related existing docs; do not duplicate architecture textbooks into requirements.

## Anti-patterns

- Writing all four layers in one go without approval
- Coding during requirements/spec
- Tasks without file paths or acceptance commands
- Treating `docs/post-project-plan.md` as approved requirements without copying into this pipeline
- Inflating a "whole product" requirements doc without P0/P1/P2 prioritization