my-pi-agent

board — one shared feature board per repository

The board is one list of features for a repository, worked by every session on it. A card carries what kind of work it is, its owner, its priority, what it waits on, the contract it promises, and the notes that explain it — and two signatures are needed before it can ship.

The board page: a toolbar with the repository's name, the live state, theme and keyboard controls; Board and Team tabs, a ten-cell done gauge and a filter; five lane columns with counts and fold controls; and note-shaped cards as tall as they draw, tinted by the lane they sit in and separated by space rather than rules, each carrying its number and kind, its title, its path hints, the state it owes somebody, and on its last line whose it is with its age and history

  • One board per repository, one page: the first /board serves it, every other session opens it.
  • The page is a view, and it follows the files: nothing is claimed, moved, or signed from a browser, and a card another session writes reaches an open tab as it lands, wearing a mark.
  • Two signatures: the lead approves a contract before execute and spot-checks the work before done; the person at the keyboard can give either, with /board approve and /board review.
  • The lane is the record, and a session is told once which cards are its own, with what each owes.
  • Steps stay out of it — they live in the owner’s plan and todo.

What you can do

What you want What to do
See the board /board — Board and Team tabs, live
Put a feature on it board add "<title>" paths ["src/area"]
Say what kind of work it is type on add or edit: feature, bug, refactor, docs, test, or chore
Flag a breaking change breaking: true on add or edit; false clears it
Take a card board claim 4 — into plan, owned by this session; board reclaim 4 takes one back, from a peer only once that owner’s record says it stopped
Record what it promises board contract 4 path <plan file> goal … acceptance … scopeOut … verify …
Approve the contract /board approve 4 as the person, or the lead with the board action approve
Start the work board move 4 execute
Park a card board move 4 blocked blocker decision blockedBy "waiting on the API owner"
Sign off finished work /board review 4, then board move 4 done
Explain something board note 4 "why the retry is capped at three"
Set finished work aside /board archive
Read the round board list round: true, or /team — owners, unassigned, unplanned, awaiting approval, awaiting review, blocked, done

Try it

Put the billing webhook's order acceptance on the board, under src/billing.

The model calls board({ action: "add", … }) and then, when you say so, board({ action: "claim", card: "1" }). Those are tool actions, not commands: you type only /board archive|approve|review|status|stop|team.

The claim’s result names the next step, and /board approve 1 refuses until the contract names a plan file in this repository’s store. A claim also joins the team (team).

A card is as tall as it draws. The line above its last one says what it owes — contract ready — needs approval, what it waits on — and is blank when it owes nothing; a note’s prose stays off the face. The row and board list print that gate in one word, and nothing for a card that owes none.

Reference

Lanes. backlog is the pool nobody holds, plan is where the card is designed and its contract signed, execute is where the work happens, blocked waits on a person, and done is closed. Each move follows the one transition from where the card is; no lane is skipped.

The page. A lane’s width follows the work it holds; five lanes sit side by side (one below 1180px, via the picker), a lane of 24 cards folds, and a card is a note as tall as it draws. The pane is the one scroll box, so a lane is as tall as the board and its head rides the pane’s edge however long a neighbour is. The Team tab draws that same card, no rule between two of them.

Actions. One tool, shaped by action: list, add, claim, release, reclaim, move, note, contract, approve, review, edit, archive, drop. claim, move and assign are refused while plan or execute is full, naming the ways out. reclaim takes a card back to backlog from its holder, the person and the lead always, a peer only while that owner’s record says quiet or gone. move into execute or done re-reads the plan where the write lands: a plan that is gone refuses the move, and the face says its plan is gone. A sign nobody heard reads · not told; saying it again sends it. A contract may name a verify command: review runs it in the board’s tree (the worktree you entered), recording the exit, commit and tree; done refuses a sign with no result, or one older than the card’s write. A refused review runs nothing; an override says why and reads closed by instruction.

Commands. /board serves or opens the page (add team for the Team tab); /board approve <id> and /board review <id> sign as the person; /board archive runs the sweep; /board status prints the seat, repository, port, and tabs; /board stop ends the page.

Who signs. The lead is team.lead in bytefly.json, and the page serves as that name. A project names its own; one that names none lets only the person sign, and /board serves no page it would seat as nobody. A session signs only while it is the lead and never while it holds the card; /board approve and /board review sign as the person, marked person: true. The sign says who heard it — quiet, not listening, or not told — and an untold one is sent again.

Where it lives. ~/.pi/agent/board/<repo-key>/ — a card per file under cards/, with archive/ and ended/ beside it.

Limits

  • done is terminal: a card finished by mistake is dropped and re-added at a new number.
  • Nothing prunes itself: done cards cost a read until archive takes them, which it only does for a card nothing open waits on — and an archived record is closed but for drop.
  • The lead is a name, not an authority: any session can join it, and a lead holding a card can release it, sign it, and claim it again. A gate is a reading, not a permission.
  • Ownership is a session id, not a lock: only session-bus path claims are. A card in execute holds its paths, and a lane change releases only the writer’s — so a peer’s reclaim names what stays held; a card whose owner ended is released by another session’s start, never its own.
  • A card keeps eight lane transitions; an unreadable card file is skipped, and named in the listing.
  • The page sweeps every five seconds for the facts no card file announces — a card gone unwritten, a peer quiet or gone, a plan removed — and scans every second with no watch.

Settings

Key Default What it does
wip.plan 3 Cards a repository may hold in plan at once (1–20).
wip.execute 5 Cards a repository may hold in execute at once (1–20).
team.lead "" The team name whose signature the two gates take. Empty is no lead: only the person signs, and /board will not serve.
team.teammates [] Who is on the team: labels, at most 20 of them. The footer draws a session’s name only when it is one of these, so an empty list draws no chip.

The limits live in board and the names in team, both edited by /bytefly settings (configuration); toggle board to switch it off.

Learn more