FrancoStino/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:

| 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.