Core concepts¶

mini-ork is built from a small vocabulary: kickoffs, task classes, recipes, nodes, lanes, gates, verdicts and run homes. This page defines each term once, with examples from the shipped code-fix recipe, so the rest of the documentation can use them without re-explaining.

One run in one picture¶

flowchart TD
    K[kickoff.md] --> TC{task class}
    TC --> R[recipe]
    R --> T[task_class.yaml]
    R --> W[workflow.yaml]
    R --> A[artifact_contract.yaml]
    W --> N[nodes]
    N --> L[lanes]
    W --> G[gates]
    G --> V[verdict]
    A --> V
    V --> H[run home: runs/<run-id>/ + state.db]

The kickoff is the input. The task class selects the recipe. The recipe's three files define what runs, on which model, and what must be true before the result is accepted.

Kickoff¶

A kickoff is a markdown file describing an outcome. It is the only input a run needs from you. It is not a prompt template — it is a brief: goal, scope, constraints, and the evidence that would prove success.

The canonical example, recipes/code-fix/example-kickoff.md, uses these sections:

## Problem

`tally.js` line 42 uses `< arr.length` as the loop bound but the accumulator
initialises `total` from `arr[0]` before the loop, so the last element is never added.

## Definition of Done

`tally(arr)` returns the correct sum for every input array, including empty arrays
and single-element arrays.

## Scope

Only `src/tally.js` may be edited. No other file may be touched.

## Success Criteria

- `tally([1, 2, 3])` returns `6`.
- `tally([])` returns `0`.
- `tally([5])` returns `5`.
- All existing tests in `tests/tally.test.js` pass.

Two properties matter more than the exact headings: the scope must be enforceable, and the success criteria must be checkable by a command, a test or an observable rule. A kickoff whose only acceptance criterion is "the code is better" gives the planner nothing to verify against.

See Writing a kickoff.

Task class¶

A task class is a named category of work with a matching rule and a default recipe. It lives in a task_class.yaml file:

name: code_fix
description: "Single-patch code change: bug fix, small feature, refactor of a single function"

artifact_contract_ref: artifact_contract.yaml
default_workflow: workflow.yaml

matches:
  keywords: [fix, bug, patch, update, refactor]
  path_globs: ["**/*"]
  regex: []

default_gates:
  - scope_gate
  - budget_gate
  - deployment_gate

risk_class: medium

The matches block is how mini-ork run ./kickoff.md picks a recipe when you do not name one. Keywords, path globs and regular expressions all contribute; default_gates apply to the class as a whole; risk_class feeds budget and review policy.

See Task classes.

Recipe¶

A recipe is a directory that packages one task class end to end. code-fix is the reference implementation. Every recipe has three core files, plus optional prompts, verifiers and probes:

recipes/code-fix/
  task_class.yaml        # when this recipe applies
  workflow.yaml          # nodes, edges, lanes, gates
  artifact_contract.yaml # what a run must produce
  prompts/               # planner.md, implementer.md, reviewer.md, …
  verifiers/             # typecheck.py, test.py, metamorphic.py
  probes/                # held-out inputs used by promotion scoring

Recipes are user-land: adding a workflow shape does not require editing the engine. Run a recipe explicitly with mini-ork run <recipe-name> <kickoff.md>, or let classification select it.

See Recipes and task classes.

`workflow.yaml`¶

The workflow is the executable shape of the recipe: a graph of nodes and edges.

version: "0.1.0"
task_class: code_fix

nodes:
  - name: planner
    type: planner
    model_lane: planner
    prompt_ref: prompts/planner.md
  - name: implementer
    type: implementer
    model_lane: worker
    prompt_ref: prompts/implementer.md
    gates: [scope_gate, budget_gate]
  - name: typecheck
    type: verifier
    verifier_ref: verifiers/typecheck.py

edges:
  - { from: planner,     to: implementer, edge_type: depends_on }
  - { from: implementer, to: typecheck,   edge_type: verifies }
  - { from: typecheck,   to: implementer, edge_type: retries, max_rounds: 2 }

rollback_strategy: revert_branch

See workflow.yaml.

`artifact_contract.yaml`¶

The artifact contract declares what a successful run must produce and which verifiers decide that.

task_class: code_fix
expected_artifact: patch

success_verifiers:
  - verifiers/typecheck.py
  - verifiers/test.py
  - verifiers/metamorphic.py

