Generated from cat-harness/work-plan/skills/work-plan/bean-drain.md — do not edit here. Typed contract: schema reference.

✎ Edit this page’s source

Bean drain

A drain is the delivery loop run over a queue instead of over one item. Each work item in it still goes through the ordinary lifecycle (bean-coordination, todo-manager, continual-progress). What this skill adds is what goes wrong only when several agents drain the same store at once: two of them starting the same work item.

The drain is drawn as a process: Process_BeanDrain (sdlc/processes/bean-drain.bpmn). It builds the queue (the drain-queue Tool), then for each work item calls OPEN (Process_BeanOpen, whose check is the bean-claim-check Tool), works it, calls CLOSE (Process_BeanClose), and refills. The steps below are the same loop in prose.

Roles

roledoesholds
queue keeperbuilds the queue, assigns work items to drainers, refills a drainer that runs drythe queue file
drainertakes the next work item from its own list, checks, claims, works, closesthe work items it claimed

One agent can be both. Drainers are cloud threads and agents on the owner’s own machine, side by side. Each one is told apart by its commit author on the work item branch, never by its own say-so:

agentcommit author on the work item branch
cloud threadsClaude <noreply@anthropic.com>, or litlfred <litlfred@users.noreply.github.com>
agy, the owner’s local Antigravity agentCarl Leitner <litlfred@fenugreek.home>
the state botfolio-state-bot

A new kind of agent joins this table when it starts committing. An author not in the table is treated as “another agent”.

Spawning drainers

A queue keeper that starts drain threads seeds each one as coordinate §”A spawned helper is reachable, and the owner’s authority is not relayed” says: the owner’s words verbatim, no relayed rulings (a merge window included), and a finishable list. Give each drainer this skill and its list, not a copy of the rules.

Three further rules: work leaves up (a parent closes when its last child does), one PR per work item or tight cluster, and scrap obsolete work items with reasons.

1. Build the queue — the drain-queue Tool

Read every work item store, not the one this checkout mounts. Each work item has one home (bean-coordination §”Each bean has one home”): the cat/cat-harness/beans branch on folio-assistant, plus the tools and core layers’ work items on their main. The cat-harness copy of that branch keeps no work items. If two stores ever hold the same id again, bun run cat check:bean-one-home names it; the newest updated_at wins here and the disagreement is listed, so somebody can fix it.

Leave out, each with its reason in the output so nothing vanishes silently:

  • goals and epics (milestone, epic): they close when their children do;
  • blocked: a work item in blocked_by that is still open (bean-blocking);
  • closed or not ready: completed, scrapped, draft;
  • owner-held or parked: the last note says it waits on the owner, a date or a ruling;
  • not drainable here: it needs something the drainers lack (a network host, a person’s account). Route it to an agent that has it instead, and say which.

Group the rest by owner (the thread or agent that already holds work in the same area), in priority order, and write the result to one shared file. Mark the work items other agents hold as skip. Refill a drainer from the deepest queue when it finishes, and refresh the file each time.

The queue is advisory. It says who should take a work item; only a claim says who did. So a drainer still runs step 2 on every work item it takes from the queue.

2. Before each bean: check, then claim — the bean-claim-check Tool

Run this before any work on the work item, including reading code for it. The trigger is starting work, not claiming (bean-coordination §”The trigger is STARTING WORK”).

  1. Refresh every store copy from its remote authority in its own step (never cached from session start; bean-coordination §”Re-derive from the REMOTE”, and work-plan-store-git-branch for the git state-branch fetch).
  2. Read the recent history on the work item, per copy (history(id) in work-plan-store). Skip the work item if another agent wrote to it in the past 24 hours, or its last note says it is claimed.
  3. Look for open work naming the work item: an open PR whose title, body or branch names the id, in every repository the drain touches — the open-work-lookup Tool. Skip if one exists and is not yours. This catches a duplicate that exists only on an open PR’s head, which step 2 cannot see.
  4. Claim: set status: in-progress (update) and append a dated note (note) naming you and your session across every store copy, persisted before any other commit of yours so the next agent’s step 2 sees it.
  5. A write conflict means somebody wrote first: refresh, re-read the work item (get(id) / history(id)), and go back to step 2. Never force-push a state branch (work-plan-store-git-branch).

