nw-deliver

name	nw-deliver
description	Orchestrates the full DELIVER wave end-to-end (roadmap > execute-all > finalize). Use when all prior waves are complete and the feature is ready for implementation.
user-invocable	true
argument-hint	[feature-description] - Example: "Implement user authentication with JWT"

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] <Section> 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 — <N> of <M> 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] <Section> only when requested via --expand <id> (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): <!-- DES-ENFORCEMENT : exempt -->.

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:

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: <NAME> / [REF|WHY|HOW] <Section>); 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: <NAME> / [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: <!-- DES-VALIDATION : required -->, <!-- DES-PROJECT-ID : {feature-id} -->, <!-- DES-MODE : orchestrator -->.

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.

Task(
    subagent_type="{agent}",
    model=rigor_agent_model,  # omit if "inherit"
    prompt=f'''
<!-- DES-VALIDATION : required -->
<!-- DES-PROJECT-ID : {project_id} -->
<!-- DES-STEP-ID : {step_id} -->

# 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] <Section> 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.