Subagent Orchestrator

A quota-aware, parallel subagent coordination skill for Antigravity 2.0. Turns one big task into a set of isolated, efficient agent missions — without burning your weekly quota.

Use this skill when

A task spans 3+ files or components
You want multiple agents working at the same time
You've hit quota issues mid-task before
The task involves both planning AND building
You need browser agent + code agent + terminal agent running together

Do not use this skill when

Editing a single file or fixing one bug
Writing a quick script under 50 lines
Asking a question or generating a plan only

Phase 1 — DECOMPOSE (before any agent runs)

Before spawning any subagent, the orchestrator MUST produce a Mission Brief. Announce:

"Running subagent-orchestrator skill. Decomposing task into isolated missions."

Then output a Mission Brief in this format:

MISSION BRIEF
─────────────────────────────────────────
Goal: [one sentence, what done looks like]
Total Agents: [N]
Quota Strategy: [FLASH / SONNET / MIXED]
Expected Token Cost: [LOW / MEDIUM / HIGH]

AGENTS:
[1] ID: agent-001
    Role: [e.g. Planner / Builder / Tester / Browser]
    Scope: [exact files or URLs this agent touches]
    Model: [Gemini Flash / Claude Sonnet]
    Input: [what it receives]
    Output: [what it produces]
    Depends on: [none / agent-001]

[2] ...
─────────────────────────────────────────

Wait for user to approve the Mission Brief before proceeding. If the user edits it, update and re-confirm. Never skip this step.

Phase 2 — QUOTA ROUTING

Before assigning models, apply this decision tree:

Is this task > 20 files OR > 500 lines of new code?
  YES → Use Gemini Flash for all agents. Reserve Sonnet for final review only.
  NO  → Is this task creative UI / complex logic / API design?
          YES → Use Sonnet for builder agent, Flash for all others.
          NO  → Use Gemini Flash for everything.

Model cost rules (never violate these):

Claude Opus → NEVER use in subagents. Too expensive.
Claude Sonnet → Max 1 subagent per mission.
Gemini Flash → Default for all subagents. Fast, cheap, separate quota pool.
Browser subagent → Always runs on its own pool. Use sparingly (1 per mission max).

Phase 3 — CONTEXT ISOLATION

Each subagent gets a scoped context packet. Never give all agents the full codebase.

For each agent, prepare:

AGENT CONTEXT PACKET — agent-[ID]
Files to read: [list only what this agent needs]
Files to write: [list only what this agent will create/edit]
Do NOT read: [explicitly exclude irrelevant files]
Knowledge: [paste only the relevant section of GEMINI.md]

Rule: If an agent doesn't need node_modules, package-lock.json, .next/, or dist/ — add them to a .antigravityignore before the agent runs.

Phase 4 — PARALLEL EXECUTION

Spawn agents in dependency order:

Round 1 (no dependencies): Run agents in parallel
Round 2 (depends on Round 1): Wait for all Round 1 outputs, then run
Round 3 (final): Integrate + verify

Between rounds, the orchestrator MUST:

Collect each agent's output artifact
Run a 3-point spot check:
- Did the agent stay within its assigned scope?
- Are there any import/export conflicts with other agents' outputs?
- Did any agent produce a placeholder ("TODO", "implement later")?
If any check fails → re-run that agent with corrected context. Do NOT continue.

Phase 5 — ERROR RECOVERY

If a subagent fails or produces broken output:

RECOVERY PROTOCOL
─────────────────────────────────────────
1. Do NOT re-run the full mission.
2. Identify the exact failure point.
3. Spawn a single repair agent with:
   - Only the broken file(s) as scope
   - The error message as context
   - Model: Gemini Flash (cheapest for repairs)
4. Validate the repair before continuing.
─────────────────────────────────────────

Never cascade a broken output to the next agent. Always fix before moving forward.

Phase 6 — INTEGRATION CHECK

After all agents complete, run a final integration sweep:

All imports resolve correctly
No duplicate function/variable names across files
No hardcoded values that should be env variables
No console.log left in production files
Types are consistent across components (TypeScript)
Build would succeed (npm run build mentally verified)

If any check fails, spawn one final repair agent scoped to the exact issue.

Quota Monitoring Rules

Track estimated usage throughout the mission:

Event	Quota Impact
Agent spawned	LOW (setup)
File indexed (each)	LOW
Tool call (file read/write)	MEDIUM
Terminal command	MEDIUM
Browser subagent activated	HIGH
Thinking mode enabled	VERY HIGH

If estimated usage crosses 60% of sprint quota mid-mission:

Pause and report: "Quota checkpoint: ~60% of sprint used. Continue or defer remaining agents?"
Switch remaining agents to Gemini Flash
Disable browser subagent if not yet started

Communication Rules

Announce which agent is running at all times

Show a compact progress bar between rounds:

Mission Progress: ████████░░ 4/5 agents complete
Quota Status: ▓▓▓▓░░░░░░ ~40% sprint used

Never go silent for more than one agent turn
If blocked, say why explicitly — never just stop

Examples

See examples/ folder:

nextjs-feature.md — Building a full Next.js feature with 3 parallel agents
api-plus-frontend.md — Backend API agent + Frontend UI agent running in parallel
debug-mission.md — Repair mission for a broken build using minimal quota

Limitations

This skill coordinates agent planning; it does not provide a runtime scheduler or enforce quota limits automatically.
Parallel agents still need explicit scoping, review, and integration by the parent agent.
Do not use it when a single focused edit or direct answer would be faster and clearer.