Antigravity

---
name: loop-engineer
description: >
  Loop engineering wizard for Antigravity. Asks 3 questions, then orchestrates
  a fully autonomous parallel agent team (resource-scout, researcher, planner,
  agent-factory, executor, verifier, auditor, memory-keeper) until the goal is met.
  Uses invoke_subagent for true parallel dispatch. Researcher agents use the
  built-in research TypeName. Modes: build (from scratch), research (investigate
  only), patch (fix/extend existing code), audit (review only, no changes).
  Persistent memory, git integration.
---

# Loop Engineer (Antigravity)

You are running a loop engineering wizard. Follow these phases in order.

**Prerequisite — reduce permission friction:** confirmed via antigravity.google/docs/permissions — file reads/writes inside your active project are auto-allowed by default, so that part shouldn't interrupt you. `command(...)` actions (every terminal/bash call — including the init script, and every `git commit` the executor makes) default to **Ask** unless you've added an allow rule. Before running an autonomous loop, add an Allow rule for the commands this loop needs (at minimum `command(bash)`, or `command(*)` for zero friction) via Antigravity's permission settings — either the in-editor approval-card "expand scope" option the first time a command prompts, or your project/user settings directly. Without this, the loop will pause on every single Bash call, which defeats "fully autonomous."

---

> **To update loop-engineer:** re-run `install.sh --update` / `install.ps1 -Update -Antigravity`. Updates are never applied automatically mid-loop.

---

## Phase 1 — Core Wizard

**Q1 — Mode:** if invoked with an argument matching `build`/`research`/`patch`/`audit`, use it as MODE and skip this question. Otherwise ask: "Mode? build (new from scratch) / research (investigate and report, no code changes) / patch (fix or add a feature using the existing codebase) / audit (review existing code/output only, no changes)". Default to `build` if unclear.

**Q2:** "What do you want the loop to accomplish? (1-2 sentences)"

Generate LOOP_ID: lowercase slug, first 4 meaningful words, max 24 chars.
Auto-set: `STOP_CONDITION` = "all tasks in loop-stack/<LOOP_ID>/PLAN.md checked", `MAX_TURNS` = 20.

**Q3:** "Should the loop auto-commit after each verified task? (yes / no)"

---

## Phase 2+3 — Initialize Loop

Run the init script — tries all three Antigravity surface paths automatically:

**Bash (macOS/Linux):**
```bash
INIT_SCRIPT="$(ls \
  "$HOME/.gemini/antigravity-cli/skills/loop-engineer/scripts/init-loop.sh" \
  "$HOME/.gemini/antigravity/skills/loop-engineer/scripts/init-loop.sh" \
  "$HOME/.gemini/config/skills/loop-engineer/scripts/init-loop.sh" 2>/dev/null | head -1)"
bash "$INIT_SCRIPT" \
  --loop-id <LOOP_ID> \
  --goal "<GOAL>" \
  --stop "all tasks in loop-stack/<LOOP_ID>/PLAN.md checked" \
  --git <yes/no> \
  --mode <MODE> \
  --platform antigravity
```

**PowerShell (Windows):**
```powershell
$init = @(
  "$env:USERPROFILE\.gemini\antigravity-cli\skills\loop-engineer\scripts\init-loop.ps1",
  "$env:USERPROFILE\.gemini\antigravity\skills\loop-engineer\scripts\init-loop.ps1",
  "$env:USERPROFILE\.gemini\config\skills\loop-engineer\scripts\init-loop.ps1"
) | Where-Object { Test-Path $_ } | Select-Object -First 1
& $init -LoopId "<LOOP_ID>" -Goal "<GOAL>" `
  -Stop "all tasks in loop-stack/<LOOP_ID>/PLAN.md checked" `
  -Git <yes/no> -Mode <MODE> -Platform antigravity
```

If the script is missing, install the skill first:
`git clone https://github.com/vibhasdutta/loop-engineer && bash install.sh --antigravity`

The script creates `loop-stack/<LOOP_ID>/`, `.agents/` with all agent .md files + knowledge-sources/, and `verifier.md` with the actual stop condition substituted.

---

## Phase 4 — Startup Sequence

**How parallel dispatch actually works in Antigravity:** confirmed via official docs (antigravity.google/docs/subagents) — there is no "Subagents array" parameter. The real mechanism: calling `invoke_subagent` spawns a subagent that "immediately begins executing its task" and "runs asynchronously in the background, allowing the parent agent to delegate a task and immediately resume its own work." So to get true concurrency, call `invoke_subagent` multiple times back-to-back in the same turn — each call returns right away without blocking, so N calls in a row dispatch N subagents running concurrently. Then wait for all of them to send their completion messages before proceeding to the next step.

**Nesting limit:** a maximum depth of 10 levels of subagents-of-subagents is enforced. Not a concern for loop-engineer's flat dispatch pattern, but worth knowing if an agent-factory-created specialist tries to spawn its own subagents.

**IMPORTANT:** Subagents start with a clean slate — no parent context. Every `Prompt` must be fully self-contained with the loop directory path, what to read, what to write, and a reference to the agent's instruction file in `.agents/`.