failure_policy: request_changes

expected_artifact: patch tells the run what kind of change it is making. success_verifiers is the execution evidence that must be present. The metamorphic verifier reports vacuous when no specification exists — recorded as unmeasured, never as a pass.

See Artifact contract and Artifact graph.

Node¶

A node is one role playing one step inside the execute stage. The framework defines eight node-type interfaces:

Type	Responsibility
`planner`	Decompose the task; emit objective, assumptions, artifact and verifier contract.
`researcher`	Gather bounded context material — prior runs, known failure modes, source excerpts.
`implementer`	Produce the artifact: patch, document, config or report.
`reviewer`	Challenge the artifact against requirements; cannot approve its own work.
`verifier`	Run a deterministic probe — typecheck, tests, schema diff, health check.
`reflector`	Extract gradients and patterns from the run's evidence.
`publisher`	Apply the delivery policy and commit or hand off the artifact.
`rollback`	Revert or quarantine when gates exhaust their retries.

Each node declares a type, a lane, an optional prompt, optional verifiers and optional gates. A recipe composes whatever subset it needs.

Edge¶

An edge is a typed relationship between nodes:

depends_on — the target waits for the source.
verifies — the target is a verifier of the source's output.
retries — a failed gate sends findings back to an earlier node for a bounded number of rounds (max_rounds).
escalates_to — after retries are exhausted, control moves to rollback or a human gate.

Edges are what make failure behaviour explicit rather than emergent. In code-fix, both verifiers and the reviewer can retry the implementer twice before the rollback edges fire.

Lane¶

A lane is a slot in the model pool: a name that resolves to a provider, a model and a transport. Nodes refer to lanes, not models:

lanes:
  planner: sonnet
  implementer: sonnet
  reviewer: opus
  verifier: sonnet

Because the mapping is configuration, the same recipe can run on a cheap pool, a frontier-only pool or a learned mix without editing the workflow. Lane resolution is where fallback chains, budgets and routing policy apply.

See Providers and lanes and agents.yaml.

Gate¶

A gate is a check that must pass before the run may proceed to delivery. Gates are broader than verifiers:

Deterministic gates run commands and read exit codes or artifacts — tests, typechecks, schema checks.
Reviewer gates ask a model to reject a result with cited evidence; they cannot approve a failing execution.
Budget, scope and deployment gates protect the run's boundaries.
Human gates pause the run and wait for an explicit approve or reject signal.

The distinction matters: a gate can only make the outcome stricter. A model in a gate may veto; it may not promote.

See Verification and gates.

Verdict¶

A verdict is the recorded decision about a run or artifact. It is computed from gate results, not from prose. Common outcomes:

Verdict	Meaning
passed / approved	Every required gate produced passing evidence; delivery may proceed.
needs change	A gate failed but retries remain; findings return to the implementer.
escalated / rolled back	Retries were exhausted or a policy escalated; the artifact is reverted or held.
vacuous / unmeasured	Nothing meaningful ran. This is explicitly not a pass.
PROVEN / REFUTED / UNVERIFIED	The three outcomes of a standalone `certify` run.

The verdict, the logs behind it and the run's traces are all retained, so "why did this fail" is answerable after the fact.

Artifact contract¶

An artifact contract is the declared interface between what a run produces and what consumers may rely on: the expected artifact kind, the ports it fills, the verifiers that must run, and the failure policy. It is what lets a later stage — or a different run — depend on an earlier output without guessing at its shape.

The contract is validated, not advisory. A run that produces the wrong artifact kind, or skips a declared verifier, fails its gates even if the artifact looks plausible.

Run home¶

The run home is where state lives. By default it is .mini-ork/ in the project; MINI_ORK_HOME moves it.

.mini-ork/
  state.db            # recorded runs, traces, gate results, costs
  runs/<run-id>/      # per-run artifacts: plan, logs, verdict, patches
  kickoffs/           # kickoff inputs
  INBOX/              # escalations awaiting a human decision
  config/             # agents.yaml, task classes, vault config

State is durable: a failed run can be resumed from its checkpoint, and every claim in a verdict is attributable to a run, a node and a model. See Recovery.

Next¶

Quickstart — install and run the loop.
Your first run — read the artifacts of a real run.
Writing a kickoff — make the plan concrete.