Loop

---
name: loop
description: Use when the user invokes /evo:loop or asks to run autonomous improvement cycles, self-evolving development, compound discovery, or multi-cycle code improvement with research, build, audit, and learning phases
argument-hint: "(--resume | [--cycles N] [strategy] <goal>)"
---

# Evolve Loop v22.22

> Self-evolving development pipeline. Orchestrates 4 agents through 6 lean phases per cycle: Discover → Build → Audit → Ship → Learn → Meta-Cycle. This skill performs destructive operations (commits, pushes, version bumps) — only invoke when the user explicitly requests it via `/evo:loop` or asks to run improvement cycles.

## Platform overlay (v8.15.0+)

Tool and command names in this file use **Claude Code conventions** (`Read`, `Bash`, `Skill`, `Agent`, etc.). If you are running this skill from a different CLI (Gemini, Codex, generic), read [reference/platform-detect.md](reference/platform-detect.md) FIRST — it tells you which translation overlay to load (`reference/<platform>-tools.md` for tool names, `reference/<platform>-runtime.md` for invocation patterns). As of v12.0.0 the runtime is the Go binary (`go/bin/evolve`); cross-CLI subagent execution is handled by `evolve subagent run` and the `evolve serve-phase <name>` phaseproto wire. See [docs/platform-compatibility.md](../../docs/platform-compatibility.md) for the support matrix.

> **v12.1 status:** All command examples in this skill use the native `evolve <subcommand>` CLI. The legacy bash dispatcher is archived at `archive/legacy/scripts/dispatch/evolve-loop-dispatch.sh` — not for general use.

> **What this does in one paragraph:** Each `/evo:loop` invocation runs one or more self-contained improvement cycles — Scout finds work, Builder implements it in an isolated worktree, Auditor reviews it, and `ship.sh` commits only what passes. A trust kernel of three shell hooks (`phase-gate-precondition.sh`, `role-gate.sh`, `ship-gate.sh`) enforces phase order and artifact integrity at the OS layer, not the prompt layer — so the pipeline's safety properties hold even in autonomous / bypass-permissions mode. Failures become structured lessons via the Retrospective agent; the loop gets smarter with each pass.

## STRICT MODE — Read this first (v11.5.0+)

When invoked via `/evo:loop [args]`, you MUST execute exactly one bash command that runs the native Go binary's `evolve loop` subcommand. The binary lives at `$EVOLVE_GO_BIN` (operator override) or `<plugin_root>/go/bin/evolve` (default). **Your cwd is the user's project directory, NOT the plugin install** — let the resolver find the binary:

```bash
"${EVOLVE_GO_BIN:-$(find $HOME/.claude/plugins \( -path '*/marketplaces/evolve-loop/go/bin/evolve' -o -path '*/marketplaces/evolve-loop/go/evolve' -o -path '*/cache/evolve-loop/evolve-loop/*/go/bin/evolve' -o -path '*/cache/evolve-loop/evolve-loop/*/go/evolve' \) -type f 2>/dev/null | sort | tail -1)}" loop <args>
```

The `find` expression locates the Go binary in either install layout (marketplace or cache). `sort | tail -1` prefers the highest-version cache install. The whole `"${EVOLVE_GO_BIN:-$(find ...)}"` expression is **one** shell argument from bash's perspective.

**Quote `<args>` correctly.** When `<args>` contains an apostrophe (e.g., `doesn't`, `won't`, `it's`), the shell tokenizer breaks because `'` opens an unmatched quoted string. Always wrap the goal portion in double quotes:

```bash
# CYCLES STRATEGY then a SINGLE double-quoted goal:
... loop 3 balanced "make UI more elegant; user said it doesn't work"

# Or just CYCLES + double-quoted goal (strategy defaults to balanced):
... loop 5 "the goal isn't trivial — needs research"

# Or use the explicit --goal-text flag:
... loop --cycles 3 --strategy balanced --goal-text "make UI more elegant"
```

Single quotes inside the goal are fine when the goal itself is double-quoted. Avoid passing apostrophe-containing goals as bare unquoted args.

**A GOAL IS MANDATORY — prompt-and-wait before dispatch:** Before you run `evolve loop`, inspect `<args>`. If it contains NO goal (no positional goal text, no `--goal-text`/`--goal-hash`) and it is NOT a `--resume` or `--dry-run` invocation, you MUST ask the user to supply a one-line goal (via AskUserQuestion or a direct prompt) and WAIT for their answer BEFORE dispatching. **Never dispatch a goal-less `evolve loop`** — the binary rejects it with `rc=10` (`a goal is required …`), which is a re-prompt-the-user condition, not a terminal error. Only the cycle COUNT is optional (see below), never the goal.

