HivemindOS manual

Loop Engineering

Loop engineering is an advanced way to turn agent work into repeatable loops, each with a clear goal, checks, a budget, receipts, and a record of what was learned. Use it when you want an agent to repeat a kind of job reliably, and eventually with less supervision.

The Work Board stays the single record. A loop can start from chat, Scheduler, Queen Bee, a company, Evo, or a Work Board task, but its contract, run history, receipts, and handoffs all live on the board.

What a loop has

A pattern describing its shape (see below).
A contract with success criteria, retry and time budgets, required evidence, and evaluation checks.
Receipts proving why a check or result passed.
Human gates for outside actions, risky spending, sensitive decisions, repeated failures, and unclear handoffs.
An exportable snapshot for people and agents: LOOP.md, STATE.md, contract.md, loop-budget.md, loop-run-log.md, and patterns/registry.yaml. contract.md holds the agreed definition of done, expected outputs, and any grading rubric.

Built-in patterns

Pattern	Mode	Typical use
Code Fix Loop	Closed	Fix code against tests, lint, type checks, and receipts.
App Build Harness	Closed	Plan, build, test in a browser, judge, and hand off app work.
Research Loop	Open	Source-backed research with receipts and review.
Content Loop	Open	Draft, judge, revise, and deliver against a rubric.
Daily Brief Loop	Open	Recurring scan, prioritize, brief, deliver, and log.
Operating Unit Learning Loop	Optimizer	Learning loops for a company, crew, or long-running goal.
Evo Benchmark Loop	Optimizer	Benchmark-driven experiments that can be handed to Evo.

Readiness levels

An audit scores how ready your setup is to run without supervision.

Level	Meaning	Use it for
L0	Pieces exist, but nothing proves the loop is running.	Design and setup.
L1	The Work Board can report on it, but contracts or receipts are thin.	Reports and dry runs with human review.
L2	Contracts and evaluation checks are in place.	Agent runs with human review before completion or side effects.
L3	Checks, receipts, budgets, recent runs, and human gates are all visible.	Carefully limited unattended loops.

L3 is deliberately strict: a high score alone is not enough without loop tasks, checks, receipts, full budget coverage, a human gate, and recent activity.

Treat the level as a ceiling, not a guarantee. Start new loops at L1 or L2 with human review, and raise autonomy only when the board shows passing receipts, set budgets, recent runs, and clear human gates.

Run the audit

From the HivemindOS repository folder:

pnpm loop:audit
pnpm loop:audit -- --json
node scripts/hive-loop export --write <folder>
node scripts/hive-loop patterns

For scripts and agents, GET /api/loops returns the patterns, templates, and checkers. Add ?readiness=true to audit the board, and &artifacts=true to include the snapshot files. POST /api/loops can return a readiness report, export a snapshot, build a contract, or create a Work Board task with a contract attached.

How finished work is checked

When a loop’s work finishes, HivemindOS evaluates it: quick checks for chat, verified checks for tasks and runs, and a separate reviewer for high-risk work. Agents cannot approve their own checks. See Agent evaluations for the levels, results, and what counts as proof.