Overview

mini-ork is a task operating system for agents: you describe an outcome, and it runs a fixed loop that classifies the work, plans it, executes it across a fleet of models, verifies the result against real execution, and learns only from what passed. This page explains the problem it addresses, the three layers it adds over an orchestration framework, and where to read next.

The problem: generation outran validation

Agents now write code and documents faster than a team can review them. The bottleneck moved from generation to validation. Two failure modes follow:

• An agent that writes its own tests and grades itself produces output that agrees with itself — fluent, green-looking, and wrong often enough to break production.
• The naive fix, sending everything to a frontier model several times, makes the bill grow faster than the unit price falls.

mini-ork is built for the world after "make it generate": ship agent work you can defend, at a cost you can defend, on a system that gets sharper on your codebase the more you run it.

What mini-ork is

mini-ork is a framework for the loop, not for a particular workflow. The pipeline opinions — which roles run, in what order, with which gates — live in recipes/ and are user-land. The framework ships the loop, the primitives and the interfaces.

Every task, whether it is a one-file bug fix, a research brief or an ops runbook, passes through six stages:

flowchart LR
    C[Classify] --> P[Plan]
    P --> E[Execute]
    E --> V[Verify]
    V -->|gates pass| R[Reflect]
    V -->|gate fails, retries remain| E
    V -->|retries exhausted| RB[Rollback]
    R --> I[Improve]
    I -->|candidate promoted| C

• Classify matches the kickoff to a task class.
• Plan decomposes the work and names how success will be checked.
• Execute walks the recipe's workflow graph, dispatching each node to a model lane.
• Verify runs deterministic gates over what the nodes produced.
• Reflect extracts only what the evidence supports.
• Improve proposes, scores and gates changes to prompts, routing or workflow shape.

The node graph inside Execute is the recipe's business. Everything around it is the framework's.

Three layers that decide whether agent work is shippable

Wiring agents into a graph is commodity. mini-ork adds the layers that decide whether the output can leave the building.

1. Execution as the oracle

The source of truth for a change is its execution outcome, captured in an isolated runtime — did the test run, did the assertion pass — not a reviewer's approval.

• An LLM judge may veto a passing result; it cannot fabricate one.
• A real assertion failure is distinguished from a broken harness, so a correct patch is not rejected because the probe had a typo.
• Non-regression is checked before a change ships.
• A run with no meaningful check is reported as vacuous, never silently successful.

mini-ork certify exposes this directly: point it at a base commit, a head commit and the bug the change claims to fix, and it generates extra inputs the change was not written for. Both a correct fix and a special-cased cheat make the reported example pass; only the correct one survives the generated invariants. See Certifying a change.

2. Cost governance across a pool of models

Not every step deserves frontier prices. Each node names a lane, and a lane maps a role to a provider and model. Bring the providers you already have and route by role.

• Heterogeneous dispatch across OpenAI/Codex, Anthropic, MiniMax, Kimi, GLM or any OpenAI-compatible endpoint.
• Selectable routing policies via MO_ROUTING_POLICY, from frontier_only to cheap_only to learning_governed.
• Spend metered per model at the provider's list price.
• Hard controls: a daily-spend circuit breaker, a cost-pause sentinel an operator must approve, and a wall-clock deadline.

See Cost governance and Providers and lanes.

3. Learning that is earned

Every run leaves a trail of verified outcomes. mini-ork feeds that signal back into routing, prompts and memory — but only when a measurement supports the change.

• A contextual-bandit router adjusts unpinned lane choices from recorded advantage, with no extra model calls.
• Group-relative (GRPO) writeback and textual-gradient prompt evolution improve the planner, implementer and reviewer prompts across runs.
• Verified-outcome memory persists only what passed the gates, and a closed learn → apply loop materialises, scores and non-regression-gates each proposal.

The self-improvement loop ships off by default and has no human approval prompt when enabled. Read The self-improvement loop before turning it on.

A run in one paragraph

You write a kickoff — a markdown file stating the goal, scope, artifact and how success is checked. mini-ork run code-fix ./kickoff.md classifies it, loads the recipe, plans the work, dispatches nodes to lanes, runs verifiers and reviewer gates, and either publishes the artifact or escalates to rollback. Every intermediate artifact lands under .mini-ork/runs/<run-id>/, and the recorded state lands in .mini-ork/state.db. A failed run can be resumed without redoing the steps that already passed.

Who it is for

• Teams shipping agent-written changes who need a verdict stronger than "the model said it looks good".
• Platform and infra engineers building an internal agent runtime with cost controls and audit trails.
• Researchers who want a harness where the reward signal is execution, not preference.
• Operators running scheduled or long-horizon work that must survive restarts and be attributable after the fact.

What it is not

• Not a workflow builder. It ships recipes, not a drag-and-drop graph editor.
• Not an autonomous coder product. It is the runtime underneath one.
• Not an eval tool. Evals score after the fact; mini-ork makes the verdict part of the run.
• Not a guarantee. The oracle is only as strong as what you can actually run. Its guarantees are richest on code with real tests and thinnest on subjective work, where it is built to surface uncertainty and refuse promotion rather than manufacture confidence.

Self-modification is real

mini-ork contains a loop that can rewrite its own prompts and workflows and promote the change unattended. It is off by default. If you enable it, read the warning in The self-improvement loop first.

Where to go next

If you want to…	Read
Install and get a first run working	Quickstart → Your first run
Learn the vocabulary	Core concepts
Write a kickoff that plans well	Writing a kickoff
Understand a verdict	Verification and gates
See the measured results and their limits	Results and benchmarks
Extend the engine	Extending mini-ork