Run the default loop by hand
This tutorial runs a copy of the default loop, which the package ships in examples/default/, without any agent. You play every agent yourself and write each document by hand.
The default loop is a plan, gate, build, and verify loop, written as three steps, a gate, and a stop in default.loop.json. The following diagram shows its states and what moves the run between them:
The run also stops in places the diagram leaves out: on a question file, such as Q-1.md, and at blocked. For each kind of stop, see Stops.
To see each step's outcomes and their targets, run npx iterward compile --config loops/default/default.loop.json.
Take a run to done
Run these steps from the root of your repository, after you copy the default loop to loops/default/ with init, as Quick start describes. If you followed the quick start, your run is ready for step 3.
-
Start a run:
npx iterward new --config loops/default/default.loop.json --run runs/example/run.json --subject 'the settings page'The CLI prints
{"ok":true,"status":"plan","warnings":[]}. -
Ask for the next move:
npx iterward next --run runs/example/run.jsonThe run is at
plan, so the CLI dispatches the planner:{"do":"dispatch","id":1,"agent":"planner","message":"Step: plan\nRun: runs/example/run.json\nDocument: runs/example/plan.md\nInputs:\n subject: the settings page\nNote: none\nFixes: none"} -
As the planner, write the plan to
plan.mdin the run folder. Its frontmatter carries itsidand its status:printf -- '---\nid: plan\nstatus: ok\n---\n\n# Plan\n\n- Add the settings form.\n' > runs/example/plan.md -
Record the planner's result:
npx iterward result --run runs/example/run.jsonThe plan says
ok, so the machine moves the run into the gate, and the run stops for your decision.closednames the dispatch the result closed and its outcome. The stop lists your moves and the file an approval freezes:{"closed":{"id":1,"step":"plan","outcome":"ok"},"do":"stop","stop":"gate","status":"gate","gate":"gate","label":"Gate","freezes":["runs/example/plan.md"],"moves":[{"call":"gate","gate":"gate","decision":"approved","to":"build","freezes":["runs/example/plan.md"]},{"call":"gate","gate":"gate","decision":"rejected","to":"plan"}],"warnings":[],"since":[{"id":1,"name":"plan","agent":"planner","attempt":1,"outcome":"ok","minutes":0}],"recorded":[]} -
As the human, approve the plan. The approval freezes
plan.md, and the run moves tobuild:npx iterward gate gate --run runs/example/run.json --decision approved --note 'Looks right.' -
Run
nextfor the builder's dispatch. Its message names the builder's document,runs/example/build.1.md, and carries your note:npx iterward next --run runs/example/run.json -
As the builder, write the document, and record it. The CLI moves the run to
verifyand dispatches the verifier, whose document isverify.1.md:printf -- '---\nid: build-1\nstatus: ok\n---\n\nAdded the form.\n' > runs/example/build.1.mdnpx iterward result --run runs/example/run.json -
As the verifier, fail the build, and record it:
printf -- '---\nid: verify-1\nstatus: fail\n---\n\nSaving drops the email field.\n' > runs/example/verify.1.mdnpx iterward result --run runs/example/run.jsonThe run moves back to
build, and the CLI dispatches the builder again. The retry writes a new document, so the first one stays:{"closed":{"id":3,"step":"verify","outcome":"fail"},"do":"dispatch","id":4,"agent":"builder","message":"Step: build\nRun: runs/example/run.json\nDocument: runs/example/build.2.md\nInputs:\n subject: the settings page\nNote: none\nFixes: none"} -
As the builder, write the second document, and record it:
printf -- '---\nid: build-2\nstatus: ok\n---\n\nFixed the email field.\n' > runs/example/build.2.mdnpx iterward result --run runs/example/run.json -
As the verifier, pass the build, and record it:
printf -- '---\nid: verify-2\nstatus: pass\n---\n\nEvery field persists.\n' > runs/example/verify.2.mdnpx iterward result --run runs/example/run.jsonThe run stops at
done, with no moves left. Runnpx iterward show --run runs/example/run.jsonfor the run's state.
To start over, delete runs/example/. For the files the run wrote, see Run format. To drive the same loop with agents, see The default loop. To start a loop of your own, see Create a loop of your own.