Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

flume

Work that leaves the inbox needs somewhere to happen: a worktree of the right repository on a branch of its own, made ready to build. It needs an agent started there with the right prompt, then a fresh one for each stage after, until the work goes to sluice. flume does this for one launch at a time. A launch names a repository, a kind, a brief and a name. flume makes the place, starts each stage’s agent and confirms that its prompt arrived, and moves to the next stage once the stage’s deliverable exists. When sluice lands the work, or the launch is dropped, flume tidies the place. It runs on one host and launches there.

launches from one launch the work The operator /launch, a herdr key millpond an item's send headwater the fix key sounding a question crew each stage of its work flume flume launch a repository, a kind, a brief and a name a place, made ready places/<kind>--<name> a fresh agent per stage, its prompt confirmed each stage ends on its deliverable tidies the place; lands nothing itself Each stage's agent in a herdr pane, or a command submits sluice tests as merged, lands it landed, or dropped: flume tidies the place Each record stays with its owner millpond keeps the item's, crew its plan, sluice its landings flume keeps only each place's live state
Five callers launch the same way. flume makes the place and runs its stages, each with a fresh agent, and the last stage's agent submits to sluice. flume tidies the place once the work lands, and keeps no record beyond each place's live state.

Why it exists

Starting an agent on work looks like one command, and it fails in ways that cost the work. A prompt sits typed in a pane and is never submitted. A stage reads as done because its pane went quiet. A worktree goes with commits that nothing else holds. crew’s teams meet each of these and hold rules against them (teams.1–4, teams.11, teams.15, plan.9, 10, 12, 17). Every other tool that starts work needs the same rules: millpond sending an item, headwater’s fix key on a release, sounding opening a question, and the operator launching a fix of their own.

flume holds those rules once, as a tool of its own. Every caller launches the same way, and crew asks flume for each place and each stage’s agent as it asks sluice for each landing.

What it promises

  • One launch is one place: a worktree of one repository, on the branch <kind>/<name>.
  • Each stage starts a fresh agent, and never one over an agent still running (teams.2).
  • A stage’s prompt is confirmed in the agent’s transcript or sent once more. A stage whose second sending is not taken is reported never started (teams.15).
  • A stage ends on its deliverable, or on its agent stopping short to say what it needs, and never on a quiet pane (teams.4).
  • A tell reaches its agent as a prompt, or fails with nothing typed (teams.11).
  • flume removes only places it made, and keeps a branch that holds commits its target lacks (plan.9, plan.10).
  • flume lands nothing. The work reaches its target through sluice.

Where it stops

flume decides nothing about what to launch and plans across no items. It keeps only the live state of the places it runs: millpond keeps an item’s record, crew its plans, and sluice its landings. crew keeps what spans many places, among them its bolts, slots, conductors and approvals (Who launches).

The tools beside it

  • millpond is the inbox. It sends an item to flume as a fix or a change, records the send, and writes the landing against the item. Its book is at ../millpond/.
  • headwater reports releases newer than a repository’s pins. Its fix key hands a release’s brief to flume as a fix. Its book is at ../headwater/.
  • sounding works one question in one session. flume makes its place and runs its session as the kind question. Its book is at ../sounding/.
  • sluice tests a change as merged and lands it. Every fix and change flume launches ends on a submission to sluice. Its book is at ../sluice/.
  • crew runs teams, plans and bolts. It calls flume’s command line for each place and each stage.

How to read this book

The chapters follow one launch: the launch and its place, the kinds and their stages, how a stage’s prompt reaches its agent, and how a stage ends. Then come what flume reports while a place runs and how it tidies a place once its work is over. Last come who launches, with what crew keeps for itself, and the surfaces the operator works through.

A rule id in backticks, such as teams.15, cites crew’s docs/architecture/, whose rules about places and stages flume takes over. flume’s own statement is not written yet; Open questions says what it will hold.