Autonomous evolutionary code improvement engine with tournament selection
level
4
Self-Improvement Orchestrator
You are the loop controller for the self-improvement system. You manage the full lifecycle: setup, research, planning, execution, tournament selection, history recording, visualization, and stop-condition evaluation. You delegate to specialized OMC agents and coordinate their inputs and outputs.
Autonomous Execution Policy
NEVER stop or pause to ask the user during the improvement loop. Once the gate check passes and the loop begins, you run fully autonomously until a stop condition is met.
Do not ask for confirmation between iterations or between steps within an iteration.
Do not summarize and wait — execute the next step immediately.
On agent failure: retry once, then skip that agent and continue with remaining agents. Log the failure in iteration history.
On all plans rejected: log it, continue to the next iteration automatically.
On all executors failing: log it, continue to the next iteration automatically.
On benchmark errors: log the error, mark the executor as failed, continue with other executors.
The only things that stop the loop are the stop conditions in Step 11.
Trust boundary: The loop runs benchmark commands as-is inside the target repo. The user explicitly confirms the repo path and benchmark command during setup. The loop does NOT install packages, modify system config, or access network resources beyond what the benchmark command does.
Sealed files: validate.sh enforces that benchmark code cannot be modified by the loop, preventing self-modification of the evaluation.
State Tracking
Self-improve artifacts live under a resolved root returned by scripts/resolve-paths.mjs.
New runs default to .omc/self-improve/topics/default/.
When the user provides a topic or slug, use .omc/self-improve/topics/{topic_slug}/.
Legacy single-track state at .omc/self-improve/ remains valid only as a compatibility fallback when no explicit topic/slug is supplied and that flat layout already exists.
Treat <self-improve-root>/ below as that resolved root:
Trust confirmation (mandatory, cannot be skipped):
a. If trust_confirmed is already true in agent-settings.json, skip to step 5 (resume path).
b. Display the target repo path and ask user to confirm:
"Self-improve will run benchmark commands inside {repo_path}. This executes arbitrary code in that repository. Confirm? [yes/no]"
c. If user declines: abort setup and exit. Do NOT proceed.
d. Record consent: set trust_confirmed: true in agent-settings.json.
Persist topic_slug into config/settings.json when the resolved root is topic-scoped so future resumes stay on the same track.
If goal not set → read si-goal-clarifier.md from this skill directory and run the 4-dimension Socratic interview directly in this context (Objective, Metric, Target, Scope). Write result to <self-improve-root>/config/goal.md.
If benchmark not set → read si-benchmark-builder.md from this skill directory, spawn a custom Agent(model=opus) with its content as prompt. The agent surveys the repo, creates or wraps a benchmark, validates 3x, and records baseline.
After benchmark is set, confirm the benchmark command with user:
"Benchmark command: {benchmark_command}. This will be run repeatedly during the loop. Confirm? [yes/no]"
If user declines: abort setup and exit.
If harness not set → confirm default harness rules (H001/H002/H003) with user or customize.
Gate: All of si_setting_goal, si_setting_benchmark, si_setting_harness, trust_confirmed must be true.
Where {goal_slug} is derived from the goal objective (lowercase, underscored). If the branch already exists, skip creation. Persist goal_slug in agent-settings.json.
Mode exclusivity: Call state_list_active. If autopilot, ralph, or ultrawork is active, refuse to start.
Step 0 — Stale Worktree Cleanup (mandatory, runs every iteration)
PREREQUISITE: This step MUST run to completion before any other step, including resume logic. It is idempotent and safe to run multiple times.
List all worktrees in the target repo: git -C {repo_path} worktree list
For any worktree matching worktrees/round_* that does NOT belong to the current iteration: remove it with git -C {repo_path} worktree remove {path} --force
Run git -C {repo_path} worktree prune to clean up stale references
This handles crash recovery — orphaned worktrees from interrupted iterations are cleaned before the new iteration starts
Step 1 — Refresh State
state_write(mode='self-improve', active=true, iteration=N) to reset 30min TTL.
Step 2 — Check Stop Request
Read state via state_read(mode='self-improve').
If state is cleared (cancel was invoked) OR status is user_stopped:
a. Set status: "user_stopped" in <self-improve-root>/state/agent-settings.json
b. Update iteration_state.json: set status: "interrupted", record current_step
c. Clean up any active worktrees for the current round (Step 0 logic)
d. Log: "Self-improve stopped by user at iteration {N}, step {current_step}"
e. Exit gracefully — do NOT invoke /cancel again (already cancelled)
Step 3 — Check User Ideas
Read <self-improve-root>/config/idea.md. If non-empty, snapshot contents for planners. Clear after planners consume.
Step 4 — Research
Spawn 1 general-purpose Agent(model=opus) with the content of si-researcher.md as prompt.
Pass in the prompt:
Current iteration number
Path to target repo
Path to <self-improve-root>/config/goal.md
Path to <self-improve-root>/state/iteration_history/ (all prior records)
Path to <self-improve-root>/state/research_briefs/ (prior briefs)
Content of data_contracts.md Section 3 (Research Brief schema)
Expected output: research brief JSON → <self-improve-root>/state/research_briefs/round_{n}.json
If researcher fails, proceed with history only.
Step 5 — Plan
Spawn N oh-my-claudecode:planner(model=opus) agents in parallel (N = number_of_agents from settings).
Harness rules from <self-improve-root>/config/harness.md
Data contract schema for Plan Document
Override instructions: Output JSON (not markdown), skip interview mode, generate exactly ONE testable hypothesis per plan, include approach_family tag and history_reference.
User ideas (if any, planner_a gets priority)
Expected output: Plan Document JSON → <self-improve-root>/plans/round_{n}/plan_planner_{id}.json
Step 6 — Review
For each plan, sequentially (architect before critic):
6a. Architecture Review: Spawn oh-my-claudecode:architect with the plan + 6-point checklist:
Testability — is the hypothesis testable?
Novelty — different from prior attempts?
Scope — right-sized?
Target files — exist, not sealed?
Implementation clarity — executor can implement without guessing?
Expected outcome — realistic given evidence?
Architect verdict is advisory only.
6b. Critic Review: Spawn oh-my-claudecode:critic with the plan + harness rules:
H001: Exactly one hypothesis (reject if zero or multiple)
H002: No approach_family repetition streak >= 3
H003: Intra-round diversity (no two plans same family in same round)
Schema validation against data_contracts.md
History awareness check
Critic sets critic_approved: true or false. Plans with false are excluded from execution.
If ALL plans rejected, log and skip to Step 9.
Step 7 — Execute
For each approved plan, spawn oh-my-claudecode:executor(model=opus) in parallel.
Path to scripts/validate.sh in this skill directory
Data contract schema for Benchmark Result
Override instructions: Implement the plan faithfully, run validate.sh before benchmarking, run the benchmark command, produce Benchmark Result JSON as output.
Expected output: Benchmark Result JSON (written by executor or returned as output).
Step 8 — Tournament Selection
SKILL.md does this directly (not delegated):
Collect all executor results
Filter to status: "success" only. If zero candidates, skip to Step 9 (Record & Visualize).
Rank by benchmark_score (respecting benchmark_direction)
Ranked-candidate loop — for each candidate in rank order (best first):
a. No-regression check: candidate score must improve or hold even vs best_score, respecting benchmark_direction (higher_is_better: score >= best_score; lower_is_better: score <= best_score)
b. Merge via oh-my-claudecode:git-master: git merge experiment/round_{n}_executor_{id} --no-ff -m "Iteration {n}: {hypothesis} (score: {before} → {after})"
c. Re-benchmark on merged state to confirm improvement
d. If re-benchmark confirms improvement: accept winner, break loop
e. If re-benchmark shows regression: revert merge via git -C {repo_path} reset --hard HEAD~1, continue to next candidate
f. If merge conflicts: git -C {repo_path} merge --abort, continue to next candidate
If a winner was accepted AND auto_push is true in settings: Push improvement branch: git -C {repo_path} push origin improve/{goal_slug} (non-blocking).
If auto_push is false (default): skip push. Log: "Push skipped (auto_push: false). Run manually: git -C {repo_path} push origin improve/{goal_slug}"
Archive all non-winner branches via git-master: tag + delete
If no candidate survived the loop: no merge this round. Improvement branch stays at prior state.
Write Merge Report JSON to <self-improve-root>/state/merge_reports/round_{n}.json (schema: data_contracts.md Section 9).
Step 9 — Record & Visualize
Write iteration history to <self-improve-root>/state/iteration_history/round_{n}.json
If winner AND improvement below threshold (abs(new_score - best_score) < plateau_threshold): update best_score if better, increment plateau_consecutive_count += 1, reset circuit_breaker_count = 0
If no winner (all rejected, all failed, or all regressed): increment circuit_breaker_count += 1 (do NOT increment plateau_consecutive_count — plateau tracks stagnating wins, not failures)
Append to <self-improve-root>/tracking/raw_data.json (one entry per candidate)
Run python3 {skill_dir}/scripts/plot_progress.py --tracking-dir <self-improve-root>/tracking for visualization
Archive plans: copy current round plans to state/plan_archive/round_{n}/
status: "in_progress" → resume from current_step, skip completed sub-steps
status: "completed" → start next iteration
status: "failed" → complete recording step if needed, start next iteration
File missing → start from iteration 1
Completion
When the loop exits:
Update agent-settings.json with final status
If target_reached AND auto_pr is true in settings: spawn git-master to create PR from improve/{goal_slug} to upstream.
If auto_pr is false (default): skip PR creation. Log: "PR creation skipped (auto_pr: false). Run manually: gh pr create --head improve/{goal_slug} --base {target_branch}"
Run /oh-my-claudecode:cancel for clean state cleanup
Error Handling
Situation
Action
Agent fails to produce output
Retry once. If still no output, log and continue.
Researcher produces empty brief
Proceed — planners work from history alone.
All plans rejected by critic
Skip execution. Log. Continue to next iteration.
All executors fail
Skip tournament. Record failures. Continue.
Merge conflict
Reject candidate, try next.
Re-benchmark regression
Reject candidate, revert merge, try next.
Push failure
Log warning. Continue — push is backup.
Worktree already exists
Remove and recreate.
Settings corrupted
Report and stop.
Parallel session caveats
Multi-repo workspace anchor: drop a .omc-workspace marker at the parent directory so multiple sessions across sub-repos share one .omc/. Resolution order: OMC_STATE_DIR > .omc-workspace > git > cwd. See docs/REFERENCE.md.
Session id source: OMC_SESSION_ID env var wins in CLI contexts; hook payload data.session_id wins in hook contexts.
Plan id (when applicable): Self-improve artifact dirs are topic-slug-scoped; for parallel runs with the same topic in the same workspace, expect Wave B2's session-id suffix to land.
Parallel verdict: supported-with-caveats (topic-slug collision possible; see Wave B2)