**Cycle count is optional:** omit `--cycles` and the advisor decides how many cycles the goal needs — completion-driven, stopping when the backlog drains, bounded by a safety cap. Pass `--cycles N` for a hard bound of exactly N cycles.

**Resume after pause:** If a cycle was checkpointed (Claude Code subscription quota wall, batch cap near, or operator-requested), recover with `--resume`:
```bash
... loop --resume
```
The native dispatcher locates the most recent paused cycle, validates state (git HEAD unchanged, worktree exists), and re-runs the orchestrator from the paused phase boundary. Trust kernel is preserved — phase-gate, role-gate, ship-gate enforce the same invariants during resume. See [docs/architecture/checkpoint-resume.md](../../docs/architecture/checkpoint-resume.md) for the full protocol.

**Rollback hatch (removed in v12):** The legacy bash dispatcher at `archive/legacy/scripts/dispatch/evolve-loop-dispatch.sh` is archived. The native dispatcher is the sole path.

**DO NOT** invent paths like `<plugin_root>/skills/loop/go/bin/...` — the binary lives at `<plugin_root>/go/bin/evolve`, NOT under `skills/`. The skill (this file) and the binary live in sibling directories under the plugin root.

…and then read the binary's summary. Nothing else. The dispatcher loops one cycle per iteration and asserts each cycle produced Intent + Scout + Builder + Auditor ledger entries. Any cycle that bypasses the pipeline (orchestrator shortcut) makes the dispatcher exit with rc=2 and a CRITICAL diagnostic.

**Why intent capture** (v8.19.1+): the intent persona structures the user's goal into an `intent.md` artifact (8 fields + AwN classifier + ≥1 challenged premise) before Scout fires. Enable via `workflow.phase_enables.intent=on` in policy.json. This is the pre-Scout phase that prevents the "vague goal → wrong direction" failure mode the cycle-25 incident exposed. It's autonomy-preserving — no human checkpoint, no pause; the kernel verifies structure and the cycle continues. The user only invokes `/evo:loop` and intent capture happens automatically as the first phase.

**Sandbox EPERM fallback** (v8.20.1+, auto-managed since cycle-10): on macOS Darwin 25.4+, `sandbox-exec` cannot be nested. The preflight auto-detects nested-Claude and enables the EPERM fallback automatically — no env flag needed. The adapter retries without sandbox-exec on EPERM, preserving sandbox where the kernel allows it.

