◈ loopsandgraphs.dev

Agent execution framework

Loops and Graphs

Your agent writes code fast, but it still needs a system to check every step on your behalf. This framework gives it one. A human declares the checks once. The agent applies them on every task, runs independent steps in parallel, and only brings the human the final merge.

Three pieces make it work. A check replaces your eyes while the agent works. A graph replaces your judgment about order. A gate, guided by checkable contracts that can be written as Lean proof obligations, replaces your approval at every step. What is left for you is the final merge.

That is harness engineering. Every agent system has one. This one is written down.

To get started, have your agent paste this command into your terminal:

LOOPS_AND_GRAPHS.md Click to copy
$ curl -fsSL -O https://raw.githubusercontent.com/awdemos/loopsandgraphs/v0.1.21/LOOPS_AND_GRAPHS.md
# place at your repo root, next to README.md
Copied to clipboard

Check

Define a failing condition before the work starts. No human eyes required for green.

Graph

Draw the map before the work. Real dependencies become edges; everything else runs in parallel.

Gate

Open lanes by evidence and reversibility. Put the human on the merge, nowhere else.

The problem

Most loops are not loops

In August, researchers from Heidelberg and Singapore Management University searched 36,487 maintained repositories for agents running in autonomous loops. They confirmed 217.

Nearly all of them had the trigger. After that, the numbers fall off a cliff.

One triage loop logged 6,290 runs. In every run the researchers checked, the agent never fired. A trigger is not a loop. It is a cron job with your credit card attached.

The study found no systematic evidence for the promised 10x yet. This framework does not promise one either. The parts everyone skips, the check, the state, the gate, are the parts that decide whether a loop is worth running. Research paper. And we fix that problem with this skill.

A loop checks its own work

Produce, check, correct, repeat

A loop is a job that checks its own work and fixes itself when it is wrong. Like a student with an answer key. No teacher needed.

  1. Do the work. Write the code, run the search, build the report.
  2. Check it. Against something that can say no.
  3. Fix what the check caught.
  4. Repeat until it passes.

Three exits: green (the check passes), budget (runs or dollars run out), or stall (the same failure twice). No fixed retry count. A count cannot tell slow progress from a stuck loop, and a repeated failure is not a retry problem. It means the agent cannot see what it needs, or the task is wrong. Both are yours.

The check is the whole point. If it cannot fail, it is not checking. Tests pass. Type checker reports zero errors. Those are checks. "Looks right," "model is confident," "no errors raised": not checks.

For unattended or wide changes, the worker cannot be the only verifier. A separate gate reviews the evidence, and real checks still run. Without that independence, a human keeps the gate. No panel of judges votes on what happens next.

Green

The test suite exits 0.

Green

Every claim carries a source line.

Green

The diff touches only files listed in the plan.

Not a check

The output looks good.

Not a check

The model says it is confident.

Not a check

No errors were raised.

A loop with a real check runs while you are somewhere else. A loop without one repeats the same mistake until it runs out of money, with a clean log.

The graph is the layer above

One loop cannot see the whole job

A loop makes one job correct. It cannot decide which jobs exist or what order to run them.

The graph holds that wider view. It is the shape of the work: what runs, what runs in parallel, what waits, where results go back. Two things: nodes and edges.

A node is one job: one input, one output, one owner. An edge is a real dependency: the next step reads the previous step's output. If nothing crosses, there is no edge. The steps can run at the same time.

A planned graph is that map drawn before work starts. You draw it so the agent does not invent the structure while doing the work.

A planned graph The map drawn before the work starts Splitter Worker A Worker B Code node Gate Merge human approves back to the unit that failed Learning edge runs in parallel only opens after the gate passes Forward edge: output feeds the next step Correction edge: send one unit back to fix itself Learning edge: accepted result becomes a future constraint
A planned graph is the map you draw before any work starts. The splitter cuts the task into bounded units. Independent workers run at the same time. The code node merges their outputs with one correct answer. The gate runs a deterministic check. If the check fails, only the unit that failed loops back to the worker that produced it. If it passes, the result continues to the merge, where a human approves it, and may also travel back along a learning edge as a constraint the splitter uses next time.

