Instruction file imported from ramsarma21/project-archive (.cursor/rules/multitask-subagent-router.mdc). Copyright stays with the author.

Multitask Subagent Router

Assumes the root session runs Opus 5 with max thinking (a repo rule cannot force or switch the root model). The orchestrator decides the tier silently and starts work; the user never picks a tier.

Model: implementers run Opus 5

Subagents that write code run Opus 5 at max thinking. While the root session is on Opus 5 max — it should be — get that by OMITTING the model parameter, so the subagent inherits the root's model. Not a cheaper tier.

The owner's reason, recorded: this project's work is coupled to context a brief cannot fully carry — which instrument lies, what has been disproven, why a compromise exists — and a weaker implementer spends that context re-deriving it or inheriting it wrongly. The extra cost is accepted deliberately. Reaffirmed 2026-07-31, with a condition attached: heavy lifting goes to Opus 5 only behind a brief the worker cannot veer from — exact files, exact numbers, an explicit out-of-scope list, and a named gate that can fail. See "An un-veerable brief" below.

Omission, not a slug, is the executable form of this rule, and the distinction is not cosmetic. The dispatch list offers no max-thinking Opus 5 — claude-opus-5-thinking-medium is the only Opus 5 on it, and the only -max on it is Opus 4.8 — so naming a slug explicitly downgrades a worker from the root's max thinking to medium. Name claude-opus-5-thinking-medium only when the root session is not on Opus 5, where it is an upgrade rather than a cut. This also means the rule is only as strong as the root: a session on a weaker model silently propagates that weakness to every worker it launches, and no rule can switch the root.

resume ignores all of this — a resumed worker keeps the model it was launched with. A worker started under a weaker root stays weak for its entire life, so relaunch fresh rather than resume when the work is heavy.

This one line has now drifted out of executable form twice. It named claude-opus-5-thinking-max until 2026-07-31, a slug no session could dispatch. Before that, the owner's original call was acknowledged only in a commit message (10bafb5) that changed the clip skill; the router itself was never edited, so every session afterwards read claude-opus-4-8-thinking-high here and dispatched it, for a full day. A preference recorded outside the artifact that drives behaviour is not a preference the system has — the same failure as the lane guard, whose own header notes that ownership "was declared in prose and in task briefs, and neither is enforcement."

An un-veerable brief

The condition on the Opus 5 spend. A capable implementer with a loose brief does not stall — it improvises, plausibly, and the drift is only visible after the work lands. Every heavy brief carries all five:

• Exact numbers, never descriptions. Every height, extent and coordinate as a literal (deck at 5.70, x33.3–41.7, z−3.2→−3.9), never "a ledge around 5–6 m". Inventing a number that looks reasonable is this repo's most common veer.
• A written out-of-scope list. Name what the worker must not touch even if it looks broken, and require it to be reported instead. Scope creep into a sibling's file is the failure the lane guard catches late and a brief should catch early.
• The lane claimed first, with the grant confirmed to cover every file the work needs. A worker that hits a refusal mid-flight either stops or routes around it.
• A named gate that can fail, quoted by command, as the pass bar — plus which instrument is inadmissible for the claim at hand. Left unsaid, a worker reaches for the replay harness to prove phasing, and it will lie to it.
• A checkpoint before the point of no return on anything long: commit in stages and report for review against the spec, rather than running to completion unobserved.

Tiers

With one model on both sides, the tiers are no longer about capability. They are only about whether diagnosis can be separated from implementation.

• Trivial (zero or one quick-tool request): parent handles it directly, no subagent.
• Tier 1 — worker end-to-end: localized, well-understood, low-risk work (routine game/UI/asset hookups, styling, isolated fixes, mechanical edits). Launch ONE coherent background worker to investigate, implement, and run focused verification. Default for most work.
• Tier 2 — parent diagnoses, worker implements: ambiguous work, or any non-obvious bug. The parent reproduces, establishes root cause, names exact constraints and files, acceptance criteria, and how to verify — then hands ONE background worker a precise bounded brief and reviews the result against the gate. Default whenever a task is tricky.
• Tier 3 — parent end-to-end (uncommon): genuinely coupled work where diagnosis and implementation cannot be separated safely (deep cross-system determinism, data integrity, security). Don't reach for it reflexively. Even here, delegate every independent mechanical subtask.

The parent's contribution is orchestration, diagnosis, brief-writing, and review. Keep it there even though the worker is now the same model — the reason to delegate is a clean context window and the freedom to coordinate, not a capability gap.

Diagnosis in a brief: candidates, never conclusions

The orchestrator's most damaging failure mode is asserting a mechanism it has not traced. Dispatching many lanes means writing briefs faster than code paths can be read, so the temptation is to infer architecture from adjacent files. Three times in one afternoon that produced a confident, wrong diagnosis, and one of the proposed "fixes" would have made the defect worse.

The pattern that works, evidenced by the case that went right:

• Give the symptom and the evidence. Always. That is what the worker cannot get elsewhere.
• Give hypotheses as a list of candidates to distinguish, labelled as untraced, with what would tell them apart. The Town House brief did this — three candidates, "say which it is, with evidence, before changing anything" — and the worker found a fourth and named it precisely. The elm and card-taxonomy briefs instead asserted a cause; both were wrong.
• Never state a mechanism as fact without having read the path the feature takes. If it has been traced, say so and cite the file. If not, say "I have not traced this."
• Ask for the brief to be challenged. Correcting the brief outranks executing it, and a worker that says "your premise is stale" has done the more valuable job.

Where the code lives is a lookup, not a guess

Read .cursor/lane-ownership.json and claim the lane before writing the brief. Two briefs in one afternoon sent workers into paths the map assigns elsewhere, because the orchestrator inferred location from what the code does — grading logic "obviously" in packages/grading when it is in apps/api. Both times the worker had to stop and report instead of working. The map is one tool call.

Policy

• In Multitask mode, use background subagents for non-trivial work; do not duplicate delegated investigation or implementation in the foreground.
• Prefer one coherent worker; use sibling agents only for genuinely independent workstreams.
• Escalate Tier 1 to Tier 2 if the worker finds ambiguity, architectural impact, repeated failure, or safety risk.
• Serialize merges to main. Concurrent merges by separate workers produce conflicts resolved badly by whoever arrives second.
• Preserve user-owned uncommitted changes, and never sweep a sibling's in-flight files into your commit — stage paths explicitly rather than git add -A.
• Verify proportional to risk, and prefer a check that can fail over one that only reports success.