### Step 1 — Parallel RESEARCHERS (dynamic count)

Determine researcher count by goal complexity:
- Simple/single-domain → 2 researchers
- Medium/multi-domain → 3 researchers
- Large/multi-system → 4 researchers

Call `invoke_subagent` once per researcher, back-to-back in the same turn (each call returns immediately, so this dispatches all of them concurrently — see note above).
Use `TypeName: "research"` — the built-in type optimized for codebase exploration.

Domains to distribute:
- **Context & Prior Work**: source structure, patterns, package files, existing tests
- **External Knowledge & Resources**: README, docs/, external APIs, .env.example, configs
- **Requirements & Constraints**: DB schema, data models, state management (for 3+ researchers)
- **Environment & Integration**: CI/CD, infrastructure, build, Docker (for 4 researchers)

Each researcher Prompt:
```
Loop directory: loop-stack/<LOOP_ID>/
Focus: {ASSIGNED_DOMAIN} — {specific files and concerns}
GLOBAL DATA FIRST: read loop-stack/.global/MEMORY.md and loop-stack/.global/TOOLS.md.
Write findings to loop-stack/<LOOP_ID>/RESEARCH.md under "## {Domain Name}".
Update loop-stack/<LOOP_ID>/STATUS.md "Last Researcher Result".
Read .agents/researcher.md for full instructions.
```

**Stuck-agent check (no watcher subagent needed):** Antigravity already exposes `manage_subagents(Action: "list")` — use it directly if one researcher is taking noticeably longer than its peers, to see whether it's still running or has stalled. If stalled, proceed without it and note `{agent}: STUCK — no output` in STATUS.md `## Active Heartbeats`.

Wait for all researcher subagents to complete before Step 2.

### Step 2 — RESOURCE SCOUT

Call `invoke_subagent` with one entry, `TypeName: "self"`:
```
Loop directory: loop-stack/<LOOP_ID>/
Check loop-stack/.global/TOOLS.md — if < 7 days old, reuse it.
Otherwise discover all tools. Write to loop-stack/<LOOP_ID>/TOOLS.md AND loop-stack/.global/TOOLS.md.
Read .agents/resource-scout.md for full instructions.
```
Wait for resource-scout to send its completion message.

### Step 3 — PLANNER

Call `invoke_subagent` with one entry, `TypeName: "self"`:
```
Loop directory: loop-stack/<LOOP_ID>/
Read RESEARCH.md (all sections) and TOOLS.md.
Task type depends on MODE: build/patch → implementation tasks; research → research/writing tasks only, no code changes; audit → review tasks only, no code changes.
Create 3–7 tasks with parallel group tags [G1], [G2], etc.
Same group = parallel (independent files/modules). Different group = sequential dependency.
Replace "## Tasks" in PLAN.md. Update STATUS.md.
Read .agents/planner.md for full instructions.
```
Wait for planner to send its completion message.

Write `loop-stack/<LOOP_ID>/AGENTS.md` with `# Specialized Agents\n## Status\nNONE CREATED YET`. (Agent-factory is on-demand, not a fixed step — see Rules.) Proceed to Phase 5.

---

## Phase 5 — Outer Loop

**FULLY AUTONOMOUS. Never pause for user input.**

Initialize: `turns_used = 0`, `skipped_tasks = []`.

**Mode gating:** build (default) — full flow. patch — same steps, but every researcher/executor prompt adds "existing codebase is ground truth — fix/extend, don't rewrite from scratch." research — skip step 5 (executors) and steps 6–7 (audit) entirely; the researcher (step 3) writes each task's final deliverable directly; the verifier checks that instead of built code. audit — skip step 5; the auditor step IS the task (read-only review, findings to RESEARCH.md); a BLOCK verdict is just recorded, never auto-fixed, always proceeds to the verifier.

For parallel steps: call `invoke_subagent` once per agent, back-to-back in the same turn (each call returns immediately without blocking — see Phase 4 note). Wait for all to send completion messages before proceeding.

### Iteration steps:

1. **Budget check** — over MAX_TURNS → Phase 6.

2. **Read state** — identify current parallel group (all unchecked [GN] tasks).

3. **Parallel RESEARCHERS** — one per task (2 if batch=1). Call `invoke_subagent` once per task, back-to-back in the same turn, `TypeName: "research"`:
   ```
   Loop directory: loop-stack/<LOOP_ID>/
   GLOBAL DATA FIRST — read loop-stack/.global/MEMORY.md AND loop-stack/.global/TOOLS.md.
   Focus: {ASSIGNED_DOMAIN} for task: {this_task}
   Append findings to RESEARCH.md under "## Task-Specific Research — {this_task}".
   Update STATUS.md "Last Researcher Result".
   Read .agents/researcher.md for full instructions.
   ```
   Wait for all. Increment turns_used.

4. **Before executors, check AGENTS.md.** For every task in the batch that clearly needs domain expertise beyond a generic executor and has no specialist yet, call `invoke_subagent` once per such task, back-to-back in the same turn (`TypeName: "self"`, each reads `.agents/agent-factory.md`) to create their agent files and update AGENTS.md — same parallel-first rule as researchers/executors. Wait for all to finish. Skip this for most tasks.

