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.

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.

A launch and its place

A launch is one start of work. It names a repository, a kind, a brief and a name, and flume makes one place for it on the host flume runs on. Every stage of the launch’s work happens in that place, and the place lasts until the work lands or the launch is dropped.

What a launch names

The caller gives all four (Who launches). millpond’s send gives an item’s brief, headwater’s fix key a release’s, sounding a question, and the operator’s /launch their own words.

The place

flume makes the place: a worktree of the repository at <repository>/places/<kind>--<name>, on a new branch <kind>/<name>. A fix named bump-parser is worked at places/fix--bump-parser on fix/bump-parser. The kind leads both, so the places of one kind sit together in the folder and their branches share a prefix.

• One launch, one place. flume refuses a launch whose place or branch already exists, and never adopts a worktree or a branch it did not make (teams.3). A place holds one launch’s work and nothing of any other.
• The agents work inside it. Each stage’s agent reads, writes and commits in the place, on its branch. flume makes the place and removes it; no agent does either.
• Its work leaves through sluice. The place’s branch reaches its target, the branch the work lands on, only by a submission to sluice (sluice’s book).

Made ready

A worktree fresh from git holds the repository’s files and nothing else: no dependencies installed, no toolchain fetched, no generated files. flume makes the place ready by the repository’s own declaration of what a worktree needs. It reads the declaration sluice reads, and runs the toolchain the repository declares and then its runner’s setup, in the place (plan.17).

• The steps run with a clean environment, never the caller’s, since a caller’s shell may belong to another checkout.
• flume runs them whenever it makes the place, and again whenever it starts a stage in a place it finds already made.
• A repository that declares nothing has nothing run. flume names no script of the repository’s and assumes no tool of its own choosing: the declaration says what runs.
• A step that fails is recorded with the place, with the step and its words, and status shows them (Status and live state).

One host

flume runs on one host and launches there. Its places are worktrees on that host, each stage’s agent runs there, and flume status reports the places of that host alone.

Kinds and stages

A kind is a list of stages. Each stage names its prompt, the text its agent starts from, and its deliverable, what flume reads its end from. flume runs a place’s stages in order, a fresh agent for each, and a stage starts only once the stage before it has delivered.

Three kinds

flume ships three kinds, and a repository may declare more.

The stages

A stage starts only on the deliverable of the stage before it. code never starts before the change is committed, and verify never before every task is ticked, so each stage’s agent finds in the place what its prompt says is there.

A stage’s deliverable is something flume reads in the place or on the host: a file, a commit, ticked tasks, or a record such as sluice’s (teams.4). A stage ends on its deliverable says how flume reads each one.

A fix

A fix is work that needs no design of its own: a release to take, a defect to mend, a file to correct. Its code stage makes the change and commits it on the place’s branch. Its submission stage submits the branch to sluice and ends when the branch lands.

A change

A change is work that needs an OpenSpec change first. construct writes the change and commits it: its proposal, its design, its specs and its tasks. code works the tasks and ticks each one in tasks.md as it is done. verify checks the code against the change as construct wrote it. The submission stage submits the branch, which then carries the change and its code together.

flume reads the change’s own files, so status shows its tasks ticked as code works through them (Status and live state).

A question

sounding launches the kind question for each sounding. flume makes the place and starts the round’s session there. sounding’s Claude Code plugin hands the session its question, its sources and its earlier rounds at its start (sounding’s book).

• The stage ends on conclusion.md, which sounding conclude writes, or when the session stops on a note saying where the next round would start. sounding’s stop check holds the session to one of the two, so the note is how a question’s session stops short (sounding’s stop check).
• Go on starts the stage again in the same place, with a fresh session. The operator’s notes join the question, and the place keeps the prototype and the files from the round before.
• Nothing lands from a question. The kind has no submission stage, and sounding’s plugin refuses a submission from a sounding’s branch (sounding’s place).

sounding’s book names a question’s branch sounding/<name>. Open questions holds which name flume gives it.

A repository’s own kinds

A repository may declare kinds of its own in the same form: a name, and a list of stages, each naming its prompt and its deliverable. flume runs a declared kind as it runs the three it ships, one fresh agent per stage, each stage ending on its deliverable. How a repository declares its kinds, and how crew’s stage prompts take that form, is on Open questions.

