evolve

$evolve — Goal-Driven Compounding Loop

Measure what's wrong. Fix the worst thing. Measure again. Compound.

Codex orchestration default: keep the skill name $evolve. In Codex, run the loop by chaining Codex skills: $evolve selects work and invokes complete $rpi --auto cycles. Treat ao evolve and ao rpi as terminal wrapper commands for humans or non-skill runtimes, not as the Codex skill default.

Operator cadence: post-mortem finished work, analyze the current repo state, select or create the next highest-value work item, let $rpi handle research, planning, pre-mortem, implementation, and validation, then harvest follow-ups and repeat until a kill switch, max-cycle cap, regression breaker, or real dormancy stops the run.

Always-on autonomous loop over $rpi. Work selection order:

1. Harvested .agents/rpi/next-work.jsonl work (freshest concrete follow-up)
2. Open ready beads work (bd ready)
3. Failing goals and directive gaps (ao goals measure)
4. Testing improvements (missing/thin coverage, missing regression tests)
5. Validation tightening and bug-hunt passes (gates, audits, bug sweeps)
6. Complexity / TODO / FIXME / drift / dead code / stale docs / stale research mining
7. Concrete feature suggestions derived from repo purpose when no sharper work exists

Dormancy is last resort. Empty current queues mean "run the generator layers", not "stop". Only go dormant after the queue layers and generator layers come up empty across multiple consecutive passes.

$evolve                      # Run until kill switch, max-cycles, or real dormancy
$evolve --max-cycles=5       # Cap at 5 cycles
$evolve --dry-run            # Show what would be worked on, don't execute
$evolve --beads-only         # Skip goals measurement, work beads backlog only
$evolve --quality            # Quality-first mode: prioritize post-mortem findings
$evolve --quality --max-cycles=10  # Quality mode with cycle cap
$evolve --compile             # Mine → Defrag warmup before first cycle
$evolve --compile --max-cycles=5  # Warm knowledge base then run 5 cycles
$evolve --test-first         # Default strict-quality $rpi execution path
$evolve --no-test-first      # Explicit opt-out from test-first mode

Delineation vs $dream

| Lane | Runs | Mutates code? | Mutates corpus? | Outer loop? | Budget | |------|------|---------------|-----------------|-------------|--------| | $dream | nightly, private local | No | Yes (heavy) | Yes (convergence) | wall-clock + plateau | | $evolve | daytime, operator-driven | Yes (via $rpi) | Yes (light) | Yes | cycle cap |

Dream owns the knowledge compounding layer; $evolve owns the code compounding layer. Both share fitness-measurement substrate via corpus.Compute / ao goals measure. Run Dream overnight, then start each day with $evolve against the freshly-compounded corpus with a clean fitness baseline.

Flags

| Flag | Default | Description | |------|---------|-------------| | --max-cycles=N | unlimited | Stop after N completed cycles | | --dry-run | off | Show planned cycle actions without executing | | --beads-only | off | Skip goal measurement and run backlog-only selection | | --skip-baseline | off | Skip first-run baseline snapshot | | --quality | off | Prioritize harvested post-mortem findings | | --compile | off | Run ao mine + ao defrag warmup before cycle 1 | | --test-first | on | Pass strict-quality defaults through to $rpi | | --no-test-first | off | Explicitly disable test-first passthrough to $rpi |

Execution Steps

YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.

FULLY AUTONOMOUS. Evolve runs without human intervention from start to teardown. Every $rpi invocation uses --auto. Do NOT ask the user for confirmation, clarification, or approval at any point. Do NOT pause between cycles. Do NOT summarize and wait. The user's only touchpoint is the teardown report at the very end.

Each cycle is a COMPLETE $rpi run — all 3 phases (discovery → implementation → validation). Never invoke a partial RPI. If a task is too large for one cycle, break it into smaller sub-tasks during discovery and let $crank handle the waves. Evolve's job is to keep the loop turning, not to micro-manage individual tasks.

For broad AgentOps 3.0 domain evolution across skills, CLI, hooks, docs, tests, beads, and knowledge, first read [references/domain-evolution-bootstrap.md](references/domain-evolution-bootstrap.md). It supplies the BDD/DDD/Hexagonal/TDD/XP control surface and the clean-room skill-factory guardrails.

Break large work into sub-RPI cycles. When work selection identifies a massive task (7+ issues, multi-subsystem scope), decompose it during $rpi's discovery phase into an epic with waves. One evolve cycle = one $rpi run = one complete lifecycle. If the epic is too large for a single session, $rpi's built-in retry and --from= resume handle continuation.

Anti-Patterns (DO NOT)

| Anti-Pattern | Why It's Wrong | Correct Behavior | |--------------|----------------|------------------| | Ask the user anything during execution | Evolve is fully autonomous — questions break the loop | Make best judgment, report in teardown | | Stop after one $rpi cycle and summarize | Evolve loops until kill switch, max-cycles, or dormancy | Increment cycle and re-enter Step 1 | | Run $rpi without --auto | Non-auto $rpi has human gates that halt the loop | Always pass --auto to $rpi | | Run partial $rpi (skip validation) | Each cycle must be a complete 3-phase lifecycle | Let $rpi run all 3 phases autonomously | | Pause between cycles to explain progress | The user wants results, not narration | Log cycle results, immediately start next cycle | | Treat "no queued work" as "stop" | Generator layers (testing, validation, drift, features) produce work | Run all generator layers before considering dormancy |

Step 0: Setup

mkdir -p .agents/evolve
ao corpus inject --query "autonomous improvement cycle" --limit 5 2>/dev/null || true

ao corpus inject routes through the typed BC1 CorpusReaderPort (cli/cmd/ao/corpus_reader_adapter.go, cycle 112 productionCorpusReader), emitting one ranked ports.CorpusItem JSON record per line from .agents/learnings/ by default. Closes soc-y5vh.1 — Step 0 prior-knowledge retrieval is load-bearing on the typed port, not an untyped ao lookup shell-out.

Apply retrieved knowledge: If learnings are returned, check each for applicability to the current improvement cycle. For applicable learnings, cite by filename and record: ao metrics cite "<path>" --type applied 2>/dev/null || true

Before cycle recovery, load the repo execution profile contract when it exists. The repo execution profile is the source for repo policy; the user prompt should mostly supply mission/objective, not restate startup reads, validation bundle, tracker wrapper rules, or definition_of_done.

• Locate docs/contracts/repo-execution-profile.md and docs/contracts/repo-execution-profile.schema.json.
• Read the ordered startup_reads and bootstrap from those repo paths before selecting work.
• Cache repo validation_commands, tracker_commands, and definition_of_done into session state.
• If the repo execution profile is present but missing required fields, stop or downgrade with an explicit warning before cycle 1. Do not silently invent repo policy.

Then load the repo-local autodev program contract when it exists. The execution profile remains the repo bootstrap and landing-policy layer; PROGRAM.md or AUTODEV.md is the repo-local execution layer for the current improvement loop.

• Locate PROGRAM.md and AUTODEV.md. PROGRAM.md takes precedence.
• Read the resolved program before cycle recovery and cache program_path, mutable_scope, immutable_scope, validation_commands, decision_policy, and stop_conditions into session state.
• If the