status: in-progress alone is not a claim you can trust. It goes stale (§”A quiet claim” in bean-coordination), so steps 2 and 3 read activity, not status.

Why every copy must be updated. bun run cat state:push and bun run cat beans:claim write the one store copy the checkout points at. With more than one copy, the others go on saying todo. So while there is more than one copy, the bean-claim-check Tool writes the claim to each copy directly (work-plan-store-git-branch), rather than through a single-checkout state:push. Where a work item has one copy, beans:claim is the claim.

3. Work it

  • Open the PR at the first commit, with Closes-bean: <id> in the body (continual-progress, pr-description). An open PR is the claim every other agent can see without the work item branch.
  • Add the PR’s link to the work item with a dated note, on every copy.
  • Work only the work item you claimed. A cause you find inside it that is a separate piece of work becomes a new work item, and is checked and claimed in its own right.

4. When the bean waits on the owner

Ask through ask-the-person: the full question and every option in the chat first, then the card. Record the question’s link in the work item. Keep the claim while the question is open, and take the next work item meanwhile. A work item that will wait long goes back to todo with the question recorded, so that it does not hold the queue.

When the question is about changed pages, it carries the staging preview: one deep link per changed page, with the same page on main, in the output contract’s stagingLinks field (feedback-deep-links).

5. Close it, and refill

Close on evidence (bean-coordination §”Closing a bean whose work has already landed”), on every copy. Then tell the queue keeper, or take the next work item on your list. A drainer whose list is empty asks for a refill instead of picking from another owner’s list.

Tools

Toolanswerscontract
drain-queuewhich open work items, grouped by owner, with what was left out and whydefinitions.queue in the output schema
bean-claim-checkmay I take this work item; if so, claim it on every copydefinitions.claimCheck
open-work-lookupdoes a path, a path prefix or a work item id appear on main or any open PR head, and wheredefinitions.lookup

Run from an index checkout, with one --copy per work item copy checkout:

bun run cat beans:drain-queue --copy folio-assistant --copy cat-harness --holdings holdings.json
bun run cat beans:claim-check <id> --copy folio-assistant --copy cat-harness \
  --repo litlfred/cat-harness --repo <tools-layer-repo> --session <your session link>
bun run cat lookup:open-work --bean <id> --repo litlfred/cat-harness   # or --path / --prefix

Pass one --repo per repository the work item’s work can land in — for example the harness and its tools layer.

--dry-run on the claim check says what it would do and writes nothing. --json on any of them emits the contract below. The claim check exits 0 when claimed, 1 on a skip and 2 when it could not tell; 2 is never “free”.

The Tools satisfy bean-coordination rather than this skill: this skill’s contract is the whole drain, and each Tool takes one step of it.

Input and output

The contract is input.schema.json and output.schema.json.

  • In: the work item copies to read, the agents and how each is recognised, the owners’ current holdings, the windowHours (24) and the queueFile.
  • Out: the queue (by owner, excluded with reasons, copies that disagree), one claimCheck per work item taken, and what each drainer closed or asked.

Input and output contracts

What this skill takes and gives, as a class diagram drawn from its JSON Schema contracts by the schemas viewer’s own renderer. Each box links to its definition; each type to its specification.

