| name | aim-agent-dispatch |
| description | Generic and BMAD agent selection, instruction preparation, and activation routing |
| allowed-tools | Read |
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
| Task Type | Correct Agent | Wrong Agent | Mode |
|---|
| Research current codebase state | Analyst | Architect | Planning |
| Create, validate, or update PRD | PM | Analyst | Planning |
| Break down features into stories | PM | Analyst | Planning |
| Design system architecture | Architect | PM | Planning |
| Check if implementation is ready | Architect | DEV | Planning |
| Plan and initialize a sprint | /bmad-sprint-planning (direct skill) | PM | Planning |
| Create individual story files | /bmad-create-story (direct skill) | PM | Execution |
| Write code / implement a story | DEV | Any other | Execution |
| Review implemented code | DEV | Architect | Execution |
| Design user flows and screens | UX Designer | PM | Planning |
| Write or review documentation | Tech Writer | PM | Execution |
| Write and run tests | /bmad-qa-generate-e2e-tests (direct skill) | DEV | Execution |
| Design test architecture/strategy | /bmad-tea (direct skill) | DEV | Planning |
| Small feature, solo workflow | /bmad-quick-dev (direct skill) | DEV | Execution |
| Research best practices / conventions / coding standards | /aim-best-practices-researcher (direct skill) | hand-rolled web search | Research |
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
| Agent | Activation Command | Description |
|---|
| Analyst | /bmad-agent-analyst | Research, codebase analysis, domain investigation |
| PM (Product Manager) | /bmad-agent-pm | PRD creation/validation, epics and stories |
| Architect | /bmad-agent-architect | System architecture design, readiness checks |
| Developer (DEV) | /bmad-agent-dev | Code implementation ONLY |
| Developer (review) | /bmad-code-review | Code review ONLY -- MUST use this for ALL review agents, never /bmad-agent-dev |
| UX Designer | /bmad-agent-ux-designer | User flows, screen design, UX research |
| Tech Writer | /bmad-agent-tech-writer | Documentation writing and validation |
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):
| Phase | Agent | Workflow Command |
|---|
| Research | Analyst | /bmad-market-research, /bmad-domain-research, /bmad-technical-research |
| Discovery | Analyst | /bmad-product-brief |
| Discovery (or any phase) | PM | /bmad-create-prd, /bmad-validate-prd, /bmad-edit-prd |
| Architecture | Architect | /bmad-create-architecture |
| Architecture | PM | /bmad-create-epics-and-stories |
| Architecture | Architect | /bmad-check-implementation-readiness |
| Architecture | UX Designer | /bmad-ux |
| Planning | (direct skill) | /bmad-sprint-planning, /bmad-create-story |
| Execution | DEV | /bmad-dev-story |
| Execution | DEV | /bmad-code-review |
| Research | (direct skill) | /aim-best-practices-researcher |
| Release | (direct skill) | /bmad-retrospective |
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
| Error | Prevention |
|---|
| Sending vague instruction | Always complete the full instruction template |
| Combining multiple tasks | One task per instruction -- always |
| Activating wrong agent | Use the BMAD selection matrix above |
| Accepting partial output | Review all DONE WHEN criteria |
| Passing raw agent output to user | Always prepare summary |
| Running agents without verification | Complete instruction checklist first |
| Starting new task before prior accepted | One active task per agent at a time |
| PM activated with thin input | Run Analyst first (DC-08) |
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
