Knowledge Wiki Orchestrata Ultimate

Orchestrata Ultimate › Plans › agent-roster

Specialized Subagent Roster — evidence-based

Source: plans/agent-roster.md at 8a2cb42ad · last changed 2026-07-27 · first committed 2026-07-05 · 69 lines.

Prose pending.

Plan text

Specialized Subagent Roster — evidence-based

Source: agent-roster-proposal swarm (wfxzhziah / wf_c669ec71-82a, 2026-07-05, 10 agents, 236K tokens). Deterministic mining (scratchpad/mine_subagent_tasks.py) of 131 unique subagent tasks across 294 sessions, then 9 Haiku categorizers (narrow 15-task batches — the A/B-safe scope) + 1 Sonnet synthesizer.

Why this exists

98 of 131 historical delegations ran on general-purpose — not because the work was generic, but because no specialized agent's remit matched. The categories are highly repeatable, so specialization + baked-in discipline (per-agent DoD, "fix code don't fake test", "stop on pre-existing debt", verify backstops) beats re-pasting the rulebook into a generic agent every time.

Task distribution (131)

exploration-mapping 38 (29%) · audit-analysis 33 (25%) · debugging-fixing 16 (12%) · refactoring 13 (10%) · testing-coverage 11 (8%) · wiring 7 (5%) · review 4 (3%) · coding-feature 4 (3%) · docs 2 · extraction-mining 2 · other 1.

The roster (.claude/agents/*.md — activate on session reload)

Agent Model Mode Evidence Remit
builder sonnet writes ~17 net-new feature code + fixes to a settled brief
wirer sonnet writes 7 surgical integration/config wiring; STOPs on pre-existing debt
auditor sonnet¹ read-only 38 spec-vs-code / completeness / false-confidence audits
refactorer sonnet writes 13 behavior-preserving decomposition; tests green before+after
test-writer sonnet writes 11 close coverage gaps to ≥90%; fix code, never fake the test
reviewer opus read-only 4 adversarial pre-merge bug-hunting (vs auditor's spec framing)
lint-fixer haiku writes 2 mechanical bounded lint/type cleanup; re-run linter as backstop

¹ auditor escalates to opus for the ~9 hardest clusters (free-threaded races, async/event-loop sharing, gateway/UI, standards).

Explore (read-only mapping, ~36 tasks) and Plan (1) are the built-ins that already cover exploration/planning — the 5 new agents + builder/wirer absorb the ~70 tasks that were falling to general-purpose.

Model rationale (ties to the Haiku A/B, wme0wptms)

Loading (IMPORTANT — discovery is launch-dir–sensitive)

Claude Code discovers subagents from <launch-cwd>/.claude/agents/ and ~/.claude/agents/ — at session start only. This session runs with cwd /home/mohamed (not the project dir), so the repo's orchestrata-ultimate-architecture/.claude/agents/ is a subdirectory that is NEVER scanned. Symptom: agentType: 'test-writer' → "agent type not found; available: claude, Explore, general-purpose, Plan…" (built-ins only), in both the Agent tool and Workflow agent().

Fix applied: each repo agent file is symlinked into ~/.claude/agents/ (ln -sfn <repo>/.claude/agents/*.md ~/.claude/agents/) — the repo stays the single source of truth (edit there; symlinks reflect it), and ~/.claude/agents/ is on the scanned path for a home-launched session. Takes effect on the NEXT reload (the registry is read at startup; a mid-session file drop is not picked up).

Notes