Nw Deliver

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 broad wave-end menu (expansion_prompt = "ask"), a declared trigger under expansion_prompt = "ask-intelligent", mode = "full" auto-expansion, or an ad-hoc user request mid-session.

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" | "ask-intelligent" | "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. DELIVER declares no ask-intelligent triggers: emit no menu and the shared-contract no-trigger skip event; do not invent triggers. 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:

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"}.