Atlas
kb://infrastructure/sub-agent-dispatch-conventionsstable2026-05-24

Sub-agent dispatch conventions — token economy + cohesion

sub-agentdispatchconventionstokensclaude-code

Sub-agent dispatch conventions

Wave 19-E. Sub-agents spawned via Claude Code's Agent tool re-explore the repo from scratch each time. When 3+ sub-agents run in parallel against the same surface (waves 13/16 dispatched 4-5 each), this creates redundant token spend + cohesion gaps where each agent doesn't know what its siblings are touching.

Conventions

1. Pass model: "sonnet" for investigative reads

NAO 2026-05-23 directive: «Всегда используй соннет саб агентов для глубоких чтений дабы экономить токены». Default Opus for the main session; Sonnet for the agents that survey repos, audit code, or build executive summaries. Sonnet 4.6 ~5x cheaper per token than Opus 4.7.

Sonnet for: audits, surveys, file inventories, large-file walks, multi-repo greps, doc syntheses. Opus for: synthesis, refactor execution with behavioral preservation, anything requiring careful reasoning about subtle invariants.

2. Pre-write a session-context file when dispatching ≥3 agents

When the parent session dispatches 3+ sub-agents that all touch the same surface area, write a short session-context.md at a known path FIRST. Each agent's prompt references it. Reduces "agent re-explores the same files" overhead.

Template:

# Session context — <date>

## What just landed
- Wave X: <commit sha> — <summary>
- Wave Y: <commit sha> — <summary>

## Active sub-agents
- Wave Z-A: <task> (touching <files>)
- Wave Z-B: <task> (touching <files>)

## Hard rules in force
- -j 4 cap (always)
- soul-block check (when touching persona)
- match clippy baseline N

## Reference templates
- learnings/<recent-wave> for proven pattern

Save at openalice-atlas/knowledge/_ephemeral/session-context-<date>.md (gitignore the _ephemeral/ dir for short-lived context) OR pin in the prompt itself.

3. Avoid duplicate cargo agents on same crate

Per feedback-cargo-j4-server-safety-2026-05-16: max 3 cargo-heavy agents concurrent on blal.de. Same crate at the same time = git tree conflicts. Different crates is fine.

When you dispatch 2 agents touching the same crate sequentially (not in parallel), tell agent #2 about agent #1's most-recent commit so it doesn't replay work.

4. Hard rules section is mandatory per agent

Every Agent dispatch prompt MUST include:

  • -j 4 cap for cargo work
  • Tests-green-at-every-commit (not just at end)
  • @feature annotations preserved
  • Conventional commits
  • Push to mvp
  • Match baseline clippy

These are the «state of the art axioms» (see kb://infrastructure/rust-build-toolchain + memory feedback-state-of-the-art-axioms-2026-05-23). Don't omit.

5. Report-back ceiling

Cap sub-agent report-back length at 250-400 words. Beyond that the token spend on the report exceeds the savings of using Sonnet.

6. Bug-spotted-but-not-touched flag

Each sub-agent should report any bugs it noticed but didn't fix (out-of-scope). Parent session aggregates these for next-wave queuing.

When NOT to dispatch a sub-agent

  • Small inline edits (<200 LOC, single file) — parent session handles directly
  • Read-only queries answerable from atlas MCP — query directly
  • Refactors that demand careful behavior preservation across files the parent session has already read — keep in-context

Anti-pattern: «delegate understanding»

Don't write «based on your findings, fix the bug» or «implement what you find». Push synthesis onto the agent and the parent loses ground. Specify file paths, line numbers, what to change. Verify the agent's report before reporting up to NAO.