What it does
You describe a goal in one or two sentences — any goal. The skill researches the problem space, discovers every available resource (MCPs, skills, APIs, datasets, local tools), plans atomic tasks, assembles a team of specialists tailored to the domain, then executes fully autonomously until every task passes verification or the budget runs out. No further user input needed after the two setup questions.
Works for any objective: software development, research papers, data analysis, content creation, automation pipelines, system configuration, or anything else.
What makes it different from a single-agent prompt:
- Domain-agnostic by design — no hardcoded task types or procedures. Agents derive their behavior from the goal. The same framework that builds a web service can write a research report or configure a data pipeline.
- Self-assembling agent team — after planning, an
agent-factory creates 1–3 specialized agents tuned to the specific goal domain and writes an AGENTS.md manifest. Executors check this and use specialists when available. If generic agents are sufficient, factory creates nothing.
- Resource scout runs before everything — discovers MCPs, skills, local tools, APIs, and datasets relevant to the goal. Writes a usage guide with exact callable names and invocation syntax so executors never have to guess.
- Researcher runs before every executor pass — the executor never acts blind. The researcher consults a 33-category knowledge-sources directory to find the right research channels for the goal domain, then prioritizes finding existing tools, MCPs, libraries, and APIs before planning how to build. Writes structured findings for two audiences: executor (how to do it) and verifier/auditor (verification criteria and quality standards).
- Memory accumulates across tasks and loops — each completed task distills learnings into
MEMORY.md. The .global/MEMORY.md persists across all loops in the project so the agent gets smarter over time.
- Fully autonomous failure handling — 3 verifier failures → auto-skip; auditor BLOCK → auto-fix once then skip. Never pauses for user input.
Supported platforms
All entries below confirmed against each vendor's own current documentation (fetched directly, not secondhand).
| Platform | Skill | Agent dispatch | Parallelism |
|---|
| Claude Code | /loop-engineer | Agent tool | ✅ true parallel — call it N times in one response |
| Cursor | /loop-engineer | Task tool | ✅ true parallel — confirmed via cursor.com/docs/subagents: multiple Task calls in one message run simultaneously |
Antigravity CLI (agy) | /loop-engineer | invoke_subagent | ✅ true parallel — confirmed via antigravity.google/docs/subagents: each call returns immediately (async background execution), so calling it N times back-to-back dispatches N concurrent subagents. No "Subagents array" parameter exists. Nesting capped at 10 levels. |
| Antigravity IDE (VS Code / JetBrains) | /loop-engineer | invoke_subagent | ✅ true parallel (see above) |
| Antigravity 2.0 (desktop) | /loop-engineer | invoke_subagent | ✅ true parallel (see above) |
| Hermes Agent | /loop-engineer | delegate_task(tasks=[...]) | ✅ true parallel — one call, array of task definitions, synchronous (blocks until all return). Default cap of 3 concurrent (delegation.max_concurrent_children, floor 1, no ceiling) |
| Gemini CLI | /loop-engineer | named agent tools (@agent-name) | ✅ true parallel (v0.36+, confirmed via developers.googleblog.com) — official caveat: avoid parallel subagents for heavy concurrent code edits (file conflict risk) |
| OpenCode | /loop-engineer | task tool | ⚡ sequential — still unresolved as of writing. Original bug (#14195) was closed, but sequential dispatch was reported again in a newer issue (#29638) with fix PRs open as of late May 2026; check that issue for current status |
Install
Plugin system — Claude Code (recommended, auto-updates)
claude plugin add https://github.com/vibhasdutta/loop-engineer
One-liner — macOS / Linux (Claude Code)
curl -s https://raw.githubusercontent.com/vibhasdutta/loop-engineer/main/install.sh | bash
Manual — macOS / Linux
git clone https://github.com/vibhasdutta/loop-engineer.git
cd loop-engineer
bash install.sh # Claude Code (default)
bash install.sh --cursor # Cursor
bash install.sh --gemini # Gemini CLI
bash install.sh --antigravity # Antigravity (CLI + IDE + 2.0)
bash install.sh --opencode # OpenCode
bash install.sh --hermes # Hermes Agent
bash install.sh --codex # OpenAI Codex CLI
bash install.sh --copilot # VS Code GitHub Copilot
bash install.sh --all # all platforms
Manual — Windows (PowerShell)
git clone https://github.com/vibhasdutta/loop-engineer.git
cd loop-engineer
.\install.ps1 # Claude Code (default)
.\install.ps1 -Cursor # Cursor
.\install.ps1 -Gemini # Gemini CLI
.\install.ps1 -Antigravity # Antigravity (CLI + IDE + 2.0)
.\install.ps1 -OpenCode # OpenCode
.\install.ps1 -Hermes # Hermes Agent
.\install.ps1 -Codex # OpenAI Codex CLI
.\install.ps1 -Copilot # VS Code GitHub Copilot
.\install.ps1 -All # all platforms
→ Full installation guide with per-platform verify steps
Quick start
Claude Code / Cursor — open any project and type:
/loop-engineer
Gemini CLI — describe a multi-step goal (auto-activates) or use the shortcut:
/loop-engineer
Antigravity — in agy, IDE, or 2.0, describe a goal or type:
/loop-engineer
OpenCode — open any project and type:
/loop-engineer
Hermes Agent — type the slash command or describe a multi-step goal:
/loop-engineer
Codex CLI — open Codex and type:
/loop-engineer
This scaffolds the state files and prints a /goal command to paste for the actual loop run.
VS Code GitHub Copilot — after installing:
- From your project root, run the init command printed by install (or run
init-loop.sh --platform copilot directly).
- Open Copilot Chat, switch to Agent mode.
- Attach
.github/prompts/loop-engineer.prompt.md via #loop-engineer.prompt and describe your goal.
The wizard asks 3 questions only (mode is skipped if passed as an argument, e.g. /loop-engineer patch):
Q1. Mode? build / research / patch / audit
Q2. What do you want the loop to accomplish? (1–2 sentences)
Q3. Auto-commit after each verified task? (yes / no)
Everything else is automatic — LOOP_ID, stop condition, budget, context gathering, task decomposition, resource discovery, agent assembly, and the full execution loop.
Modes:
| Mode | What it does |
|---|
| build (default) | New work from scratch — the full pipeline below, unchanged. |
| patch | Fixes or extends the existing codebase instead of building greenfield — same pipeline, but every researcher/executor is told the existing code is ground truth: read it first, then fix or extend it. |
| research | Investigate and report only — no code changes. Skips the build and audit steps; the researcher writes each task's final deliverable directly, and the verifier checks that against the stop condition. |
| audit | Review only — no code changes. Skips the build step; the auditor's review of existing code/output is the task, with findings written to RESEARCH.md instead of triggering an auto-fix. |
How it works
Phase 1 Wizard
3 questions (mode, goal, git). Generates LOOP_ID (4 meaningful words, max 24 chars).
No resume support — every invocation starts a fresh loop.
Phase 2+3 Initialize loop (one script call)
scripts/init-loop.sh|.ps1 creates loop-stack/<LOOP_ID>/ (PLAN.md,
STATUS.md, MEMORY.md, TOOLS.md, RESEARCH.md, AGENTS.md), copies agent
files, and writes verifier.md/.toml with the actual stop condition
substituted in. Creates loop-stack/.global/ if missing.
Phase 4 Startup sequence (parallel on supporting platforms)
├── Researchers (2–4, universal domains, run in parallel)
└── Resource Scout (discovers MCPs, skills, tools, APIs, datasets)
Planner runs once, reading all research + resources, creating tasks
with [G1]/[G2] tags (task type depends on mode). Agent-factory does
NOT run here — it's on-demand (see below), not a fixed startup step.
Phase 5 Outer loop — per parallel group until all tasks done or budget hit:
├── Researchers (one per task, parallel)
├── Agent Factory (on-demand: only for tasks that clearly need a
│ specialist and have none yet — most tasks skip this)
├── Executors (one per task, parallel — skipped entirely in research/audit
│ mode; check AGENTS.md for specialists first)
├── Auditors (one per task, parallel — in audit mode this IS the task)
│ CLEAN/WARN ─────────────────────────────→ Verifier
│ BLOCK ──────────────────────────────────→ auto-fix once → re-audit → auto-skip
├── Verifiers (one per task that passed audit — the final gate: checks
│ RESEARCH.md's criteria AND runs the stop condition)
│ PASS ──────────────────────────────────→ Memory-keeper
│ FAIL < 3 ──────────────────────────────→ retry from Researchers
│ FAIL ≥ 3 ──────────────────────────────→ auto-skip
└── Memory-keeper (single, local + global write — learnings/context only,
never executes the goal)
→ mark [x], git commit if enabled, find next group
Stuck-agent detection is inline — the orchestrator itself checks stale
heartbeats in STATUS.md; there is no dedicated watcher agent.
Phase 6 Report
loop-stack/<LOOP_ID>/ → loop-stack/<LOOP_ID>_DONE/ (bookkeeping only).
Writes REPORT.md, prints summary.
The agent team
| Agent | What it does |
|---|
| resource-scout | Discovers everything available for the goal — MCP servers, skills, local tools, APIs, datasets, external resources. Writes TOOLS.md with a usage guide of exact callable names and invocation syntax. Propagates newly discovered resources live during execution. Cached globally for 7 days. |
| researcher | Maps what's known, what's needed, and what could go wrong before the executor acts. Consults knowledge-sources.md to identify the right research channels for the goal domain (33 categories: search engines, package registries, GitHub, APIs, security databases, finance, medical, etc.), then searches across those sources — prioritizing existing MCPs, skills, libraries, and APIs before building from scratch. Writes RESEARCH.md for two audiences: the executor (how to do it) and the verifier/auditor (what to verify, what right looks like). Dynamic count (2–4) based on goal complexity. Runs before every executor pass. |
| planner | Reads all researcher output and resource discoveries. Creates atomic tasks tagged with parallel group markers: same [GN] = run in parallel, different [GN] = sequential dependency. Runs once at startup. |
| agent-factory | On-demand tool, not a fixed phase — invoked only right before executing a specific task that clearly needs domain expertise a generic executor lacks, and only for that task. Reads PLAN.md, RESEARCH.md, and TOOLS.md, then writes one purpose-built agent to loop-stack/<LOOP_ID>/agents/ (loop-specific, not platform-global) and updates the AGENTS.md manifest. Most loops never call it. |
| executor | Reads RESEARCH.md, checks AGENTS.md for loop-specific specialists (from loop-stack/<LOOP_ID>/agents/), then derives execution method from the goal — writes code, produces documents, processes data, runs pipelines, or whatever the task requires. Implements one task. Appends discoveries to MEMORY.md inline. Goal output always goes to the project directory, never inside loop-stack/. Never marks tasks complete. |
| auditor | Runs right after the build. Reads RESEARCH.md § Quality Standards first — the researcher already documented what good output looks like vs. what to avoid for this task. Catches problems a functional check wouldn't: things that technically work but aren't done the right way. Three outcomes: CLEAN (proceed to verifier), WARN (non-blocking, proceed), BLOCK (triggers one auto-fix attempt, then proceeds either way). In audit mode this review IS the task. |
State files
loop-stack/
<loop-id>/ ← one dir per loop, namespaced, no collisions
PLAN.md ← goal, [G1]/[G2] task checklist, stop condition, budget
STATUS.md ← current state, attempt count, last result per agent
MEMORY.md ← learnings accumulated this loop
TOOLS.md ← resources, tools, APIs, usage guide
RESEARCH.md ← 7 sections: context, tools, requirements, approach,
verification criteria, quality standards, prior attempts
AGENTS.md ← specialized agents manifest, updated on-demand by agent-factory
REPORT.md ← written on completion
agents/ ← loop-specific domain specialists (written by agent-factory)
<loop-id>_DONE/ ← renamed when a loop completes (bookkeeping only — nothing
reads it back; every /loop-engineer run starts fresh)
.global/
MEMORY.md ← cross-loop project learnings (shared, persistent)
TOOLS.md ← cached resource discovery (7-day TTL)
Platform details
| Platform | Context file | Agent files | Skills path | MCP config |
|---|
| Claude Code | CLAUDE.md | .claude/agents/ | ~/.claude/skills/ | ~/.claude/settings.json |
| Cursor | .cursorrules / CLAUDE.md | .cursor/agents/ | ~/.cursor/skills/ | ~/.cursor/mcp.json |
| Gemini CLI | GEMINI.md | .gemini/agents/ | ~/.gemini/skills/ | ~/.gemini/settings.json |
| Antigravity CLI | AGENTS.md | .agents/ | ~/.gemini/antigravity-cli/skills/ | ~/.gemini/config/mcp_config.json |
| Antigravity IDE | AGENTS.md | .agents/ | ~/.gemini/antigravity/skills/ | ~/.gemini/config/mcp_config.json |
| Antigravity 2.0 | AGENTS.md | .agents/ | ~/.gemini/config/skills/ | ~/.gemini/config/mcp_config.json |
| OpenCode | AGENTS.md | .opencode/agents/ | ~/.config/opencode/skills/ | opencode.json → mcp key |
| Hermes Agent | HERMES.md / .hermes.md | .hermes/agents/ | ~/.hermes/skills/ | ~/.hermes/config.yaml → mcp_servers |
| OpenAI Codex CLI | — | .codex/agents/ (TOML) | ~/.codex/skills/ | ~/.codex/config.yaml |
| VS Code Copilot | .github/copilot-instructions.md | .github/agents/ | ~/.config/loop-engineer/copilot/ | .vscode/mcp.json |
Codex note: knowledge-sources live at .codex/knowledge-sources/ (sibling of agents/, not inside it) — Codex's agents/ directory holds only TOML agent definitions.
Copy the platform's context file to your project root after installing — it tells the agent where the skill lives, how subagents work, and what slash commands are available.
Docs
| |
|---|
| Installation | Per-platform install steps, post-install setup, verify commands |
| How It Works | Full phase walkthrough, agent roles, state file schema, failure handling |
| Loop Engineering | What loop engineering is, maker/checker split, references |
License
MIT
