Lifecycle commands¶

The universal loop is exposed as eight commands. mini-ork run calls them in order; you can also call any stage yourself to inspect or retry it.

Stage	Command	Produces
1	`classify`	A task class for a kickoff
2	`plan`	`plan.json` with a verifier contract
3	`execute`	Node outputs and artifacts
4	`verify`	A JSON verdict from gates
5	`reflect`	Gradients, patterns, proposed lessons
6	`improve`	Workflow candidates
7	`eval`	A utility delta for a candidate
8	`promote`	A promotion decision

flowchart LR
    A[classify] --> B[plan] --> C[execute] --> D[verify]
    D --> E[reflect] --> F[improve] --> G[eval] --> H[promote]

classify¶

Match a kickoff against config/task_classes/*.yaml.

mini-ork classify <kickoff.md> [--workflow-version <ver>] [--dry-run]

Flag	Default	Meaning
`--workflow-version <ver>`	class default	Override the workflow version for this class
`--dry-run`	off	Print the classification; write nothing to the DB

Outputs task_class=<name> on stdout, and a runs row unless --dry-run.

plan¶

Generate a structured plan. The plan must include a verifier_contract with checks[]; a plan without one fails validation and is repaired rather than accepted.

mini-ork plan <kickoff.md> [--task-class <name>] [--out <plan.json>] [--dry-run]

Flag	Default	Meaning
`--task-class <name>`	`$MINI_ORK_TASK_CLASS`	Override the task class
`--out <path>`	`<run>/plan.json`	Write the plan elsewhere
`--dry-run`	off	Print the plan JSON; write no files or DB rows

execute¶

Dispatch plan steps to node handlers.

mini-ork execute [<plan.json>] [--node-type <type>] [--dispatch-mode <mode>] \
                 [--dry-run] [--from-node <id>] [--recovery] [--repair-budget <usd>]

Node types: planner, researcher, transform, implementer, reviewer, verifier, reflector, publisher, rollback.

Dispatch modes: serial, parallel, partitioned, speculative.

Flag	Default	Meaning
`--node-type <type>`	all	Execute only nodes of this type
`--dispatch-mode <mode>`	workflow setting	Override the workflow's dispatch mode
`--dry-run`	off	Print what would dispatch; no model calls
`--from-node <id>`	start	Enter the loop at this node (recovery)
`--recovery`	off	`--from-node` plus the closure filter; set by `mini-ork recover` and honours `MINI_ORK_RECOVERY_CLOSURE`
`--repair-budget <usd>`	`$5.00` (`MO_REPAIR_BUDGET_USD`)	Cost ceiling for a repair-strategy recovery

verify¶

Run the artifact's verifiers and gates against its contract.

mini-ork verify <artifact-path> [--plan <plan.json>] [--task-class <name>] [--dry-run]

Flag	Default	Meaning
`--plan <path>`	discovered	Plan carrying the artifact contract
`--task-class <name>`	plan's class	Override gate selection
`--dry-run`	off	List the verifiers; run none

Emits a JSON verdict on stdout. An empty set of meaningful checks is not a pass — it is reported as vacuous.

reflect¶

Run the reflection pipeline over recent execution traces.

mini-ork reflect [--since <timestamp>] [--task-class <name>] [--lane <lane>] [--dry-run]

Flag	Default	Meaning
`--since <ts>`	24 hours ago	ISO-8601 or unix timestamp window start
`--task-class <name>`	all	Restrict to one class
`--lane <lane>`	`reflector`	Resolve the reflection model from `agents.yaml`
`--dry-run`	off	Show the trace count; skip the model call

Reflection proposes lessons; it does not inject them. Injection happens only through the promotion path (see apply).

improve¶

Read group performance history and propose workflow candidates.

mini-ork improve [--task-class <name>] [--limit <n>] [--dry-run]

Flag	Default	Meaning
`--task-class <name>`	all	Scope to one class
`--limit <n>`	`3`	Maximum candidates to generate
`--dry-run`	off	Show the performance summary only

Candidate ids are printed one per line, for eval and promote.

eval¶

Run a benchmark suite against a candidate and compute utility versus the current baseline.

mini-ork eval --candidate <id> [--suite <name>] [--dry-run]

Flag	Default	Meaning
`--candidate <id>`	required	Candidate to evaluate
`--suite <name>`	`default`	Benchmark suite
`--dry-run`	off	List benchmark tasks; dispatch none

Prints utility_delta; positive means improvement.

promote¶

Run the promotion gate.

mini-ork promote --candidate <id> [--force] [--dry-run]

Flag	Default	Meaning
`--candidate <id>`	required	Candidate to decide on
`--force`	off	Skip the utility-delta threshold (emergency only)
`--dry-run`	off	Compute the decision; write nothing

Decisions:

promoted — the candidate is registered and goes live;
rejected — the candidate stays evaluated, no version bump;
quarantined — permanently blocked from re-evaluation. No CLI clears it; version_registry.clear_quarantine from Python is the documented escape.

Examples¶

# Inspect classification before spending anything
mini-ork classify ./kickoff.md --dry-run

# Plan without dispatching
mini-ork plan ./kickoff.md --dry-run

# Re-run only the verifier nodes
mini-ork execute plan.json --node-type verifier

# Full loop
mini-ork reflect --since 2026-10-01 && \
  mini-ork improve --limit 5 && \
  mini-ork eval --candidate <id> && \
  mini-ork promote --candidate <id>