spec-driven

name

spec-driven

description

WellForge spec-driven development conventions: the spec → plan → tasks workflow, file formats, status lifecycle, and drift rule. Use whenever working in a project that has a specs/ directory, when the user mentions a spec, feature specification, or task list, when implementing any task that references a specs/NNN-slug/ path, or when asked about the status of a feature. Also the authoritative reference for the /wellforge:spec, /wellforge:plan, /wellforge:design, and /wellforge:tasks commands — they MUST follow this format exactly.

Spec-driven development — WellForge conventions

One standardized path from idea to reviewed task list. Three artifacts per feature, three commands, two human approval gates. The spec directory is the contract between agents: the Product Owner writes spec.md, the Architect writes plan.md, developers consume tasks.md.

idea ──/wellforge:spec──► spec.md ──[user approves]──/wellforge:plan──► plan.md ──[user approves]──/wellforge:tasks──► tasks.md ──► implementation
                                                              └─(UI features)─/wellforge:design──► design.md ──┘

For UI features, the optional design stage (/wellforge:design, the designer agent) runs between plan and tasks — flows, screens/states, component reuse, a11y — so frontend tasks derive from a real inventory. Ungated by default (validated at QE — the flow's only mandatory gates are spec and plan); opt into a design checkpoint with /wellforge:design --gate. /wellforge:orchestrate runs it automatically for UI features; in the manual flow, /wellforge:plan and /wellforge:tasks nudge you to it.

Directory layout

specs/
├── 001-user-auth/
│   ├── spec.md      # WHAT & WHY — problem, user stories, acceptance criteria
│   ├── plan.md      # HOW — architecture, data model, API contracts, test strategy
│   ├── design.md    # optional, UI features only — flows, screens, component reuse, a11y
│   ├── tasks.md     # ordered, dependency-aware task list
│   ├── eval.md      # optional — per-feature rubric overrides (add dims / raise floors only)
│   └── eval-report.md  # LM-judge scored verdict (written by /wellforge:eval)
├── 002-csv-export/
│   └── spec.md
└── 003-pricing-poc/
    └── brief.md     # spike tier ONLY — a brief replaces spec/plan/tasks (see rigor-tiers)

The full spec→plan→tasks set is the production tier. Lower rigor tiers carry less: mvp skips plan.md/design.md/eval (one gate), and spike replaces the whole set with a single brief.md. The tier lives in the feature's frontmatter as rigor: (default production). See the rigor-tiers skill — load it whenever a feature isn't production.

• NNN is zero-padded and sequential across the project (ls specs/ | sort | tail -1 to find the next).
• slug is short kebab-case; never rename a directory after creation (it's referenced from commits).

Status lifecycle

Status lives in spec.md frontmatter only (plan.md has its own status limited to draft | approved; design.md is draft and only reaches approved if you opt into the design checkpoint with /wellforge:design --gate — by default design is ungated and stays draft, validated at QE). Transitions:

draft ──► approved ──► in-progress ──► done
                                └────► superseded (link the successor)

• Only the user moves a spec from draft to approved — never set it yourself. Record approval as approved: 2026-06-04 in the frontmatter when the user says so.
• in-progress is set when the first task starts. Reaching done goes through the guarded /wellforge:done command (or /wellforge:orchestrate's close step, same gate) — never a hand-edit or an agent. The done gate is tier-aware: production needs every task checked + QE PASS + a fresh passing eval-report.md (the LM-judge — QE alone isn't enough, "set the bar at the eval, not the demo"); mvp needs tasks checked + QE-light PASS (no eval); spike closes via its brief.md findings. /wellforge:done refuses to close a feature whose gate isn't met.

File formats

spec.md

---
id: 002
slug: csv-export
status: draft
rigor: production   # production (default) | mvp | spike — see the rigor-tiers skill
created: 2026-06-04
---

# CSV export for reports

## Problem
<2-5 sentences: who hurts, how, why now. No solutions here.>

## User stories
### US-1: <title>
As a <role>, I want <capability>, so that <benefit>.
**Acceptance criteria:**
- AC-1.1: Given <context>, when <action>, then <observable outcome>.
- AC-1.2: ...

## Non-goals
- <explicitly out of scope, with one-line reason>

## Open questions
- [ ] <question> — owner: <who>

Rules: every AC must be objectively verifiable (a QE can turn it into a test without asking anything). Open questions must be empty or explicitly accepted-as-risk before approval.

plan.md

---
spec: 002
status: draft
---

# Plan: CSV export for reports

## Architecture
<components touched/added, sequence of interactions, why this shape. Reference ADRs.>

## Data model
<new/changed tables, migrations needed>

## API contracts
<endpoints/events with request/response shapes — concrete, not prose>

## Test strategy
<what gets unit / integration / e2e coverage; which ACs map to which test level>

## Risks
<what could invalidate this plan>

## Security
<security-sensitive? YES/NO + why (auth, PII, upload, external calls, payments, regulated
data). YES schedules an owasp-reviewer pass in parallel with QE — see the architect agent.>

tasks.md

---
spec: 002
generated: 2026-06-04
---

# Tasks: CSV export for reports

- [ ] T1: <imperative title> — refs: US-1, AC-1.1 — deps: none
  - touch: `backend/src/.../ReportExporter.kt`
  - done when: <objective check, e.g. "integration test X passes">
- [ ] T2: ... — deps: T1

Rules: every task references at least one AC; every AC is covered by at least one task; deps: must form a DAG (tasks with no mutual deps may run in parallel).

Workflow gates

• /wellforge:plan MUST refuse to run if spec.md status is not approved.
• /wellforge:tasks MUST refuse to run if plan.md status is not approved.
• Never skip a stage "because it's small" — for trivial changes the spec is 10 lines, not absent. The ONLY sanctioned way to run fewer stages is a declared lower rigor tier (rigor: mvp/spike in frontmatter, via /wellforge:spike or --mode) — explicit and recorded, never an ad-hoc skip. These gates apply in full to the production tier.

Drift rule

The spec is the source of truth. If implementation reveals the spec/plan is wrong:

1. Stop, update spec.md / plan.md first (status stays in-progress, note the change).
2. Re-run /wellforge:tasks to re-sync tasks.md.
3. Then continue coding.

Enforced mechanically: the Stop hook (stop-verify.sh) blocks finishing a session where spec.md/plan.md changed but tasks.md did not.

Implementing tasks

• Work tasks in dependency order; set the checkbox immediately on completion.
• Reference task IDs in commit messages: feat(report): add CSV serializer (T1, specs/002).
• When the last task is checked and gates pass, close the feature with /wellforge:done (it verifies the tier's done gate before flipping the status).