Aim Agent Dispatch

Agent Dispatch -- Generic and BMAD Agent Activation

Purpose: Prepare instructions for all agents (generic and BMAD). Determines if BMAD persona is needed and routes accordingly. BMAD routing is handled within this skill.

Embedded Constraints (Layer 3)

• EC-02: MUST use the instruction template for every agent dispatch. Story files are planning artifacts -- implementation instructions translate requirements into precise, actionable specifications.
• GC-11 L3: ALWAYS use the instruction template for every agent dispatch. Every requirement must cite a project file. Every DONE WHEN criterion must be objectively measurable.
• DC-08: Analyst research MUST precede PM when input is thin. When goals.md is the only input, Analyst must run before PM begins. PM does NOT begin from goals.md alone when input is thin.
• Agent activation verification: Never send an instruction to an unverified agent. Verify activation before proceeding.
• One task per instruction: Never combine multiple tasks in a single dispatch.

Step 0: Pre-Spawn Sentinel Gate (MANDATORY -- re-run before EVERY spawn)

Before routing any dispatch, assert the current directory is the workspace root by confirming co-presence of _ai-memory/, _bmad/, and oversight/ (CLAUDE.md workspace-root sentinel). Concretely: test -d _ai-memory && test -d _bmad && test -d oversight.

• PASS -> proceed to Step 1.
• FAIL -> ABORT the spawn. Report: "CWD drift -- not at workspace root; return to root before spawning." Do NOT route to /aim-model-dispatch or /aim-agent-lifecycle.

CWD drifts across Bash calls, so re-run this gate immediately before EACH spawn -- not once per session.

Step 1: Determine Dispatch Type

BMAD dispatch (use the BMAD Agent Dispatch section below) when:

• The task requires ANY BMAD agent role (Analyst, PM, Architect, DEV, UX Designer, Tech Writer)
• The agent requires persona activation via /bmad-agent-<name> commands

Generic dispatch (use the Generic Agent Dispatch section below) when:

• The agent does NOT need a BMAD persona
• The agent is a generic worker spawned for a specific task
• Examples: code-reviewer agent, verify-implementation agent, skill-creator agent

Mandatory (BMAD-or-fail): if the task maps to any BMAD role/skill above, you MUST dispatch that BMAD persona. A generic/no-persona agent on BMAD-shaped work is a FAILED dispatch — shut it down and respawn via the correct /bmad-*. Generic dispatch is only for work with no BMAD role.

Generic Agent Dispatch

2. Prepare Instruction Using Template

Build the instruction using the instruction template (templates/agent-instruction.template.md):

• TASK: Single, specific, unambiguous description. One task per instruction.
• CONTEXT: Relevant background -- only what is necessary.
• REQUIREMENTS: Cited project files and sections (PRD, architecture, standards, story criteria)
• SCOPE: Explicit IN SCOPE and OUT OF SCOPE lists
• OUTPUT EXPECTED: Exactly what the agent should produce (file names, formats, contents)
• DONE WHEN: Measurable, specific criteria the agent can self-assess
• STANDARDS TO FOLLOW: Specific coding standards, patterns, naming conventions
• IF YOU ENCOUNTER A BLOCKER: Stop and report immediately. Do not guess.

3. Verify Instruction Quality

Before dispatching, verify the instruction is:

• Complete (all template sections filled)
• Unambiguous (could not be interpreted multiple ways)
• Scoped (clear IN and OUT boundaries)
• Cited (every requirement references a project file)
• Measurable (DONE WHEN criteria are objectively verifiable)

IF ANY CHECK FAILS: fix the instruction before proceeding.

4. Route Based on Provider

Check provider from the dispatch plan:

Claude provider: → /aim-model-dispatch (MANDATORY next step) Pass: instruction, AI_MEMORY_AGENT_ID, model from dispatch plan.

Non-Claude provider: → /aim-agent-lifecycle (MANDATORY next step) Pass: instruction, AI_MEMORY_AGENT_ID, provider, model from dispatch plan.

MUST spawn fresh agent for every task -- never reuse across roles or stories.

5. Dispatch Complete

Agent instruction prepared and routed. Downstream skill handles spawn and activation.

BMAD Agent Dispatch

Agent Selection Guide

See agent-selection-guide.md for detailed role descriptions, selection criteria, and dispatch decision tree.

Quick Selection Matrix

Agent Combination Sequences

Some phases require agents in sequence:

