Wave Directory Structure
Where nWave's artifacts live in v4, and which earlier locations were removed.
Delivery features: one feature directory
Every delivery feature has one feature directory: docs/feature/{id}/. The
nwdes.feature.directory setting selects the base directory (default
docs/feature); nwdes appends /<ID>.
docs/feature/{id}/
handoff.json the one canonical record of the feature
brief.md briefs rendered by nwdes document (with .html versions)
architecture.md
acceptance.md
runs/ run records, for example runs/craft.S1.json, runs/review.candidate.json
The handoff holds what the roles recorded: the request, promises, slices, design facts, expectations, acceptance rows and examination verdicts. Run records capture what each role closed. nwdes renders the briefs beside the handoff; they are the reading surface for humans. See Understanding delivery artifacts.
There is no per-wave subdirectory and no per-wave ledger inside the feature directory.
Product SSOT: docs/product/
Durable product files live under docs/product/ and are updated in place
instead of copied per feature. A wave command updates them when its skill
says so:
| Command | Updates |
|---|---|
/nw-discover |
docs/product/vision.md and/or docs/product/jobs.yaml (SSOT bootstrap); a quantified KPI baseline goes to docs/product/kpi-contracts.yaml |
/nw-diverge |
docs/product/jobs.yaml: the validated job, opportunity scores and a changelog entry |
/nw-diverge writes no wave-decisions.md and no other per-wave ledger. Its
recommendation.md and supporting analysis are working files while the
delivery is open, not durable authority.
Removed in v4: the per-wave runtime records
Earlier versions wrote per-wave subdirectories under the feature directory,
ending in a deliver/ phase tracked by two JSON files:
docs/feature/{id}/
discover/ ... discuss/ ... design/ ... devops/ ... distill/ ... deliver/
deliver/roadmap.json
deliver/execution-log.json
wave-decisions.md
v4 removed this workflow:
- The delivery record is the nwdes handoff and its run records.
roadmap.jsonandexecution-log.jsonare retired. No converter exists.- The installed hooks block every direct write to
execution-log.json. wave-decisions.mdis retired; no current wave writes a per-wave ledger.- A 3.x delivery in progress is finished on 3.22.2 or restarted from the
original request with
nwdes feature new(Migrate from nWave 3.x).
Existing per-wave trees in your repository are read-only history. Read them for context; do not extend them and do not rebuild their records.
Reading progress
nwdes keeps no workflow state and has no resume command. Read the artifacts
yourself (see Wave Routing). A DELIVER
run is complete when every slice in docs/feature/{id}/handoff.json has an
accepted craft run, the whole-candidate review and the examiner verdicts are
accepted, and the candidate is integrated.
A slice's acceptance oracle lives at the path the slice declares
(nwdes slice set --oracle). nWave fixes no test directory.
Cross-feature artifacts
| Location | Content | Written by |
|---|---|---|
| Your repository's ADR files | Architecture decision records | solution-architect, recorded through nwdes design verbs |
docs/evolution/ |
Historical post-completion archives; the current route writes none | - (existing files only) |
Feature ID Derivation
When you run /nw-deliver or any wave command, nWave derives a feature ID
from your description:
- Strip common prefixes: "implement", "add", "create", "build"
- Remove English stop words: "a", "the", "to", "for", "with", "and", "in", "on", "of"
- Convert to kebab-case (lowercase, hyphens)
- Limit to 5 segments maximum
Examples:
- "Add rate limiting to the API gateway" →
rate-limiting-api-gateway - "OAuth2 upgrade" →
oauth2-upgrade
The ID names the feature directory docs/feature/{id}/.