Prompt delivery

A stage begins when its agent has its prompt. flume starts the agent, waits until it accepts input, sends the prompt, and then reads the agent’s transcript to see that the prompt arrived. A prompt shown typed in a pane proves nothing, and text left in a pane for a hand to submit is never a stage’s state (teams.15).

A fresh agent for each stage

Every stage starts a fresh agent, once the place’s previous agent has ended (teams.2). flume never starts an agent over one still running in the place, since a start typed into a running agent’s pane lands as text in its conversation.

A fresh agent carries nothing from the stage before it except what the place holds: the commits, the files, and the deliverable the stage before it left. Each stage’s prompt names what the stage starts from.

The agent starts in a herdr pane, or as a command flume prints for the operator to run.

Taken, or sent again

1. flume starts the stage’s agent.
2. It waits until the agent accepts input. An agent still starting is slow, never failed.
3. It sends the prompt.
4. It reads the agent’s transcript. When the transcript holds the prompt within a short time, the prompt is taken, and the stage has begun.
5. When it does not, flume sends the prompt once more and reads again.
6. When the second sending is not taken either, flume reports the stage as never started.

The transcript is the agent’s own record of what it was given. herdr reads the pane’s screen, and a screen shows what was typed into the pane, whether or not the agent received it. So flume confirms a prompt in the transcript and nowhere else.

A start flume cannot read is unknown: no transcript yet, as when the agent is still starting on a loaded host. flume watches it until the transcript tells. A working agent whose transcript holds its prompt is a stage that began, however long the start took (teams.15).

A tell

A tell is more text for a place’s agent: the operator’s answer to what it needs, or a caller’s note. flume tell reaches the agent as a prompt or not at all (teams.11).

• An agent that is not up is reported, and the tell fails with nothing typed.
• An agent waiting on a question in its pane is reported the same way, since text typed into a question’s dialog never reaches the agent. flume reads two things before it types: herdr’s state for the pane, and the agent’s own record that it asked a question still unanswered.
• A tell that goes through is confirmed in the transcript, as a stage’s prompt is.

Ending an agent

flume stop ends a place’s agent. It fails, rather than report success, when the agent did not exit, and it ends a working agent only with --force (teams.2). flume itself ends a stage’s agent that delivered, before the next stage starts (A stage ends on its deliverable).

A stage ends on its deliverable

A stage ends when its deliverable exists, or when its agent stops short and says what it needs. It never ends because its pane went quiet (teams.4). When the deliverable exists, flume ends the stage’s agent and starts the next stage.

Why the pane says nothing

An agent’s pane goes quiet for many reasons. The agent may wait on a long build, think through a hard step, or finish a turn with the work half done. A quiet pane says nothing about whether the work exists. The deliverable does, so flume reads the deliverable where the work lives: in the place, or on the host.

Reading a deliverable

flume reads a deliverable at one commit. It reads the branch’s head once, then reads the ticks and the commit’s time at that head. An agent’s last tick that lands between two reads never shows a deliverable that is not there (teams.4).

For a change, flume reads the OpenSpec change’s own files and agrees with what openspec reports on the same worktree (plan.12).

Stopping short

An agent may stop without its deliverable: a question only the operator can answer, a step outside its place, a brief that cannot be done as written. It stops and says what it needs. flume reads that from its transcript, records what the agent needs with the place, and shows the agent as waiting.

An agent that stops short ends flume’s wait on the stage without the deliverable, so flume starts no next stage. A tell answers the agent in its pane, and it goes on with the stage. flume retry starts the stage again with a fresh agent and its prompt (Prompt delivery).

Stuck

A stage quiet past flume’s limit, with no deliverable and no word of what it needs, is reported stuck. flume ends nothing: the agent may be in a long build, and ending it would lose the work it is doing. The operator, or the caller, decides what follows: a tell, a stop, or a retry.

Moving on

When the deliverable exists, flume ends the stage’s agent and starts the next stage’s fresh agent with its prompt. Whoever waits on the place learns of the end with the deliverable itself: a caller reading flume status sees the stage ended and what it delivered in the same reading (teams.4).

