Nw Agent Creation Workflow

Agent Creation Workflow

Overview

Create agents through 5 phases: ANALYZE -> DESIGN -> CREATE -> VALIDATE -> REFINE. Each phase has clear inputs, outputs, and quality gates. Follow "start minimal, add based on failure."

Skill-addressing tables (the load-by-trigger convention)

Every agent that carries skills: in frontmatter needs two things, kept aligned (DESIGN step 6, CREATE steps 4-6 below):

1. A ## Skill Loading section with a MANDATORY-first-action instruction — the agent's FIRST action is reading the table and loading, via Read tool at the exact path, ONLY the skill(s) whose Trigger matches its CURRENT phase/task. Every other skill loads on-demand the moment its trigger fires; never preload the whole set. Then a | Phase | Load | Trigger | table, one row per skill, where Trigger is a precise load-when condition, not a vague "when needed".

   Well-formed row (from nw-product-owner): | Expectation Charter Authoring | nw-expectation-charter | when examine=true and total charter discovery returns Missing or Empty |

2. Frontmatter <-> table coherence (avoids the D1 packaging-bug) — every skill in frontmatter skills: MUST have a row in the table, and every row's skill MUST be in frontmatter. Declaring in only one is D1 (checklist items #12/#13 exist to catch it). Direction to converge on: GENERATE the frontmatter list FROM the table (one SSOT) instead of hand-keeping two lists in sync — not built yet; prescribe double-declaration-with-coherence-check until it is.

3. Self-description in the skill itself — the skill's own description frontmatter field states its when-to-use (no separate field); this is what a buddy-recommender or another agent uses to discover it. KNOWLEDGE skills (reference, no forced sequence) carry user-invocable: false + disable-model-invocation: true — they load ONLY via Read-on-trigger, never model-invoked directly.

4. GOOD vs BAD:

Phase 1: ANALYZE

Goal: Understand requirements and determine agent architecture.

Inputs: User requirements, use case description, existing codebase context.

Steps:

1. Identify single clear responsibility
2. Determine new agent or modification of existing
3. Check overlap with existing agents (avoid duplication)
4. Classify agent type:
   • Specialist: Single-domain expert (most common)
   • Reviewer: Validates outputs from another agent (Reflection pattern)
   • Orchestrator: Coordinates multiple agents
