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.