After a fix’s or a change’s last stage the work has landed, and the place waits only to be tidied (Tidying). A question’s place stays while the operator decides its conclusion, since go on runs the stage again there (Kinds and stages).

Status and live state

flume status reports every place flume runs on its host, as each stands now. flume status --json gives the same to callers: millpond, crew, sounding and flume’s own plugins read it.

What status gives

Beside these, status names what an agent that stopped short needs, and a stage reported stuck or never started. It names a readying step that failed, with its words, and a place tidying kept, with the reason.

A change’s tasks

For a change, flume reads the OpenSpec change’s own files in the place. Its tasks show ticked as code ticks them: three of eight, then eight of eight, and the stage ends once the last tick is committed. flume reads the files directly, and what it reads agrees with what openspec reports on the same worktree (plan.12).

Live state, and the records that outlast it

flume keeps only the live state of the places it runs. Once it tidies a place, the place leaves its status.

An item’s record outlives its place, so the record belongs to whoever keeps the item:

• millpond keeps an item’s send and its landing, written from sluice’s record (millpond’s items).
• crew keeps its plans, its bolts and each unit’s stage.
• sluice keeps every submission and every landing.
• git keeps the commits, and a branch tidying kept.

flume holds no history a caller needs later, and no caller reads one from it.

One reading per repository

A flume command reads each repository once, however many of its places it reports (plan.12). A status of twenty places in one repository costs one reading of that repository, so the herdr sidebar and crew can read status as often as they need.

Tidying

A place lasts as long as its work. flume tidies a place once its work lands or its launch is dropped, and its agent has stopped (teams.1). It removes the worktree, and deletes the branch unless the branch holds work its target lacks.

When a place’s work is over

• Landed: sluice’s record shows the place’s branch landed on its target.
• Dropped: the caller dropped the launch, as sounding’s drop does for a sounding, or the operator did.

flume tidies a place when it reads that its work is over, and flume tidy runs the same pass on demand. When flume cannot read whether a place’s work is over, it removes nothing (plan.9).

What flume removes

flume removes only places it made: worktrees directly under <repository>/places/, each on the branch of a launch flume made (plan.9). It never removes:

• the repository’s main checkout;
• a worktree made by hand, or by another tool;
• a locked worktree;
• a worktree with modified files, or untracked files that are not ignored.

A place kept for one of these reasons stays in status, named with the reason (Status and live state).

Through the repository’s own tool

flume removes a place through the repository’s own worktree tool, such as worktrunk’s wt remove, so the repository’s remove hooks run. Whatever the repository stood up for that worktree goes with it: a database, a dev server, a test service (plan.9). A hook that fails keeps the worktree, and flume names it.

The branch

When the worktree goes, flume judges its branch against its target with git cherry (plan.10):

• a branch holding a commit whose patch the target lacks is kept and named;
• a branch holding nothing beyond its target is deleted.

git cherry compares patches, so a commit that reached the target under another id, as a rebase gives it, counts as landed, and a patch found nowhere in the target keeps the branch. A branch kept by mistake costs a deletion by hand; a branch deleted by mistake loses the work.

A launch dropped part way

A launch dropped before its work lands leaves a branch with the commits its stages made: a construct’s change, a code stage’s work. Tidying keeps that branch and names it, so the work stays reachable until someone deletes the branch by hand.

Who launches

flume decides nothing about what to launch. Its callers do, and each launches the same way: a repository, a kind, a brief and a name.

From the operator

/launch <brief> in any Claude Code session launches the brief, and the session that asked goes on with its own work, since the launch’s agent works in a place of its own. The herdr plugin’s key launches from herdr (The operator’s surfaces). Which repository and kind a /launch takes is on Open questions.

From millpond

millpond sends one item to one worktree through flume. The send names the repository and the kind, a fix or an OpenSpec change. millpond records the send and hands flume the item’s brief, and flume makes the place and starts the agent. The work submits through sluice, and millpond writes the landing against the item from sluice’s record of that branch (millpond’s items).

• An item that asks a question goes to a sounding, which launches its own place through flume.
• An inbox crew keeps sends no item to flume itself. Its settings hand items to crew’s planner, and millpond refuses a send from it.

From headwater

