--- name: nwave-ai/nw-deliver source: https://app.decimal.ai/s/nwave-ai-nw-deliver@1/SKILL.md source_sha256: 3d2e311cc3fc --- # NW-DELIVER: Complete DELIVER Wave Orchestrator **Wave**: DELIVER (wave 6 of 6)|**Agent**: Main Instance (orchestrator)|**Command**: `/nw-deliver "{feature-description}"` ## LANGUAGE CONVENTION FRAME (read FIRST — overrides all examples below) **Code examples in this skill use Python syntax for illustration only.** They are NOT prescriptive about target language. nWave is language-agnostic per the "genericity and agnosticism" mandate (2026-05-24). **Before crafting**, detect the target project's language from manifest files: `package.json` → TypeScript/JS; `Cargo.toml` → Rust; `go.mod` → Go; `pyproject.toml`/`setup.py`/`Pipfile` → Python; `pom.xml`/`build.gradle` → Java/Kotlin; `*.csproj`/`*.fsproj` → C#/F#; `Gemfile` → Ruby; `Package.swift` → Swift. **When the target language is NOT Python**: adapt every code example to target conventions (imports, type system, test-framework idioms, file extensions, directory layout). Project conventions ALWAYS WIN over examples below. **Empirical anchor**: skill examples being Python-only caused LLM to emit Python code in greenfield TS project. Fix per F-SKILL-EXAMPLES-LANGUAGE-LEAK. Connects [[feedback_language_adapter_plugin_architecture_2026_05_24]]. ## Overview Orchestrates complete DELIVER wave: feature description → production-ready code with mandatory quality gates. You (main Claude instance) coordinate by delegating to specialized agents via Task tool. Final wave (DISCOVER > DISCUSS > SPIKE > DESIGN > DEVOPS > DISTILL > DELIVER). Sub-agents cannot use Skill tool or `/nw-*` commands. You MUST: - Read the relevant command file and embed instructions in the Task prompt - Remind the crafter to load its skills as needed for the task (skill files are at `~/.claude/skills/nw-{skill-name}/SKILL.md`) ## Output Tiers (per D2) Provenance: feature `lean-wave-documentation` — D2 (schema-typed sections), D10 (one-line expansion descriptions). Tier-1 [REF] sections (always emitted) + Tier-2 EXPANSION CATALOG items (lazy, on-demand) are the two output bands. Implementation details live in code; the wave-delta sections are pointers + structured summaries. Full contract: `nWave/skills/nw-density-resolution-contract/SKILL.md`. ### Tier-1 [REF] — always emitted Under `## Wave: DELIVER / [REF]
` headings: - Implementation summary — one-paragraph description of what shipped (no design rationale) - Files modified — categorized list (production, tests, docs) with one-line per file - Scenarios green count — ` of ` from the `.feature` file with timestamp - DoD check — itemized pass/fail against the DISCUSS Definition of Done items - Demo evidence — captured stdout/exit-code per Elevator Pitch demo command (Phase 3.5 gate) - Quality gates — per-phase outcomes (refactor, review, mutation, integrity) - Pre-requisites — DISTILL scenarios + DESIGN component manifest the implementation depended on ### Tier-2 EXPANSION CATALOG — lazy, on-demand (per D10) Rendered under `## Wave: DELIVER / [WHY|HOW]
` only when requested via `--expand ` (DDD-2), the wave-end menu (`expansion_prompt = "ask"`), `mode = "full"` auto-expansion, or an ad-hoc user request mid-session. | Expansion ID | Tier label | One-line description | |---|---|---| | `refactoring-journal` | [HOW] | L1-L6 refactoring log with rationale per micro-transformation | | `retrospective-notes` | [WHY] | 5 Whys analysis on issues encountered, lessons learned, what to repeat/avoid | | `performance-measurements` | [WHY] | Benchmarks, profiling output, latency/memory deltas vs baseline | | `alternative-implementations-rejected` | [WHY] | Implementation approaches tried and rejected with one-paragraph reason each | | `mutation-testing-report` | [HOW] | Mutmut/Pitest output: kill rate, surviving mutants, mitigation actions | | `architecture-decision-deviations` | [WHY] | Where DELIVER deviated from DESIGN and the back-propagation logged in upstream-issues.md | | `coverage-deltas` | [HOW] | Per-module coverage delta with rationale for any drops | | `expansion-catalog-rationale` | [WHY] | Why this set of expansions, why these defaults, why D10 enforces one-line descriptions | ## Density resolution (per D12) Call `resolve_density(global_config)` from `scripts/shared/density_config.py` after reading `~/.nwave/global-config.json` (missing/malformed = empty dict). Returns `mode` (`"lean"` | `"full"`) + `expansion_prompt` (`"ask"` | `"always-skip"` | `"always-expand"` | `"smart"`) per the D12 cascade (resolver-internal, DDD-5 — do NOT replicate locally). Branch on `density.mode` for what to emit; branch on `density.expansion_prompt` at wave end for menu behaviour. Full cascade detail, branch semantics, ad-hoc override workflow: `nWave/skills/nw-density-resolution-contract/SKILL.md`. ## Telemetry (per D4 + DDD-6) Every expansion choice emits a `DocumentationDensityEvent` (dataclass at `src/des/domain/telemetry/documentation_density_event.py`) via `event.to_audit_event()` → `JsonlAuditLogWriter().log_event(...)`. Schema fields per D4: `feature_id`, `wave`, `expansion_id`, `choice`, `timestamp`. For this wave the schema declares `"wave": "DELIVER"`. Use helper `scripts/shared/telemetry.py:write_density_event(...)` — do NOT write JSONL directly. Wave-specific signal: a DELIVER wave recording `choice = "expand"` for `retrospective-notes` indicates the team needed deeper learning capture; over time the data drives whether retrospective notes should be promoted to Tier-1. Full emission rules: `nWave/skills/nw-density-resolution-contract/SKILL.md`. ## CRITICAL BOUNDARY RULES 1. **NEVER implement steps directly.** ALL implementation MUST be delegated to the selected crafter (@nw-software-crafter or @nw-functional-software-crafter per step 1.5) via Task tool with DES markers. You are ORCHESTRATOR — coordinate, not implement. 2. **NEVER write phase entries to execution-log.json.** Only the crafter subagent that performed TDD work may append entries. 3. **Extract step context from roadmap.json ONLY for Task prompt.** Grep roadmap for step_id ~50 lines context, extract (name|criteria|files_to_modify) per `nWave/templates/roadmap-schema.json`, pass in DES template. **DES monitoring is non-negotiable.** Circumventing DES — faking step IDs, omitting markers, or writing log entries manually — is a **violation that invalidates the delivery**. DES detects unmonitored steps and flags them; finalize **blocks** until every flagged step is re-executed through a properly instrumented Task. There is no workaround: unverified steps cannot pass integrity verification, and the delivery cannot be finalized. Without DES monitoring, nWave cannot **verify** TDD phase compliance. For non-deliver tasks (docs, research, one-off edits): ``. ## Rigor Profile Integration Before dispatching any agent, read the rigor profile from `.nwave/des-config.json` (key: `rigor`). If absent, use standard defaults. **How rigor affects deliver phases:** | Setting | Effect | |---------|--------| | `agent_model` | Pass as `model` parameter to all Task tool invocations for crafter agents. If `"inherit"`, omit `model` parameter (Task tool inherits from session). | | `reviewer_model` | Pass as `model` parameter to reviewer Task invocations. If `"skip"`, skip Phase 4 entirely. | | `review_enabled` | If `false`, skip Phase 4 (Adversarial Review). | | `double_review` | If `true`, run Phase 4 twice with separate review scopes. | | `tdd_phases` | Pass to crafter in DES template. Replace `# TDD_PHASES` section with the configured phases. The 3-phase canon (ADR-025) is `[RED, GREEN, COMMIT]`; legacy 5-phase contract is `[PREPARE, RED_ACCEPTANCE, RED_UNIT, GREEN, COMMIT]`. If lean profile (`[RED_UNIT, GREEN]` legacy or `[RED, GREEN]` canon), omit setup/commit instructions accordingly. | | `refactor_pass` | If `false`, skip Phase 3 (Complete Refactoring). | | `mutation_enabled` | If `false`, skip Phase 5 regardless of mutation strategy in CLAUDE.md. | **Task invocation with rigor model:** ```python Task( subagent_type="{agent}", model=rigor_agent_model, # omit this line entirely if "inherit" max_turns=45, prompt=..., ) ``` ## Prior Wave Consultation Before beginning DELIVER work, read prior wave content. With lean v3.14, all wave decisions live in a single `feature-delta.md` (sections tagged `## Wave: / [REF|WHY|HOW]
`); legacy multi-file directories are no longer produced. 1. **DISCOVER** (skip): Synthesized into DISCUSS sections of `feature-delta.md`. 2. **DISCUSS** (read on demand): in `docs/feature/{feature-id}/feature-delta.md` under `## Wave: DISCUSS / [REF] ...` sections. Already encoded as acceptance scenarios — read for elevator pitch extraction (Phase 3.5) and clarification only. 3. **DESIGN** (structural context, MANDATORY): Read `docs/product/architecture/brief.md` (cross-feature SSOT — component boundaries, driving ports, C4 diagrams). PLUS read `docs/feature/{feature-id}/feature-delta.md` filtered to `## Wave: DESIGN / [REF] ...` sections — DDD list, component decomposition, driving/driven ports, technology choices, decisions table, reuse analysis. 4. **DEVOPS** (read on demand): in `feature-delta.md` under `## Wave: DEVOPS / [REF] ...` sections. Read only if test environment issues arise. 5. **DISTILL** (primary input, MANDATORY): TWO sources: - `feature-delta.md` `## Wave: DISTILL / [REF] ...` sections — scenario list with tags, walking skeleton strategy, adapter coverage, scaffold inventory, test placement, driving adapter coverage, pre-requisites - Executable `.feature` files at the test placement path declared in DISTILL (e.g. `tests/{feature-id-or-bounded-context}/acceptance/*.feature`) — these are the authoritative specification **READING ENFORCEMENT**: You MUST read `feature-delta.md` (full file) AND `docs/product/architecture/brief.md` AND every `.feature` file referenced in the DISTILL Test Placement section before proceeding. After reading, output a confirmation checklist (`✓ {file}` for each read, `⊘ {file} (not found)` for missing). Do NOT skip files that exist — skipping causes implementation disconnected from architecture and acceptance tests. **Migration fallback for legacy features**: If `docs/feature/{feature-id}/feature-delta.md` does NOT exist BUT legacy multi-file directories (`discuss/`, `design/`, `devops/`, `distill/`) DO exist, treat the legacy layout as authoritative for THIS feature only. Read all files in those directories. Future waves should consolidate to `feature-delta.md` per lean v3.14. **Upstream issues check**: look for `## Wave: / [WHY] Upstream Issues` sections in `feature-delta.md` (or legacy `upstream-changes.md` / `upstream-issues.md` files in legacy multi-file features). If unresolved issues exist, flag them to the user before starting implementation. **On-demand escalation**: If during implementation a crafter encounters ambiguity not resolved by DISTILL tests or DESIGN architecture, the orchestrator re-reads specific sections of `feature-delta.md` — never re-reads the full file unnecessarily. ## Document Update (Back-Propagation) When DELIVER implementation reveals gaps or contradictions in prior waves: 1. Document findings as a `## Wave: DELIVER / [WHY] Upstream Issues` section appended to `docs/feature/{feature-id}/feature-delta.md` (lean v3.14 — Tier-2 expansion) OR `docs/feature/{feature-id}/deliver/upstream-issues.md` (legacy multi-file) 2. Reference the original prior-wave document and describe the issue 3. If implementation requires deviating from architecture or requirements, document the deviation and rationale 4. Resolve with user before continuing past the affected step ## Orchestration Flow At the start of execution, create these tasks using TaskCreate and follow them in order: 0. **Read Rigor Profile** — Read `.nwave/des-config.json` key `rigor`. Store: `agent_model`, `reviewer_model`, `tdd_phases`, `review_enabled`, `double_review`, `mutation_enabled`, `refactor_pass`. Use standard defaults if absent. Gate: rigor profile loaded or defaults set. 0.5. **Prior Wave Consultation** — Read `docs/feature/{feature-id}/feature-delta.md` (lean v3.14: full file with DISCUSS/DESIGN/DEVOPS/DISTILL sections) + `docs/product/architecture/brief.md` + every `.feature` file declared in the DISTILL Test Placement section. Legacy fallback: if `feature-delta.md` is missing but multi-file dirs exist, read those instead. Flag contradictions, resolve before proceeding. Summarize key design decisions into a reusable DESIGN_CONTEXT block for crafter dispatch (component structure, boundaries, tech choices, data models). Gate: all required files read, confirmation checklist output, no unresolved contradictions. 1. **Setup** — Parse input, derive `feature-id` (kebab-case), create `docs/feature/{feature-id}/deliver/`. - a. Create `execution-log.json` via CLI: `des-init-log --project-dir docs/feature/{feature-id}/deliver --feature-id {feature-id}`. Do NOT use Write tool directly. - b. Create deliver session marker: `.nwave/des/deliver-session.json`. - Gate: directory exists, `execution-log.json` created via CLI, session marker written. 1.5. **Detect Development Paradigm** — Read project `CLAUDE.md` (project root, NOT `~/.claude/CLAUDE.md`). Search "## Development Paradigm". - Found → extract paradigm: `"functional"` → `@nw-functional-software-crafter` or `"object-oriented"` → `@nw-software-crafter` (default). - Not found → ask user "OOP or Functional?", offer to write to `CLAUDE.md`. - Store selected crafter for all Phase 2 dispatches. - Functional → property-based testing default; `@property` tags signal PBT; example-based = fallback. - Gate: crafter selected and stored. 1.6. **Detect Mutation Testing Strategy** — Read same `CLAUDE.md`, search "## Mutation Testing Strategy". - Found → extract: `per-feature` | `nightly-delta` | `pre-release` | `disabled`. - Not found → default `nightly-delta` (recommended mode — CI runs mutmut nightly on changed modules; keeps per-feature gates fast). - Log strategy for traceability. Note: strategy locks at deliver start; `CLAUDE.md` edits during delivery take effect next run. - Gate: strategy recorded. 1.7. **Detect Deliverable Type** (ADR-PST-003 / DDD-6) — Read `deliverable_type` from the SAME `.nwave/des-config.json` the runtime gate uses — this is the single source of truth (`DESConfig.deliverable_type` precedence, ADR-PST-002): (1) declared project `.nwave/des-config.json` key `deliverable_type` if in the known set `{application, plugin, skill}`; (2) else global `~/.nwave/global-config.json` `defaults.deliverable_type`; (3) else root-only FS detection; (4) a present-but-typo'd value resolves to the safe default (treated as `application`). Do NOT re-detect independently — read what the gate reads so the verification plan and the enforcement gate never diverge. - `application` (or unresolved) → store `application`. Verification plan UNCHANGED (pytest / Hypothesis routing, `@nw-software-crafter-reviewer`). - `plugin` → store `plugin`. The Phase 4 verification plan branches (see Phase 4). - `skill` → store `skill`. The Phase 4 verification plan branches (see Phase 4). - Gate: deliverable type read from `.nwave/des-config.json` and stored for Phase 4 routing. 2. **Phase 1 — Roadmap Creation + Review** — Gate: roadmap created, integrity verified, reviewer approved. - a. Skip if `docs/feature/{feature-id}/deliver/roadmap.json` exists with `validation.status == "approved"`. If found in `design/` instead, move to `deliver/` and log warning. - b. Dispatch `@nw-solution-architect` to create `roadmap.json` (load `~/.claude/skills/nw-roadmap/SKILL.md`). Step IDs MUST match `NN-NN` format (01-01, 01-02). If `distill/` exists, architect MUST populate `test_file` and `scenario_name` per step. - c. Run automated quality gate (see Roadmap Quality Gate section below). - c2. Run roadmap integrity verification (HARD GATE): `des-verify-integrity docs/feature/{feature-id}/deliver/ --roadmap-only` — validates `roadmap.json` against the schema only; execution-log cross-reference is skipped (no log entries exist yet pre-crafter). Exit 0 = roadmap OK; exit 1 = schema errors printed; exit 2 = file missing or usage error. BLOCK on any non-zero exit; fix before dispatching any crafter. - d. Dispatch `@nw-acceptance-designer-reviewer` to review roadmap (load `~/.claude/skills/nw-review/SKILL.md`): verify every DISTILL scenario has a step, flag orphan scenarios as BLOCKER; flag steps covering 8+ scenarios as `@sizing-review-needed`; verify walking skeleton scenarios map to Phase 1 steps. - e. Retry once on rejection → stop for manual intervention. 3. **Phase 2 — Execute All Steps** — Gate: all steps reach COMMIT/PASS in `execution-log.json`. - a. Extract steps from `roadmap.json` in dependency order. - b. Check `execution-log.json` for prior completion (resume mode). - c. Dispatch selected crafter (from step 1.5) with full DES Prompt Template from `execute.md` (load `~/.claude/skills/nw-execute/SKILL.md`). Include DES markers (`DES-VALIDATION`, `DES-PROJECT-ID`, `DES-STEP-ID`) + all mandatory sections. Functional crafter → PBT default; `@property` tags signal PBT. - d. Verify COMMIT/PASS in `execution-log.json` per step. - e. Missing phase → RE-DISPATCH agent. NEVER write entries directly. - f. Stop on first failure. - g. Timeout recovery: GREEN completed → resume (~5 turns); GREEN partial → resume; otherwise → restart with higher `max_turns`. - h. Wiring smoke check: verify every new function defined in production files has at least one call site in production code (not just tests). Flag "function X defined but only called from tests" → re-dispatch crafter. - i. Acceptance test gate: after each step's COMMIT/PASS, run `tests/acceptance/{feature-id}/`. Fix failures before proceeding to next step. No deferral. 3.5. **Post-Merge Integration Gate (Hard Gate)** — AFTER all steps reach COMMIT/PASS, BEFORE Phase 3. Gate: full acceptance suite passes in all environments AND every story's Elevator Pitch demo command produces non-empty output. - a. Run `uv run pytest tests/acceptance/{feature-id}/ -v --tb=short`. - b. Run acceptance tests against EVERY environment listed in the `## Wave: DEVOPS / [REF] Environment Matrix` section of `feature-delta.md` (lean v3.14) OR `docs/feature/{feature-id}/devops/environments.yaml` (legacy multi-file). If neither, use defaults: `clean`, `with-pre-commit`, `with-stale-config`. - c. BLOCK if ANY test fails in ANY environment. - d. **Elevator Pitch demo execution (HARD GATE)** — For every user story in the `## Wave: DISCUSS / [REF] User Stories with Elevator Pitches` section of `feature-delta.md` (lean v3.14) OR `docs/feature/{feature-id}/discuss/user-stories.md` (legacy) that is NOT tagged `@infrastructure`: - Extract the `After: run ... → sees ...` line - Execute the exact command (subprocess, not function call) - Capture stdout + exit code - Verify: exit code is 0, stdout is non-empty, stdout contains the substring described by the "sees" clause - On any failure: BLOCK with message "Story {N}: demo command {cmd} did not produce visible output — either the CLI is broken or the story Elevator Pitch is fictional. Fix one or the other." - Append demo output to `docs/feature/{feature-id}/feature-delta.md` as `## Wave: DELIVER / [REF] Demo Evidence` (lean v3.14 — single narrative file) OR `docs/feature/{feature-id}/deliver/wave-decisions.md` under a `## Demo Evidence — {date}` section (legacy multi-file). Do NOT create a separate demo-output file. - e. On failure at step a/b: identify failing environment + test, re-dispatch crafter for new TDD cycle, re-run full gate after fix. If same test fails in 2+ environments after one fix attempt, STOP and report to user. - f. On success: record gate passage in `execution-log.json`: `{"gate": "post-merge-integration", "status": "PASS", "environments_tested": [...], "stories_demoed": [...], "timestamp": "ISO-8601"}`. 4. **Phase 3 — Complete Refactoring (L1-L6)** — [SKIP if `rigor.refactor_pass = false`]. Gate: all tests green after each module refactored. - a. Collect modified files: `git diff --name-only {base-commit}..HEAD -- '*.py' | sort -u`. Split into PRODUCTION_FILES (`src/`) and TEST_FILES (`tests/`). - b. Run `/nw-refactor {files} --levels L1-L6` via selected crafter with DES orchestrator markers: ``, ``, ``. 5. **Phase 4 — Adversarial Review** — [SKIP if `rigor.review_enabled = false` or `rigor.reviewer_model = "skip"`]. Gate: review passed or one revision complete. **Reviewer routing branches on the deliverable type stored in step 1.7** (ADR-PST-003 / DDD-6): **`application` (or unresolved)** — UNCHANGED: - a. Dispatch `/nw-review @nw-software-crafter-reviewer implementation "{execution-log-path}"` with `model=rigor.reviewer_model` and DES orchestrator markers. - b. If `rigor.double_review = true` → run review a second time with different scope focus. - c. Scope: ALL files modified during feature; includes Testing Theater 7-pattern detection. - d. One revision pass on rejection → proceed. **`plugin`** — dispatch `@nw-plugin-validator` (Claude Code plugin structure/schema) AND `@nw-skill-reviewer` (SKILL.md quality), both on Haiku, plus `@nw-software-crafter-reviewer` for any application-layer code in the same feature. Verification evidence is behavioral Gherkin + example-interaction evidence (the plugin demonstrated through its real invocation path), with optional `bats`/`shellcheck` for any shell. NOT pytest/Hypothesis-centric. One revision pass on rejection → proceed. **`skill`** — dispatch `@nw-skill-reviewer` (SKILL.md quality, Haiku). Do NOT dispatch `@nw-plugin-validator` (no plugin structure to validate). Verification evidence is behavioral Gherkin. One revision pass on rejection → proceed. **Authoring stays with `@nw-agent-builder`**: when a plugin/skill review finds content to author or rewrite, route the fix to `@nw-agent-builder` — the validators/reviewers are read-only. The four `*-development` specialist agents remain DEFERRED. 6. **Phase 5 — Mutation Testing** — [SKIP if `rigor.mutation_enabled = false`]. Gate: ≥80% kill rate or strategy skip logged. - `per-feature` → gate ≥80% kill rate (load `~/.claude/skills/nw-mutation-test/SKILL.md`). - `nightly-delta` → SKIP; log "handled by CI nightly pipeline". - `pre-release` → SKIP; log "handled at release boundary". - `disabled` → SKIP; log "disabled per project configuration". 7. **Phase 6 — Deliver Integrity Verification** — Gate: `verify_deliver_integrity` exits 0. - a. Run: `des-verify-integrity docs/feature/{feature-id}/deliver/`. - b. Exit 0 → proceed. Exit 1 → STOP, read output. Exit 2 → rigor misconfiguration (see e). - c. No entries = not executed through DES. Partial = incomplete TDD. - d. Violations → re-execute via Task with DES markers. Proceed only after pass. - e. **Rigor-aware integrity** (F-3, ADR-025): the verifier tracks the rigor-profile phase set declared in `.nwave/des-config.json` (`rigor.tdd_phases`), intersected with the canonical TDDSchema. 3-phase ADR-025 projects (`[RED, GREEN, COMMIT]`) verify cleanly. Legacy 5-phase projects continue to verify unchanged. Empty intersection → exit 2 with diagnostic naming the offending rigor phases (fix `.nwave/des-config.json` and rerun). 8. **Phase 7 — Finalize** — Gate: evolution archived, session markers removed, commit pushed, hook offer made (if applicable). - a. Dispatch `@nw-platform-architect` to archive to `docs/evolution/` (load `~/.claude/skills/nw-finalize/SKILL.md`). - b. Commit + push. Run: `rm -f .nwave/des/deliver-session.json .nwave/des/des-task-active`. - c. **One-time test-hook offer** — Check whether the project's pre-commit/pre-push test hooks are installed (absence of the pre-commit framework marker in `.git/hooks/pre-push`). If NOT installed AND not previously declined (no `.nwave/hook-offer-declined` marker): offer the user ONCE — suggest running `pre-commit install --hook-type pre-commit --hook-type pre-push` so tests also run automatically on commit/push. This is an OFFER, not enforcement; it does NOT replace the crafter's own mandatory terminating test run (the suite always runs at the end of every code modification regardless of hooks — `feedback_target_machine_independence_2026_05_15`). If the user declines, write `.nwave/hook-offer-declined` and do not re-offer. 9. **Phase 8 — Retrospective (conditional)** — Skip if clean execution. Gate: 5 Whys documented or clean-run noted. - On issues found → dispatch `@nw-troubleshooter` for 5 Whys analysis. 10. **Phase 9 — Report Completion** — Display summary: phases, steps, reviews, artifacts. Gate: report output, return to DISCOVER for next iteration. ## Orchestrator Responsibilities Follow this flow directly. Do not delegate orchestration. Per phase: 1. **Read command file** — Read the relevant command file (paths listed in each phase above). 2. **Embed instructions** — Extract instructions and embed them in the Task prompt. 3. **Add task boundary** — Include task boundary instructions to prevent workflow continuation. 4. **Verify artifacts** — Verify output artifacts exist after each Task completes. 5. **Update progress** — Update `.develop-progress.json` for resume capability. ## Task Invocation Pattern DES markers required for step execution. Without markers → unmonitored. Full DES Prompt Template in `~/.claude/skills/nw-execute/SKILL.md`. When dispatching steps via Agent tool, use the COMPLETE DES template from execute.md verbatim. Fill all `{placeholders}` from roadmap step context. The DES hook validates the prompt BEFORE the sub-agent starts — abbreviated prompts that delegate template reading to the sub-agent will be BLOCKED. Copy the template from the code block in `~/.claude/skills/nw-execute/SKILL.md` (between ``` markers), fill placeholders, and pass as the Agent prompt. The template sections are defined in execute.md — do not hardcode the list here. ```python Task( subagent_type="{agent}", model=rigor_agent_model, # omit if "inherit" prompt=f''' # DES_METADATA Step: {step_id} Feature: {project_id} Command: /nw-execute # AGENT_IDENTITY Agent: {agent} # SKILL_LOADING Before starting TDD phases, read your skill files for methodology guidance. Skills path: ~/.claude/skills/nw-{skill-name}/SKILL.md Always load at PREPARE: tdd-methodology.md, quality-framework.md Load on-demand per phase as specified in your Skill Loading Strategy table. # TASK_CONTEXT {step context extracted from roadmap - name|criteria|test_file|scenario_name|implementation_notes|deps|files_to_modify (per nWave/templates/roadmap-schema.json)} # DESIGN_CONTEXT {Summarize key architectural decisions from design wave artifacts read at step 0.5. Include: component structure, dependency-inversion boundaries, technology choices, data models, and any design constraints relevant to this step. Source files: docs/product/architecture/brief.md, wave-decisions.md. If no design artifacts exist, write "No design artifacts available — use project conventions."} # TDD_PHASES ... (copy remaining sections from execute.md template verbatim) # TIMEOUT_INSTRUCTION Target: 30 turns max. If approaching limit, COMMIT current progress. ''', description="{phase description}" ) ``` ## Roadmap Quality Gate (Automated, Zero Token Cost) After roadmap creation, before reviewer, run these checks: 1. **AC coupling** — Flag AC referencing private methods (`_method()`). HIGH → return to architect. 2. **Decomposition ratio** — Flag steps/files > 2.5. HIGH → return to architect. 3. **Identical patterns** — Flag 3+ steps with same AC structure (batch them). HIGH → return to architect. 4. **Validation-only** — Flag steps with no `files_to_modify`. HIGH → return to architect. 5. **Step ID format** — Flag non-matching `^\d{2}-\d{2}$`. HIGH → return to architect. 6. **DISTILL linkage** — If `feature-delta.md` contains `## Wave: DISTILL / [REF] ...` sections OR `docs/feature/{feature-id}/distill/` exists (legacy), flag steps missing `test_file`/`scenario_name`. HIGH → return to architect. ## Skip and Resume 1. **Check progress** — Read `.develop-progress.json` on start for resume state. 2. **Skip approved roadmap** — Skip Phase 1 if `roadmap.json` exists with `validation.status == "approved"`. 3. **Skip completed steps** — Skip steps already showing COMMIT/PASS in `execution-log.json`. 4. **Cap retries** — Max 2 retries per review rejection → stop for manual intervention. ## Input - `feature-description` (string, required, min 10 chars) - `feature-id`: strip prefixes (implement|add|create), remove stop words, kebab-case, max 5 words ## Outputs **Single narrative file**: `docs/feature/{feature-id}/feature-delta.md` — implementation summary, files modified, scenarios green count, DoD check, demo evidence, quality gates, pre-requisites all become `## Wave: DELIVER / [REF|WHY|HOW]
` headings. Implementation details live in code; the wave-delta sections are pointers + structured summaries. **Machine artifacts** (declared, parseable by DES + downstream tooling): - `docs/feature/{feature-id}/roadmap.json` — step-by-step execution plan (created by nw-solution-architect, consumed by DES dispatcher) - `docs/feature/{feature-id}/execution-log.json` — DES audit log of phase events per step (created by `des-init-log`, written by crafter sub-agents only) - `docs/feature/{feature-id}/.develop-progress.json` — resume marker for skip-and-resume **Long-term archive** (outside the feature dir): `docs/evolution/{feature-id}-evolution.md` — written by the platform architect at finalize time; cross-feature retrospective context. **SSOT updates** (per Recommendation 3 / back-propagation contract): - `docs/product/architecture/brief.md` — append shipped components to the Component Inventory subsection; mark previously-planned components that did NOT ship as deferred. - `docs/product/kpi-contracts.yaml` — record measured baselines for each outcome KPI (the value at GA / first dogfood) so future deltas have a reference point. Legacy multi-file outputs (`implementation-notes.md`, `commits.md`, `retrospective.md` as separate files in `docs/feature/{id}/deliver/`) are NOT produced — that content lives in `feature-delta.md` and `docs/evolution/`. Validator: `scripts/validation/validate_feature_layout.py`. ## Quality Gates Roadmap review (1 review, max 2 attempts)|Per-step TDD cycle (3-phase canon RED→GREEN→COMMIT per ADR-025, or legacy 5-phase PREPARE→RED_ACCEPTANCE→RED_UNIT→GREEN→COMMIT for pre-2026-05-07 audit-log replay)|Paradigm-appropriate crafter|L1-L6 refactoring (Phase 3)|Adversarial review + Testing Theater detection (Phase 4)|Mutation ≥80% if per-feature (Phase 5)|Integrity verification (Phase 6)|All tests passing per phase ## Design Compliance Check (MANDATORY — RCA F-2 fix) After each crafter step's COMMIT, verify the files modified match the DESIGN specification: 1. Read the `## Wave: DESIGN / [REF] Component Decomposition` table in `feature-delta.md` (lean v3.14) OR `docs/feature/{feature-id}/design/architecture-design.md` "Changes Per File" table (legacy multi-file) 2. Compare against `git diff --name-only` for the crafter's commit 3. If the crafter created a NEW file not listed in the design table: **STOP and flag** - A new file means a new component — this may be duplication of an existing component - Check the DESIGN's Reuse Analysis table (F-1) — if the new file's class overlaps an existing component, the crafter must extend the existing component instead - Do NOT proceed to the next step until resolved 4. If the crafter modified files not in the design table: acceptable (tests, config) but flag for review This gate prevents the pattern where crafters create parallel implementations instead of extending existing components (see RCA `docs/analysis/rca-systematic-duplication-despite-design.md`). ## Wave Completion Enforcement (MANDATORY — RCA F-3 fix) A feature CANNOT be marked COMPLETE unless ALL waves in its scope have been executed: - DISTILL must have produced acceptance test files (`.feature` + `test_*.py`) - All acceptance tests must be GREEN (no "DESIGNED, DISTILL needed" allowed at close) - Old code paths superseded by new components must be DELETED (no fallback coexistence) - The scaffold marker `__SCAFFOLD__ = True` must not exist in any production file Violating this rule creates dead code, dual paths, and accumulated technical debt. ## Success Criteria - [ ] Roadmap created and approved - [ ] All steps COMMIT/PASS (3-phase TDD canon per ADR-025, or legacy 5-phase for pre-2026-05-07 logs) - [ ] **Design compliance verified** per step (F-2 — no unauthorized new files) - [ ] **Wave sequence complete** (F-3 — no "DISTILL needed" at close) - [ ] L1-L6 refactoring complete (Phase 3) - [ ] Adversarial review passed (Phase 4) - [ ] Mutation gate ≥80% or skipped per strategy (Phase 5) - [ ] Integrity verification passed (Phase 6) - [ ] Evolution archived (Phase 7) - [ ] Retrospective or clean execution noted (Phase 8) - [ ] Completion report (Phase 9) ## Examples ### 1: Fresh Feature `/nw-deliver "Implement user authentication with JWT"` → roadmap → review → TDD all steps → mutation → finalize → report ### 2: Resume After Failure Same command → loads `.develop-progress.json` → skips completed → resumes from failure ### 3: Single Step Alternative For manual granular control, use individual commands: ``` /nw-roadmap @nw-solution-architect "goal" /nw-execute {selected-crafter} "feature-id" "01-01" /nw-finalize @nw-platform-architect "feature-id" ``` ## Completion DELIVER is final wave. After completion → DISCOVER for next feature or mark project complete.