---
{
  "n": 63,
  "title": "Orchestrating a board, improved",
  "abstract": "",
  "refs": [
    "todo:1876",
    "todo:1877",
    "message:11199",
    "message:11190"
  ],
  "seen": [
    "agent",
    "user"
  ],
  "data": {
    "environment": "main",
    "revisions": 1,
    "open_until": 1790356257.020331,
    "buttons": [
      {
        "label": "Accept option B",
        "say": "I accept option B of the orchestrating proposal"
      },
      {
        "label": "Accept option A",
        "say": "I accept option A of the orchestrating proposal"
      },
      {
        "label": "Change it first",
        "say": "I want changes to the orchestrating proposal first"
      }
    ],
    "pressed": [
      "Accept option B"
    ]
  },
  "created": 1790354432.976976,
  "updated": 1790789677.696262,
  "deleted": 1790789677.696189,
  "completed": 0.0,
  "outcome": "",
  "type": "doc"
}
---
Proposal for the Orchestrating a board sequence (message 11199): what today's run in code-commandments showed, and two ways to improve it.

## What today showed
Orchestrating already is a sequence: "Orchestrating a board" ships with the journal and starts when a board starts. The code-commandments orchestrator ran it all day on board 1, and four things went wrong.

- **It asked the journal agent to operate the board.** When ticket 10 hung, it asked me to press Enter and restart the agent, because nothing in the sequence says it may restart a ticket agent itself. You ruled it may (message 11190).
- **Journal faults and board work were mixed.** The sequence says to report journal faults to the agent-journal agent, but not where that ends. A stuck agent is the orchestrator's to restart; only what a restart does not fix is a journal fault.
- **One step holds everything.** Step 5, "See every ticket through", is a paragraph covering plan reviews, checkpoints, merges and faults, for hours. The orchestrator follows it once and is then on its own; the new nudges cannot help, because there is no smaller step to be nudged about.
- **Nothing is checked before a merge.** The sequence says "finished and reviewed" but not how: no tests run on the branch, no reviewer named.

## Option A: sharpen the one sequence
Keep one lasting sequence and rewrite its steps:

1. **Read the board**, as now.
2. **Set the board up**, as now.
3. **Start the tickets**, as now.
4. **Know your powers.** You may stop and start a ticket's agent yourself when it is stuck (journal ticket stop <n>, then journal ticket start <n>); tell the agent-journal agent only what a restart does not fix, with the exact command and output.
5. **See every ticket through**, split into what to do on each notice: a plan waits (review, approve or send back), a checkpoint (check the phase, continue), work finished (run the board's tests on the branch, have a reviewer read it, merge), an agent stuck (restart it).
6. **Report the board done**, as now.

Small change, same shape; the long step stays long, but it is clearer.

## Option B: a short sequence for each moment
Keep the lasting sequence for reading, setting up and starting the board, and give each moment of a ticket its own short sequence, started by that moment and handed first because sequences now nest like calls:

- **Reviewing a ticket's plan** (starts when a ticket's plan waits): read the ticket and its plan; check it does the ticket and nothing more; approve it, or send it back with what must change.
- **Passing a checkpoint** (starts when a ticket's plan stops at one): check the phase before it; continue the plan.
- **Merging a ticket** (starts when a ticket's work is finished): run the board's tests on its branch; have a reviewer subagent read the diff against the ticket; merge with journal ticket merge <n>, or send it back.
- **Unsticking a ticket agent** (starts when the journal finds one waiting on a prompt, silent or gone): look at its screen; restart it; if a restart does not fix it, report it to the agent-journal agent with the command and output.

Each is two to four steps, so the one-minute nudge and the step hold keep the orchestrator on track, every review and merge leaves a finished run behind as a record, and the lasting sequence's step 5 shrinks to "act on each ticket sequence as it is handed to you". This is the one I would pick.

## What stays the same
In both options the orchestrator does no ticket's work itself, merges only with journal ticket merge, never waits for the user overnight at a checkpoint while auto mode is on, and ends with an update for the user. The sequences ship with the journal, so an upgrade brings them to every project.