headwater’s fix key hands a release’s brief to flume as a fix (headwater’s surfaces). An agent starts in a place to make the bump, and submits it to sluice. The brief holds what the agent needs to move the pin (headwater’s briefs).

In a repository crew runs, a bump comes only as a chore crew’s planner makes from an item. There the fix key hands the release to millpond as a capture instead, and no agent starts outside crew’s plan.

From sounding

sounding launches the kind question for each sounding. flume makes the place and runs the round’s session in it. sounding keeps the question, its rounds and the operator’s decision on each conclusion (sounding’s book). A sounding waiting on the operator shows as a row in flume’s herdr sidebar.

From crew

crew starts each stage of a unit, a chore or a fix through flume, in a slot of its team, and reads each stage’s end from flume status. It calls flume’s command line, as it calls millpond’s and sluice’s, since crew’s Python uses only the standard library (code.1).

What crew keeps

crew keeps what spans many places:

• plans and bolts;
• slots, which bound how much of a team’s work is in flight;
• the dispatcher, which gives each team its next bolt;
• conductors, which run a team’s work through its stages;
• approvals, the operator’s word on each decision;
• conflicts between units, forecast and settled in the later unit’s place.

crew asks flume for each place and each stage’s agent, as it asks sluice for each landing, and no crew code makes a worktree itself. A unit in crew runs stages flume’s change does not name: a fix round after verify, a settle stage when a conflict reaches it, and a merge stage that archives the change (teams.14, teams.17). Those stages stay crew’s. How their prompts take the form of a kind is on Open questions.

The operator’s surfaces

The operator works flume from whichever surface is at hand: the command line, a Claude Code session, or herdr. flume keeps one plugin per host under plugins/ beside its core, plugins/claude and plugins/herdr, as millpond and sounding keep theirs.

The command line

The Claude Code plugin

• /launch <brief> in every session launches the brief, while the session goes on with its own work.
• status over MCP lets any session read where each place stands.

The herdr plugin

• The sidebar shows every place in flight, with its kind, its stage and its agent’s state, and a change’s tasks ticked.
• Keys open a place’s pane, tell its agent, stop it and retry its stage, and launch from herdr.
• A sounding waiting on the operator shows as a row there, since soundings share flume’s sidebar (sounding’s surfaces).

Where a stage’s agent runs

Each stage’s agent runs in a herdr pane, where the herdr plugin shows it and its keys reach it. Where herdr is not running, flume prints the command that starts the agent, for the operator to run. Either way flume confirms the prompt in the agent’s transcript and reads the stage’s end from its deliverable (Prompt delivery).

Glossary

The words of the design, each defined once. flume has no statement yet, so the capture design (design/capture/design.md) is the binding copy. The words of millpond and of crew that millpond’s book defines are millpond’s book’s, word for word, and a sounding’s words are sounding’s book’s. A number in parentheses cites Flywheel’s statement, and a rule id in backticks cites crew’s docs/architecture/.

Three words mean one thing elsewhere and another here. millpond’s kind is a signal’s type, one of five, while flume’s is a launch’s list of stages. An item’s brief in millpond, and a release’s in headwater, each becomes a launch’s brief when its caller launches it. sounding’s question is what a sounding works, while flume’s is the kind that runs a sounding’s session. Each word keeps its meaning in the book it belongs to.

flume’s words

crew’s words

Words from sounding’s book

sounding’s book defines these, and this page gives its definitions word for word.

Words from millpond’s book

millpond’s book defines these, and this page gives its definitions word for word.

Open questions

What the design does not settle, and where each question is held. A question leaves this page when the operator rules; the ruling lands in the design, and the chapter that rests on it is rewritten whole.

flume’s statement

flume’s statement of invariants, design/flume/requirements.md, is to come (design/capture/plan.md, step L1). It is written from the capture design and from the crew rules flume takes over, teams.1–4, teams.11, teams.15 and plan.9, 10, 12, 17. It states a launch, places, kinds and stages, prompt delivery, stage ends, status, tidying, and what flume never does. A fresh model then reconstructs flume from the statement alone, and the operator rules the questions it asks.

The statement becomes this book’s appendix, and the chapters cite its clauses by number. Until it lands, the chapters rest on the capture design, design/capture/design.md, and cite crew’s rules by id. crew’s record gains an ADR, “crew calls flume for each place and stage”, and the rules flume takes over are amended to name it (plan steps C1 and C7).

