| name | orchestration |
| description | Decompose work and delegate to subagents, bridge workers, and fleets effectively. Use for large multi-part tasks, parallel research, codebase-wide analysis, swarm audits, independent workstreams, or when the user mentions agents, subagents, parallelization, workflows, swarms, or in-parallel execution. |
Orchestration & Subagents
Subagents and bridge workers have their own context. The point is to protect the
main context, parallelize independent work, and get back compact reports instead
of raw exploration.
When to delegate
Delegate when:
- Search or analysis would burn the main context.
- Workstreams are independent and can run in parallel.
- Isolation is useful: experiments, second reviews, or blind review passes.
- A bundled prompt asset already matches the role better than an ad hoc prompt.
Do it yourself when:
- The task depends heavily on conversation context.
- Steps are sequential and depend on the previous edit.
- The task is small enough that briefing would cost more than doing.
Writing worker prompts
Every delegated prompt must be self-contained:
- Context: repo path, project shape, constraints.
- Task: precise scope and explicit non-goals.
- Verification: command or evidence proving success.
- Report format: exact shape and maximum length.
If the prompt is under five lines, it is probably under-specified.
Prompt asset routing
Prompt assets are interchangeable role/workflow/reference contracts. Use them
instead of rewriting specialist prompts from memory.
- Discover assets with
prompt_catalog or maaaw://prompts/catalog.
- Read exact text with
prompt_read <id> when the contract matters.
- For bridge jobs, pass
--prompt-asset <id> or MCP promptAssetId.
- For handoffs, record
promptAssetId so the receiving model knows the active
contract.
- Switch assets deliberately between waves. Example:
repo-scout for recon,
architecture-auditor for structure, then test-writer for regression tests.
If a selected asset conflicts with the explicit task, the explicit task wins and
the conflict must be reported under Assumptions.
Parallelization rules
- Independent tasks: launch in one message so they run concurrently.
- Never let two writers own the same files. Partition by module/path.
- Read-only agents may overlap.
- Fan out breadth-first: recon → synthesize → implementation → verification by
the orchestrator.
- Cap implementation concurrency around 4-5. Research fan-out can go wider.
Orchestrator discipline
- You own final state. Delegates own subtasks.
- Track dispatched / returned / verified / integrated.
- After each wave, verify, integrate, then dispatch the next wave.
- A failed delegate gets one retry with a sharper prompt. A second failure means
re-plan or do it yourself.
- Persist state for multi-session work in
PLAN.md or .agent/handoff/.
Model tiering
The orchestrator should use the strongest available model: it owns partitioning,
synthesis, severity judgment, and final integration. Breadth workers can use
cheaper/faster models when the task is search, mapping, or lane auditing.
Fleets
For more than about five agents, run phases instead of a soup of workers:
- Recon.
- Parallel specialists.
- Synthesis.
- Optional parallel fixes.
- Verification.
Schema every agent report. Free-text reports from many agents do not compose.
For audit swarms, read references/audit-swarm-spec.md.
Bundled agents
This kit ships eight agents:
repo-scoutcode-reviewerbug-huntertest-writersecurity-auditorarchitecture-auditorscalability-auditorquality-auditor
Prefer these assets over generic delegation when their specialty matches the
task. Their prompts encode discipline and tool restrictions.