Treating "and then" as an edge is the mistake behind every unnecessary wait. Summarize the file and then check the weather. No edge. The weather does not read the summary. A linear script chained them because of the order you typed them.

Test every arrow in a pipeline you already have: does the next step actually read the previous step's output? If you cannot name what crosses, there is no edge. The wait is waste.

Four kinds of node

Splitter, worker, code node, gate

TypeRoleExample
SplitterCuts the work into units and writes each brief.Divide a refactor into slices by blast radius.
WorkerDoes one unit with one lens, in its own context.Audit one slice for race conditions.
Code nodeApplies a transformation with one correct answer.Merge, rank, deduplicate, compare exports.
GateDecides whether a unit's output may continue.Open only if tests pass and scope is clean.

The code node is the one people forget. Merging, ranking, deduplicating: one correct answer, a few lines of code. A model adds cost, latency, and variance to a step that had none.

If you can describe it without saying judge, decide, assess, or summarize, it is code.

Where the loop lives

The loop lives inside a node. The graph lives between them.

Inside one unit: produce, check, correct. Between units: split, fan out, merge, gate, send back.

You do not choose between them. A graph without loops makes unverified work in parallel. A loop without a graph is one good step in a queue nobody designed.

The two return paths

Return failures to the unit. Return accepted results as constraints.

A graph without a way back is a pipeline. It produces output and forgets.

Two return paths, two jobs. A correction edge rejects one unit back to the step that made it. Fixes this run. A learning edge sends an accepted result back to the splitter as a constraint. Fixes every run after.

Almost everyone builds the first. The tell is a system that is fast and never gets smarter.

The learning edge does not carry the output, it carries a constraint derived from it. Accepted: utils slice ported, green on first pass. Derived: adapters preserve keyword args exactly. Lands in: a stored constraint file that every later splitter reads. If that file cannot persist, the learning lasts for this session only.

Four slices ported. One fails. Send the whole batch back and three correct slices get rewritten into different, not better, versions. Now you re-verify all four. One failure became four uncertain outcomes.

Every return carries five things:

The scope line matters most. Without it a returned unit grows: the agent notices two adjacent issues, fixes those too, and your one-slice correction becomes a four-file diff nobody reviewed.

Open the gate on evidence

Blast radius, not confidence

Most systems gate on a confidence score. Wrong variable. Confidence is the only input the model can influence.

LaneReversibilityGate rule
Open firstReversible and containedCopy changes, tests, isolated functions with coverage. One bad merge costs a revert.
Open secondReversible but wideShared utilities, schema additions, anything a dozen callers touch. Gate on deterministic checks plus a clean trajectory.
Never openHard to reverseMigrations, deletions, anything writing to production data or moving money. This lane does not open, regardless of score.

The third row is not a high threshold. It is a closed lane. Thresholds get adjusted. Closed lanes do not.

A skill is not a runtime

The skill instructs the agent. The runtime executes unattended.

The skill tells the current agent how to plan, check, route, record, and escalate. It does not turn that agent into an unattended system.

A real runtime must start scheduled or event-driven runs, preserve state after a restart, isolate parallel writers, enforce budgets, provide a kill switch, and keep execution logs. If one of those mechanisms is missing, say so and reduce autonomy.

The four node types and gate rules are this project's design, not a standard proved by the paper. The traceability matrix shows exactly which ideas came from research, which are ours, and which need a runtime.

Where to start

Build the gate first

Pick one thing you do repeatedly. Draw the splitter, the lanes, the merge, one gate, one back edge.

Build the gate first. A graph without a gate is a faster way to produce unverified output. Then the lanes. Then the learning edge, because you cannot learn from accepted results until something accepts them.

Put the human on one step: the merge. Approve it. Nothing else.

Most people tune one loop and call it a system. The ones who draw the graph around it run a fleet.

To further enhance the Loop and Graph Skill, combine it with ADVERSARIAL_REVIEW.md. It is reported at adversarial-review.com to improve prompting performance by up to 35%, especially for software bugs.