Skip to content

mini-ork self-improve

Recursive self-improvement of this checkout. Each iteration runs in its own worktree and branch; a change is committed only after its verifiers pass. The loop is gated and off unless you invoke it deliberately.

Usage

mini-ork self-improve [flags]

Options

Flag Default Meaning
--soft-cap-hours <H> 3 Finish the current iteration when the cap is reached, then stop
--hard-cap-hours <H> 5 Kill mid-iteration and exit
--max-iters <N> unbounded Additional bound on iteration count
--auto-merge off Merge successful iterations into the parent branch
--parent-branch <ref> resolved base ref Branch to merge into
--dry-run off Plan and scan, then exit before any model dispatch
--resume off Continue an interrupted session, reading MINI_ORK_DB for the last iteration

Soft and hard caps are independent of --max-iters; whichever trips first ends the session. --dry-run is the safe first call: it shows what the loop would work on without spending anything.

Preconditions

  • A clean checkout. The loop creates worktrees and branches; uncommitted work in the parent is not swept into an iteration.
  • A working verifier path. A candidate that cannot be verified is not committed, so an unverifiable checkout produces no improvement.
  • Credentials for the lanes the iteration dispatches.

This loop modifies its own prompts and workflows

self-improve can rewrite the engine's prompt files and workflow definitions. It ships off, and it never commits without passing verifiers — but a passing verifier is still a bounded guarantee. Read the safety note in The self-improvement loop before enabling unattended runs.

How an iteration runs

flowchart LR
    S[scan] --> W[worktree + branch]
    W --> I[implement]
    I --> V{verifiers}
    V -- pass --> C[commit]
    V -- fail --> R[discard, record reason]
    C -. --auto-merge .-> P[parent branch]

Each iteration leaves its evidence in the worktree and in the run database, so a later session can reconstruct why a change was attempted and what stopped it.

lessons is the operator view of learned rules — the patterns reflection has produced, whether they are approved, and whether they reach agent prompts.

mini-ork lessons list [--json] [--home <dir>]
mini-ork lessons forget <id>
mini-ork lessons restore <id>
mini-ork lessons promote <id>
Action Effect
list Show approved and proposed learned rules
forget <id> Stop giving this lesson to agents
restore <id> Return a forgotten lesson to the agents
promote <id> Approve a proposed lesson that has an authored lesson text

promote refuses a row with no authored text — promoting a frequency count would inject noise, not guidance — and refuses a row that is not proposed. The action is defined in mini_ork/cli/lessons_cmd.py; --help may lag the source, so promote is documented here rather than in the usage line.

Static evaluation of recipe definitions, without dispatching a run:

mini-ork recipe-eval [recipe-name] [--json]

Use it after editing a workflow.yaml or artifact_contract.yaml to catch structural errors before spending a real run on them. See Maintenance.

Examples

# See what would happen, spend nothing
mini-ork self-improve --dry-run

# One bounded session, no merging
mini-ork self-improve --max-iters 2 --soft-cap-hours 1

# Continue where a session stopped
mini-ork self-improve --resume --soft-cap-hours 2