input [1..1]output [1..1]copies [1..*]agents [1..*]results [0..*]pages [0..*]lastTouch [0..1]sources [0..*]byOwner [0..*]excluded [0..*]disagreements [0..*]recent [0..3]copies [0..*]query [1..1]hits [0..*]holdings [1..1]queue [1..1]checks [0..*]bean [1..1]stagingLinks [0..1]id [1..1]at [1..1]refreshedAt [1..1]beans [0..*]spare [0..*]id [1..1]id [1..1]bean [1..1]at [1..1]openWork [1..1]checkedAt [1..1]createdAt [0..1]bean-drain«skill»bean-draininput : BeanDrainInput [1..1]output : BeanDrainOutput [1..1]BeanDrainInput«json-schema»BeanDrainInputcopies : BeanDrainInput.copies[] [1..*]agents : BeanDrainInput.agents[] [1..*]holdings : object [1..1]windowHours : integer [1..1]queueFile : string [1..1]repos : string[] [0..*]BeanDrainInput.copies«json-schema»BeanDrainInput.copiesrepo : string [1..1]ref : string [1..1]defs : string [1..1]BeanDrainInput.agents«json-schema»BeanDrainInput.agentsname : string [1..1]authors : string[] [1..*]self : boolean [1..1]beanId«json-schema»beanIdBeanDrainOutput«json-schema»BeanDrainOutputqueue : queue [1..1]checks : claimCheck[] [0..*]results : BeanDrainOutput.results[] [0..*]stagingLinks : stagingLinks [0..1]BeanDrainOutput.results«json-schema»BeanDrainOutput.resultsbean : beanId [1..1]outcome : "completed" | "scrapped" | "asked-owner" | "re… [1..1]prs : string[] [0..*]question : string [0..1]stagingLinks.pages«json-schema»stagingLinks.pagestitle : string [1..1]before : string [0..1]after : string [0..1]summary : string [0..1]stagingLinks«json-schema»stagingLinksbranch : string [1..1]slug : string [1..1]branchUrl : string [1..1]pr : integer [0..1]mainBaseUrl : string [1..1]stagingBaseUrl : string [1..1]pages : stagingLinks.pages[] [0..*]missing : string[] [0..*]beanId«json-schema»beanIdtimestamp«json-schema»timestampqueueEntry.lastTouch«json-schema»queueEntry.lastTouchauthor : string [1..1]at : timestamp [1..1]agent : string [1..1]queueEntry«json-schema»queueEntryid : beanId [1..1]title : string [1..1]status : "todo" | "in-progress" [1..1]type : "task" | "bug" | "feature" [1..1]priority : string [1..1]lastTouch : queueEntry.lastTouch [0..1]skip : string [0..1]queue.sources«json-schema»queue.sourcesrepo : string [1..1]ref : string [1..1]sha : string [1..1]queue.byOwner«json-schema»queue.byOwnerowner : string [1..1]beans : queueEntry[] [0..*]queue.excluded«json-schema»queue.excludedid : beanId [1..1]reason : "goal" | "epic" | "blocked" | "completed" | "sc… [1..1]detail : string [0..1]queue.disagreements«json-schema»queue.disagreementsid : beanId [1..1]byCopy : object [1..1]used : string [1..1]queue«json-schema»queuerefreshedAt : timestamp [1..1]sources : queue.sources[] [0..*]byOwner : queue.byOwner[] [0..*]spare : queueEntry[] [0..*]excluded : queue.excluded[] [0..*]disagreements : queue.disagreements[] [0..*]claimCheck.copies.recent«json-schema»claimCheck.copies.recentauthor : string [1..1]at : timestamp [1..1]subject : string [1..1]agent : string [1..1]claimCheck.copies«json-schema»claimCheck.copiesrepo : string [1..1]ref : string [1..1]recent : claimCheck.copies.recent[] [0..3]status : string [0..1]claimCommit : string [0..1]pushAttempts : integer [0..1]claimCheck«json-schema»claimCheckbean : beanId [1..1]state : "claimed" | "would-claim" | "skip-recent-commit"… [1..1]copies : claimCheck.copies[] [0..*]openWork : lookup [1..1]reason : string [0..1]lookup.query«json-schema»lookup.querykind : "path" | "prefix" | "bean" [1..1]value : string [1..1]lookup.hits«json-schema»lookup.hitsrepo : string [1..1]where : "default-branch" | "open-pr" [1..1]pr : integer [0..1]head : string [0..1]author : string [0..1]createdAt : timestamp [0..1]match : "file" | "title" | "body" | "branch" [1..1]paths : string[] [0..*]lookup«json-schema»lookupquery : lookup.query [1..1]checkedAt : timestamp [1..1]hits : lookup.hits[] [0..*]unread : string[] [0..*]

