Writing plans by hand

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.

Section 01

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.

[ 2 , "build" , "bun run build" , ["file:app/page.tsx"] ] seq intent command resources recorded; must match on resume a shell string, or {"prompt": ...} optional; claimed before step 1 order Change a command only for a step that failed; resume refuses a changed command on any other step.
One step, four fields. Resume compares the intents and a hash of each command with what was recorded, so keep the plan file you started with.
A shell-only plan, no model involved: feature.json, kept anywhere; run it from the app repo
[[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"]]]
From the app repo, with the settings from Where to run what
git switch -c feat/welcome                     # a plan that declares files must not run on main
iterum run feature.json

Rules that keep plans safe

  • Declare files and you need a branch. A plan with resources refuses to run on --target (default main), 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. iterum finds the same database from any folder; if you set ITERUM_DB, make it an absolute path.
Section 02

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.05

Writing 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.
Section 03

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 trap on 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.
check.sh for a footer on each note page (Next.js, run after 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"
Section 04

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.

1 and 2: the check fails on main and passes a correct version, in a throwaway worktree
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
3: the dry run fails at the check, on a scratch database
# 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*
Section 05

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.

↑ Top