Skip to content

Your first run, stage by stage

This page follows one mini-ork run from the command line to a verdict and explains what each stage produced. The example is the shipped examples/01-hello-world kickoff: add a changelog entry, touch nothing else.

The command

mini-ork run code-fix examples/01-hello-world/kickoff.md

run is the recipe runner. It resolves the recipe (code-fix here, or by classification if you omit it), then walks the lifecycle:

flowchart LR
    K[kickoff.md] --> C[classify]
    C --> P[plan]
    P --> E[execute]
    E --> V[verify]
    V -- pass --> D[verdict]
    V -- fail --> E

Each stage prints a bracketed block so the run is legible in a terminal or a log. A run also writes its state into .mini-ork/runs/<run-id>/.

What each stage does

classify

[classify]  task_class=code_fix  risk=medium  confidence=0.96

The classifier matches the kickoff text against every seeded task_class.yaml and picks the best-scoring one above its threshold. The task class binds the recipe, which supplies the workflow and artifact contract.

If classification is wrong, force a recipe explicitly:

mini-ork run framework-edit ./kickoff.md

plan

[plan]      model=claude-sonnet-4-5
[plan]      objective: Add session-token-rotation entry to CHANGELOG.md
[plan]      steps: 1  estimated_lines_changed: 5
[plan]      success_check: grep -A3 "## [Unreleased]" CHANGELOG.md returns ≥1 bullet

The planner decomposes the objective into nodes and states the success check it will hand to verification. A plan that fails schema validation is repaired and retried rather than silently accepted.

execute

[implement] step 1/1: edit CHANGELOG.md — insert entry under [Unreleased]
[implement] files_changed: CHANGELOG.md
[implement] confidence=0.95

The implementer runs in the workspace mini-ork chooses: a fresh worktree by default when the review policy requires approval before merge, otherwise in-place. See Running work in worktrees.

Each node is routed to a lane by role. The lane, model and transport are recorded with the node result, so a later review can see which model produced which artifact.

verify

[verify]    gates: 4/4 passed

Verification is not a model reading a diff. Gates execute: the declared success check, the repository's test command, schema validation, and the non-regression checks the recipe declares. A judge may veto a pass, but it cannot turn a failed command into a pass. The full model is in Verification and gates.

verdict

[verdict]   PROVEN
Verdict What it means
PROVEN Every required gate ran and passed
REFUTED At least one required gate ran and failed
UNVERIFIED No gate produced a trustworthy signal
VACUOUS The checks that ran had no discriminating power

A PROVEN verdict is a claim about this run's evidence, not a proof of correctness in all cases. Read Results and benchmarks for what the oracle does and does not cover.

Where the run lives

.mini-ork/runs/<run-id>/
  plan.json              the decomposed plan
  nodes/<node-id>/       prompt, output, logs, artifacts
  verifier-*.log         every gate's raw output
  run-verdict.json       the final verdict and reasons

The database mirrors the important parts:

sqlite3 .mini-ork/state.db \
  'SELECT id, recipe, status, verdict, created_at FROM task_runs ORDER BY created_at DESC LIMIT 3;'

Inspecting from the CLI

mini-ork board                       # project state
mini-ork board show <run-id>         # one run, all tabs
mini-ork board node <run-id> <node>  # one node's output
mini-ork verifier list               # recent gate results

board is what the web app and IDE read. Every verb and view is documented in Inspecting state.

Resuming an interrupted run

If a run stops — a provider timeout, a crashed node, a cost pause — resume it instead of starting over:

mini-ork run --resume <run-id>

Resume semantics:

  • nodes that succeeded are skipped, with their persisted outputs intact;
  • failed, errored or never-ran nodes are re-dispatched;
  • before executing anything, one [mini-ork-resume] line states the skip and dispatch sets;
  • an unknown run id is a hard error — there is no silent fresh start.

Rewind to an earlier point with --checkpoint-id <id>. Checkpoints and their restore path are covered in Recovery.

Common first-run problems

Symptom Likely cause Fix
no provider lane / auth error A lane in agents.yaml has no credential mini-ork providers status, then providers configure
Classification picks the wrong recipe Kickoff lacks scope or acceptance detail Force the recipe; tighten the kickoff
Plan fails schema validation repeatedly Kickoff is too large or contradictory Split it; state one outcome
Verify fails with a test error The repository's own tests are red before the change Fix the baseline first; a run cannot prove against a broken base
Run pauses and prints a cost notice A budget or daily cap tripped Raise the cap or wait for the daily reset
home DB last migrated by vX The engine and the project's state disagree Run mini-ork update from the intended engine

Next