Skip to content
flumeflumeflume

flume is designed, not built. Its design book holds the design whole.

flume

flume carries one piece of work into a worktree of its own, runs each stage with a fresh agent, and tidies the place once the work lands.

How it worksRead the designGitHub
flume: one launch, one place, a fresh agent for each stageThree callers stand at the head of the flume: your session’s /launch, millpond’s send and headwater’s fix key. millpond sends item 7 as a change: the launch names the repository ledger, the kind change, the name csv-export, the base main and the brief, export the ledger as CSV. It runs down the flume into its place, a worktree at ledger/places/change--csv-export on the branch change/csv-export, cut from main, which flume makes ready by the repository’s declaration. Four stages light in turn, each with a fresh agent in a herdr pane whose prompt flume confirms in the agent’s transcript: construct ends when the OpenSpec change is written, code when all five of its tasks are ticked, and verify when its report exists. submit’s agent archives the change and submits the branch to main; sluice tests main with the change as merged and lands it, which ends the stage. flume then tidies the place: the worktree is removed, and the branch with it, since it holds nothing main lacks. flume one launch, one place, a fresh agent for each stage LAUNCHED FROM THE PLACE SLUICE TIDY your session /launch <brief> millpond sends item 7 as a change headwater its fix key on a release no launch yet flume launch repository ledger kind change name csv-export base main brief export as CSV csv-export no place yet ledger/places/change--csv-export on change/csv-export cut from main made ready by the repository’s declaration toolchain setup construct waits onthe change the changewritten code waits onevery task 5 of 5 tasksticked verify waits onits report report:0 to fix submit waits onthe landing landed,change archived a herdr pane, for each stage’s agent agent 1 · construct a fresh agent prompt sent: construct… prompt in its transcript wrote proposal, design, tasks committed openspec/changes/csv-export ended: the change exists agent 2 · code a fresh agent prompt sent: code… prompt in its transcript ticking tasks.md as it goes committed the export and its test ended: every task ticked agent 3 · verify a fresh agent prompt sent: verify… prompt in its transcript checked the code against the change ended: the report exists agent 4 · submit a fresh agent prompt sent: submit… prompt in its transcript archived the change wt submit main ended: landed on main ledger/places/change--csv-export removed sluice tests a change as merged testing main + csv-export landed on main main when the work lands or is dropped, flume removes the place it made change/csv-export holds nothing main lacks place removed branch removed 1 A launch: a repository, a kind, brief, name, base. 2 flume makes the place and makes it ready. 3 A fresh agent per stage, ended by its deliverable. 4 The last stage submits; sluice lands the work. 5 flume tidies the place it made.
flume: one launch, one place, a fresh agent for each stageThree callers stand at the head of the flume: your session’s /launch, millpond’s send and headwater’s fix key. millpond sends item 7 as a change: the launch names the repository ledger, the kind change, the name csv-export, the base main and the brief, export the ledger as CSV. It runs down the flume into its place, a worktree at ledger/places/change--csv-export on the branch change/csv-export, cut from main, which flume makes ready by the repository’s declaration. Four stages light in turn, each with a fresh agent in a herdr pane whose prompt flume confirms in the agent’s transcript: construct ends when the OpenSpec change is written, code when all five of its tasks are ticked, and verify when its report exists. submit’s agent archives the change and submits the branch to main; sluice tests main with the change as merged and lands it, which ends the stage. flume then tidies the place: the worktree is removed, and the branch with it, since it holds nothing main lacks. flume one launch, one place, a fresh agent per stage LAUNCHED FROM your session /launch millpond send headwater fix key no launch yet flume launch repository ledger kind change name csv-export base main brief item 7, export as CSV csv-export THE PLACE no place yet ledger/places/change--csv-export on change/csv-export cut from main made ready by the repository’s declaration ready construct working waits on the change the change written code working waits on every task 5 of 5 tasks ticked verify working waits on its report report: 0 to fix submit working waits on the landing landed, change archived a herdr pane, for each stage’s agent agent 1 · construct a fresh agent prompt sent: construct… prompt in its transcript wrote proposal, design, tasks committed openspec/changes/csv-export ended: the change exists agent 2 · code a fresh agent prompt sent: code… prompt in its transcript ticking tasks.md as it goes committed the export and its test ended: every task ticked agent 3 · verify a fresh agent prompt sent: verify… prompt in its transcript checked the code against the change ended: the report exists agent 4 · submit a fresh agent prompt sent: submit… prompt in its transcript archived the change wt submit main ended: landed on main ledger/places/change--csv-export removed SLUICE sluice tests a change as merged testing main + csv-export landed on main TIDY when the work lands or is dropped, flume removes the place it made change/csv-export holds nothing main lacks place removed · branch removed 1 A launch: repository, kind, brief, name, base. 2 flume makes the place, and makes it ready. 3 A fresh agent per stage, ended by its deliverable. 4 The last stage submits; sluice lands the work. 5 flume tidies the place it made.

Why

Section titled “Why”

Every tool that starts an agent on a piece of work meets the same four failures. The agent starts before it can take a prompt, and the prompt is lost. A pane goes quiet while a test runs, and someone takes the quiet for done. A worktree outlives its work, or a branch goes with its worktree while it still holds commits nobody landed. flume handles all four once, for one place at a time, so your own /launch, millpond, headwater, sounding and crew start work the same way.

One launch, one place

A launch names a repository, a kind, a brief, a name and a base. flume makes a worktree on a branch of its own, cut from the base, and makes it ready by the repository’s own declaration of what a worktree needs.

A fresh agent for each stage

Each stage starts a new agent in a herdr pane. flume sends the stage’s prompt once the agent takes input, and confirms it in the agent’s transcript.

Ended by its deliverable

A stage ends when its deliverable exists, or when its agent stops short and says what it needs. A quiet pane ends nothing.

Tidied when it is done

Once the work lands or is dropped, flume removes the place it made. It keeps a branch that holds commits its base lacks.

The name

Section titled “The name”

In a watermill the flume is the channel that carries water from the pond to the wheel, a measured flow to where it does work. In the family, flume carries one item from millpond to one worktree, where an agent does the work. sluice gates what lands, and the Flywheel keeps turning.

Where it stands

Section titled “Where it stands”

flume is designed and not built. Its design lives in agentplot/blueprints with the design of every tool around it, and its statement is written and awaits its ruling. The roadmap says what gets built in what order.

How it worksA launch and its place, kinds and their stages, prompt delivery, stage ends, tidying and status.
How it fitsWho launches through it, what crew keeps for itself, and what flume never does.

Built in the open by agentplot, under the MIT licence.