Create a loop of your own
A loop of your own starts as a copy of the default loop, which the package ships in examples/default/. For the files in that folder, see The default loop.
Change a copy of the default loop
To start a loop of your own from the default loop, follow these steps:
- Copy the default loop to a directory of your repository, such as
loops/review/, withnpx iterward init --to loops/review. - In the copy, rename
default.loop.json, and changename,inputs,artifacts,steps,gates,stops,machine, andhuman. For every field, see Configuration. - In
hooks.mts, change the hooks your loop needs, and add a hook for each guard,onEnter, or preflight the loop file names. The hooks import nothing from Iterward, so the copy works wherever it lives. - Run
npx iterward compile --config loops/review/review.loop.json, and check each outcome's target it prints. - Change the agents in
agents/to match your steps and their statuses. For each template and its placeholders, see Default agents. - Test the loop with
node:test, as Test a loop describes.
A run holds the sha256 of its loop file and hook modules, so start a new run after you edit either.
If a gate freezes an artifact that no step writes, such as a file a guard writes, declare a human move into that gate. No step rewrites such an artifact, so that move is how a human releases its freeze after the file changes.
Design the loop with an agent
To have an agent draft the loop with you, give the agent the build-loop skill. An agent following the skill drafts the whole loop first, asks you one decision at a time with a recommended answer, and checks the result with compile. The agent gets the skill from the MCP server's build-loop tool, or from npx iterward build-loop, which prints the same text. To register the server, see Set up the MCP server.