daniel.w
/
thread-master
1
0
Fork 0
Code Issues Pull Requests 1 Packages Projects Releases Wiki Activity
thread-master/.grok/skills/spec-driven/SKILL.md

5.3 KiB
Raw Blame History

name description
spec-driven 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

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:

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

Optional scaffold:

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