135 lines
5.3 KiB
Markdown
135 lines
5.3 KiB
Markdown
---
|
||
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
|