Processes that run this skill

This skill has its own process: Drain the beans.

BPMN diagram: Drain the beans


Provenance (11)

Who decided, when, and under which work item. This record was moved out of the text of the page.

Bean drain

  • bean Bean n7x7 Owner 2026-10-24
    Owner, 2026-10-24: "update Skills so on draining beans/stories as part of SDLC and describe Tools for coordination on spawned bean drains". Bean n7x7.
  • bean bean bssi
    The drain is drawn as a process: Process_BeanDrain ([sdlc/processes/bean-drain.bpmn](../../../sdlc/processes/bean-drain.bpmn), bean bssi).

Spawning drainers

  • owner-decision owner's
    A queue keeper that starts drain threads seeds each one as [coordinate](../../../sdlc/skills/sdlc-core/coordinate.md) §"Since 2026-10: a spawned helper is reachable, and the owner's authority is not relayed" says: the owner's words verbatim, no relayed rulings (a merge window included), and a finishable list.
  • bean epic ml9h bean yex5 2026-10-10
    The first multi-lane drain was epic ml9h (2026-10-10, three lanes over three stores). Its lane B stalled on relayed authority, which is bean yex5 and the coordinate section above.

1. Build the queue — the drain-queue Tool

  • date 2026-10-30
    Since 2026-10-30 each bean has one home ([bean-coordination](bean-coordination.md), "Each bean has one home"): the cat/cat-harness/beans branch on folio-assistant, plus the tools and core layers' beans on their main. The cat-harness copy of that branch keeps no beans any more.

2. Before each bean: check, then claim — the bean-claim-check Tool

  • bean bean pomp
    A fetch in the same compound command as the read is not a barrier (bean pomp, case 2). 2.
  • date 2026-10-16
    With more than one copy, the others go on saying todo, and that drift is what the 2026-10-16 store reconciliation had to repair by hand.

The measured case: f1e1, 2026-10-24

  • issue cat-harness-tools#686 cat-harness#502 cat-harness-tools#688 cat-harness#503
    | UTC | what | |---|---| | 07:46:28 | agy's first commit for f1e1 | | 07:47:35 | agy opens [cat-harness-tools#686](https://github.com/litlfred/cat-harness-tools/pull/686) | | 07:49:20 | agy opens cat-harness#502 | | 07:50:08 | a cloud thread's first commit for f1e1 | | 07:50:22 | the cloud thread opens [cat-harness-tools#688](https://github.com/litlfred/cat-harness-tools/pull/688), merged 08:04 | | 07:50:29 | the cloud thread opens cat-harness#503 | | 07:52:57 | agy's first commit to f1e1 on a bean branch |
  • date 2026-10-16
    And step 2 alone would not have helped: both copies said in-progress since 2026-10-16 and showed no new commit until 07:52:57.

Tools

  • bean bean pomp
    | does a path, a path prefix or a bean id appear on main or any open PR head, and where (bean pomp)

As a process

  • bean bean m8gz Bean bssi owner 2026-10-24
    The drain will be drawn as a BPMN process that calls the shared bean OPEN and CLOSE subprocesses (owner choice A on bean m8gz, 2026-10-24): OPEN's check is step 2, CLOSE is step 5. Bean bssi builds it once m8gz lands.

folio-assistant — code under the Apache License 2.0, documentation under CC BY 3.0. Generated schema and API references are rebuilt from source on every push to main.

deployed dev