5. **Parallel EXECUTORS** — one per task. Call `invoke_subagent` once per task, back-to-back in the same turn, `TypeName: "self"`:
   ```
   Loop directory: loop-stack/<LOOP_ID>/
   GLOBAL DATA FIRST — read loop-stack/.global/MEMORY.md AND loop-stack/.global/TOOLS.md.
   Read MEMORY.md, TOOLS.md, PLAN.md, STATUS.md.
   READ: RESEARCH.md "## Task-Specific Research — {this_task}".
   Current task: {this_task}. Scope: only files for this task.
   Implement. Append discoveries to MEMORY.md directly. Update STATUS.md.
   Goal output (code, documents, files) goes to the project directory, NOT inside loop-stack/. loop-stack/ is state-only.
   Read .agents/executor.md for full instructions.
   ```
   Wait for all. Increment turns_used.

6. **Parallel AUDITORS** — one per task just built. `TypeName: "self"`. Wait for all.

7. **Process audit results**:
   - CLEAN/WARN → proceed to verifier
   - BLOCK → auto-fix (one executor with BLOCK context, `TypeName: "self"`, re-run auditor once). Still BLOCK → auto-skip.

8. **Parallel VERIFIERS** (tasks that passed audit only) — one per task. Verifier is the final gate: checks the task against RESEARCH.md's Verification Criteria (right place, satisfies criteria, no placeholders), then runs the stop condition. `TypeName: "self"`. Wait for all.

9. **Process verifier results**:
    - PASS → memory-keeper
    - FAIL < 3 → retry from step 3
    - FAIL ≥ 3 → auto-skip

10. **MEMORY-KEEPER consolidation** — single `invoke_subagent`, `TypeName: "self"`, local + global write. This is the only memory-keeper call per batch — executors already appended their raw learnings inline during step 5. Wait.

11. **Advance** — mark [x], git commit if enabled. Find next group.
    None → ALL DONE → rename `loop-stack/<LOOP_ID>/` → `loop-stack/<LOOP_ID>_DONE/` → Phase 6.

---

## Phase 6 — Completion Report

Write `REPORT.md` inside the renamed loop directory and print summary.

---

## Rules

- **File copy**: try CLI path (`~/.gemini/antigravity-cli/skills/`), then IDE path (`~/.gemini/antigravity/skills/`), then 2.0 path (`~/.gemini/config/skills/`). Never write manually.
- **Global data first**: every agent reads `.global/MEMORY.md` + `.global/TOOLS.md` before acting.
- **invoke_subagent**: parallel = multiple calls back-to-back in the same turn (each returns immediately, no "Subagents array" parameter exists). Sequential = deliberately waiting for one to finish before calling the next. Wait for completion messages between steps.
- **TypeNames**: use `"research"` for researcher agents (built-in, codebase-optimized). Use `"self"` for all others.
- **Self-contained prompts**: subagents have a clean context slate — every Prompt must include loop dir, files to read/write, and `.agents/{role}.md` reference.
- **Researcher before executor**: always. Dynamic count based on goal complexity.
- **Agent-factory is on-demand, not a fixed phase step.** Invoke it only right before executing a task that clearly needs a specialist. Most loops never call it.
- **knowledge-sources.md is a reference file researchers consult on demand**, not a phase step.
- **No watcher agent.** Use `manage_subagents(Action: "list")` directly if you need to check whether an agent is still running; never spawn a dedicated watcher subagent.
- **No separate evaluator.** Verifier is the final gate: checks the task against RESEARCH.md's Verification Criteria, then runs the stop condition. One agent, one call, same rigor — not two sequential subagents for what's really one quality gate.
- **Audit before verify.** Auditor reviews the build first (step 6); verifier runs last as the final pass/fail gate (step 8) and is what triggers retry.
- **Memory-keeper runs once per task batch** (after verify, local + global) — not a separate mid-batch checkpoint. Executors already append their own learnings to MEMORY.md directly as they work, so there's nothing left for a checkpoint pass to do that isn't already written. Its only job is capturing learnings/context — never executes the goal or writes goal output.
- **Executors append to MEMORY.md directly** during work.
- **Planner**: once at startup. Tasks MUST include [G1]/[G2] parallel group tags.
- **Fully autonomous**: no pauses. Audit BLOCK → auto-fix once → skip. 3 verifier fails → auto-skip.
- **Modes**: `build` (default), `research`, `patch`, `audit` — set once in Phase 1, gates Phase 5 (see above).
- **HARD RULE — no plan-approval gate**: after Phase 1's questions, proceed through Phase 2 onward without presenting a plan for approval or waiting for a "click proceed" confirmation. Do not use any native plan-then-approve UX for this loop.
- No resume support: every invocation starts a fresh loop. On completion: rename to `<LOOP_ID>_DONE/` (bookkeeping only).
- **Monitor**: use `manage_subagents(Action: "list")` to check running subagents if needed.
- **AGENTS.md**: ensure `AGENTS.md` is in the project root for workspace context.
- **MCP config**: remote servers require `serverUrl` field (not `url` or `httpUrl`).