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

Askers and surfaces

An asker is whoever asks headwater about a repository: a person, a coding agent, a surface, a recorder or a scheduler. It decides which repository and which tiers to ask about, and when. It never changes an answer by who it is, and never supplies a release or a version order (section 2). A surface is one way an asker reaches headwater.

One core, one answer

The same question about the same repository state and the same held state gets the same answer, whoever asks and through whichever surface (32). Every surface answers from one core, and no surface computes a report, a brief, a due tier or an acknowledgement of its own (33). Nothing headwater reports depends on which surface asked, which recorder will keep it, or which fixer will act on it, and headwater needs none of them to answer (34).

Every answer has one form a program reads, the same through every surface, and that form only ever gains fields (35). A program written against an early answer keeps reading every later one. The form is JSON, given on request (section 9).

SURFACES command line a person, a script Claude Code plugin at a session's start herdr plugin sidebar, popup and key Flywheel plugin an adapter part same question, same state: the same answer (32) one core reports, briefs, due tiers, acknowledgements (33) one answer form JSON that only gains fields (35)
Every surface asks the one core and reads the one form. A person at the command line, an agent in its session and a pane in its sidebar, asking about one repository state, read the same report (S12).

The four surfaces

The Claude Code, herdr and Flywheel surfaces are plugins kept outside the core, as sluice keeps its plugins (section 9), one per host under plugins/ beside the core, plugins/claude, plugins/herdr and plugins/flywheel (design/capture/design.md).

  • The command line answers any question a person or a script asks, rendered for reading or as JSON.
  • The Claude Code plugin notes new releases at a session’s start, and hands a release to a background agent in a worktree of its own. A colleague who opens a session in a repository is told of the newer releases in its favorites tier, with their notes, and nothing in the repository changes (S1).
  • The herdr plugin gives a sidebar row, a popup, and a key that hands a release to a new agent in a worktree. The key hands the release’s brief to flume as a fix, and flume starts the agent that makes the bump and submits it to sluice (design/capture/design.md). A sidebar that asks what headwater holds reaches no source however often it redraws (17). Where sounding is installed, another key opens a sounding on a release that needs judgment (design/capture/design.md).
  • The Flywheel plugin holds one part, an adapter that turns each release into a capture (Releases as captures).

Telling

headwater tells nobody on its own (section 8). A surface tells, when its asker asks: the Claude Code plugin at a session’s start, the herdr plugin when its pane is drawn, the Flywheel plugin’s adapter when millpond runs it. A scheduler is an asker like any other.

Handing a release on

A surface may hand a brief to a fixer, and the change the fixer makes is the fixer’s (36). headwater itself never acts on a release.

In a repository crew runs, the herdr plugin’s key hands the release to millpond as a capture and starts no agent outside crew’s plan (Releases as captures).

Where sounding is installed, a release that needs judgment can go from the herdr plugin’s key to a sounding instead, such as a major version or notes that announce breaking changes. The release’s brief is the sounding’s source. The plugin hands a brief on, as any surface may (36). The sounding works the release as one question in a worktree of its own and ends on a conclusion the operator decides (Deciding a conclusion). The person at the key decides which release needs judgment: headwater judges no release (11) and acts on none (36) (design/capture/design.md).

Still to rule: question 3 and the names of the questions a surface asks, in Open questions.