| 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:
- Stop, update spec.md / plan.md first (status stays
in-progress, note the change).
- Re-run
/wellforge:tasks to re-sync tasks.md.
- 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).