The decision awaiting a ruling

The capture design’s decision 12 awaits the operator’s ruling (design/capture/plan.md, step D2). Each chapter states it as the design has it.

12. flume is a standalone tool that launches and tracks one agent in one worktree through a kind’s stages on the host it runs on, taken from crew’s places and stages. millpond’s send, headwater’s fix key, sounding and crew call it; millpond keeps the item’s record and flume the live state of each place (Who launches).

Held by the design

A repository’s kinds

The capture design’s own Open section asks how a repository declares its kinds and their prompts, and how crew’s stage prompts move into that form. crew’s units run stages flume’s change does not name, a fix round, a settle stage and a merge stage (teams.14, teams.17), so the form decides how crew’s work runs on flume (Kinds and stages).

A question’s branch

The capture design gives a question’s place two branch names. flume names a place’s branch <kind>/<name>, which makes a question’s question/<name>. The section on sounding names it sounding/<name>, “which flume makes and runs as the kind question”, and sounding’s guard refuses a submission from sounding/* (sounding’s place). One name stands, or a kind names its branch’s prefix.

Left to the statement

The capture design leaves these details of flume’s open. Where a chapter needed an answer, it takes crew’s, as the rule cited beside each says, and the statement confirms or changes it.

What /launch takes

/launch <brief> names only a brief. Which repository and kind it takes, and the name flume gives its place, are left to the statement, and the same holds for the herdr plugin’s launch key (Who launches).

The rest of flume’s details

• Where the declaration that readies a place lives. The design says “the repository’s own declaration of what a worktree needs”. The chapters take crew’s: the toolchain and the runner’s setup the repository declares for sluice (plan.17).
• A place that cannot be made ready. crew starts a fix’s agent all the same, told the failed step and its words, since a fix is how a broken branch is repaired (teams.3). It refuses a unit’s or a chore’s stage until its place is ready (plan.17). Which kinds start their agent when readying fails.
• Where a place’s branch starts, and its target. A launch names a repository, a kind, a brief and a name, and no branch to start from or land on. millpond’s and headwater’s launches land on the repository’s shared branch, and crew’s on a bolt.
• Deliverables the design does not name. For a fix’s code stage the chapters take a commit made since the stage began, as crew’s settle stage has (teams.14). Where verify’s report sits, and whether a finding verify marks fix runs code once more, as crew’s fix round does (teams.17).
• A change’s submission: whether the stage archives the OpenSpec change on its branch before it submits, as crew’s merge stage does (teams.17).
• How a caller drops a launch. The command line names launch, status, tell, stop, retry and tidy. How a caller marks a launch dropped, so tidying takes its place, as sounding’s drop and crew’s drop of a fix need.
• How crew starts one stage. crew starts each stage of its work through flume and reads its end from status (plan step C7). How it starts one stage in a place flume made, a settle stage or a fix round among them, which no kind names.
• crew’s names. crew names a fix’s branch for its bolt as well as its own name (teams.3), and flume names a place’s branch <kind>/<name>. How crew’s names take flume’s form is settled when crew’s rules are amended (C1, C7).
• flume’s limit: how long a stage stays quiet before flume reports it stuck, and who sets it.
• Reading a question in the pane. crew reads a question open in an agent’s pane from a mark its own hook leaves until the transcript holds the answer (teams.11). flume’s Claude Code plugin, as the design gives it, holds /launch and the status tool and no hook. How flume gets that second reading.
• A printed command: how a stage’s agent started as a command the operator runs carries its prompt, and how flume reads that it accepts input with no herdr pane to read.
• Agents other than Claude Code. flume confirms a prompt, and reads what an agent that stopped short needs, from the agent’s transcript. Flywheel’s statement makes nothing in its machinery depend on one agent program’s transcript (173). Which agents flume starts, and how it reads another program’s record.
• What accept and drop do to a question’s place. sounding’s statement rules what accept does to a sounding’s worktree and branch, and whether drop deletes the branch, and with them when flume tidies a question’s place (sounding’s open questions).
• Launching on another host. flume runs on one host and launches there. How a caller on one host reaches the flume of another, as a crew team on a remote host needs.