Subagent Orchestrator

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:

1. Collect each agent's output artifact
2. 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")?
3. 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:

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.