nw-execute

name	nw-execute
description	Dispatches one unit of DELIVER work to a specialized agent for TDD execution. Runs a single roadmap.json step through the TDD cycle.
user-invocable	true
argument-hint	[agent] [feature-id] [step-id] - Example: @nw-software-crafter "auth-upgrade" "01-01"

NW-EXECUTE: Atomic Task Execution

Wave: EXECUTION_WAVE | Agent: Dispatched agent (specified by caller)

Overview

Dispatch one unit of DELIVER work to an agent: a single roadmap step. /nw-execute extracts the step from roadmap.json and dispatches it for the 3-phase TDD canon; the agent appends phase events to execution-log.json.

Syntax

/nw-execute @{agent} "{feature-id}" "{step-id}"

Context Files Required

• docs/feature/{feature-id}/deliver/roadmap.json — Orchestrator reads once, extracts step context
• docs/feature/{feature-id}/deliver/execution-log.json — Agent appends only (never reads)

Rigor Profile Integration

Before dispatching the agent, read rigor config from .nwave/des-config.json (key: rigor). If absent, use standard defaults.

• agent_model: Pass as model parameter to Agent tool. If "inherit", omit model (inherits from session).
• tdd_phases: Modify the TDD_PHASES section in the DES template to match the configured phases. The 3-phase canon (ADR-025) is [RED, GREEN, COMMIT]; the lean variant is [RED, GREEN]. Legacy 5-phase contract ([PREPARE, RED_ACCEPTANCE, RED_UNIT, GREEN, COMMIT]) and its lean variant ([RED_UNIT, GREEN]) remain supported for audit-log replay of pre-2026-05-07 commits. Remove omitted phases' instructions from the template.
• refactor_pass: If false, skip COMMIT phase refactoring instructions.

Dispatcher Workflow

1. Parse Parameters — Extract agent name, feature ID, and step ID from invocation. Gate: all three parameters present and non-empty.
2. Load Rigor Profile — Read .nwave/des-config.json key rigor (default: standard if absent). Gate: config loaded or default applied.
3. Validate Context Files — Confirm roadmap.json and execution-log.json exist under docs/feature/{feature-id}/deliver/. Gate: both files present; report path-not-found if missing.
4. Extract Step Context — Grep roadmap for step_id: "{step-id}" with ~50 lines context. Gate: step found; report available step IDs if missing.
5. Invoke Agent — Call Agent tool with DES template below, applying rigor model and phases from step 2. Gate: Agent tool called, not executed inline.

Agent Invocation

@{agent}

Use this DES template verbatim. Fill {placeholders} from roadmap. Without DES markers, hooks cannot validate.

<!-- DES-VALIDATION : required -->
<!-- DES-PROJECT-ID : {feature-id} -->
<!-- DES-STEP-ID : {step-id} -->

# DES_METADATA
Step: {step-id}
Feature: {feature-id}
Command: /nw-execute

# AGENT_IDENTITY
Agent: {agent-name}

# SKILL_LOADING
Before starting TDD phases, read your skill files for methodology guidance.
Skills path: ~/.claude/skills/nw-{skill-name}/SKILL.md
Always load before RED: tdd-methodology.md, quality-framework.md (3-phase canon, ADR-025) — legacy 5-phase logs reference loading at PREPARE.
Load on-demand per phase as specified in your Skill Loading Strategy table.

# TASK_CONTEXT
{step context from roadmap - name|criteria|test_file|scenario_name|implementation_notes|deps|files_to_modify (per nWave/templates/roadmap-schema.json)}

# DESIGN_CONTEXT
{Summary of architectural decisions relevant to this step, extracted by the orchestrator from docs/product/architecture/brief.md and wave-decisions.md. Include: component structure, dependency boundaries, technology choices, and any design constraints that affect implementation. If no design artifacts exist, write "No design artifacts available — use project conventions."}

# TDD_PHASES
3-phase canon (ADR-025, 2026-05-07). Execute in order:

1. RED - Activate the pre-authored acceptance test (PRIMARY TBU DEFENSE); write PBT unit tests ONLY if the AT cannot reach GREEN without them.
   AT activation: If TASK_CONTEXT includes test_file, locate it and remove the @skip/@ignore/@pending/xit/.skip/[Ignore] marker from the target scenario (the AT scaffold was authored by DISTILL — DELIVER does NOT re-author ATs). Run it — must fail for business logic reason (not import/syntax error). Fail-for-right-reason gate: collected ≥ 1, failures ≥ 1, no collection errors, semantic AssertionError / expected-exception-not-thrown.
   PORT-TO-PORT PRINCIPLE: The acceptance test exercises the scenario through
   the driving port (application service, orchestrator, CLI handler, API controller),
   not a decomposed helper or internal class. A correctly-written port-to-port test
   makes TBU structurally impossible — if a new function were missing or unwired,
   THIS test stays RED. That is the entire point: GREEN is unreachable without wiring.
   Litmus test: "If I delete the call-site that wires the new code, does this test fail?"
   If no → the test is at the wrong level. Stop and flag to orchestrator (DISTILL re-author needed).
   Conditional unit-test authoring: write PBT unit tests (or integration tests for adapter/infrastructure code — adapters use real infrastructure, never mocked unit tests) ONLY when the AT requires them to reach GREEN. If the AT can pass via direct minimal implementation, skip unit-test authoring inside RED.

2. GREEN - Minimal code to pass AT + any unit tests authored in RED.
   After GREEN: run FULL test suite. If all pass, proceed to COMMIT immediately.
   Smell test: if any new function is only called from test code, your acceptance
   test is at the wrong abstraction level — stop and flag.
   Never move to new task or stop without committing green code.

