Writing Iterum plans yourself
/iterum:fleet-plan writes plans for you (Planning a feature). This page is for writing one yourself, or reading and fixing one it wrote: the format, prompt steps, a check script, and the free proofs to run before anything is billed. A plan with no prompt step, such as a script or a migration, never needs the skill.
macOS. Iterum is built and tested on macOS. It does not run on Windows: it relies on Unix process groups and file locks. Linux, or WSL on Windows, may work but is untested.
The plan format
A plan is a JSON list of steps. Each step has a number, a short intent, a command, and, optionally, the files it may touch.
[[1, "edit the page", "sed -i '' 's/Hello/Welcome/' app/page.tsx", ["file:app/page.tsx"]], [2, "build", "bun run build", ["file:app/page.tsx"]], [3, "commit it", "git add app/page.tsx && git commit -m 'Welcome'", ["file:app/page.tsx"]]]
git switch -c feat/welcome # a plan that declares files must not run on main
iterum run feature.jsonRules that keep plans safe
- Declare files and you need a branch. A plan with resources refuses to run on
--target(defaultmain), because its commits would skip the merge gate. - All files are claimed before step 1, in sorted order, and renewed by a heartbeat at half
ITERUM_CLAIM_TTL(default 300 s). If another run holds one, the run is refused before anything runs, and the message names that run. - A failing command fails the run. Fix the command for that step in the plan file and resume; committed steps stay committed.
- Run from the repo the plan works on. Steps run in the directory you start from.
iterumfinds the same database from any folder; if you setITERUM_DB, make it an absolute path.
Prompt steps
Replace a step's command with a prompt object and that step runs a Claude Code session. model is optional; without it, your default model is used. What the session may and may not do is in the guide's Prompt steps chapter.
[[1, "404 page", {"prompt": "Create app/not-found.tsx ... Create no other file.", "model": "claude-haiku-5-5"}, ["file:app/not-found.tsx"]],
[2, "build", "bun run build", ["file:app/not-found.tsx"]],
[3, "commit", "git add app/not-found.tsx && git commit -m 'Add a 404 page'", ["file:app/not-found.tsx"]]]iterum run feature.json --allow-claude 0.05 # each prompt step capped at $0.05Writing prompts that work
- Name the exact files to edit and say "change nothing else". Every prompt step must declare at least one file.
- Say exactly what should appear, so a shell step can check it (A check script).
- If the task touches an API you know has changed, name the doc file that states the rule. A general "read the docs" hint cost about 7 times as much per run in testing.
A check script
The build only proves the code compiles. A check proves the change is there. It runs as a shell step after the build, from the app root, and its error is what the model reads on a retry (the fix loop), so:
- Report every miss, one line each, on stderr, and exit 1 at the end if there was any. A check that stops at its first miss costs one retry per miss.
- Name exactly what is expected in each line: the text, the link, the status code. The fix loop passes on only the last 2,000 characters.
- Start the built server on a port of its own, stop it and its children with a
trapon its pid, and wait until it answers. Stop only that server, never every server of its kind. - Look only where the change belongs. A layout can already have the element you check for: a site footer outside
<main>made an early version of the check below report the wrong miss on a page with no note footer, so its "has no footer" line could never appear.
bun run build)# Does each note page end with the notes footer? Run after the build.
# Report every miss, one line each on stderr so they reach the step's error; exit 1 if any.
port=3231
node_modules/.bin/next start -p $port >/dev/null 2>&1 &
pid=$!
# next start runs the server as a child process; stop both.
trap 'pkill -P $pid 2>/dev/null; kill $pid 2>/dev/null' EXIT
for _ in $(seq 1 40); do curl -s -o /dev/null "localhost:$port/" && break; sleep 0.25; done
misses=0
miss() { echo "$1" >&2; misses=$((misses + 1)); }
code() { curl -s -o /dev/null -w '%{http_code}' "localhost:$port$1"; }
page() { curl -s "localhost:$port$1" | sed 's/<!-- -->//g'; } # drop React's text separators
footer() { page "$1" | grep -o '<main[^>]*>.*</main>' | grep -o '<footer[^>]*>.*</footer>'; }
for n in first-run resume fences; do
[ "$(code /notes/$n)" = 200 ] || { miss "/notes/$n did not answer 200"; continue; }
[ -n "$(footer /notes/$n)" ] || { miss "/notes/$n has no <footer>"; continue; }
footer /notes/$n | grep -qF 'Part of the iterum notes.' || miss "/notes/$n: the footer must contain the exact sentence \"Part of the iterum notes.\""
footer /notes/$n | grep -qF '<a href="/notes">All notes</a>' || miss "/notes/$n: the footer must contain a link to /notes whose text is exactly \"All notes\""
done
[ $misses -eq 0 ] || exit 1
echo "every note page ends with the notes footer"Proving it for free
Three proofs, none billed. A check that passes on main proves nothing, a check that fails a correct change makes the fix loop pay for retries that cannot succeed, and a dry run that fails anywhere but the check means the plan is wrong.
git worktree add --detach /tmp/proof main && cd /tmp/proof bun install --frozen-lockfile && bun run build sh <plan>/check.sh; echo "exit $?" # must be 1, naming what is missing # write the change by hand, then bun run build && sh <plan>/check.sh # must exit 0 cd - && git worktree remove --force /tmp/proof
# dry.json: plan.json with step 1's prompt object replaced by "echo dry" git switch -c feat/<slug> main ITERUM_DB=/tmp/dry.db iterum run <plan>/dry.json step 1 notes footer -> committed step 2 build -> committed run 4526ec9d8476 failed: step failed with exit 1: /notes/first-run has no <footer> rm /tmp/dry.db*
Running it
From here a hand-written plan is the same as one from the skill: run it with --allow-claude and --fix-retries, or queue it for the night, then land it with --check. See Running and landing it and A night's queue.