The role taxonomy expansion in #404 added Implementer + Verifier as
distinct postures alongside General / Explore / Plan / Review /
Custom. The issue body explicitly lists \`docs/AGENTS.md or
docs/SUBAGENTS.md\` as a target file; this commit creates that file.
Coverage:
- Role taxonomy table — stance, write/shell access, typical use per
role.
- "When to pick which role" — narrative guidance the model can read
if the role choice isn't obvious.
- Alias map — every accepted spelling routed to a canonical role,
matching what \`SubAgentType::from_str\` accepts.
- Concurrency cap — the 10-by-default value, the
\`[subagents].max_concurrent\` knob, and the running-only
semantics (#509).
- Lifecycle — Pending → Running → terminal states, plus
\`Interrupted\` after a process restart.
- Session boundaries (#405) — \`session_boot_id\` mechanics,
default current-session filter, \`include_archived=true\` escape
hatch, pre-#405 record handling.
- Output contract — the SUMMARY/CHANGES/EVIDENCE/RISKS/BLOCKERS
format every sub-agent must produce.
- Memory + \`remember\` integration (#489) — sub-agents inherit the
parent's memory file when memory is enabled and can append durable
notes.
- Implementation notes — source path, persisted state file,
is_running semantics, RwLock pattern.
Cross-link added in \`docs/TOOL_SURFACE.md\` so the sub-agent section
points to this doc.
No Rust code changed.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Hunter Bown