@lovek4d/kickflip 0.7.0 → 0.7.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CONTEXT.md +43 -43
- package/SKILL.md +12 -10
- package/bin/event-lines.mjs +1 -1
- package/bin/kickflip.mjs +2 -2
- package/board/agents.mjs +2 -2
- package/board/arch-review.mjs +4 -4
- package/board/bin/board.mjs +87 -87
- package/board/domain.mjs +7 -7
- package/board/finish.mjs +4 -4
- package/board/headless.mjs +8 -8
- package/board/hub-lines.mjs +1 -0
- package/board/onboarding.mjs +1 -1
- package/board/public/app-arch.js +1 -1
- package/board/public/app-cards.js +5 -6
- package/board/public/app-header.js +1 -1
- package/board/public/app-lanes.js +37 -59
- package/board/public/app-needs.js +16 -11
- package/board/public/app-reader.js +2 -2
- package/board/public/app.js +2 -2
- package/board/public/dialogs.js +1 -1
- package/board/public/hub-kit.js +1 -1
- package/board/public/hub.css +2 -0
- package/board/public/linear-key.js +1 -1
- package/board/public/new-task.js +1 -1
- package/board/public/prototype-kit.js +2 -5
- package/board/public/router.js +1 -1
- package/board/public/sidebar.css +2 -2
- package/board/public/sidebar.js +2 -2
- package/board/public/style.css +20 -29
- package/board/public/ui-cards.js +19 -17
- package/board/public/ui-hub.js +1 -5
- package/board/public/ui-links.js +5 -5
- package/board/public/ui-order.js +5 -6
- package/board/public/ui-questions.js +12 -10
- package/board/public/ui-threads.js +10 -7
- package/board/public/ui.js +11 -2
- package/board/public/view-hub-settings.js +28 -31
- package/board/public/view-hub.js +7 -9
- package/board/public/view-notes.js +1 -1
- package/board/public/view-questions.js +18 -5
- package/board/public/view-settings.js +3 -3
- package/board/render-check.mjs +10 -10
- package/board/review.mjs +1 -1
- package/board/server.mjs +18 -19
- package/board/stop.mjs +1 -1
- package/board/store.mjs +26 -25
- package/hooks-plugin/hooks/board-data-gate.mjs +6 -6
- package/hub/awake.mjs +1 -1
- package/hub/boards.mjs +4 -4
- package/hub/github.mjs +3 -3
- package/hub/hub.mjs +11 -11
- package/hub/incoming.mjs +2 -2
- package/hub/locks.mjs +1 -1
- package/hub/new-board.mjs +2 -2
- package/hub/owner-checks.mjs +1 -1
- package/hub/try.mjs +6 -7
- package/hub/views.mjs +1 -1
- package/package.json +1 -1
- package/shared/usage-gate.mjs +1 -1
package/CONTEXT.md
CHANGED
|
@@ -55,7 +55,7 @@ The levels back climbs in the app shell: a board, its Waiting on you, then a sep
|
|
|
55
55
|
_Avoid_: nav stack, breadcrumbs
|
|
56
56
|
|
|
57
57
|
**Hub page**:
|
|
58
|
-
The hub's status page, `/_hub/`, which the sidebar's Hub row opens: a pause or Keep going banner at the **pause line**, a banner while pushes are held or snoozed, with End snooze on a snooze, then **usage readings**, then the **pending prompts** of sessions that own no board, **Health**, whose Hub row reads the **hub status** and says Keeping awake
|
|
58
|
+
The hub's status page, `/_hub/`, which the sidebar's Hub row opens: a pause or Keep going banner at the **pause line**, a banner while pushes are held or snoozed, with End snooze on a snooze, then **usage readings**, then the **pending prompts** of sessions that own no board, **Health**, whose Hub row reads the **hub status** and says Keeping awake while Keep awake is on, **Integrations**, then **Boards** and **Pages** with each site's health and each board's hub links and watcher, and on each board a Restart that stops its session, restarts its server and resumes the session ([a board restarts from its row on the Hub page](docs/adr/2026-11-02-1736-a-board-restarts-from-its-row-on-the-hub-page.md)), each session's remembered Always allow rules read-only under its board, polling status, then the **hub settings** summary rows ([a sidebar of every board replaces the hub home](docs/adr/2026-10-29-1639-a-sidebar-of-every-board-replaces-the-hub-home.md), [a background session's prompts and questions come to the phone](docs/adr/2026-10-30-1516-background-sessions-prompts-come-to-the-phone.md)).
|
|
59
59
|
_Avoid_: dashboard, console, hub home
|
|
60
60
|
|
|
61
61
|
**Hub status**:
|
|
@@ -71,9 +71,13 @@ The last reported Claude or Codex usage for its 5-hour and weekly windows, with
|
|
|
71
71
|
_Avoid_: quota, live usage
|
|
72
72
|
|
|
73
73
|
**Pause line**:
|
|
74
|
-
The Usage card's “Pause work at”, last in the group below Codex: `pauseAt` in `~/.claude/kickflip/settings.json`, 50–100 in steps of 5, default 90 (10% buffer); 100 reads Off. Either live Claude window at or over it pauses new work until that window resets
|
|
74
|
+
The Usage card's “Pause work at”, last in the group below Codex: `pauseAt` in `~/.claude/kickflip/settings.json`, 50–100 in steps of 5, default 90 (10% buffer); 100 reads Off. Either live Claude window at or over it pauses new work until that window resets, and a **card pause** stops each running Claude build ("usage limit") until it resets; new agents wait, watchers hold the hub's work events, and owner messages get a brief “paused until <time>”. Keep going lifts that window's pause until its reset; Stop restores it. Codex hands work to Opus builders at the same line, without pausing. The Hub banner and sidebar and board header status slots show the pause, never the logo. Claude's reading joins the status line's with every headless run log's newest `rate_limit_event`. Within twice the buffer of the line the gate is **near**: the board server starts one agent at a time, each once the last has reported its usage, and the Hub banner reads "Approaching usage limit, reducing parallel agents" with its own Keep going. `shared/usage-gate.mjs` owns it; `kickflip usage-gate` prints it ([work pauses at the pause line](docs/adr/2026-11-01-1710-work-pauses-at-the-pause-line.md), [the pause line reads every headless agent's usage](docs/adr/2026-11-06-1249-the-pause-line-reads-every-headless-agents-usage.md), [a card pause stops its builder at its next stopping point](docs/adr/2026-11-09-1300-a-card-pause-stops-its-builder-at-its-next-stopping-point.md)).
|
|
75
75
|
_Avoid_: buffer threshold, quota guard
|
|
76
76
|
|
|
77
|
+
**Card pause**:
|
|
78
|
+
How the board stops a running build without moving its card: blocked, held, the usage pause (the **pause line**, **Pause board** and **Pause hub**, "board paused" or "hub paused" for those two, and a builder that hit its hard limit) and a **bump-out**. The pause sits on the card's open build record (`pause {cause, words}`) and the build stays In Progress. The builder stops at its next stopping point, the reply to its next progress report, call or ask, which tells it to commit and end its turn; one waiting in `builder asks --wait` is already at one, and after 15 minutes the board stops it. The card reads "pausing · blocked by #53" in orange, then "paused · blocked by #53" in grey, its phase bars dimmed at the phase it stopped at, with the thread line "Paused at building: blocked by #53. It resumes once nothing blocks it." A paused build frees its **implementer slot**. Once the cause clears the board writes "Resumed: nothing blocks it." and resumes the builder's own session (`claude --resume`) in its worktree with its record, before the pull starts new cards; a session's builder gets the same reply, and the clear sends `builder-resume` for the orchestrator to tell it to carry on. A cause that clears before the builder stops drops the pause. A **busy Mac** still lets running work finish ([a card pause stops its builder at its next stopping point](docs/adr/2026-11-09-1300-a-card-pause-stops-its-builder-at-its-next-stopping-point.md)).
|
|
79
|
+
_Avoid_: stopped, sent back, suspended
|
|
80
|
+
|
|
77
81
|
**Pause hub** and **Pause board**:
|
|
78
82
|
The owner's manual pause, first in Hub settings and Board settings, with the snooze picker's chips, Forever included, and Custom: until its end (Forever's lasts until Resume) it pauses new work exactly as the **pause line** does, Codex builders included, on every board for Pause hub (settings.json's `paused_until`) and on that board alone for Pause board (board.json's `paused_until`, no board setting). It outranks the usage pause and Keep going, Pause hub first. Resume ends it, and the end wakes the boards with `usage-resumed {window: "manual"}`. It reads paused in gray wherever the usage pause shows: Pause hub on the Hub banner and row and every board, Pause board on its own sidebar row, header and cards ([Pause board and Pause hub pause new work by hand](docs/adr/2026-11-05-1849-pause-board-and-pause-hub-pause-new-work-by-hand.md)).
|
|
79
83
|
_Avoid_: snooze (pushes only), hold (one card)
|
|
@@ -91,7 +95,7 @@ One JSON line for each call the code makes on its own, with when, the call, the
|
|
|
91
95
|
_Avoid_: hub.log (the hub's free-text stderr), history
|
|
92
96
|
|
|
93
97
|
**Board registry**:
|
|
94
|
-
`hub/boards.mjs`, the only hub code that reads a board's `board.json` and
|
|
98
|
+
`hub/boards.mjs`, the only hub code that reads a board's `board.json` and item files. Every hub feature that serves boards (the GitHub check, wakes, rules, the handshake, the not-listening push) takes its boards from it, so a board over the waves and a board over its own file get the same links ([one board registry for every hub feature](docs/adr/2026-10-29-1639-one-board-registry-for-every-hub-feature.md)).
|
|
95
99
|
_Avoid_: board list, wave boards and file boards (as separate code paths)
|
|
96
100
|
|
|
97
101
|
**Site**:
|
|
@@ -153,7 +157,7 @@ A start and end time, 10:00pm to 8:00am by default. With its hold on, pushes que
|
|
|
153
157
|
_Avoid_: overnight window, wake times
|
|
154
158
|
|
|
155
159
|
**Hub settings**:
|
|
156
|
-
The summary rows below the **hub page**’s health and status: **Pause hub** first, then Notifications, Quiet hours,
|
|
160
|
+
The summary rows below the **hub page**’s health and status: **Pause hub** first, then Notifications, Quiet hours, Rules for every board and Closed boards. Each opens its controls in a centred modal with its own scroll area. Snooze and Pause hub share one duration picker: 1h, 3h, 6h, 1d, Forever and Custom. Keep awake, Linear and Slack are not summary rows: they sit inline on the hub page between the boards and these rows ([Keep awake, Linear and Slack sit inline on the Hub page](docs/adr/2026-11-09-2152-keep-awake-linear-and-slack-sit-inline-on-the-hub-page.md)). Keep awake is an on/off toggle that has the hub run `caffeinate -s`, holding the Mac awake only on AC power, and is disabled on hosts other than macOS ([Keep awake is a toggle that holds the Mac awake only on AC power](docs/adr/2026-11-09-1200-keep-awake-is-a-toggle-that-holds-the-mac-awake-only-on-ac-power.md)). Old Hub Settings links open the matching modal over Hub ([hub settings open as modals](docs/adr/2026-11-01-1221-hub-settings-open-as-modals.md)).
|
|
157
161
|
_Avoid_: Hub Settings page, preferences, hub config
|
|
158
162
|
|
|
159
163
|
**Shared person**:
|
|
@@ -199,39 +203,35 @@ A button the owner taps on the board, sent as an event. The board's rule for tap
|
|
|
199
203
|
_Avoid_: action, click
|
|
200
204
|
|
|
201
205
|
**Wave**:
|
|
202
|
-
A set of
|
|
203
|
-
_Avoid_:
|
|
204
|
-
|
|
205
|
-
**Lineup**:
|
|
206
|
-
What the owner calls a wave on a board: a named set of cards from one wave file, in **wave steps** in build order, with a goal and a short note. Only the owner asks for one, with the +, or Claude proposes one as a board question when it spots a grouping in Todo. `board.mjs lineup create --step <keys> --step …` makes each card blocked by every card of the step before and writes the note to `lineup-<slug>.md` beside the wave file; each card stays one PR and starts on its own as it unblocks, so one step's cards build side by side ([a wave builds in phases, and cards in one phase build side by side](docs/adr/2026-11-04-0238-a-wave-builds-in-phases.md)). A lineup made before steps is a chain, one card per step. Todo shows it as a **wave band**. It is open until `lineup finish` or until all its cards are Done ([a wave the owner asks for is a lineup of cards](docs/adr/2026-11-02-1202-a-wave-the-owner-asks-for-is-a-lineup-of-cards.md)).
|
|
207
|
-
_Avoid_: wave (in code and `board.mjs`, where a wave is a wave file), group, epic
|
|
206
|
+
A named set of cards from one **item file**, in build order, with a goal and a short note. Only the owner asks for one, with the +, or Claude proposes one as a board question when it spots a grouping in Todo. `board.mjs wave create --card <key>[:<earlier keys>] --card …` makes each card blocked only by the earlier cards of the wave it would conflict with, and writes the note to `wave-<slug>.md` beside the item file; each card stays one PR and starts on its own as it unblocks, so cards that don't conflict build side by side ([a wave's cards wait only on the earlier cards they'd conflict with](docs/adr/2026-11-09-1321-a-waves-cards-wait-only-on-the-earlier-cards-they-conflict-with.md)). A wave made in steps reads its steps in order and keeps its links. Todo shows it as a **wave band**. It is open until `wave finish` or until all its cards are Done ([a wave the owner asks for is a lineup of cards](docs/adr/2026-11-02-1202-a-wave-the-owner-asks-for-is-a-lineup-of-cards.md); the names are [a lineup is called a wave, and the wave file an item file](docs/adr/2026-11-09-2100-a-lineup-is-called-a-wave-and-the-wave-file-an-item-file.md)).
|
|
207
|
+
_Avoid_: lineup (its old name), group, epic, batch, sprint
|
|
208
208
|
|
|
209
|
-
**
|
|
210
|
-
|
|
211
|
-
_Avoid_: wave
|
|
209
|
+
**Item file**:
|
|
210
|
+
The JSON file a board's cards are stored in, with its title, repo, reviewers and `waves`: on a board over its own cards `data/items.json`, named by board.json `items`, and on a board over `~/.claude/waves` each `<slug>/wave.json` that wave-build writes. A card's key starts with its item file's slug, and code calls it `file` ([a lineup is called a wave, and the wave file an item file](docs/adr/2026-11-09-2100-a-lineup-is-called-a-wave-and-the-wave-file-an-item-file.md)).
|
|
211
|
+
_Avoid_: wave file, wave (for the file)
|
|
212
212
|
|
|
213
213
|
**Wave band**:
|
|
214
|
-
A wave shown inside Todo: one band per open **
|
|
214
|
+
A wave shown inside Todo: one band per open **wave**, then on a board over `~/.claude/waves` one per unfinished **item file**, above Todo's cards in no wave ("No wave"; every other lane groups its cards by wave too, a header per wave with cards there and its x/y/k/z counts across lanes, [docs/adr/2026-11-05-0215-every-lane-groups-its-cards-by-wave.md](docs/adr/2026-11-05-0215-every-lane-groups-its-cards-by-wave.md)). Its head reads its name (the goal as its tooltip, or a long-press popover), its Todo count and its started cards, then "Notes ↗" (an item file has none), then Implement for a wave's next card when it is ready, else "next: #N <why not>". Open, it lists its Todo cards in wave order, each with the board's own blocked-by line, after one "N done" line ([a wave's cards wait only on the earlier cards they'd conflict with](docs/adr/2026-11-09-1321-a-waves-cards-wait-only-on-the-earlier-cards-they-conflict-with.md)). A wave's next card is its first ready Todo card, so its free cards take Implement in turn. Only the first band with a ready next card starts open ([waves are bands in Todo, each with its next card's Implement](docs/adr/2026-11-03-1840-waves-are-bands-in-todo.md)).
|
|
215
215
|
_Avoid_: Waves section, wave bars, wave filter, pills
|
|
216
216
|
|
|
217
217
|
**Wave triage**:
|
|
218
|
-
Claude reading the code for a
|
|
218
|
+
Claude reading the code for a wave's unstarted cards and proposing to split, merge, add or close cards, or to relink a card to the earlier cards it would conflict with, as one open board question per change on topic `wave:<slug>`, which Needs you shows as "<wave> · N questions". For an item file, Claude checks each unfinished card's PR, CI, reviews and blockers, and whether a merged card already covers a Todo card, fixes what it can, and asks one question per card that needs the owner on topic `file:<slug>`. A band's Triage confirms, sends `wave-triage {wave}` or `wave-triage {file}` and reads Triaging… in orange until the session replies to that event, then "Triage: N open questions" in grey while any is open or answered ([a wave the owner asks for is a lineup of cards](docs/adr/2026-11-02-1202-a-wave-the-owner-asks-for-is-a-lineup-of-cards.md)).
|
|
219
219
|
_Avoid_: grooming, refinement
|
|
220
220
|
|
|
221
221
|
**Architecture review**:
|
|
222
|
-
Claude reviewing a board's repo, chosen by `hub/board-repo.mjs` `boardRepo`, with the mattpocock skills: the bulb at the foot of the board, beside the gear, opens a sheet with the last review and Run, which confirms. The board server makes a **
|
|
222
|
+
Claude reviewing a board's repo, chosen by `hub/board-repo.mjs` `boardRepo`, with the mattpocock skills: the bulb at the foot of the board, beside the gear, opens a sheet with the last review and Run, which confirms. The board server makes a **wave** "Architecture <date>", or on a board over `~/.claude/waves` an **item file** of its own, whose first card is its audit card, and wakes the session with `arch-review`. The bulb glows orange while the audit card is open with no question yet. The audit card's Notes are the report, and it asks one question per finding, with possible solutions and Skip; each finding not skipped becomes a card after it. One review is open at a time, so Run while one is open opens its audit card. A board on the running kickflip clone, as the hub board is, has its review cover kickflip's code, the board template and the model, reading the live data only for its shapes. It waits, saying why, while a skill it follows isn't installed ([the bulb runs an architecture review of the board's repo](docs/adr/2026-11-02-1813-the-bulb-runs-an-architecture-review-of-the-boards-repo.md)).
|
|
223
223
|
_Avoid_: improvements round, audit (for the whole review), bulb round
|
|
224
224
|
|
|
225
225
|
**Reviewers**:
|
|
226
|
-
The people who get a board's PR links once they are ready, and the weekday digest. Each board keeps its own in `board.json`, which its Settings modal lists, and a new
|
|
226
|
+
The people who get a board's PR links once they are ready, and the weekday digest. Each board keeps its own in `board.json`, which its Settings modal lists, and a new item file copies them into its own `reviewers`. The board server writes both an add and a remove: an add picks a Slack member and a GitHub login from lists it fetches with the hub's Slack token and `gh`, and the server opens the DM ([the server adds reviewers from fetched lists](docs/adr/2026-11-05-2100-the-server-adds-reviewers-from-fetched-lists.md), extending [the board server removes reviewers itself](docs/adr/2026-11-04-0119-the-board-server-removes-reviewers-itself.md)). Kickflip owns the sent messages per PR, not per card, in each board's `data/pr-slack.json` `{<owner/repo#n>: {head, links: {<name>: {channel, ts, reactions}}, replies}}`: a card holds 1:m PRs, and each PR has 1:m reviewer DMs sharing one thread and one set of reactions. The card, Stale age, hub Slack link and digest read each reviewer's first link across the card's PRs, with an item's older `review_link_ts` and slack-bridge topic files only as a fallback ([Slack sends hang off PRs and go out from the hub tick](docs/adr/2026-11-07-0300-slack-sends-hang-off-prs-and-go-out-from-the-hub-tick.md)). The hub sends them as the owner, through the Slack user token pasted on Hub settings › Slack and kept in `~/.claude/kickflip/secrets.json` beside Linear's key, opening the owner's DM with each reviewer, and records each message as it posts, so a failed one goes again next poll and a posted one never twice ([the hub sends reviewer Slack messages with its own token](docs/adr/2026-11-05-0141-the-hub-sends-reviewer-slack-messages-with-its-own-token.md)). Hub Slack identity lives in `~/.claude/kickflip/slack.json`, read or set by `board.mjs slack`; its timezone sets the weekday 09:00 to 17:00 digest window ([kickflip owns the reviewer record](docs/adr/2026-11-01-2347-kickflip-owns-the-reviewer-record.md)).
|
|
227
227
|
_Avoid_: approvers, watchers
|
|
228
228
|
|
|
229
|
-
**Finished
|
|
230
|
-
|
|
231
|
-
_Avoid_: closed wave, archived wave
|
|
229
|
+
**Finished item file**:
|
|
230
|
+
An item file with work items that are all in Done. Done shows it as one row that opens to its cards, and its **wave band** leaves Todo ([lists never cut silently](docs/adr/2026-10-29-1639-lists-never-cut-silently.md)).
|
|
231
|
+
_Avoid_: finished wave (a wave finishes with `wave finish`), closed wave, archived wave
|
|
232
232
|
|
|
233
233
|
**Work item**:
|
|
234
|
-
One unit of work in
|
|
234
|
+
One unit of work in an **item file**, usually one PR. Its key is `<file>/<id>`. It reads as its ticket when the ticket is from the board's source (`#27`, `ENG-12`, `INT-5`), else as its id, and `item add <file>` takes its id from its ticket ([a card is named by its board's ticket source](docs/adr/2026-11-02-2100-a-card-is-named-by-its-boards-ticket-source.md)).
|
|
235
235
|
_Avoid_: task (a **new task** is the owner's), ticket (the identity of its work in the board’s ticket source)
|
|
236
236
|
|
|
237
237
|
**Ticket**:
|
|
@@ -283,19 +283,19 @@ Similar cards that should be cross-referenced, shown on both cards. The session
|
|
|
283
283
|
_Avoid_: sibling, link (alone)
|
|
284
284
|
|
|
285
285
|
**Split**:
|
|
286
|
-
A card a grill broke into a **
|
|
286
|
+
A card a grill broke into a **wave** of smaller cards: the grill planner proposes it, when the code shows separable parts, as one question, Split as proposed or Keep as one card, and on Split the orchestrator files the cards when the card stages, as Children of the original, which closes Done "Split into …"; a card already in a wave splits into it at its place ([a grill can propose splitting its card into a wave](docs/adr/2026-11-07-1216-a-grill-can-propose-splitting-its-card-into-a-wave.md)). Wave triage's splits are of a wave's cards after filing.
|
|
287
287
|
_Avoid_: breakdown, epic
|
|
288
288
|
|
|
289
289
|
**Plan waves**:
|
|
290
|
-
The Show more row at the foot of Todo, shown when two or more work cards there are neither held nor blocked. Confirming sends `plan-waves {keys}`, and the session triages those cards into one or more
|
|
290
|
+
The Show more row at the foot of Todo, shown when two or more work cards there are neither held nor blocked. Confirming sends `plan-waves {keys}`, and the session triages those cards into one or more waves and asks to confirm each as a board question ([Plan waves plans from any Todo cards](docs/adr/2026-11-03-0509-plan-waves-plans-from-any-todo-cards.md)).
|
|
291
291
|
_Avoid_: backlog item, todo
|
|
292
292
|
|
|
293
293
|
**Done archive**:
|
|
294
|
-
`data/done-archive.json`, where a finished work card goes once 100 newer Done cards close, with its resolved questions and the asks it was made from, unless a
|
|
294
|
+
`data/done-archive.json`, where a finished work card goes once 100 newer Done cards close, with its resolved questions and the asks it was made from, unless a wave band, an unfinished card or an open question still needs it. The board build never reads it. The Done list pages it in 100 at a time as Show more reaches the cards the page holds, each card built as it pages in ([archived Done cards are built as they page in](docs/adr/2026-11-04-1056-archived-done-cards-are-built-as-they-page-in.md)), and a command that names an archived card brings it back to its item file. Its thread stays whole ([the board keeps the newest 100 Done cards, and older ones page in from an archive](docs/adr/2026-11-04-0307-the-board-keeps-the-newest-100-done-cards.md)).
|
|
295
295
|
_Avoid_: history, old cards
|
|
296
296
|
|
|
297
297
|
**Lane**:
|
|
298
|
-
Where a card sits (In Review, In Progress, Todo, Done, Asks), set by who acts next ([the lane follows who acts next, and a card waiting on the owner says Action needed](docs/adr/2026-10-29-1639-the-lane-follows-who-acts-next.md)). In Progress means a card is building: a running build agent, a **checking** item, or a ready PR whose CI is red, or a red draft on a board that **skips the draft**. A work card stores its **lane** (todo, progress, review, done, with `lane_at`), which one writer moves with a "Moved to <lane>: <why>" thread line; a card has no status, and held, blocked, merged and dropped are facts beside the lane ([a card stores its lane, and facts replace statuses](docs/adr/2026-11-07-1400-a-card-stores-its-lane-and-facts-replace-statuses.md)). A work card that has left Todo never drops back to it
|
|
298
|
+
Where a card sits (In Review, In Progress, Todo, Done, Asks), set by who acts next ([the lane follows who acts next, and a card waiting on the owner says Action needed](docs/adr/2026-10-29-1639-the-lane-follows-who-acts-next.md)). In Progress means a card is building: a running build agent, a **checking** item, or a ready PR whose CI is red, or a red draft on a board that **skips the draft**. A work card stores its **lane** (todo, progress, review, done, with `lane_at`), which one writer moves with a "Moved to <lane>: <why>" thread line; a card has no status, and held, blocked, merged and dropped are facts beside the lane ([a card stores its lane, and facts replace statuses](docs/adr/2026-11-07-1400-a-card-stores-its-lane-and-facts-replace-statuses.md)). A work card that has left Todo never drops back to it: held, blocked or **bumped out**, its build takes a **card pause** In Progress ([a card pause stops its builder at its next stopping point](docs/adr/2026-11-09-1300-a-card-pause-stops-its-builder-at-its-next-stopping-point.md), [a card moves to In Progress only once building starts](docs/adr/2026-11-03-0202-a-card-moves-to-in-progress-only-once-building-starts.md)). A running grill or prototype agent shows its status line but leaves the card where it is. In Review means finished work waits on a person: the reviewers, or the owner's review of a draft ("Review draft PR #n", whatever its CI), Merge, manual steps or the Done of an ask (see **Action needed**), or of a reopened card. An owner message or a new question on a Done card, merged or not, reopens it: In Progress until Claude answers, then In Review until the owner's Done, its next step "Tap Done once it is settled" ([a message or question on a Done card reopens it until the owner's Done](docs/adr/2026-11-02-1952-a-message-or-question-on-a-done-card-reopens-it.md), [a merged card reopens on a message, and its PR badge shows the PR's state](docs/adr/2026-11-03-1843-a-merged-card-reopens-and-its-pr-badge-shows-the-prs-state.md), [a card waiting only to be closed has no Action needed](docs/adr/2026-11-03-0137-a-card-waiting-only-to-be-closed-has-no-action-needed.md)). A card waiting only on those moves there from In Progress; one Claude still works on stays in In Progress. A card with several PRs, in any repos, sits where its least-ready PR puts it, shows a PR badge for each, and is Done once every PR has merged or closed with at least one merged ([a card holds several PRs across repos](docs/adr/2026-11-03-1904-a-card-holds-several-prs-across-repos.md)). Todo holds work that hasn't started building: the New cards, which wait on Claude ([the + makes a New card, which Claude files, folds or answers](docs/adr/2026-10-29-1639-the-plus-makes-a-new-card.md)), and every work card with no build yet, where its **Implement** shows. Discussion keeps a card there: open questions or a prototype pick, with Action needed, answered or resolved questions, grill and prototype agents, a working mark on a message in its thread and a prototype recorded for it ([a card moves to In Progress only once building starts](docs/adr/2026-11-03-0202-a-card-moves-to-in-progress-only-once-building-starts.md)). A started card that gets a question keeps its lane ([an unstarted card waits on its questions in Todo, and its one action button follows what it waits on](docs/adr/2026-10-30-1309-an-unstarted-card-waits-on-its-questions-in-todo.md)). Each lane has one fixed order, with no sort menu ([each lane has one fixed order](docs/adr/2026-11-03-0223-each-lane-has-one-fixed-order.md)): every lane but Done lists its bumped cards first, the earliest bump on top ([a bump marks the priority through every lane](docs/adr/2026-11-06-1700-a-bump-marks-the-priority-through-every-lane.md)); Todo then lists the rest oldest made first, so a new card joins the bottom ([new Todo cards join the bottom, so old ones leave first](docs/adr/2026-11-05-2345-new-todo-cards-join-the-bottom.md)); In Progress, after its bumped cards, by when each came into the lane, its reopening or its latest build agent's start, the newest arrival on top; In Review, after its bumped cards, by when the PR was first sent to a reviewer, the newest on top; Done by when each card closed, the most recent on top; Asks, the answered asks in their own lane below Done, by when Claude answered, the newest on top. Done and Asks each show 10 cards, then a Show more, the thread's, that adds 10 and says how many are left; a card the owner has open stays shown ([answered asks have their own section below Done, and Done and Asks show 10 cards at a time](docs/adr/2026-11-03-0259-answered-asks-have-their-own-section-below-done.md)). Every card, a New card included, ends with one muted line holding the time its lane sorts by: the time only today, the day too before today ("10/31, 2:49 PM"), and the year too past 365 days. A card with no such time has no time on that line.
|
|
299
299
|
_Avoid_: column, status (status is the item's own field)
|
|
300
300
|
|
|
301
301
|
**Checking**:
|
|
@@ -307,7 +307,7 @@ A card the board reads as having had no updates for a while, on the signals it a
|
|
|
307
307
|
_Avoid_: stalled (only the orchestrator's flag), old, overdue
|
|
308
308
|
|
|
309
309
|
**Footer status**:
|
|
310
|
-
The words after the time on a card's last line: held, blocked by, Action needed, a grey "
|
|
310
|
+
The words after the time on a card's last line: held, blocked by, Action needed, a grey "held while host recovers", an orange "pausing · <cause>" or a grey "paused · <cause>" in place of held or blocked by ([a card pause stops its builder at its next stopping point](docs/adr/2026-11-09-1300-a-card-pause-stops-its-builder-at-its-next-stopping-point.md)), a red "stalled" or a grey "stale", then the card's **phase** word (every lane but In Progress) or an In Progress card's phase bars, and its unread count (owner, gh327-pause; [every lane has phases](docs/adr/2026-11-11-1200-every-lane-has-phases.md)).
|
|
311
311
|
_Avoid_: time line, status line (the line under the title)
|
|
312
312
|
|
|
313
313
|
**Next step**:
|
|
@@ -320,7 +320,7 @@ _Avoid_: blocked by, assignee
|
|
|
320
320
|
|
|
321
321
|
**Phase**:
|
|
322
322
|
Where a work card is within its lane, stored on the card beside its lane and written with it ([every lane has phases]({ADR})). Todo: new, grilling, prototyping, staging, ready. In Progress: reading, building, testing, checking, landing, shown only as the progress bar. In Review: draft, reviewers, merge, stale. Done: merged, closed. The settle pass writes In Progress and In Review phases from the builder and the PR, a close writes merged or closed, and a phase change inside one lane writes no thread line. Every lane but In Progress ends the card's last line with the phase word, toned by who acts next: grey new, draft, stale, closed; blue grilling, prototyping; orange staging, "pending review", "pending merge"; green ready; purple merged.
|
|
323
|
-
_Avoid_: state (the old name of a Todo card's phase), status (the wave entry's `status` is a different field)
|
|
323
|
+
_Avoid_: state (the old name of a Todo card's phase), status (the wave entry's `status` is a different field)
|
|
324
324
|
|
|
325
325
|
**Todo phase**:
|
|
326
326
|
What a card made from a **New task** does next: **grilling** (questions on the card), **prototyping** (takes on the card), **staging** (the owner has acted: a Send that left it nothing open, an Implement, or a Reply on a ready card, whose words the board wrote into its notes; the orchestrator judges it) or **ready** (its notes leave the owner nothing to decide, so it can be built; the plan lives only in the notes). Only the board sets staging; the session sets the others with `item set --phase`, and ready only from staging, with a `--text` line saying what it checked against the board, or on an Implement ask it files. A finished grill's questions are **screened** first: they wait on the orchestrator, which settles the ones the board already answers, and reach the owner with `question publish` or 15 minutes on ([every signal that wakes the orchestrator says what to do](docs/adr/2026-11-07-0043-every-signal-that-wakes-the-orchestrator-says-what-to-do.md)). A question added on a ready or staging card moves it to grilling. Moving a staging or ready card back to grilling or prototyping starts that round from code ([staging, then ready](docs/adr/2026-11-07-0700-staging-then-ready.md)). The board enforces the four: `--phase` refuses any other, on a card that has left Todo too, and `--state` is refused with a pointer to `--phase`, and ready while the card has an open question. Until it has one, the card reads New beside its ticket id and is never pulled. So does an older card an agent added with `item add` and no `--phase`, which a `card-added` event hands the session to link and file ([the orchestrator links a new card when it files it](docs/adr/2026-11-05-0130-the-orchestrator-links-a-new-card-when-it-files-it.md)); on a board `item add` now refuses a card with no `--phase` ([a board's lessons live in the product](docs/adr/2026-11-06-1700-a-boards-lessons-live-in-the-product.md)). A Ready card's time line reads a green "ready" in Action needed's place ("10:26 · held · ready · 2 new messages") while nothing blocks it and nothing waits on the owner, and the idle pull takes it like any settled card; a staging card reads an orange "staging" there and is never pulled ([a new card is ready, grilling or prototyping, and reads ready in green when it is](docs/adr/2026-11-03-0516-a-new-card-is-ready-grilling-or-prototyping.md)).
|
|
@@ -351,7 +351,7 @@ The session's steps for PR comments, CI, review, conflicts and merging, defined
|
|
|
351
351
|
A board setting, `auto_merge` in its `board.json`, off unless set: on, the hub's GitHub tick merges a PR once it is approved, CI is green and its merge state is CLEAN; off, the card shows the owner Action needed and a Merge button, which reads "Merging…" until the board server merges the PR or says in the thread why it didn't. The board's Settings modal toggles it, and the watcher prints it with every wake as `setting auto-merge on|off`. A setting, not a **rule**, since the board itself acts on it ([Auto-merge is a board setting, off by default, and the owner merges from the card](docs/adr/2026-10-29-1752-auto-merge-is-a-board-setting-off-by-default.md)).
|
|
352
352
|
_Avoid_: merge rule, merge policy
|
|
353
353
|
|
|
354
|
-
A card with no PR lands the same way: with Auto-merge off its builder's `done` stops after the tests, and the card waits in In Review with a Merge button; the tap makes the board server rebase it onto main as it is now, rerun the tests and land it, sending a conflict or a failing test to a headless lander ([a land waits for your Merge](docs/adr/2026-11-04-2100-a-land-waits-for-your-merge.md)).
|
|
354
|
+
A card with no PR lands the same way: with Auto-merge off its builder's `done` stops after the tests, and the card waits in In Review with a Merge button; the tap makes the board server rebase it onto main as it is now, rerun the tests and land it, sending a conflict or a failing test to the card's own builder, its session resumed with the lander's brief, or a fresh headless lander when no session can be resumed ([a land waits for your Merge](docs/adr/2026-11-04-2100-a-land-waits-for-your-merge.md), [a builder resumes to land its own conflict](docs/adr/2026-11-09-1500-a-builder-resumes-to-land-its-own-conflict.md)).
|
|
355
355
|
|
|
356
356
|
**Rebase run**:
|
|
357
357
|
The headless run the board server starts on a card whose open PR, draft or ready, GitHub reads CONFLICTING, once per head and base: in the card's worktree, or one made from the PR's branch, it rebases onto the board's branch, reruns the suite and finishes with `builder done`, which force-pushes the PR's branch with a lease and leaves the PR as it is. The card stays In Review, its status line the run's; one it can't resolve hands the card back with a judgment call, to the orchestrator before the owner. A merge counts the run's push after an approval as trivial when it only replayed the PR's commits, and says so. The GitHub tick no longer rebases ([the board rebases a conflicting PR with a headless run](docs/adr/2026-11-06-0200-the-board-rebases-a-conflicting-pr-with-a-headless-run.md)).
|
|
@@ -395,12 +395,12 @@ The thread line, of kind `build-refused`, the board server writes when it refuse
|
|
|
395
395
|
_Avoid_: Couldn't start the build, build error, failed start
|
|
396
396
|
|
|
397
397
|
**Auto-pull**:
|
|
398
|
-
The board's `auto_pull` setting, off by default, which reads "Auto implement Todo cards" in Board settings' Auto section and turns on or off with no confirmation. On, the board server starts and launches the build of the top **pullable** cards in board order, one per **implementer slot** free, on every board change and at start ([auto implement fills In Progress up to Maximum parallel implementers, on every board change](docs/adr/2026-11-04-0057-auto-implement-fills-in-progress-up-to-a-cap.md)): a pullable card is a Ready, unstarted work card that nothing blocks or holds, with no question open or waiting on Claude, no grill under way and no message a session is working on, taken in Todo's order, bumped first and then oldest first ([the idle pull takes ready cards first, and plans the top card when none is ready](docs/adr/2026-11-03-1631-the-idle-pull-takes-ready-cards-first.md), [a card moves to In Progress only once building starts](docs/adr/2026-11-03-0202-a-card-moves-to-in-progress-only-once-building-starts.md)). The slots are the board's **Maximum parallel implementers** (`max_implementers`, 10 by default, the number beside the switch), less the running implementer agents, one each (a build, a rebase run, a lander, a **helper** that writes), less the pulled cards whose build hasn't started; a running grill or prototype, a read-only helper, an agent blocked on its own helper, and a card waiting in Orchestrator review or on the owner take none ([planners and implementers are two kinds of agent](docs/adr/2026-11-03-1551-planners-and-implementers-are-two-kinds-of-agent.md), [the implementer limit counts agents, and any agent on a card can ask the board for helpers](docs/adr/2026-11-06-0425-the-implementer-limit-counts-agents-and-a-card-spawns-helpers.md)). A helper that writes and is waiting for a slot takes it before the pull, the topmost card's first. New cards are never pulled, nor a card from an ask still New, grilling or prototyping; a Ready one is ([a new card is ready, grilling or prototyping, and reads ready in green when it is](docs/adr/2026-11-03-0516-a-new-card-is-ready-grilling-or-prototyping.md)). A bumped pullable card starts whatever the slots, each one past them **bumping out** a build, and landers and rebase runs take the free slots before the helpers and the pull, a bumped card's past the cap ([a bump marks the priority through every lane](docs/adr/2026-11-06-1700-a-bump-marks-the-priority-through-every-lane.md)). It writes "Pulled in: an implementer slot was free." in the card's thread ([an idle board pulls in its top Todo card](docs/adr/2026-11-02-1754-an-idle-board-pulls-in-its-top-todo-card.md)). Busy board or idle, it also launches a grill on each card that **arrives in Todo**: an open work card in Todo not set Ready or held, with no planner record, no grill or prototype asked for and no questions yet, however it was filed. Up to **Maximum parallel planners** (`max_planners`, 3 by default, the number under the implementers) run at once, less the grills and prototypes running, a bumped card's grill starting past them; the rest wait in board order. Each gets one grill, never a prototype straight away, and the
|
|
398
|
+
The board's `auto_pull` setting, off by default, which reads "Auto implement Todo cards" in Board settings' Auto section and turns on or off with no confirmation. On, the board server starts and launches the build of the top **pullable** cards in board order, one per **implementer slot** free, on every board change and at start ([auto implement fills In Progress up to Maximum parallel implementers, on every board change](docs/adr/2026-11-04-0057-auto-implement-fills-in-progress-up-to-a-cap.md)): a pullable card is a Ready, unstarted work card that nothing blocks or holds, with no question open or waiting on Claude, no grill under way and no message a session is working on, taken in Todo's order, bumped first and then oldest first ([the idle pull takes ready cards first, and plans the top card when none is ready](docs/adr/2026-11-03-1631-the-idle-pull-takes-ready-cards-first.md), [a card moves to In Progress only once building starts](docs/adr/2026-11-03-0202-a-card-moves-to-in-progress-only-once-building-starts.md)). The slots are the board's **Maximum parallel implementers** (`max_implementers`, 10 by default, the number beside the switch), less the running implementer agents, one each (a build, a rebase run, a lander, a **helper** that writes), less the pulled cards whose build hasn't started; a running grill or prototype, a read-only helper, an agent blocked on its own helper, and a card waiting in Orchestrator review or on the owner take none ([planners and implementers are two kinds of agent](docs/adr/2026-11-03-1551-planners-and-implementers-are-two-kinds-of-agent.md), [the implementer limit counts agents, and any agent on a card can ask the board for helpers](docs/adr/2026-11-06-0425-the-implementer-limit-counts-agents-and-a-card-spawns-helpers.md)). A helper that writes and is waiting for a slot takes it before the pull, the topmost card's first. New cards are never pulled, nor a card from an ask still New, grilling or prototyping; a Ready one is ([a new card is ready, grilling or prototyping, and reads ready in green when it is](docs/adr/2026-11-03-0516-a-new-card-is-ready-grilling-or-prototyping.md)). A bumped pullable card starts whatever the slots, each one past them **bumping out** a build, and landers and rebase runs take the free slots before the helpers and the pull, a bumped card's past the cap ([a bump marks the priority through every lane](docs/adr/2026-11-06-1700-a-bump-marks-the-priority-through-every-lane.md)). It writes "Pulled in: an implementer slot was free." in the card's thread ([an idle board pulls in its top Todo card](docs/adr/2026-11-02-1754-an-idle-board-pulls-in-its-top-todo-card.md)). Busy board or idle, it also launches a grill on each card that **arrives in Todo**: an open work card in Todo not set Ready or held, with no planner record, no grill or prototype asked for and no questions yet, however it was filed. Up to **Maximum parallel planners** (`max_planners`, 3 by default, the number under the implementers) run at once, less the grills and prototypes running, a bumped card's grill starting past them; the rest wait in board order. Each gets one grill, never a prototype straight away, and the planner's own status line shows the grill running ([every card arriving in Todo is grilled by the board](docs/adr/2026-11-04-2359-every-card-arriving-in-todo-is-grilled-by-the-board.md), [the hub launches every agent from the card](docs/adr/2026-11-04-2130-the-hub-launches-every-agent-from-the-card.md)).
|
|
399
399
|
_Avoid_: auto-start, idle pickup
|
|
400
400
|
|
|
401
401
|
**Bump-out**:
|
|
402
|
-
What a bumped card that starts past **Maximum parallel implementers** does to the newest unbumped build:
|
|
403
|
-
_Avoid_:
|
|
402
|
+
What a bumped card that starts past **Maximum parallel implementers** does to the newest unbumped build: a **card pause** "bumped out by #61", which keeps the card In Progress with its worktree, branch and record, writes "Paused at <phase>: bumped out by #61. It resumes once a slot frees." once its builder stops, and resumes it before the pull starts new cards. Only an In Progress card with no PR, pushed branch or held Merge, whose one run the board launched and no helper is open, not landing or checking, is bumped out; with none, the bump starts anyway. A busy host holds a bump too, and a bumped ready card reads "held while host recovers" ([a bump marks the priority through every lane](docs/adr/2026-11-06-1700-a-bump-marks-the-priority-through-every-lane.md), [a card pause stops its builder at its next stopping point](docs/adr/2026-11-09-1300-a-card-pause-stops-its-builder-at-its-next-stopping-point.md)).
|
|
403
|
+
_Avoid_: preempted, evicted
|
|
404
404
|
|
|
405
405
|
**Auto-triage**:
|
|
406
406
|
The board's `auto_triage` setting, off by default, which reads "Triage overnight" in Board settings' Auto section and turns on or off with no confirmation. On, once a night from the middle of the hub's quiet hours (03:00 by default) to their end, when two or more cards wait on open questions, nothing builds, usage isn't paused and something changed since the last triage, the board server declares topic `overnight-triage-<date>` ("Overnight triage <date>") and sends `overnight-triage {date, topic, cards}` before any pull. The session merges overlapping questions onto the newest of their cards, resolving the others "Replaced by" it and copying the owner's answer onto each card once it lands; merges duplicate cards; and does the Todo hygiene over the Todo and Stale cards, never Done: duplicates, cards a newer card covers, cards ready to close and stale deps. It asks one question per finding it can't settle on that topic, held until morning by quiet hours, and replies to the event, which lets the pull go ([triage runs once overnight on cards waiting on your answers](docs/adr/2026-11-04-1900-triage-runs-once-overnight-on-cards-waiting-on-your-answers.md)).
|
|
@@ -419,15 +419,15 @@ The owning session's understanding of a work item so far: what was asked, what i
|
|
|
419
419
|
_Avoid_: full plan, plan, spec
|
|
420
420
|
|
|
421
421
|
**Held**:
|
|
422
|
-
A work card the owner paused with its Hold button, which opens the shared duration picker: Forever, until the owner taps Unhold, or until a time, its **pick-up time**. Hold and Unhold apply on the board at once, and the board server writes them to the
|
|
422
|
+
A work card the owner paused with its Hold button, which opens the shared duration picker: Forever, until the owner taps Unhold, or until a time, its **pick-up time**. Hold and Unhold apply on the board at once, and the board server writes them to the item file with the owner's thread line ([the CLI and board server do the board's housekeeping](docs/adr/2026-11-02-2044-the-cli-and-board-server-do-the-boards-housekeeping.md)). It doesn't start, and a running build takes a **card pause** "held" In Progress, until it is resumed (a held Todo card's Build resumes and starts it, [a held Todo card shows Build in place of Unhold](docs/adr/2026-11-03-0234-a-held-todo-card-shows-build-in-place-of-unhold.md)) ([the board applies the owner's Hold, Resume and Done at once](docs/adr/2026-11-02-0009-the-board-applies-the-owners-hold-resume-and-done-at-once.md)). The card's last line reads "held" or "held until Wed 9:00 am" after its time. A card that leaves Todo is never still held: any write that takes it out (a build's start, a hand-back, `--done`, `--pr`, `--pushed`) clears the hold and its pick-up time, and the board shows held only on a Todo card. Every other action-row button, Unhold included, asks to confirm first, through `B.confirm` (`dialogs.js`).
|
|
423
423
|
_Avoid_: paused, frozen, on hold (as a status name)
|
|
424
424
|
|
|
425
425
|
**Blocked**:
|
|
426
|
-
A work card that waits on something concrete before it can start: other cards (its deps, until each reaches Done), or a condition an agent can check, which the orchestrator clears with `item set --blocked-until ""` once it holds, either with a reason. Its time line reads "blocked by #53" or "blocked until <condition>", then ", <reason>". A time is a hold, never a block ([nothing waiting on the orchestrator is missed](docs/adr/2026-11-05-2358-nothing-waiting-on-the-orchestrator-is-missed.md)). Blocked In Progress, a card
|
|
426
|
+
A work card that waits on something concrete before it can start: other cards (its deps, until each reaches Done), or a condition an agent can check, which the orchestrator clears with `item set --blocked-until ""` once it holds, either with a reason. Its time line reads "blocked by #53" or "blocked until <condition>", then ", <reason>". A time is a hold, never a block ([nothing waiting on the orchestrator is missed](docs/adr/2026-11-05-2358-nothing-waiting-on-the-orchestrator-is-missed.md)). Blocked In Progress, its build takes a **card pause** and the card stays In Progress ([a card pause stops its builder at its next stopping point](docs/adr/2026-11-09-1300-a-card-pause-stops-its-builder-at-its-next-stopping-point.md)); blocked In Review, it stays but can't land, its Merge disabled ([a block past Todo bumps a build and holds a land](docs/adr/2026-11-06-0102-a-block-past-todo-bumps-a-build-and-holds-a-land.md)).
|
|
427
427
|
_Avoid_: held (a pause, not a dependency), waits on (who the card waits for)
|
|
428
428
|
|
|
429
429
|
**Pick-up time**:
|
|
430
|
-
When a card held until a time resumes itself: `pick_up_at` in its
|
|
430
|
+
When a card held until a time resumes itself: `pick_up_at` in its item file (`board.mjs item set --pick-up-at`), or the `until` of the owner's newer `card-hold`. Within a minute of it the board server resumes the card, writes a thread line, and sends `card-unblocked {key, until}` unless a dep is unfinished, so it starts on its own once nothing else blocks it ([a card can be held until a time](docs/adr/2026-11-02-1727-a-card-can-be-held-until-a-time.md)). A bump doesn't skip it; resume the card or change the time to start early. It is separate from a Linear due date.
|
|
431
431
|
_Avoid_: due date, reminder, snooze (for a card)
|
|
432
432
|
|
|
433
433
|
**Builder**:
|
|
@@ -464,7 +464,7 @@ A free-form request or question the owner sends from the board's + button (or by
|
|
|
464
464
|
_Avoid_: ask (in what the owner reads), message, prompt, Waiting for Claude strip
|
|
465
465
|
|
|
466
466
|
**Thread**:
|
|
467
|
-
The conversation on one work item: Claude's reports, builders' status lines, the owner's messages, mirrored GitHub comments, and answers to the item's questions. An In Review card's reply form sends with Reply then Done, which closes the card; a Todo card closes from Close, right of Hold in its actions, and an In Progress card has neither, only Send ([Done shows only in In Review, beside Reply](docs/adr/2026-11-05-1918-done-shows-only-in-in-review-beside-reply.md)).
|
|
467
|
+
The conversation on one work item: Claude's reports, builders' status lines, the board's status lines, the owner's messages, mirrored GitHub comments, and answers to the item's questions. Every line the board (Kickflip) writes is a status line, a mark and at most 100 characters, red when it is a fault, which alone of them counts as unread; only the orchestrator's own words make a message titled Orchestrator, at most 2000 characters ([the board writes status lines, and only the orchestrator writes messages](docs/adr/2026-11-09-1200-the-board-writes-status-lines-and-only-the-orchestrator-writes-messages.md)). An In Review card's reply form sends with Reply then Done, which closes the card; a Todo card closes from Close, right of Hold in its actions, and an In Progress card has neither, only Send ([Done shows only in In Review, beside Reply](docs/adr/2026-11-05-1918-done-shows-only-in-in-review-beside-reply.md)).
|
|
468
468
|
An open card shows its thread's newest 3 messages as it opens, or from its oldest **unread message** when more than 3 messages follow it, at most 10, unread as of when the card opened. Messages that arrive while it is open add below, hiding none. Messages are the owner's, Claude's (replies included) and other people's; builder, status and ask-link lines show among the messages they sit between and don't count. "Show more · N previous messages" at the top adds the next 3 older messages each tap and goes when nothing older is left. The expansion lasts while the card stays open, through repaints and new messages, and closing the card puts it back to 3. A message being edited always shows, with every line after it; one waiting on Claude shows only where the window reaches it.
|
|
469
469
|
An owner message Claude hasn't answered yet ends with **Waiting for Claude…**, or Working on it while Claude is on it. An answer to a question stops waiting once it's acted on: its question resolved after it, a later prototype round on it, or a build started on the card after it ([an answer stops waiting once it's acted on, and a Next set during the card's questions clears](docs/adr/2026-11-03-1313-an-answer-stops-waiting-once-its-acted-on.md)). A batch of the owner's answers in a row in the same state carries it once, under the last answer.
|
|
470
470
|
_Avoid_: comments, chat
|
|
@@ -494,15 +494,15 @@ The one line at the top of a board, above Needs you, naming new tasks Claude ans
|
|
|
494
494
|
_Avoid_: notification, toast
|
|
495
495
|
|
|
496
496
|
**Owner question**:
|
|
497
|
-
A multiple-choice question Claude needs the owner to decide, attached to a topic. A builder's judgement call becomes one. One marked **urgent** blocks a build or a merge and shows alone; Claude resolves a question in the step that acts on its answer ([Needs you gathers what waits on the owner, and a topic's questions are answered on one page](docs/adr/2026-10-29-1639-needs-you-gathers-what-waits-and-questions-answer-on-one-page.md)), except an answer with a note and no option, which resolves its question as it arrives ([a pick with no note settles a prototype round](docs/adr/2026-11-02-1607-a-pick-with-no-note-settles-a-prototype-round.md)), and recording a card's close in the
|
|
497
|
+
A multiple-choice question Claude needs the owner to decide, attached to a topic. A builder's judgement call becomes one. One marked **urgent** blocks a build or a merge and shows alone; Claude resolves a question in the step that acts on its answer ([Needs you gathers what waits on the owner, and a topic's questions are answered on one page](docs/adr/2026-10-29-1639-needs-you-gathers-what-waits-and-questions-answer-on-one-page.md)), except an answer with a note and no option, which resolves its question as it arrives ([a pick with no note settles a prototype round](docs/adr/2026-11-02-1607-a-pick-with-no-note-settles-a-prototype-round.md)), and recording a card's close in the item file resolves each of its questions that has an answer; one with no answer yet stops that write unless forced. The owner's Done still moves the card on the board at once ([the board applies the owner's Hold, Resume and Done at once](docs/adr/2026-11-02-0009-the-board-applies-the-owners-hold-resume-and-done-at-once.md)). Adding a question on the same card or setting its notes file resolves answered questions still waiting on Claude; once a card's Action needed is gone, the board server drops its queued push ([the board records what it knows, and commands make the rule calls](docs/adr/2026-11-03-0003-the-board-records-what-it-knows-and-commands-make-the-rule-calls.md)).
|
|
498
498
|
_Avoid_: poll, decision card
|
|
499
499
|
|
|
500
500
|
**Suggested answer**:
|
|
501
|
-
The option of an owner question the overnight triage is confident the owner already chose, from their answer on another card or their long-running context, never from an ADR or CONTEXT.md. The question shows it pre-checked with a
|
|
501
|
+
The option of an owner question the overnight triage is confident the owner already chose, from their answer on another card or their long-running context, never from an ADR or CONTEXT.md. The question shows it pre-checked with a blue line under its label, "Orchestrator choice: <reason>" (the orchestrator's reason, else you answered this on #N: "<answer>"), and only the owner's Send answers it ([overnight triage suggests your earlier answers](docs/adr/2026-11-04-2200-overnight-triage-suggests-your-earlier-answers.md)).
|
|
502
502
|
_Avoid_: auto-answer, default, recommendation (the grill's own pick)
|
|
503
503
|
|
|
504
504
|
**Topic**:
|
|
505
|
-
The group an owner question belongs to; an item's questions use the topic `item:<
|
|
505
|
+
The group an owner question belongs to; an item's questions use the topic `item:<file>/<id>`. A Done card's topic with no open question is resolved, so it never waits on Claude.
|
|
506
506
|
_Avoid_: category, section
|
|
507
507
|
|
|
508
508
|
**Needs you**:
|
|
@@ -571,7 +571,7 @@ Refs in text that Claude or the owner wrote are linked by the renderer, never by
|
|
|
571
571
|
| `ui-enums.js` | `BoardUI.BUTTON` and `BoardUI.ACTION_KIND`, the **action button**'s enums, shared with `board/domain.mjs`, which runs it in a vm context; load it before `ui-threads.js` and `ui-cards.js`. `view.test.mjs` checks that every action kind makes one button orange and every action button draws |
|
|
572
572
|
| `ui-patch.js` | `BoardUI.applyPatch`, applying the board's patches on the page: cards by key, questions and topics by id, every other part whole when it changed, onHost beside the board ([the board sends per-card patches](docs/adr/2026-11-04-0332-the-board-sends-per-card-patches.md), [the board syncs by change number](docs/adr/2026-11-05-1819-the-board-syncs-by-change-number.md)) |
|
|
573
573
|
| `ui-order.js` | `BoardUI.laneOrder`, the board's order of its items ([each lane has one fixed order](docs/adr/2026-11-03-0223-each-lane-has-one-fixed-order.md)), shared with `board/domain.mjs`, which runs it in a vm context, so a tap the page draws at once lands where the server puts it |
|
|
574
|
-
| `ui-cards.js` | A card's lines, in order: title with its ticket badge, or New chip on an unsorted ask (none once sorted); status with its ETA, grey when the builder is stale; then PR, review and other chips, then the try badge (Visit or Install, with running, failed and stale states); its
|
|
574
|
+
| `ui-cards.js` | A card's lines, in order: title with its ticket badge, or New chip on an unsorted ask (none once sorted); status with its ETA, grey when the builder is stale; then PR, review and other chips, then the try badge (Visit or Install, with running, failed and stale states); its wave's grey wave chip; last the time its lane sorts by and its footer status: its hold, blocked by, Action needed, staging, ready, stalled or stale, an In Progress card's phase bars and its unread count; the Hold sheet's picker; and at its top right a New card's bump, edit and delete icons, or another bumpable card's bump icon, filled orange once bumped; and the action row's Merge and Serve/Build buttons, main's bar and build wording |
|
|
575
575
|
| `ui-progress-bar.js` | `BoardUI.progressBar({count, done, now, percent, dim, label})`, the one progress bar every bar draws from: an In Progress card's five build phases and a Todo card's planner dashes (`ui-cards.js`), and a starting board's three start steps (`ui-sidebar.js`); done steps filled, the one step at index `now` pulsing (none when dim), a `percent` filling the next. `BoardUI.onePulse`, listening for `animationstart`, puts every pulse on the page, bars and status dots, on one clock ([a progress bar pulses one step at a time](docs/adr/2026-11-06-0038-a-progress-bar-pulses-one-step-at-a-time.md)). Needs nothing else: `hub/hub.mjs` renders the app shell's first sidebar with it in a vm context; load it before `ui-cards.js` and `ui-sidebar.js` |
|
|
576
576
|
| `ui-sidebar.js` | `BoardUI.sidebar`, the sidebar's markup from `/_hub/sidebar.json`, with the New version row from `updateRow`, Reload or the npm update's Upgrade, headed by `BoardUI.header` itself, with each row's key in **switch mode**; `switchKeys`, which row each key opens; `othersWaiting`, for the logo's label; `shortcuts`, the **shortcuts sheet**'s content from the one list of shortcuts; and `startCaption`, a starting board's step and seconds. Needs `ui-progress-bar.js` and `ui-page-header.js` loaded before it: `hub/hub.mjs` renders the app shell's first sidebar with all three in a vm context |
|
|
577
577
|
| `sidebar.js` | Painting the sidebar from the copy written into the shell, else this device's last copy, then from each copy the hub's stream sends; this device's push subscription for its Turn on row; the logo's toggle, the drawer and its swipes, the rail's collapse, which this device keeps, and the logo's label; **switch mode**'s keys, from the document and a framed page, each row opened through the shell; the **shortcuts sheet**'s h h and Escape |
|
|
@@ -580,9 +580,9 @@ Refs in text that Claude or the owner wrote are linked by the renderer, never by
|
|
|
580
580
|
| `shell.js` | `AppShell`: the hub code check that shows New version with an owner-tapped Reload, the sidebar mounted once, one view at a time, asking before leaving an unsaved edit, `/`'s pick of a board, the hub's one stream and which left boards are unchanged, a framed page's URL and title copied to the top, a push tap from `hub/sw.js` or a framed page's view URL (`AppShell.open`) routed in place, and registering `hub/sw.js`, which opens the shell while the host is asleep |
|
|
581
581
|
| `view-settings.js` | Board Settings as a modal over its board, which shell.js mounts: repo and branch (Change uses the same list and GitHub link search as New board), | `view-settings.js` | Board Settings as a modal over its board, which shell.js mounts: repo and branch (Change uses the same list and GitHub link search as New board), ticket source, auto-merge, auto-build, auto-pull (Auto implement Todo cards) with Maximum parallel implementers and planners, auto-triage, reviewers, rules and Close board with its typed-name sheet |
|
|
582
582
|
| `view-questions.js` | Waiting on you as a view: a topic's questions, a prototype question's View prototypes link to its viewer, each question's eye, which asks for a prototype of that question, and one Send, which stays while the topic has a question open and otherwise opens the next topic with one, or goes back to the board |
|
|
583
|
-
| `view-notes.js` | One item's notes, or with `?wave=` a
|
|
583
|
+
| `view-notes.js` | One item's notes, or with `?wave=` a wave's goal, order and note, as a view, from `GET /api/notes`; the server redirects `plan.html` to `notes.html` |
|
|
584
584
|
| `view-hub.js` | The **hub page** as a view, from `/_hub/api/hub`, refreshed every 30 seconds while it shows; the Usage card, whose Claude model posts `/_hub/settings/claude-model`, Codex share posts `/_hub/settings/codex` and pause line posts `/_hub/settings/pause-at`, with Keep going and Stop banners posting `/_hub/settings/keep-going`, pending prompts of sessions with no board, Send now, then `view-hub-settings.js` below its status |
|
|
585
|
-
| `view-hub-settings.js` |
|
|
585
|
+
| `view-hub-settings.js` | Keep awake’s checkbox row and Linear’s and Slack’s slots (`linear-key.js`) inline at the root of the hub page, then summary rows opening **hub settings** modals over it, from `/_hub/api/settings`: Notifications with Snooze, Pause hub with their one duration picker (`durationPicker`: chips and a native Custom picker), Quiet hours, Rules for every board and Closed boards with Reopen |
|
|
586
586
|
| `linear-key.js` | `LinearKey`, Hub’s Linear key slot: the masked key or why it doesn’t work, the link to where keys are made, saving on paste, change or Enter with Remove, and the same slot as a modal over Board Settings or New board, which the Tickets control opens when Linear is tapped without a working key |
|
|
587
587
|
| `ui-hub.js` | `HubUI`, the hub views' pure renderers: rows, tiles, the flash, the Now row, this device's row, pause banners and the Usage card with the pause line stepper and ticks |
|
|
588
588
|
| `hub-kit.js` | `HubKit`, what the hub views share: `live` (load, the header's time and ↻, the 30-second refresh), `forms` (posting a hub form for JSON, and saving a toggle or time on change) and `device` (this device's push subscription) |
|
|
@@ -604,14 +604,14 @@ Refs in text that Claude or the owner wrote are linked by the renderer, never by
|
|
|
604
604
|
| `rules-editor.js` | `RulesEditor`, the rules list on Board Settings and the Hub page, with its own CSS; `ui.test.mjs` tests its pure parts |
|
|
605
605
|
| `app-threads.js` | Loading a thread, once at a time per card; an open card's thread, its reply box, quick replies and its send buttons |
|
|
606
606
|
| `app-cards.js` | Cards, their open detail with the details list ending in Notes ↗ · Visit/Install ↗ · Review on GitHub ↗ when present, and the workflow row: Merge, Hold, the **action button**, Serve/Build and rightmost **Implement**, each confirming but Hold, which opens its sheet with the duration picker; try requests, failure-thread links and main’s failed-build log and Retry sheet; the bump icon's bump and unbump, with no confirmation; an ask's detail shows only its action button; the thread's Done confirmation and send |
|
|
607
|
-
| `app-lanes.js` | Lanes, Done's and Asks' Show more, Done's finished-
|
|
607
|
+
| `app-lanes.js` | Lanes, Done's and Asks' Show more, Done's finished-item-file folds, Todo's **wave bands** with their Implement and Triage, and Plan waves |
|
|
608
608
|
| `new-task.js` | The + button, its new-task sheet and press-n-twice shortcut, on every page of a board |
|
|
609
609
|
| `app-asks.js` | Bump, edit and delete for a New card or pending message, and ⌘↵ in a thread box |
|
|
610
610
|
| `app-needs.js` | The Needs you box, led by the board session's pending prompts |
|
|
611
611
|
| `ui-prompts.js` | A pending prompt's Needs you line: its details, Allow once, Always allow and Deny, or a question's options, Skip and Send |
|
|
612
612
|
| `prompts.js` | `PromptAnswers`, answering pending prompts from their lines on a board and the hub page: which taps send at once, Always allow's confirmation, and the picks a Send waits on |
|
|
613
613
|
| `app-arch.js` | The bulb at the foot of the board and its **architecture review** sheet: the last review, Run with its confirm, what a review waits on, and the bulb's glow while one runs |
|
|
614
|
-
| `app-reader.js` | The **reader sheet**: a run's transcript from its View transcript link (the whole run as rows, each tool call's output on a tap, or the raw log; following it as it grows) and a card's or
|
|
614
|
+
| `app-reader.js` | The **reader sheet**: a run's transcript from its View transcript link (the whole run as rows, each tool call's output on a tap, or the raw log; following it as it grows) and a card's or wave's Notes, opened over the board from their links, closing on ✕, Escape, the dim area or Back |
|
|
615
615
|
| `app-banner.js` | The answer banner, its tap and its ✕ |
|
|
616
616
|
| `app-header.js` | The board's header controls and time, refresh, the offline state, the In Review header's GitHub line, the Hub links sheet and the setup checklist |
|
|
617
617
|
| `app-snapshot.js` | Reading and saving the last visit in IndexedDB, also as the view unmounts, with its change number for `app.html`'s first board request, the flash when the catch-up lands, and each card's sign: the flash on a card that changed lanes or took a New task's place, and the tint on a card otherwise updated, unless the owner changed it from this page |
|