fanout

Fanout

Split work so parallel sessions can't collide. The script fanout.mjs sits next to this file; run it with node.

Steps

1. Plan. Use at most about 4 sessions, grouping related tasks into one: more agents writing at once on one account slow each other down (in our benchmark, three sessions ran at full speed and six at a third of it). Write .fanout/plan.md in the repo root (add .fanout/ to .git/info/exclude so it isn't committed). Use exactly this shape:

   test: npm test
   regen: src/index.ts via npm run gen
   
   ## foundations
   owns: src/types.ts, src/db/**
   exposes: src/types.ts
   task: store money as integer cents plus a currency code everywhere in the db layer
   done: money is integer cents plus currency; typecheck passes
   
   ## money
   owns: src/present.ts, src/components/MatchCard.tsx
   uses: src/types.ts
   task: show prices in the user's currency on match cards
   done: no hard-coded currency left
   agent: codex
   

   • Above the first ##, once for the whole plan: test: <command> (the project's full test command; rehearse runs it) and one regen: <paths> via <command> line per set of generated files every session would otherwise touch (codegen output, barrel/index files, API clients, lockfiles, snapshots). No session owns those; they are rebuilt after merging. Omit regen: if there are none.
   • In each session, only these fields: owns (required: paths or globs, each owned by exactly one session), task (one line: what this session builds), done, check (a command that exits 0 only when done holds on the merged code; rehearse runs it after the test, so give one to every session whose work the test can't see, e.g. when the test is only a lint), exposes, uses, after, and optionally agent (claude, codex, or a command that takes the brief on stdin) to run that session in a different agent, and model to run it on a different model. Well-specified sessions run fine on a cheaper model (Haiku sessions cost about a quarter as much in our benchmark, with the same results); keep the strongest model for planning and for sessions that need judgment.
   • Contracts: a file several sessions depend on (types, function signatures, schema) is listed under exposes: by its owner and uses: by each session that depends on it; uses also sets the merge order. Contracts are the real code files, not a separate notes document. Keep them to interfaces only.