/nw-command-design-patterns

name: nw-command-design-patterns
description: Best practices for command definition files - size targets, declarative template, anti-patterns, and canonical examples based on research evidence
user-invocable: false
disable-model-invocation: true

Command Design Patterns

The Forge Model (Gold Standard)

`forge.md` at 40 lines is the reference dispatcher. Contains: header (wave, agent, overview) | Agent invocation (name + command + config) | Success criteria (checklist) | Next wave handoff | Expected outputs. Every dispatcher should aspire to this pattern.

Command Categories

| Category | Description | Size Target | Examples | |----------|-------------|-------------|----------| | Simple | Direct action, minimal delegation | 40-80 lines | forge, start, version, git | | Dispatcher | Delegates to one agent with context | 40-150 lines | research, review, execute | | Orchestrator | Coordinates multiple agents/phases | 100-300 lines | develop, document |

Declarative Command Template

Commands declare WHAT, not HOW. The agent knows how to do its job.

# DW-{NAME}: {Title}

**Wave**: {WAVE_NAME}
**Agent**: {persona} ({agent-id})

## Overview

One paragraph: what this command does and when to use it.

## Context Files Required

- {path} - {why needed}

## Agent Invocation

@{agent-id}

Execute \*{command} for {parameters}.

**Context Files:**
- {files the orchestrator reads and passes}

**Configuration:**
- {key}: {value} # {comment}

## Success Criteria

- [ ] {measurable outcome}
- [ ] {quality gate}

## Next Wave

**Handoff To**: {next wave or workflow step}
**Deliverables**: {what this command produces}

# Expected outputs:
# - {file paths}

Size Targets and Evidence

Research (Chroma Research, Anthropic context engineering): focused prompts (~300 tokens) outperform full prompts (~113k tokens) | Claude shows most pronounced performance gap | Information buried mid-prompt gets deprioritized ("Lost in the Middle") | Opus 4.6 is proactive/self-directing; verbose instructions cause overtriggering

Targets: Dispatchers 40-150 lines | Orchestrators 100-300 lines | Current average 437 lines; target under 150

The Duplication Triangle

Commands duplicate content in three directions, all waste tokens:

1. **Command-to-Command**: Orchestrator briefings, agent registries, parameter parsing repeated in 5-12 files (~620 lines waste) 2. **Command-to-Agent**: Domain knowledge belonging in agents (~1,300 lines waste). Examples: TDD phases in execute.md, DIVIO templates in document.md, refactoring hierarchies in refactor.md 3. **Command-to-Self**: develop.md embeds other commands inline (~1,000 lines)

Fix: Extract shared content to preamble skill. Move domain knowledge to agents. Have orchestrators reference sub-commands.

Anti-Patterns

| Anti-pattern | Impact | Fix | |---|---|---| | Procedural overload | Step-by-step for capable agents wastes tokens, "lost in the middle" | Declare goal + constraints, let agent apply methodology | | Duplicated briefings | Same orchestrator constraints in every command (30-80 lines each) | Extract to shared preamble, reference once | | Embedded domain knowledge | Refactoring hierarchies, review criteria, TDD cycles in commands | Move to agent definitions or skills | | Aggressive language | "CRITICAL/MANDATORY/MUST" causes overtriggering in Opus 4.6 | Direct statements without emphasis markers | | Example overload | 50+ lines of JSON examples | 2-3 canonical examples suffice | | Inline validation logic | Prompt template validation in command text | Platform/hook responsibility | | Dead code | Deprecated formats, aspirational metrics, old signatures | Remove; version control preserves history | | Verbose JSON state examples | 200+ lines of unused JSON | Show actual format (pipe-delimited), 3 examples max |

When Commands Should Contain Logic vs Delegate

**Contain in command** (declarative):

1. Which agent to invoke 2. What context files to read/pass 3. Success criteria and quality gates 4. Next wave handoff

**Delegate to agent**:

1. Methodology (TDD phases, review criteria, refactoring levels) 2. Domain-specific templates/schemas 3. Tool-specific config (cosmic-ray, pytest) 4. Quality assessment rubrics

Rule: if content describes HOW the agent does its work, it belongs in agent definition or skill, not command.

Canonical Examples

Example 1: Minimal Dispatcher (forge.md pattern, ~40 lines)

# DW-FORGE: Create Agent (V2)

**Wave**: CROSS_WAVE
**Agent**: Zeus (nw-agent-builder)

## Overview

Create a new agent using the research-validated v2 approach.

## Agent Invocation

@nw-agent-builder

Execute \*forge to create {agent-name} agent.

**Configuration:**
- agent_type: specialist | reviewer | orchestrator

## Success Criteria

- [ ] Agent definition under 400 lines
- [ ] 11-point validation checklist passes
- [ ] 3-5 canonical examples included

## Next Wave

**Handoff To**: Agent installation and deployment
**Deliverables**: Agent specification file + Skill files

Example 2: Medium Dispatcher with Context (~80 lines)

# DW-RESEARCH: Evidence-Driven Research

**Wave**: CROSS_WAVE
**Agent**: Nova (nw-researcher)

## Overview

Execute systematic evidence-based research with source verification.

## Orchestration: Trusted Source Config

Read .nwave/trusted-source-domains.yaml at orchestration time, embed inline in prompt.

## Agent Invocation

@nw-researcher

Execute \*research on {topic} [--embed-for={agent-name}].

**Configuration:**
- research_depth: detailed
- output_directory: docs/research/

## Success Criteria

- [ ] All sources from trusted domains
- [ ] Cross-reference performed (3+ sources per major claim)
- [ ] Research file created in docs/research/

## Next Wave

**Handoff To**: Invoking workflow
**Deliverables**: Research document + optional embed file

Example 3: Orchestrator (~200 lines)

Coordinates multiple phases without embedding agent knowledge:

#