• Discovery phase: Analyst (research) -> PM (PRD creation)
• Architecture phase: Architect (design) -> PM (epics/stories) -> Architect (readiness check)
• Execution cycle: DEV (implement) -> DEV (code review) -> [loop if issues] -> DEV (re-review)
• Integration phase: DEV (full review) -> Architect (cohesion check)
• Release phase: /bmad-retrospective (direct skill) -> PM or Analyst (documentation update)

Steps

B1. Select the Correct Agent

Use the selection guide and matrix above. When uncertain, assess the primary skill required by the task, not the phase you are in.

If still uncertain, use /bmad-help -- it can answer questions about which agent and workflow to use for a given task.

B2. Prepare BMAD-Specific Instruction

Extends the generic instruction template (from the Generic Agent Dispatch section above) with:

• Persona confirmation requirement
• BMAD activation command reference

B3. Route Based on Provider

Check provider from the dispatch plan:

Claude provider: → /aim-model-dispatch (MANDATORY next step) Pass: BMAD activation command, instruction, AI_MEMORY_AGENT_ID, model from dispatch plan.

Non-Claude provider: → /aim-agent-lifecycle (MANDATORY next step) Pass: BMAD activation command, instruction, AI_MEMORY_AGENT_ID, provider, model from dispatch plan.

MUST spawn fresh agent for every task -- never reuse across roles or stories.

Core Project Agents

MUST use /bmad-agent-tech-writer for ALL documentation tasks (writing, updating, reviewing docs). MUST use /bmad-code-review for ALL review agents (never /bmad-agent-dev). MUST use /bmad-help whenever unsure which agent or workflow to use -- the tables above are NOT exhaustive.

MUST route ALL best-practice / conventions / coding-standard research through /aim-best-practices-researcher -- never hand-run web searches for this. The skill saves the finding to a BP file and stores it to the project-scoped conventions collection, so hand-rolling the research loses it to future sessions.

Workflow commands by phase (sent AFTER activation, when in planning mode):

Set AI_MEMORY_AGENT_ID environment variable when spawning.

Maintenance check: scripts/check_bmad_commands.sh verifies every /bmad-* command in the tables above resolves to an installed skill under .claude/skills/ (fire-only-if-missing: silent when all resolve, non-zero listing any that don't; degrades gracefully when BMAD is not installed). Run it after editing these tables or updating the BMAD module.

B4. Verify Activation (MANDATORY — two-phase)

Sentinel (CLAUDE.md workspace-root): before every spawn, as its own Bash step, assert workspace root: test -d _ai-memory && test -d _bmad && test -d oversight. FAIL → ABORT.

Spawn (two-phase, GC-20): the spawn prompt loads the BMAD persona via the Skill tool (e.g. Use the Skill tool to load bmad-agent-dev — likewise bmad-create-story, bmad-code-review; a bare /bmad-* at spawn activates the lead, not the persona) + one line — "You're activated as a teammate under Parzival (team-lead). Once activated, SendMessage your activation reply (greeting + menu, and anything the agent asks) to team-lead, then wait for my instructions before doing any work." Never the task. mode: auto.

Wait: idle pings (idle_notification "available") are NOISE — no reaction, no on-disk checks, no nudges; the teammate sends a real message when it has one.

Instruct: read the menu, then SendMessage the task — one task per message, never bundled (GC-20).

B5. Dispatch Complete

Agent selection and instruction complete. Downstream skill handles spawn and activation.

Dispatch & Coordination Playbook (life of the teammate)

• Reporting address (mandatory-for-function): a teammate reaches the lead only by name — team-lead. to:"main" is background-subagents-only; a teammate using it is rejected and the lead receives nothing (plain text is invisible between agents). Every report/answer → team-lead.
• One message, then wait: send ONE message, then wait for the reply. A teammate gets a new message only after it stops and replies; another before then just re-triggers its work. Never multiple in a row.
• Task-auto-replay: the harness sometimes re-delivers a prior message; distinguish a re-delivered prior message from genuine new direction before re-acting.
• Acceptance: accept ONLY against Parzival's own cold on-disk verification (re-read the files) — never a "done"/idle signal.
• Reviewer disagreement: adjudicate via review-cycle/workflow.md (## Reviewer Disagreement).
• Stall (state-based, not time-based): respawn FRESH only on a genuine stall — no activation output and no loading/work, or output stopped at a crash/error signature with no menu. A slow load ≠ stall. (Inspect: Claude-native = the spawn's first response / SendMessage reply; tmux = tmux capture-pane.)

Common Dispatch Errors

Instruction Template Reference

Convention: All POV skill templates use the .template.md extension to distinguish them from step files and other markdown documents.

The full instruction template is at: templates/agent-instruction.template.md