Dispatch

Purpose

Every sub-agent starts cold. It has no rules, no memory, and no awareness of the project it is about to work on. This skill defines how the Maestro assembles the initial prompt that boots a sub-agent into a ready state, and routes it to the correct provider based on the persona's preferred model.

Terminology

A sub-agent is a persona defined in this framework — nothing else. The terms "sub-agent" and "persona" are interchangeable throughout this skill. Sub-agents are not host-runtime features (IDE subprocesses, tool-provided agents, or built-in workers). The Maestro must never route work to a host-runtime agent when a framework persona exists for the job.

To discover available sub-agents, read:

• personas/README.md — lists every persona and its purpose.

This is the only registry. If a persona is not listed there, it does not exist. The Maestro must consult this registry during the Route step before dispatching.

Procedure

1. Identify the host runtime. Run ps -p $PPID -o comm= and match the process name against the CLI column of the Providers list to identify the host runtime's provider (e.g., opencode → opencode host, claude → claude provider, codex → codex provider, cursor-agent → cursor provider). Store the result in session state — the host runtime does not change mid-conversation.

2. Extract routing fields.

   sed -n '/^---$/,/^---$/{ /^\(preferredModel\|modelTier\):/p }' personas/<name>.md

3. Select the provider and model. Resolve preferredModel and modelTier against the Providers list. If preferredModel is host, always use native dispatch — the persona runs on whatever model the host runtime provides, ignoring tier upgrades. If preferredModel is omitted, use the host runtime's provider. The persona's modelTier is a floor — upgrade one tier when the task demands multi-step reasoning across system boundaries (e.g., cross-layer architectural changes, security/auth logic, or production deployment pipelines). If already at tier-3, remain at tier-3.

4. Decide how to dispatch. If preferredModel is host, use native dispatch and skip the provider lookup. Otherwise, look up the persona's preferredModel in the Providers list to find its CLI column. Then:

   • Native dispatch — the provider's CLI matches the host runtime. Use the host's built-in subagent mechanism (e.g., OpenCode's task tool, Claude Code's Task tool, Codex subagent environment, Cursor's native agent/subagent flow). Do not shell out to the same tool's CLI.
   • CLI dispatch — the provider's CLI does not match the host runtime. Shell out to the provider's CLI tool (see CLI Dispatch section).
   • If the preferred provider's CLI is not installed or unreachable, fall back to native dispatch and record the deviation in session memory.

5. Build task context. Extract relevant context from two sources:

   • Long-term memory — read .memory/long-term.md (uses: skills/agent-memory/SKILL.md), select entries relevant to the task.
   • Conversation — scan recent turns for corrections, explicit user decisions, and stated constraints.

   Combine into a single block. Cap at 30 lines. Wrap in <additional-context> tags. Omit if nothing qualifies.

6. Strip the frontmatter. Run the sed command below to remove YAML frontmatter from the persona file. Take the complete, unmodified sed output and wrap it in <identity> tags — do not summarize, paraphrase, or shorten the persona file. The full text must arrive exactly as written. Each dispatch targets exactly one persona — never multiple in a single prompt.

   sed '/^---$/,/^---$/d' personas/<name>.md

7. List the rules (scoped). Consult rules/README.md and select rules whose scope matches the task category. List their file paths in <rules> tags — do not inline the file contents. The persona has file access and will read them directly. If no rules match, omit the block entirely. When the task involves code changes — even if the persona does not write code (e.g. architect planning implementations) — include coding-scoped rules so the persona's output aligns with the conventions the coder will follow.

8. List relevant skills. Consult skills/README.md and identify skills that would help the persona complete the task. List their file paths in <skills> tags. If no extra skills are relevant, omit the block entirely. When the task brief contains ambiguity (missing info, conflicting requirements, multiple valid paths), include skills/agent-decision/SKILL.md so the sub-agent can structure its escalation.

9. Write the task brief. Translate the user's intent into actionable instructions, wrapped in <task> tags. The brief must contain:

   • Intent — what the user wants accomplished, in the Maestro's words.
   • Entities — key nouns: files, modules, endpoints, services.
   • Constraints — deadlines, tech stack limits, scope boundaries. Omit if none.
   • Acceptance criteria — what "done" looks like. If the user did not provide criteria, the Maestro defines them.

10. Compose and dispatch. Assemble the final prompt:

<identity>
  [PASTE STRIPPED PERSONA CONTENT HERE — DO NOT LITERALLY OUTPUT THIS BRACKETED TEXT]
</identity>

<preload>
  Before reading `<task>` or `<additional-context>`, read every file listed in `<skills>` and `<rules>` above. Framework files (personas, skills, rules) live under `.agents/` — prepend `.agents/` to each path when reading. After reading all files, list every path you read (one per line, no abbreviations). Only then may you proceed to `<additional-context>` and `<task>`.
</preload>

<rules>
  [file paths to scoped rules — omit block if no scope matches]
</rules>

<skills>
  [file paths to relevant skills — omit block if none apply]
</skills>

<additional-context>
  [combined long-term memory and conversation context — omit block if empty]
</additional-context>

<notes>
  - You are running non-interactively. Never pause for input. If critical information is missing, stop and return a handoff explaining the gap.
  - If you encounter pre-existing issues outside the current task's scope, list them in `## Discovered Issues` at the end of your handoff. Do not fix them.
  - If you notice patterns, risks, or suggestions outside your deliverable, list them in `## Observations` at the end of your handoff. Be honest — no glamour, no filler.
  - If you repeat the same failing action three times, stop and read `.agents/skills/loop-recovery/SKILL.md`.
  - For any task that is not a simple edit, create and maintain a todo list following `.agents/skills/task-tracking/SKILL.md`.
  - Read every file referenced in the task brief in full BEFORE acting. Then make changes, then verify once. Do not run exploratory shell commands to "understand" the code.
</notes>

<task>
  [task brief]
</task>