| name | subagent-orch |
| description | Orchestrate implementation and verification subagents across the subagent CLIs (cursor/codex/claude) and built-in forks. Invoke ONLY when the user explicitly requests subagent orchestration — do not self-trigger. |
Subagent Orchestration
Standard Process
The default loop for delegated implementation work:
- Brief — write the task as a self-contained brief (goal, constraints,
file paths, acceptance criteria). For anything over a few lines, put it in
a file and pass via stdin/
--prompt-file — never inline-quote a multi-line
brief through the shell.
- Implement — default coder is Composer 2.5 via
cursor-subagent.
Launch sync (exec) for bounded tasks, detached (start → status →
result --wait) for long ones.
- Verify — default verifier is a self-fork (Agent tool,
subagent_type: "fork"): it inherits your full session context at cache
prices and needs no onboarding brief. Alternative: gpt-5.5 high via
codex-subagent when you want an independent perspective or a review
uncontaminated by your own session's assumptions.
- Converge — feed verified findings back to the implementor by
resuming its session (
--resume <session_id> from the envelope), so
fixes land with the implementor's full context. Repeat implement→verify
until the verifier passes clean. Two consecutive rounds with no new
findings = converged.
- Never treat envelope
status: ok as task success. It means the run
exited cleanly. Verification (tests, diff review) decides success.
Keep roles separated: the implementor codes, the verifier judges, you route.
Don't have the implementor self-certify, and don't fix the implementor's
work inline yourself unless it's a trivial finishing edit.
Forking Yourself (Verification Clone)
Agent tool with subagent_type: "fork" clones the orchestrator:
- Runs on your model, whatever that is (model override is ignored),
with your full conversation context — it already knows the spec, the
decisions, and the history. No briefing cost, cache-priced input.
- Runs in the background; its tool output stays out of your context. Its
final message is returned to you — tell it exactly what to report back
(verdict + deviations, not a transcript).
- Best for: verification of work you orchestrated, audits against a spec
discussed in-session, any judgment task where session context is the
main input.
- Limit: the clone shares your priors and blind spots — same model, same
assumptions, reviewing plans it (as you) helped shape. When the risk is
"we're both wrong the same way," use a fresh outside model
(gpt-5.5 via codex-subagent) instead of, or in addition to, a fork.
- A fork can itself use the subagent CLIs — so "fork verifies, and where it
finds issues, it launches the pinned-model rerun" is a valid composition.
The Subagent CLIs
Three sibling CLIs, identical verb surfaces (exec/start/status/result/last/ messages/tools/list/stop/docs), identical envelope and session-file
contracts. On PATH:
cursor-subagent — Cursor's agent; Composer 2.5 default. The coder.codex-subagent — Codex; gpt-5.5 @ high effort from config.toml.claude-subagent — Claude Code headless; full-autonomy default.
Supports exact model pinning (--model claude-opus-4-6) and
--effort low|medium|high|xhigh|max.
First use of any of these in a session: run the bare CLI with no
arguments (e.g. Bash: cursor-subagent). Each prints a complete
self-onboarding page — commands, envelope contract, execution profile,
safety notes, examples. Read it before the first exec; it is the current
and authoritative usage doc. Do not operate from memory of a prior session.
Runs execute in the cwd at invocation — cd into the target project first.
Model Table
| model | cost | intelligence | taste | harness |
|---|
| composer-2.5 | 9 | 7 | 7 | cursor-subagent |
| gpt-5.5 | 9 | 8 | 5 | codex-subagent |
| opus-4.6 | 6 | 7 | 8 | claude-subagent --model claude-opus-4-6 |
| opus-4.8 | 4 | 8 | 8 | claude-subagent, or Agent tool model:"opus" |
| fable-5 | 2* | 9 | 9 | Agent tool fork (*cache-priced) or model:"fable" |
Routing by task weight:
- Simpler / mechanical (clear-spec implementation, refactors, test
writing): composer-2.5. Fast, near-free, no hygiene debt.
- Harder implementation (gnarly logic, cross-cutting change): still try
composer first; escalate to opus-4.6 high effort, then opus-4.8. Judge
the output, not the price — escalating costs less than shipping mediocre
work.
- Analysis / investigation / second-opinion review: gpt-5.5. Raw
intelligence at effectively zero cost; hygiene risk doesn't apply to
read-only work.
- Verification of orchestrated work: self-fork first (context is the
input); gpt-5.5 high for independence; both when stakes justify it.
- Taste-sensitive work (API design, UX copy, naming): opus-4.6/4.8 or
fable — taste ≥ 7.
Nuance and Factors
gpt-5.5 hygiene caveat. Very smart, but when it writes code it
over-protects: backwards-compat shims, regression tombstones, silent
"gentle fallback" paths instead of asking. This compounds into cleanup
debt. If gpt-5.5 implements, pair the brief with explicit instructions:
no fallbacks, no compat shims, no defensive wrappers — fail loudly and
ask on ambiguity. Prefer it for analysis and review, where the caveat is
irrelevant.
The opus ladder. Default Claude is opus-4.6; prefer 4.6 at high effort
before reaching for 4.8. Reserve 4.8 for the hardest non-fable work. No
sonnet in this rotation.
Thinking-level control by harness. Ad-hoc Agent tool spawns take a
model alias but no effort parameter and no version pinning ("opus"
means current opus). Effort control requires: a subagent definition file
(.claude/agents/*.md frontmatter), the Workflow tool's per-call
effort option, or the CLIs (claude-subagent --effort, codex via
-c model_reasoning_effort=...). If a specific model version or thinking
level matters, use the CLI harness.
Harness selection rule. Built-in Agent tool for context-sharing and
alias-level Claude spawns (forks, quick fable/opus lookups). Subagent CLIs
for precision: exact model versions, effort levels, non-Claude models, and
anything needing a durable inspectable session (envelope, stream.jsonl,
resume across turns).
Parallelism. One coder per project directory. For parallel work,
prefer parallel projects (separate cwds) over parallel agents in one
tree. Two runs in the same cwd may serialize, hang, or tread on each
other's edits.
Cost posture. Every CLI run is a paid call. A fumbled launch (wrong
cwd, corrupted inline prompt) costs more than any token-saving shortcut.
Briefs via file, verify cwd before launch, check git status before
retrying a failed run — partial edits may already be in the tree.
