--- { "n": 64, "title": "The board's sequences, from goal to done", "abstract": "", "refs": [ "todo:1902", "todo:1901", "message:11382", "message:11377", "doc:63" ], "seen": [ "agent", "user" ], "data": { "environment": "main", "revisions": 1, "open_until": 1790367034.351904, "buttons": [ { "label": "Accept this proposal", "say": "I accept the board sequences proposal", "choice": "answer" }, { "label": "Change it first", "say": "I want changes to the board sequences proposal first", "choice": "answer" } ], "pressed": [ "Accept this proposal" ] }, "created": 1790365197.6663492, "updated": 1790365840.773077, "deleted": 0.0, "completed": 0.0, "outcome": "", "type": "doc" } --- Proposal (message 11382, to-do 1902): the sequences of the agentic board, from the fast filling subagent to the main agent orchestrating after Play. Drafted by Ada Kanbanowski (filling) and Grace Orchestrova (Play to done), each critiqued by the other. ## The shape A board turns a rough goal into the tickets that reach it. Two agents do that, with one hand-over between them. - **Filling**: a fast subagent with a single task. It finds the goal and what "done" means, then drafts the cards that reach it: at least 6, preferably 8. You pick the cards to keep. - **Play**: the main agent becomes the board's orchestrator. It runs the tickets in order, each with its own agent in its own worktree, reviews them and merges them, while staying free for anything else you ask. - **Done**: when the last ticket closes, the orchestrator checks the goal itself, clause by clause, and says whether it is reached. Everything below is a shipped sequence, so every journal gets it on upgrade, and every short one sits on top of the long one, handed first. ## Filling the board Run by the filling subagent, four sequences replacing today's Exploring, Drafting, Revising and Drafting from a document: **Finding the goal** (on a new request; at most three questions) 1. Read the board and its cards, and give a first one-line reading of what you want. 2. If the goal is unclear: one question offering three outcomes, each a result rather than a feature. 3. What "done" means: one question offering three or four finished states ("done when a user can ..."). 4. Only if it changes a card: settle the edges. Then it stores the board's goal and its done-when clauses, numbered. **Drafting the board's cards** 1. Say how many cards are coming: at least 6, preferably 8. 2. Map the work: the core pieces, setup, data and migrations, tests, docs, edge and failure cases. 3. Draft each card (What, Why, Touches, Done when, Risk), naming which done-when clause it serves, and record the order between cards. 4. Check against the goal: every clause is covered by a card; add what is missing, merge what cannot stand alone. 5. Offer two to four groups to pick from, then hand over in one line. **Drafting from a document**: the same, with the goal and clauses taken from the document and no questions; cards the document does not cover are marked as added. **Revising the drafts**: change only the cards you named, then recheck the goal, the minimum of 6 and the order. Once the board has started, a revision goes to the orchestrator instead, so a running card is never changed underneath its agent. A stalled fill (the subagent stops, or nothing is written for about 90 seconds) shows Retry in the panel, keeping the drafts so far. ## The agent types Four custom agent types ship with the journal (Claude Code reads them from .claude/agents/), each with only the tools it needs and its model set from Settings: - **board-filler** (Sonnet by default): runs the four filling sequences. Tools: the shell and reading the attached document. The journal itself refuses any command outside its short list (the board and draft-ticket commands, and stepping its sequence), because an agent file cannot narrow the shell. It loads no skills and never writes in the chat, starts the board or touches files. - **ticket-reviewer** (Sonnet): before a merge, reads the ticket's diff and runs its tests; returns pass or fail per done-when clause, with the file and line as evidence. Read-only. - **plan-reviewer** (Sonnet): used when a board hands plan reviews to a subagent; checks a ticket's plan against its card. Read-only. - **goal-verifier** (Sonnet): at the end, checks each of the board's done-when clauses on the board's branch. Read-only. Reviewers write nothing: every change to the board goes through the orchestrator. The ticket agents themselves are full sessions in their own worktrees, not subagents. For Codex, which I still have to check for named agent types, the same instructions and model go into the dispatch. ## Play When you add the cards, the chat shows one line and a button: "8 cards are in To do. Press Play and I'll run them." If a clause of the goal is left without a card you kept, the line says so: "Without X, *done when ...* won't be met." Pressing Play starts **Orchestrating a board**: 1. **Tell you**, once: which board, how many tickets, that each gets its own agent and worktree and merges into its branch in order, that you are asked only what the orchestrator cannot decide, and that you can keep asking it for anything else. The board's header then reads "Run by the main agent". 2. **Read the board**, and accept the order between the cards (the waits); when auto mode is off, Play first asks you to confirm them. 3. **Start the tickets**. 4. **Hand off**: from here the long sequence only waits, reminded every five minutes rather than every minute, and ends when the board is done. Each ticket's moments arrive as their own short sequences on top of it. ## Running the board Short sequences, three steps or fewer, each started by a moment of a ticket: - **Reviewing a ticket's plan** (its plan waits): read the ticket and plan, check it does the ticket and nothing more, approve it or send it back. Sending back is counted. - **Passing a checkpoint**: check the phase before it, then let it go on. - **Merging a ticket** (its work is finished): the ticket-reviewer runs the tests and checks the diff against the card's clauses; then merge. A failed check sends it back. - **Resolving a merge conflict** (a merge was refused): name the conflicting files and tell the ticket's agent exactly what to rebase onto; its next finish starts a new merge. - **Escalating a ticket** (sent back twice): stop it and ask you: "Let me look", "Rewrite the card" (which the board-filler revises) or "Drop it". Tickets that wait on it stay queued; the rest run on. - **Unsticking a ticket agent** (dead, silent, or idle with nothing running): look at its screen, answer it or restart it; stuck again within 15 minutes goes to the agent-journal agent with the exact command and output, and escalates. - **Pausing a board** (you press Pause): stop the running tickets, keep their worktrees, wait silently until Resume. When two moments arrive together, merges go first, since a merge frees a slot for the next ticket. None of these ever starts your own work inside a ticket's sequence. ## Finishing the board **Closing a board** starts when the last ticket closes: 1. **Check the goal**: the goal-verifier runs the full tests on the board's branch and checks each done-when clause for real: runs it, opens it, reads it. Clauses you chose to leave without a card are marked "left out by choice", not failed. 2. **If it falls short**: the board-filler drafts only the missing tickets, and you are told what is missing; pressing Play again runs them. 3. **Report**: an update card with each clause met or not, what landed on the branch, what was sent back and what was escalated. "The goal is reached" means: every ticket closed and merged, the tests pass on the board's branch, and every clause checked true by the orchestrator, not assumed from the tickets' own checks. ## What the journal needs New in the journal to make this work: - A board **goal** and numbered **done-when** clauses, kept on the board (not in the drafting state, which is cleared), and each card naming its clause. - The four **agent types** shipped with their model from Settings, and the journal refusing the board-filler any command outside its list. - New commands: **board stall** (the filler says it cannot go on), **board pause** and **resume**, **ticket send_back** (counted), and the minimum of 6 in **board expect** (except from a document, or when the orchestrator drafts only what is missing). - New moments: **ticket.conflicted**, **ticket.escalated**, **board.paused**, **board.completed** (the last ticket closed). - A long step that waits is reminded every five minutes, not every minute. - The board's header shows who runs it; the added line carries the Play button. - The New work dialog from Saul's prototype shows the reading line, the goal and the drafts.