0xVoidw/subagent-allocator

Sub-Agent Allocator

Turns a plan.md into an executable task assignment sheet: who does what, which model to use, how much thinking effort to allocate, and how to escalate on failure.

The principle of saving quota is simple: most of the work in a plan consists of reading files, searching code, running tests, and making changes per spec—none of that requires the most expensive model. The expensive model should only be used where real judgment is needed. This skill's job is to separate the two.

Input

1. Path to plan.md. If not provided, look for plan.md / PLAN.md / PLANS.md in the current directory; if still not found, ask.
2. Target platform: claude (Claude Code), codex (OpenAI Codex), or both. If not specified, infer from the current running environment; if inference fails, ask once.
3. Orientation (optional): save, balanced (default), or stable. Only affects step 4 below when uncertain about which direction to lean.

Once the platform is determined, read the corresponding reference file, which contains the platform-specific model names, price ratios, and effort levels:

• Claude → references/claude.md
• Codex → references/codex.md
• both → read both, output two sets of configurations side by side

Model names and prices go out of date. The reference file is the single source of truth; do not fill in model names from memory.

Process

1. Read Plan, Break into Task Units

Follow the step divisions of plan.md itself, only adjusting in two cases:

• Split: A single step contains both "heavy reading/searching" and "making judgments/changing code." Split off the reading part to a cheap sub-agent that only returns a summary.
• Merge: Several consecutive small steps modify the same set of files and need the same context. Combine them into one task to avoid repeatedly loading context.

Do not over-split. Each sub-agent has a startup cost (reloading context, writing handoff instructions). If a task can be done in a few minutes, let the main agent do it directly, marking it as "main agent executes directly" in the document.

2. Tag Each Task with Five Marks

Mark	Question to Ask	Values
Clarity	Is the spec already locked in and just needs to be followed?	Clear / Partial / Open
Error Cost	If wrong, is it easy to detect and roll back?	Low / Medium / High
Verifiability	Are there tests, builds, lints, or scripts that can automatically determine correctness?	Yes / Can be added / No
Reading Volume	How much material needs to be read before starting work?	Low / High
Impact Scope	Is the change local, cross-module, or architectural?	Local / Cross-module / Architecture

If something is not clear in plan.md, make the most likely assumption and write it in the "Assumptions" column of the output. Do not stop to ask about each item.

3. Map to Four Tiers

Platform-specific models are in the reference files; here we only define the tiers:

Tier	Use for	Typical Tasks
T0 Light	Clear + Low cost + Result immediately verifiable	Search files, read logs, run tests and report, classify, extract, summarize
T1 Standard	Clear + Local + Verifiable	Implement feature per spec, fix a localized bug, write tests, write docs, UI implementation
T2 Heavy	Partially clear, or cross-module, or requires debugging judgment	Multi-file features, debug hard-to-trace bugs, code review, integrate sub-agent results
T3 Flagship	Open-ended + Architectural, or high error cost with no automatic verification	Architectural decisions, large refactoring plans, trade-offs with multiple constraints, orchestrate multiple sub-agents

Judgment order: assume T1 first, then see if there is reason to go down or up.

• Reason to go down to T0: The task is essentially "find and report" and does not produce code to be merged.
• Reason to go up to T2: Clarity is not "Clear," or Impact Scope is not "Local."
• Reason to go up to T3: Must satisfy both "Open or Architecture" and "Error cost is high." If only one is true, use T2 with high effort.

In a normal plan, there are usually only 0 to 2 T3 tasks. If more than half are T3, go back and check the splitting—chances are "reading" and "judgment" were bundled together.

4. Set Thinking Effort

Effort is a finer-grained knob than swapping models; adjust it first.

• Start with the default starting value for that tier in the reference file.
• Verifiability = Yes: Keep the starting value, or even lower one level. When the model can self-check via tests, high effort yields little benefit.
• Verifiability = No AND Error Cost ≥ Medium: Raise one level.
• Someone is waiting for results in real time: Lower one level, prioritize speed.
• When uncertain, lean toward the lower value if orientation is save, or the higher value if stable.

Once effort exceeds high, further increases often cost nearly as much as switching to the next tier's model at low effort. Therefore, the escalation ladder is:

1. First, add a verification method (give it a runnable test or check command)
2. Raise effort by one level, up to high
3. Switch to the next tier model, starting at the lowest default effort for that tier

Codex T0 is an exception; its high effort still offers good cost-effectiveness. See references/codex.md.

5. Quality Protection

Saving quota must not come at the cost of rework—rework is more expensive than using the right model from the start. The following measures ensure "quality does not noticeably degrade":

• Every task must have a completion standard. If it can be written as a command (like pytest tests/x, npm run build), write it as a command. Tasks that cannot define a completion standard get upgraded one tier.
• Code changes and key decisions stay in T1 and above. T0 only reads, or writes things that won't go into the main branch (reports, lists).
• After a cheap model finishes, a model one tier higher reviews the diff. Reviewing a diff only checks the changed parts, consuming few tokens, yet catches most issues. List this as a separate review task at the end of each phase.
• Sub-agents only return conclusions. In the role description, specify the output format and length limit (e.g., "a summary no longer than 200 characters + list of relevant file paths") to avoid flooding the main agent's context with lengthy output.

6. Plan Execution Order

• Mark mutually independent tasks as parallelizable.
• Try to group tasks using the same model together, and switch models at natural breakpoints between phases. Switching models mid-phase frequently discards cache, effectively paying for the context again.
• Platform-specific notes (cache ownership, long-context pricing thresholds, etc.) can be found in the reference files—include them in the output's "Notes" section when applicable.

Output

Write plan.dispatch.md in the same directory as plan.md, using the structure below. For many tasks, keep all tasks in the table; only write role cards for sub-agent tasks.

# Sub-Agent Dispatch: <Plan Name>

Source: <plan.md path>　Platform: <claude / codex / both>　Orientation: <save / balanced / stable>

## Overview

| # | Task | Executor | Tier | Model | Effort | Dependencies | Parallelizable |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 1 | … | Scout | T0 | … | … | None | With 2 |

Tier distribution: T0 ×n, T1 ×n, T2 ×n, T3 ×n
Main agent: <model> / <effort>, responsible for <coordination, integration, final acceptance, etc.>

## Execution Phases

### Phase 1: <Name> (Model: …)
- Tasks 1, 2 run in parallel
- End-of-phase review: <who reviews what>

## Role Cards

### Task 1: <Name>
- **Role**: <One-line description, e.g., "Read-only scout: locate all call sites using the old API">
- **Model / Effort**: … / …
- **Goal**: …
- **Input**: <Files, directories, error messages to read>
- **Constraints**: <What not to modify, which conventions to follow>
- **Completion Standard**: <Command or checkable state>
- **Output Format**: <Content and length limit>
- **Escalation Ladder**: Add verification → raise effort to … → switch to … / …
- **Rationale for Selection**: <One sentence based on the five marks>

## Assumptions and Notes
- <Items that `plan.md` didn't specify and were inferred by this skill>
- <Platform-specific cost traps>

## Estimated Savings
Rough estimate compared to "all tasks using the default heavy-tier configuration": <e.g., "About half the tasks dropped to T0/T1, reducing unit cost to 1/2 to 1/20">

The "Goal," "Input," "Constraints," and "Completion Standard" in the role card are meant to be directly pasted as prompts to the sub-agent. Write them so they can be understood independently—the sub-agent will not see the rest of plan.md.

The "Estimated Savings" should only give an order of magnitude and the rationale; do not fabricate exact percentages. Actual consumption depends on the tasks themselves; suggest that the user adjust settings after comparing against the usage statistics.

Example

In plan.md, there is a step:

3. Replace all uses of oldLogger in utils/ with newLogger; note that some places pass a custom formatter

Processing: This step mixes "locate all call sites" (high reading volume, read-only) and "replace and handle formatter edge cases" (requires code changes, has special cases that need judgment). Split into two tasks:

#	Task	Executor	Tier	Effort	Rationale
3a	List all oldLogger call sites, mark those with custom formatters	Scout	T0	Default value	Read-only; misses will be caught by 3b's grep check
3b	Replace per the list, adapt formatter edge cases one by one	Implementer	T1	Default value	Clear spec; completion standard: grep -r oldLogger utils/ returns empty and tests pass

If there are no tests covering formatter behavior, raise 3b's effort by one level and note it in "Assumptions and Notes."