**You MUST NOT, when activating this skill** (tool names below are Claude Code conventions; consult `reference/<platform>-tools.md` for your CLI's equivalents — the prohibitions apply to those equivalents too):
- Use TodoWrite (CC) / `write_todos` (Gemini) / your CLI's task-list tool to decompose the goal into sub-tasks (the goal is for the orchestrator subagent inside each cycle, not for you).
- Invoke Edit, Write, or Bash (or `replace`/`write_file`/`run_shell_command` on Gemini, etc.) for any task other than the dispatcher itself (and reading its output).
- Invoke the in-process Agent / Task / `activate_skill`-as-subagent dispatch to run Scout/Builder/Auditor. Phase agents are spawned by `evolve subagent run` from inside the native `evolve cycle run` orchestrator. They are profile-restricted; the in-process subagent dispatch is not.
- "Help out" by editing files between cycles. Builder edits files inside its worktree, gated by `role-gate.sh`. You are not Builder.

**Why this is strict and not advisory:** the 2026-04-29 flow audit (cycles 8201–8213) showed that prompt-driven orchestration routinely shortcuts. Most cycles in that window have an Auditor ledger entry but no Scout/Builder entries — meaning Scout and Builder were either skipped or run via the in-process Agent tool that bypasses the kernel hooks (`role-gate`, `phase-gate-precondition`, `ship-gate`). The dispatcher closes that gap structurally: every cycle goes through `evolve cycle run` (or `evolve loop` for batches), which spawns the orchestrator subagent under `.evolve/profiles/orchestrator.json` (Edit/Write/git ops blocked at the kernel layer); that orchestrator then invokes Scout, Builder, Auditor via `subagent-run.sh` (sequence enforced by `phase-gate-precondition.sh`).

**Reading the summary correctly:**

| Dispatcher exit | Meaning | Your follow-up |
|---|---|---|
| `0` | All cycles ran AND ledger verified clean | Report the summary; that's it |
| `1` | A cycle invocation failed (e.g., subagent crash, state.json unwritable) | Surface the specific cycle's stderr and stop — do NOT retry inline |
| `2` | INTEGRITY BREACH: orchestrator silently skipped Scout/Builder/Auditor (no orchestrator-report.md, or report doesn't disclose the gap) — CRITICAL | Quote the exact ledger counts to the user; recommend inspecting `.evolve/runs/cycle-N/` to investigate; STOP |
| `3` | Batch completed with one or more recoverable failures (infrastructure / audit-fail / build-fail). Failure modes recorded to `state.json:failedApproaches[]` for the next dispatch's orchestrator to read and adapt | Report which cycles had which classification; surface state.json:failedApproaches summary; offer to re-run with the same goal so subsequent cycles can adapt |
| `10` | Bad arguments — most often a MISSING GOAL (`a goal is required …`) | Re-prompt the user for a one-line goal (not a terminal error), then re-dispatch with the goal supplied |

**Dispatch policy:** Configured in `.evolve/policy.json` under `dispatch.policy` (`off` / `verify` / `stop`; default: `verify`). Controls per-cycle ledger verification.

The rest of this file (architecture, model routing, phase docs) is reference material for the **orchestrator subagent** that `evolve cycle run` spawns. You, the slash-command handler, do not consult it during a `/evo:loop` invocation.

---

> **Trust boundary (v8.13.1, v12.1-updated)**: enforced by THREE PreToolUse kernel hooks running as native Go: `evolve guard ship` (only `evolve ship` can perform git commit/push/gh release), `evolve guard role` (Edit/Write must match the active phase's path allowlist), `evolve guard phase` (denies the in-process `Agent`/`Task` dispatch tool while a cycle is active per `.evolve/cycle-state.json`, forcing phase agents through the native bridge — NOTE: currently a wired no-op, rewire to the `Agent|Task` matcher pending per ADR-0074; phase ORDER itself is enforced by the Go state machine, `go/internal/core`). For automated cycles, prefer `evolve cycle run [--goal-text GOAL]` (or `evolve loop` for batches) — it spawns a profile-restricted orchestrator subagent that operates within these hooks. Legacy in-line orchestration remains supported but the hooks apply equally to it.

> **v8.13.2 / v12.0.0**: self-healing release pipeline. For version-bump releases use `evolve release <version>` (native Go). The pipeline runs pre-flight gating, auto-generates a CHANGELOG entry from conventional commits, atomically ships via `evolve ship`, polls the marketplace for up to 5 minutes, and auto-rolls-back on any post-push failure. Use `--dry-run` to simulate without mutations. See [docs/release-protocol.md](../../docs/release-protocol.md) for vocabulary (push ≠ tag ≠ release ≠ publish ≠ propagate).

## Shared Agent Values

The following JSON block is the canonical state initialization for the evolve-loop. Agents must use these field names when reading from or writing to `state.json`.

```json
{
  "lastUpdated": "2026-04-20T10:00:00Z",
  "lastCycleNumber": 0,
  "version": 1,
  "research": {
    "queries": []
  },
  "evaluatedTasks": [],
  "failedApproaches": [],
  "evalHistory": [],
  "instinctCount": 0,
  "operatorWarnings": [],
  "stagnation": {"nothingToDoCount": 0, "recentPatterns": []},
  "warnAfterCycles": 5,
  "mastery": {"level": "novice", "consecutiveSuccesses": 0},
  "ledgerSummary": {"totalEntries": 0, "cycleRange": [0, 0], "scoutRuns": 0, "builderRuns": 0, "totalTasksShipped": 0, "totalTasksFailed": 0, "avgTasksPerCycle": 0},
  "instinctSummary": [],
  "projectBenchmark": {
    "lastCalibrated": null, "calibrationCycle": 0, "overall": 0,
    "dimensions": {
      "documentationCompleteness": {"automated": 0, "llm": 0, "composite": 0},
      "specificationConsistency": {"automated": 0, "llm": 0, "composite": 0},
      "defensiveDesign": {"automated": 0, "llm": 0, "composite": 0},
      "evalInfrastructure": {"automated": 0, "llm": 0, "composite": 0},
      "modularity": {"automated": 0, "llm": 0, "composite": 0},
      "schemaHygiene": {"automated": 0, "llm": 0, "composite": 0},
      "conventionAdherence": {"automated": 0, "llm": 0, "composite": 0},
      "featureCoverage": {"automated": 0, "llm": 0, "composite": 0}
    },
    "benchHist": [], "highWaterMarks": {}
  },
  "fitnessScore": 0.0,
  "fitnessHistory": [],
  "fitnessRegression": false,
  "discoveryVelocity": {
    "current": 0,
    "benchHist": [],
    "rolling3": 0.0
  },
  "proposals": [],
  "researchAgenda": {
    "lastUpdated": null,
    "items": [],
    "capsuleIndex": {
      "docComp": [],
      "specCons": [],
      "defDesign": [],
      "evalInfra": [],
      "modul": [],
      "schemaHyg": [],
      "convAdher": [],
      "featCov": []
    }
  },
  "researchLedger": {
    "triedConcepts": [],
    "diversityTracker": {
      "dimensionCoverage": {},
      "lastResearchedDims": []
    }
  },
  "promptVariants": []
}
```

**Usage:** `/evo:loop [--cycles N] [strategy] <goal>` — a `<goal>` is REQUIRED
(except with `--resume` or `--dry-run`); only the cycle COUNT is optional.
(legacy bare positional integer = cycles; deprecation WARN emitted —
prefer explicit `--cycles N`)

## Quick Start

Parse `$ARGUMENTS`:

- **`--cycles N`** → run exactly N cycles. Omit it and the advisor decides
  the cycle count (completion-driven, bounded by a safety cap).
- **Strategy** (positional, after flags): `balanced` (default) | `innovate` |
  `harden` | `repair` | `ultrathink` | `autoresearch`.
- **Goal** (positional, after strategy): free-form text; quote it when it
  contains apostrophes or shell metacharacters.
- **Legacy bare integer** (`/evo:loop 3 balanced "goal"`) still parses
  as cycles with a deprecation WARN. Prefer the explicit `--cycles N` flag.

| Strategy | Focus | Approach | Strictness |
|----------|-------|----------|------------|
| `balanced` | Broad discovery | Standard | MEDIUM+ blocks |
| `innovate` | New features, gaps | Additive | Relaxed style |
| `harden` | Stability, tests | Defensive | Strict all |
| `repair` | Bugs, broken tests | Fix-only, smallest diff | Strict regressions |
| `ultrathink` | Complex refactors | tier-1 forced | Strict + confidence |
| `autoresearch` | Hypothesis testing | Fixed metrics, embraces failure | Divergent, unpenalized |

## Quota Handling & Auto-Resume (v10.6.0+)

When the dispatcher exits with `DISPATCH_RC=5` it emits a structured marker
line:

```
QUOTA-PAUSE: cycle=N wake-at=ISO8601 source=X attempts=K/M
```

This is the Claude Code subscription quota wall: the cycle ran far enough
to hit the quota ceiling, then a phase failed with empty stderr (the
quota-likely signature). `subagent-run.sh` wrote a checkpoint and
`cycle-state.json` carries the wake-at timestamp.

**Auto-resume is always on.** When you (the model) see `DISPATCH_RC=5` /
`QUOTA-PAUSE:` in dispatcher output, do this:

1. **Parse** the `wake-at=ISO8601` value from the marker line.
2. **Compute delay**: `delaySeconds = max(60, min(3600, wake_at_epoch - now_epoch + 60))`.
   - Floor at 60s so a near-zero remaining window doesn't busy-loop.
   - Cap at 3600s because `ScheduleWakeup` clamps to [60, 3600]; if the
     window is longer, call ScheduleWakeup again on the next wake.
3. **Call `ScheduleWakeup`** with that delay and `prompt="/evo:loop --resume"`.
   Provide a `reason` like `"waiting for quota reset at <wake-at>"`.
4. On each wake, if `now < wake_at`, repeat steps 2–3 (chained wake-ups).
5. When `now >= wake_at`, the prompt fires `/evo:loop --resume` which
   in turn invokes the native `evolve loop --resume` path → it bumps the
   `autoResumeAttempts` counter and re-runs the paused cycle from its
   last clean phase boundary.
6. The `autoResumeAttempts` cap (default 3, see `attempts=K/M` in the
   marker) prevents infinite quota-resume-quota loops; once exhausted,
   `evolve loop --resume` exits rc=2 and leaves the marker for operator
   intervention.

**Operator interrupt window.** The QUOTA-PAUSE marker line includes the
exact `wake-at=ISO8601` timestamp so the operator can Ctrl+C any pending
ScheduleWakeup before it fires. There is no flag-based opt-out — the loud
log is the intervention surface.

**Fallback if `ScheduleWakeup` is unavailable.** If you cannot call
`ScheduleWakeup` (e.g., the tool isn't loaded in this session's surface),
log the QUOTA-PAUSE marker verbatim so the operator can resume manually:
`evolve loop --resume`. Never silently swallow the DISPATCH_RC=5 signal.

See `docs/architecture/auto-resume.md` for the full architectural
contract and env-var reference.

## Architecture

```
Phase 0:   CALIBRATE ─ benchmark (once per invocation) → phase0-calibrate.md
Phase 0b: INTENT ─── [Intent] structure user goal     → docs/architecture/intent-phase.md
                     (always-on for /evo:loop slash command path; v8.19.1+)
Phase 1: RESEARCH ── proactive research loop          → online-researcher.md
Utility:   SEARCH ─── intent-aware web search engine    → smart-web-search.md
Phase 2:   DISCOVER ── [Scout] scan + task selection    → phases.md
Phase 2b: TRIAGE ─── [Triage] top_n scope decision    → agents/evolve-triage.md
                     (v8.56.0+ Layer C, default-on v8.59+; opt-out via workflow.phase_enables.triage=off)
Phase 3:   BUILD ───── [Builder] implement (worktree)   → phase3-build.md
Phase 4:   AUDIT ───── [Auditor] review + eval gate     → phases.md
Phase 5:   SHIP ────── publish via `evolve release` (or `evolve ship` for non-release commits) → phase5-ship.md
Phase 6:   LEARN ───── instinct extraction + feedback   → phase6-learn.md
Phase 7:   META ────── self-improvement (every 5 cycles) → phase7-meta.md
```

## Orchestrator Loop

For each cycle:
1. Claim cycle number (OCC protocol)
2. **Phase transitions (ORDER) are enforced by the in-process Go orchestrator's state machine** (`go/internal/core`). `evolve guard phase` (PreToolUse hook in `.claude/settings.json`) is a complementary backstop that denies the in-process `Agent`/`Task` dispatch tool during a cycle — currently a wired no-op pending the ADR-0074 rewire to the `Agent|Task` matcher. Operators do not invoke a separate phase-gate command; the state machine enforces order automatically.
3. Intent (v8.19.1+, always for /evo:loop) → Scout → Builder → Auditor → phase-gate verification → Ship → Learn
4. **Subagents are dispatched by the Go orchestrator** (`go/internal/core/orchestrator.go`) via the `bridge` adapter, which spawns the configured CLI (`claude -p`, `gemini`, or the agy/codex adapter) and feeds the per-phase agent prompt from `agents/<name>.md`. The kernel still enforces per-agent CLI permission profiles in `.evolve/profiles/` and writes tamper-evident ledger entries. The `evolve subagent run <agent> <cycle> <workspace>` CLI is available for manual single-phase dispatch (used by `evolve serve-phase` and the cross-CLI consensus harness). The bash `subagent-run.sh` path was removed in v12.0.0.
5. Max 3 retries per task; WARN/FAIL blocks shipping
6. Output Discovery Briefing → continue immediately
7. **Never stop to ask. Never skip agents. Never fabricate cycles. Complete ALL requested cycles.**

### Declarative cycle driver (v11.5.0+: native Go)

Instead of running the loop from inside this skill's prompt, the native binary's `evolve cycle run` subcommand drives a single cycle end-to-end:

1. Picks the next cycle number (or accepts `--cycle N`).
2. Initializes `.evolve/cycle-state.json` with `phase=calibrate`.
3. Spawns the orchestrator subagent (via the Go subagent runner under `.evolve/profiles/orchestrator.json`; Edit/Write/git ops still blocked at the kernel hook layer — hooks are unchanged).
4. Clears cycle-state on exit.

The orchestrator subagent (`agents/evolve-orchestrator.md`) advances phases via the native state machine, which is the authoritative phase-ORDER enforcer; the `evolve guard phase` PreToolUse hook reads cycle-state to deny the in-process `Agent`/`Task` dispatch tool during a live cycle (pending the ADR-0074 rewire; currently wired under `Bash` only, so inert).

Use `evolve loop` (multi-cycle batch) or `evolve cycle run` (single cycle) for autonomous runs.

## Agents

| Role | File | Tier | Output |
|------|------|------|--------|
| Scout | `agents/evolve-scout.md` | tier-2 | `scout-report.md` |
| Builder | `agents/evolve-builder.md` | tier-2 | `build-report.md` |
| Auditor | `agents/evolve-auditor.md` | tier-2 | `audit-report.md` |

## Model Routing

| Phase | Default | Upgrade → | Downgrade → |
|-------|---------|-----------|-------------|
| Scout | tier-2 | Cycle 1 / goal → tier-1 | Cycle 4+ → tier-3 |
| Builder | tier-2 | M+5 files / retry ≥ 2 → tier-1 | S + cache → tier-3 |
| Auditor | tier-2 | Security → tier-1 | Clean → tier-3 |