loop

---
name: loop
description: Use when the user 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.30

> 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 through `/evo:loop` or asks to run improvement cycles.

## Platform overlay (v8.15.0+)

Tool and command names in this file use **Claude Code conventions** (for example, `Read`, `Bash`, `Skill` and `Agent`). If you run this skill from a different CLI (Gemini, Codex or a generic CLI), 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 and `reference/<platform>-runtime.md` for invocation patterns. As of v12.0.0, the runtime is the Go binary (`go/bin/evolve`). `evolve subagent run` and the `evolve serve-phase <name>` phaseproto wire do the cross-CLI subagent execution. See [docs/architecture/platform-compatibility.md](../../docs/architecture/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 `evolve ship` commits only what passes. The Go state machine (`go/internal/core`) enforces the phase order for every CLI. The OS sandbox, the worktree fence and the ship gates hold the write rules (the protected write rule denies only at `isolation.i7.stage` `enforce`).
>
> The `evolve guard` hooks (`ship`, `phase`, `role`, `docdelete`) are defence in depth in Claude Code panes only. The shell hooks (`phase-gate-precondition.sh`, `role-gate.sh`, `ship-gate.sh`) were removed. Failures become structured lessons through the Retrospective agent; the loop gets smarter with each pass.

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

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

```bash
"$(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 `"$(find ...)"` expression is **one** shell argument from bash's perspective.

**Quote `<args>` correctly.** When `<args>` contains an apostrophe (for example, `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>`.

- A goal is missing when `<args>` has no positional goal text, no `--goal-text` and no `--goal-hash`.
- A `--resume` or `--dry-run` invocation needs no goal.
- When the goal is missing, you MUST ask the user for a one-line goal (with AskUserQuestion or a direct prompt). WAIT for their answer BEFORE dispatching.
- **Never dispatch a goal-less `evolve loop`.** The binary rejects it with `rc=10` (`a goal is required …`). This 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:** when you omit `--cycles`, the advisor decides how many cycles the goal needs. The run is completion-driven: it stops when the backlog drains, within 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 it with `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 do these things when you activate this skill.** The tool names below are Claude Code conventions. For your CLI's equivalents, consult `reference/<platform>-tools.md`. 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 for any task other than the dispatcher itself (and reading its output). On Gemini, the same applies to `replace`/`write_file`/`run_shell_command`; other CLIs have equivalent tools.
- 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, held there by the sandbox, the fence and `evolve guard role`. 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. Thus Scout and Builder were skipped, or they ran through the in-process Agent tool that bypasses the kernel guards. The dispatcher closes that gap structurally.

Every cycle goes through `evolve cycle run`, or `evolve loop` for batches. The Go orchestrator (`go/internal/core`) then dispatches Scout, Builder and Auditor through the native bridge, and its state machine enforces the sequence. The bash `subagent-run.sh` path and the shell hooks were removed in v12.0.0.

**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 (for example, 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, re-verified 2026-10-25)**: four PreToolUse hooks in `.claude/settings.json` run the native Go guards.
>
> - `evolve guard ship` (matcher `Bash`) lets only `evolve ship` commit, push or release.
> - `evolve guard phase` (matcher `Agent|Task`) acts outside a phase cell during a cycle. It denies an `Agent` or `Task` call that names a phase persona (`evolve-*`), so phase agents go through the native bridge. Inside a cell each subagent of the own harness passes (component X7 of [ADR-0154](../../docs/architecture/adr/0154-the-pipeline-is-the-only-controller-and-each-agent-is-an-isolated-replaceable-worker.md)).
> - `evolve guard role` (matcher `Edit|Write`) holds each edit to the path allowlist of the active phase.
> - `evolve guard docdelete` (matcher `Bash`) blocks a delete under `docs/` without an archive move.
>
> The hooks fire only in Claude Code panes, so they are defence in depth. The OS sandbox write rules, the worktree fence and the ship gates hold each guarantee for every family ([llm-isolation.md §9.1](../../docs/architecture/llm-isolation.md#91-as-built-x7)). The protected write rule of the sandbox denies only at `isolation.i7.stage` `enforce`; at the default `shadow` it only reports. The Go state machine (`go/internal/core`) enforces the phase order for every CLI. For automated cycles, use `evolve cycle run [--goal-text GOAL]` (or `evolve loop` for batches).

> **v8.13.2 / v12.0.0**: the release pipeline heals itself. For a version-bump release, use `evolve release <version>` (native Go). The pipeline runs the pre-flight gates and writes a CHANGELOG entry from conventional commits. It ships atomically through `evolve ship`, polls the marketplace for up to 5 minutes, and rolls back automatically when a step after the push fails. Use `--dry-run` to simulate without changes. See [docs/guides/publishing-releases.md](../../docs/guides/publishing-releases.md) for the vocabulary (push ≠ tag ≠ release ≠ publish ≠ propagate).

## Code carries no comments (system policy)

Every phase that writes code writes no comments. The code explains itself through names, types, small functions and test names. A design reason goes to the package's notes under `docs/architecture/packages/`. Only the comments a tool reads survive; [the code-comments convention](../../docs/conventions/code-comments.md) lists them.

The build handoff floor counts the comments a build adds (`comment_floor` in `.evolve/policy.json`). At `shadow`, the default, it WARNs. At `enforce`, it sends the build back for correction before its audit. The auditor reports any comment that reaches it, and the commit gate refuses a console commit that adds one.

## 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 |

## Waves at a boundary: `evolve wave` (2026-10-08)

Use `evolve wave` to run and watch the next wave. Do not write a goal script, and do not edit the last goal by hand.

- `evolve wave note add "<text>"`: queue a fact for the next goal. `wave next` puts the notes in the goal and then removes them.
- `<plane>/go/bin/evolve wave next [--merge n,...] [--max-cycles N] [--dry-run] [--json]`: run the boundary and launch the wave. Use the plane binary, so that the build, the pin and the loop are one binary. With `--json`, every exit prints one envelope `evolve.wave.next/2` (cli-contract.md §2): `error` gives the exit code and its kind, and `data.refused`, `data.failed_step` and `data.error` say what went wrong. The goal has the standing goal (`.evolve/wave-goal.md`) and the facts of the last wave from cycle state. It also has the notes and the last wave summaries (policy key `wave.history_k`). Run `--dry-run` first to see the goal and the steps.
- `evolve wave status --json`: read the current wave, the loop pid and each cycle's phase, verdict and ship state from `data`. It is read-only.
- `evolve wave watch`: get one line for each phase change, seal, ship and quota pause, until the loop exits. It reads state files, not the text log.

For one cycle in the foreground, use `evolve cycle run --goal-text "<goal>"`. To resume a paused cycle, use `evolve loop --resume`.

## 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 resume-in=Ss
QUOTA-PAUSE: cycle=N wake-at= source=unknown attempts=K/0 auto-resume=off: <operator action>
```

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 runs only when the marker has `resume-in=`.** A marker with
`auto-resume=off` has no known reset time or no resume budget left: do not
schedule a wake-up. Report the operator action that the marker gives, and stop.
When you (the model) see `DISPATCH_RC=5` / `QUOTA-PAUSE:` with `resume-in=`,
do this:

1. **Parse** the `wake-at=ISO8601` value from the marker line.
2. **Use the delay** in `resume-in=Ss`. The loop computes it as
   `max(60, min(3600, wake_at_epoch - now_epoch + 60))` (`quotaPause.resumeDelay`).
   - The 60 s floor stops a near-zero remaining window from a busy loop.
   - The 3600 s cap matches the clamp of `ScheduleWakeup` 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 --auto-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 --auto-resume`. It runs
   `evolve loop --auto-resume`. This command increments the
   `autoResumeAttempts` counter and runs the paused cycle again from its
   last clean phase boundary.
6. The `autoResumeAttempts` cap (default 3, see `attempts=K/M` in the
   marker) stops a quota-resume-quota loop. At the cap,
   `evolve loop --auto-resume` does not run the cycle. It records the operator
   action in the checkpoint, prints the marker with `auto-resume=off: <action>`
   and exits rc=2. An operator resume (`evolve loop --resume`) sets the
   counter to 0.

**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` (for example, the tool isn't loaded in this session's surface),
log the QUOTA-PAUSE marker verbatim. Then 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. **The in-process Go orchestrator's state machine enforces the phase transitions (ORDER)** (`go/internal/core`). `evolve guard phase` is a backstop (a PreToolUse hook in `.claude/settings.json`, matcher `Agent|Task`). It acts outside a phase cell, during a cycle. It denies an `Agent` or `Task` call that names a phase persona (ADR-0154 X7). 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. **The Go orchestrator dispatches subagents** (`go/internal/core/orchestrator.go`) through the `bridge` adapter.
   - The adapter spawns the CLI that `cli_routing` names (claude, agy, codex or ollama; `gemini` has no driver). It feeds the per-phase agent prompt from `agents/<name>.md`. The kernel still enforces per-agent CLI permission profiles in `.evolve/profiles/`. It also writes tamper-evident ledger entries.
   - The `evolve subagent run <agent> <cycle> <workspace>` CLI is available for manual single-phase dispatch. `evolve serve-phase` and the cross-CLI consensus harness use it. 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 (through the Go subagent runner under `.evolve/profiles/orchestrator.json`). Edit/Write/git ops are still blocked at the kernel hook layer; the hooks are unchanged.
4. Clears cycle-state on exit.

The orchestrator subagent (`agents/evolve-orchestrator.md`) advances phases through the native state machine, which is the authoritative phase-ORDER enforcer. The `evolve guard phase` PreToolUse hook (matcher `Agent|Task`) reads cycle-state. Outside a phase cell, during a live cycle, it denies an `Agent` or `Task` call that names a phase persona. Inside a cell it allows each call (ADR-0154 X7).

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

## Agents

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

## Model Routing

Each profile in `.evolve/profiles/` names a default tier and an envelope on the ladder `fast`, `balanced`, `deep` and `top`. The advisor can move a phase inside its envelope (`router.dynamic_routing` in `.evolve/policy.json` is `advisory` by default).

| Phase | Default | Envelope |
|-------|---------|----------|
| Scout | `balanced` | `balanced` to `deep` |
| Builder | `balanced` | `balanced` to `deep` |
| Auditor | `deep` | `deep` only |

The `cli_routing` table in `.evolve/policy.json` decides which CLI runs each phase. `evolve cli-routing explain <agent>` prints the chain of an agent. See [model-routing.md](../../docs/reference/model-routing.md).

• SKILL.md 25 KB
• benchmark-eval.md 21 KB
• eval-runner.md 11 KB
• lesson-template.yaml 1 KB
• memory-protocol.md 3 KB
• online-researcher.md 18 KB
• phase0-calibrate.md 3 KB
• phase1-research.md 6 KB
• phase2-discover.md 9 KB
• phase3-build.md 14 KB
• phase5-ship.md 6 KB
• phase6-learn.md 26 KB
• phase7-meta.md 7 KB
• phases.md 15 KB
• smart-web-search.md 5 KB
• reference/agy-runtime.md 10 KB
• reference/agy-tools.md 3 KB
• reference/claude-runtime.md 5 KB
• reference/claude-tools.md 2 KB
• reference/codex-runtime.md 4 KB
• reference/codex-tools.md 2 KB
• reference/gemini-runtime.md 6 KB
• reference/gemini-tools.md 3 KB
• reference/generic-runtime.md 4 KB
• reference/initialization.md 2 KB
• reference/output-contracts.md 4 KB
• reference/phases-detail.md 9 KB
• reference/platform-detect.md 3 KB
• reference/policies.md 9 KB
• reference/safety.md 3 KB
• reference/search-integration.md 10 KB
• reference/search-stages.md 16 KB
• reference/skill-routing.md 8 KB
• reference/task-selection.md 1 KB