3. COMMIT - Commit this step's owned files via `des-commit` (parallel-safe).
   Use `des-commit` instead of raw `git add` / `git commit`. It holds an
   exclusive lock and commits ONLY the paths you pass, so a parallel agent's
   staged work is never swept into your commit (issue #51 / ADR-027). Pass
   EVERY file you created or modified for this step (production + tests) as
   `--owned-paths`; anything omitted is not committed.

des-commit
--owned-paths <all files this step created/modified>
--step-id {step-id}
--message "feat(feature-id): implement feature X"

The `Step-Id: {step-id}` trailer (required for DES verification) is appended
automatically. Resulting commit:

feat(feature-id): implement feature X

Step-Id: 02-01

LEGACY 5-PHASE CONTRACT (ADR-024 era, pre-2026-05-07): PREPARE → RED_ACCEPTANCE → RED_UNIT → GREEN → COMMIT. Preserved for audit-log replay only — new work uses the 3-phase canon above. Audit-log entries referencing RED_ACCEPTANCE/RED_UNIT/PREPARE represent merged sub-steps now folded into RED.

# QUALITY_GATES
- All tests pass before COMMIT
- No skipped phases without blocked_by reason
- Coverage maintained or improved

# OUTCOME_RECORDING
Immediately after ACTUALLY EXECUTING each phase — and BEFORE any
permission-gated or interruption-prone command (e.g. `nix-build`, a network
fetch, a long verification run) — record it via the DES CLI. Do NOT batch
`des-log-phase` calls to end-of-run: a permission prompt or STOP between phases
drops the un-written entries, leaving an incomplete trace (e.g. 3/5) that fails
`des-verify-integrity` at finalize and forces a resume to re-log work already
done.

 des-log-phase \
   --project-dir docs/feature/{feature-id}/deliver \
   --step-id {step-id} \
   --phase {PHASE_NAME} \
   --status EXECUTED \
   --data PASS

For `--status EXECUTED`, `--data` MUST be exactly `PASS` or `FAIL` — no prose,
no prefix. The stop-hook StepCompletionValidator compares the value against
`{PASS, FAIL}` exactly; anything else (e.g. `--data "PASS: unit layer folded
into shape suite"`) is rejected as an INCOMPLETE_PHASE and the phase must be
re-logged. Put any explanation in your report to the orchestrator, not in
`--data`. Only `--status SKIPPED` may carry text — and only as a valid prefix
(see below).

For SKIPPED phases (genuinely not applicable):

 des-log-phase \
   --project-dir docs/feature/{feature-id}/deliver \
   --step-id {step-id} \
   --phase {PHASE_NAME} \
   --status SKIPPED \
   --data "NOT_APPLICABLE: reason"

CLI enforces real UTC timestamps and validates phase names.
Do NOT manually edit execution-log.json.
Use the DES CLI to record phase outcomes and create log files.
Python resolution: `$(command -v python3 || command -v python)` — works on macOS (python3 only), Linux, and Windows.

CRITICAL: Only the executing agent calls the CLI.
Orchestrator MUST NEVER write phase entries — only the agent that performed the work. A log entry without actual execution is a **violation that DES detects and that will cause integrity verification to fail**, blocking finalize.

# RECORDING_INTEGRITY
Valid Skip Prefixes: NOT_APPLICABLE, BLOCKED_BY_DEPENDENCY, APPROVED_SKIP, CHECKPOINT_PENDING
Anti-Fraud Rules:
- NEVER write EXECUTED for phases you did not actually perform
- NEVER invent timestamps — DES CLI generates real UTC timestamps
- DES audits all entries; integrity violations block finalize

# BOUNDARY_RULES
- Only modify files listed in step's files_to_modify
- Do not load roadmap.json
- Do not modify execution-log.json structure (append only)
- NEVER write execution-log entries for phases you did not execute

# TIMEOUT_INSTRUCTION
Target: 30 turns max. If approaching limit, COMMIT current progress.
If GREEN complete (all tests pass), MUST commit before returning — even at turn limit.

Configuration:

• subagent_type: extracted agent name
• Turn limits are defined in each agent's maxTurns frontmatter field (not as a tool parameter)

Error Handling

1. Invalid Agent — Report available agents from the agent registry. Gate: error message returned, no invocation attempted.
2. Missing Context Files — Report exact path not found for roadmap or execution-log. Gate: clear path reported.
3. Step Not in Roadmap — Report available step IDs from roadmap. Gate: list of valid IDs returned.
4. Dependency Failure — Explain which blocking tasks are incomplete. Gate: blocking step IDs named explicitly.

Resume vs Restart

When subagent times out:

Last Completed Phase (3-phase canon)	Legacy phase (5-phase)	Action	Rationale
GREEN (or later)	GREEN	Resume	Only COMMIT remains (~5 turns)
RED with partial GREEN	RED_UNIT with partial GREEN	Resume	Preserves implementation progress
RED only (pre-GREEN)	PREPARE or RED_ACCEPTANCE	Restart	Little context worth replaying

Resume costs ~50% more tokens/call due to context replay (measured: 3.7K vs 2.5K tokens/call). For <5 remaining turns, resume is efficient. For 15+ turns, restart is cheaper.

Examples

/nw-execute @nw-software-crafter "des-us007-boundary-rules" "02-01"
/nw-execute @nw-researcher "auth-upgrade" "01-01"
/nw-execute @nw-software-crafter "des-us007" "03-01"  # retry after failure

TDD_PHASES

{{MANDATORY_PHASES}}

Success Criteria

• Agent invoked via Agent tool (dispatcher does not execute the work)
• Step context extracted from roadmap and passed in prompt
• Agent appended phase events to execution-log.json
• Agent did not load roadmap.json

Next Wave

Handoff To: /nw-review for post-execution review Deliverables: Updated execution-log.json, implementation artifacts, and git commits