5. Identify required tools (start with Read, Glob, Grep -- add only what's needed)
6. Determine if Skills needed (domain knowledge > 50 lines)

Gate: Single responsibility identified. Agent type classified. No overlap.

Output: Requirements summary with agent type, tools list, skill needs.

Phase 2: DESIGN

Goal: Design agent architecture and structure.

Inputs: Requirements summary from Phase 1.

Steps:

1. Select design pattern (load design-patterns skill)
2. Define role and goal (1-2 sentences each)
3. Identify core principles that DIVERGE from Claude defaults:
   • What must this agent do differently than Claude naturally would?
   • Domain-specific methodology steps
   • Non-obvious constraints | Project-specific conventions
4. Design workflow (3-7 phases)
5. Plan Skills extraction: domain knowledge -> separate Skill | Testing/validation -> separate Skill | Keep workflow and principles in core agent
6. Design Skill Loading Strategy (required for 3+ skills):
   • Map each skill to the workflow phase where it's needed
   • Create a loading table: Phase → Skill → Trigger condition
   • Add explicit Load: skill-name directives in each workflow phase
   • Document path: ~/.claude/skills/nw-{skill-name}/SKILL.md (installed) or nWave/skills/nw-{skill-name}/SKILL.md (repo)
   • Note: skills: in frontmatter eagerly preloads full skill content into context — reserve it for always-needed skills; skills meant for on-demand loading stay out of frontmatter and load via Load: directives (Read tool or Skill invocation) triggered by workflow text instead.
7. Draft frontmatter:

   ---
   name: {kebab-case-id}
   description: Use for {domain}. {When to delegate.}
   model: inherit
   tools: [{minimum tools needed}]
   maxTurns: 40
   skills:
     - nw-{skill-name}
   ---
   

Gate: Design fits ~200-300 lines (core) + Skills. Pattern selected. Frontmatter drafted.

Output: Agent architecture document (working notes, not deliverable).

Phase 3: CREATE

Goal: Write agent definition file and Skills.

Inputs: Design from Phase 2.

Steps:

1. Create agent .md file:

   • YAML frontmatter (name, description, tools, model, maxTurns, skills)
   • Role + Goal paragraph
   • Core Principles (divergences only, 3-8 items)
   • Workflow phases
   • Critical Rules (3-5, where violation causes real harm)
   • Examples (3-5 canonical cases)
   • Subagent mode instructions
   • Constraints (what agent does NOT do)

2. Create Skill files if needed: each in nWave/skills/{agent-name}/ | YAML frontmatter with name and description | Focused content, 100-250 lines each

3. Measure: wc -l. Target: under 300 lines.

4. Add Skill Loading Strategy section (required for agents with 3+ skills):

   ## Skill Loading Strategy
   
   Load on-demand by phase, not all at once:
   
   | Phase | Load | Trigger |
   |-------|------|---------|
   | 1 Phase Name | `skill-name` | Always — core methodology |
   | 2 Phase Name | `other-skill` | When condition is met |
   
   Skills path: `~/.claude/skills/nw-{skill-name}/SKILL.md` (installed) or `nWave/skills/nw-{skill-name}/SKILL.md` (repo)
   

5. Add Load: directives at the start of each workflow phase referencing the applicable skills

6. Verify: every skill in frontmatter skills: has at least one Load: directive in the workflow text. Orphan skills (declared but never loaded) are a bug.

Gate: Agent file created. Under 300 lines. Skills created if needed. Skill Loading Strategy present for 3+ skills.

Output: Agent .md file + Skill files.

Phase 4: VALIDATE

Goal: Verify agent meets quality standards.

Steps:

1. Run 14-point validation checklist:
   • Uses official YAML frontmatter format
   • Total definition under 400 lines (domain knowledge in Skills)
   • Only specifies behaviors diverging from Claude defaults
   • No aggressive signaling language
   • 3-5 canonical examples for critical behaviors
   • Tools restricted to minimum needed
   • maxTurns set in frontmatter
   • Safety via platform features, not prose
   • Instructions phrased affirmatively
   • Consistent terminology throughout
   • Description clearly states delegation criteria
2. Check anti-patterns: no monolithic sections (>50 lines without structure) | No duplicated Claude defaults | No embedded safety frameworks | No aggressive language
3. Test with representative inputs (Layer 1 testing)

Gate: All 14 items pass. No anti-patterns.

Output: Validation report (pass/fail per item).

Phase 5: REFINE

Goal: Iteratively improve based on testing feedback.

Steps:

1. Address validation failures
2. Test with edge cases
3. Add instructions ONLY for observed failure modes: wrong decision -> add rule/example | Missed step -> clarify workflow | Over-generated -> add constraint
4. Re-measure: wc -l. If approaching 400 lines, extract to Skills.
5. Re-validate with 14-point checklist.

Gate: All validation passes. Line count within target. Edge cases handled.

Output: Final agent definition, ready for installation.

Quality Gates Summary

Naming Conventions

• Agent files: nw-{name}.md in nWave/agents/
• Skill files: {skill-name}.md in nWave/skills/{agent-name}/
• Reviewer agents: nw-{name}-reviewer.md
• Agent names in frontmatter: nw-{name} (kebab-case with nw- prefix)

Reviewer Agent Creation (Special Case)

Reviewer agents pair with a primary agent and use the Reflection pattern:

1. Set model: haiku in frontmatter (cost-efficient review)
2. Use same tools as primary agent (no Write/Edit -- reviewers don't modify)
3. Define structured critique output format (YAML)
4. Include max 2 review iterations
5. Define clear approval/rejection criteria