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.