Roles and how work moves

What happens to a ticket, who does what, and what is waiting on you.

What you need to do

  1. Approve or reject Triage. What the PM and workers file waits there for you. Press Approve or Reject.
  2. Press Start. On a Ready card, when you want that work begun. Or let the Lead start Ready tickets, a few at a time (see The Lead starts tickets).
  3. Answer a worker who is waiting. Click them, then answer in the terminal. See how to tell, because a worker who asks a question in words does not raise a hand.
  4. Decide what a PR asks. Read what the worker wrote and what the reviewer posted. The relay tells the worker about new comments on its PR (see How findings get back to the Dev), so check that they act on what matters.
  5. Merge, then update the relay if needed. Workers are told not to merge. Merge on GitHub, or let the Lead merge a PR that is reviewed and green (see The merge rung). The room does not notice, and merged code is not live until someone pulls it. See Update, after a merge.
  6. Move the task along. In the Tasks panel, set the task to In review, Waiting on you or Done. Nothing else does, and this is what moves the card on the Board. The one other move is Needs you: a card shows in Waiting on you while that list names its ticket. The one exception: when the relay tells a worker about a review, it moves their task to Changes requested, unless the review's verdict says merge (see How findings get back to the Dev).
  7. Stop finished sessions. Click the worker, then Stop this session. Until you do, they keep their desk, unless you let the Lead stop them (see What the Lead stops). Marking a task Done does not stop its worker.
  8. Clean up. Once a task is Done and its worker stopped, Clean up on the task removes its copy of the repo. The branch stays. If the copy holds files git ignores, such as .env, it names them and asks first (see A task).

How to tell what is waiting on you

When a session needs your OK for something, or is waiting on a question dialog, you get all of these:

A question in words raises no hand. If a worker ends their turn with a question, the room sees a finished turn, and the Floor says Ready for a prompt. So read what the "ready" ones wrote. The Board's Waiting on you column helps only in part: it holds a Dev that stopped with no PR, but not one that stopped after it opened a PR.

What you seeWhat it means
At their desk, typingThe session is working, unless the manager is visiting. See the manager. The Floor list is not fooled by the manager, but see the times below when it can be off.
Hand up, in the chairNeeds your OK, or has asked you something in a question dialog. Both say Needs your OK, so click them to see which.
Floor says Ready for a promptTheir turn ended and the session is still open. They may be finished, or they may have asked you something. They hold a desk.
Floor says freeNo session. The desk is open.
Coffee, couch, window, bar table, ping pongQuiet. That is all it says.

A worker playing ping pong is not working and is not asking you for anything. But the session may still hold a desk: check the Floor. Ready for a prompt means there is a session to read and perhaps stop, and free means there is nothing to do. The same goes for coffee and the couch. Any two quiet people but the Lead can start a game, and there is no game if your computer is set to reduce motion.

Times when the picture is off. Work with no new activity for 15 minutes ends by itself, in case an end was missed, so a very long command can look finished. Pressing Esc to interrupt sends the room no word, so the worker looks busy until your next prompt or those 15 minutes. Events sent while the page is closed are dropped. When you reopen it, sessions started here come back in the state the relay last heard, and ones from another terminal wait for their next event. Finish all also makes a working session say Ready for a prompt until its next tool call.

Needs you

The Floor and Autopilot each say what waits on you, in their own way, and they do not always agree. Needs you is one list for you, at the top of the Floor, under the Huddle bar. Its heading has a count, and under it is one line for each thing you need to do, most urgent first. When nothing needs you, it says Nothing needs you now.

Click a line to open what it names: the session at its desk, the PR or the failed CI run on GitHub, or the ticket on the Board. A line about another relay has a Stop button instead. A line about a session that also has a PR has a PR link after it. The page reads the list every 2 seconds.

Each kind of line has one rule. The list comes in this order:

Nothing shows twice for one cause. A session gives at most one line, and so does a task. A task whose Dev already has a line gives none, since answering the Dev is the one move.

The list reads only what the relay already keeps, so it asks gh and git nothing. A red main comes from the last answer the check of main kept. A merge line needs the PR watch to be on, or a huddle report, since only they ask GitHub who may merge. The huddle headline counts this list, and the Board's Waiting on you column holds the tickets it names (see The life of a ticket), so all three agree. A line for a session with no ticket, such as the Lead's, is not on the Board. The relay's side is relay/needs-you.js, with the rules in relay/needs-you-plan.js, and the page's is office/needs-you.js. See GET /needs-you.

The life of a ticket

A ticket is work that exists before anyone starts on it. These are the Board's columns, in order. How the room works draws the same life with every part that takes a step.

  1. Triageyou approve
  2. Readyyou press Start, or the Lead if you let it
  3. Buildingyou, in Tasks
  4. In reviewyou, in Tasks
  5. Changes requestedyou, in Tasks, or a review
  6. Waiting on youwhat Needs you names
  7. Donethe end

Rejected is not a column. Triage and Ready tickets can go there, and it is a folded list under the Board, with Back to Triage on each. From Building on, the Tasks dropdown can set any state in any order, so In review and Waiting on you can be skipped.

ColumnWhat it meansWhat moves it onDo you need to do anything?
TriageThe PM or a worker filed it, and no person has looked yet.You, with Approve, Reject or Merged elsewhere.Yes. It waits for you for as long as it takes.
ReadyApproved, or filed by you with Add ticket, which skips Triage. No worker yet.You, with Start, Reject or Merged elsewhere. Or a Lead you let start tickets.Yes, when you want it built. Start stays off while the ticket is waiting for another; its card names which.
BuildingIt has a task, a copy of the repo, a branch and a worker. It stays here after the worker opens a PR, though the PR's link appears on the card.You, with the dropdown in Tasks.Answer the worker if they need you. Move it on when the PR is up.
In reviewWhatever you decide it means: usually that the PR is up. It gets here if you put it here, or if you set it to Waiting on you and a review of its PR runs. Its card stays in Building while its pipeline is running or failed (see A clean pipeline before review).You, with the dropdown.Read the PR and the review. It also stops counting against the 3 being built.
Changes requestedThe work went back for fixes: you set it there, or the relay did when it told the worker about a review (see How findings get back to the Dev). It has its own column so it does not look like new work.You, with the dropdown.Check the worker is on the fixes, then move it on when they are pushed.
Waiting on youThe started tickets that Needs you names, whatever their task's state: a task you set to Waiting on you, a Dev that waits on your answer, a PR only you may merge, a PR whose automatic review could not start, a Dev that stopped with no PR, or a worker whose session ended with no PR. A card whose task you set to Waiting on you, but that Needs you leaves out, shows where its work is: In review while a review of its PR runs, else Building, as while its Dev is at work or its pipeline is running or failed.You, with the dropdown, or by doing what its Needs you line says.Yes. Do what its Needs you line says.
DoneYou marked the task Done, which frees any ticket that was waiting for this one. Merging does not do this. Or the ticket never had a task: its work merged outside the room, and you gave the PR that merged it with Merged elsewhere. That card links the PR and says "merged outside the room". From you, the relay takes any link of the form https://github.com/owner/repo/pull/12, and does not check on GitHub that it merged or that it is in the ticket's repo. From the Lead, it does check (see Work that merged outside the room). The column shows the latest 8, and Show N older under it shows the rest.Nothing. Setting the task back to another state reopens the ticket, until Clean up removes the task. A ticket done with Merged elsewhere stays done.Stop the worker, then press Clean up on the task. A ticket done with Merged elsewhere has no task, so there is nothing to do.
RejectedYou turned it down. Anything waiting for it stops waiting, and the card says it was rejected. A worker or the PM filing the same title from the same branch gets this ticket back, not a new one, though from another branch it makes a new ticket. You can file it again.You, with Back to Triage.No.

The Board in its own tab. Open in its own tab, at the top of the Board, opens office/board.html with the room's channel and key, so you can keep the whole Board beside the room. It works only on this computer, like the room page. It does everything the Board on the room page does, from the same code (office/tickets.js), and adds:

Cards in both places name the ticket's priority, task state and who has it (see its history). Anyone else the relay has seated on the ticket shows as also with, from the Floor. In the tab, a running session in a card's history says to open it from the room page, since the tab has no terminal. The line above the columns gives the WIP limit, which counts Changes requested as well as Building, as the limit explains. The room page does not ask for the Board. The relay sends it on the event stream the page already holds, once when the stream opens and again only when something a card shows has changed: it looks once a second, and at once after a change made on the Board or with ticket.js. The time a pipeline was last checked is not on a card, so a new check with the same result sends nothing. While that stream is down, the room page asks with GET /tickets every 10 seconds until it is back. The tab asks the relay every 2 seconds and keeps no connection open, so the room page and its terminal keep theirs. On both Boards, a change redraws only the cards whose content changed, matched by ticket id. Every other card, and each column, stays as it was, so where each column and the Board sideways were scrolled stays too. While a picker or text box on a card has focus, the Board does not redraw. It catches up as soon as you leave the control. If the address has no channel or key, the key is wrong, or the relay stops answering, the tab says so at the top, and keeps the last cards it had.

The order of the cards. Each card shows its priority: high, normal or low. Within a column, the cards go high first, then normal, then low, and in work order within a priority. Done shows the latest first, and so does the Rejected list. The relay works the order out each time the Board asks for the tickets, so closing a ticket changes no other ticket. A ticket saved with no priority counts as normal. node relay/ticket.js list prints the tickets in the same order: the open ones first, then the done and rejected ones, the latest first, each line with its status and priority, and (set by the person) at the end when you set its priority or place last.

Reading one ticket. node relay/ticket.js list gives one line per ticket, with no body. node relay/ticket.js show T-5 prints one ticket in full: its id and title, then its status, its priority and who filed it (the person; the session's name and (a session); with the GitHub store, an issue someone opened on GitHub shows their login and on GitHub, such as alice on GitHub; or not recorded when the store kept no filer), then the tickets it is blocked by, each with its status and title, or nothing, and last its body, or (no body). It reads the same list as ticket.js list, so any session that can list tickets can show one, and it changes nothing. The id may be in any case, such as t-5. An id that is not on the Board gets an error that says so and exits with 1.

Folded cards. Done always shows its cards in one closed group, Latest, with its count. Show older is inside it. When Triage or Ready holds 7 cards or more, its cards fold into one group per priority: High, Normal and Low, each with its count, and only the priorities it has. Pick Fold by label, above the columns on the room page and in the Board's own tab, to fold them into one group per label instead, A to Z, then No label. A ticket with two labels is in both groups, so the counts can add up to more than the column holds. The pick is kept in this browser only, and the room page and the tab share it. Every group is closed until you open one. The page keeps the groups you opened in this browser only, so they stay open after a reload, and every other browser starts with them closed. While a filter is on in the Board's own tab, every group is open. A group also opens when it holds a ticket you went to, such as from the Floor or the Waiting on you line. Building, In review, Changes requested and Waiting on you never fold.

Folded sections. On the room page, Activity, the Board, Chat, Tasks and Games each start folded to their title line. The Board's line still shows where tickets are kept, the building limit and Approve all Ready. Press a title to open or close it. The page keeps the ones you opened in this browser only, so they stay open after a reload. Going to a ticket from the Floor opens the Board for that visit without keeping it open. The Board in its own tab never folds.

The PM notes. The relay keeps one notes file per repo for the PM, so what you told one PM is not lost when its conversation is cleared or it is stopped. The file is pm-notes/ in the relay's state folder, named after the repo's main folder with a short code, for example ~/.office-world/pm-notes/shop-1a2b3c4d.md. Every PM asked for that repo, from any of its worktrees, gets the same file. The PM's brief names it, tells the PM to read it first if it is there, to rewrite it before it stops, and to rewrite it again each time you tell it something worth keeping after that: at most 40 lines, each dated, with only what the board and the tickets cannot show, such as your decisions about the product, ideas you parked and why, and what the PM promised you. Like the Lead's notes, they are context, not permission: they copy no ticket or board state, they grant nothing, since any session could write that file, and the PM checks with you any line that reads like a permission. The relay does not write the file itself; a PM that stops before rewriting it leaves the old notes as they were.

The PM-brief eval. A change to the PM's brief can make the PM file worse tickets, and that does not show until a PM runs. So npm test holds the brief to the text the PM-brief eval last judged, which is kept in relay/pm-brief-eval.json. That text is the brief as a PM gets it with Let the PM set the order off, no PM notes and no skills, and with relay/ticket.js for the path. Once the brief changes, that test fails until you rerun the eval with node relay/pm-brief-eval.js --kit DIR. DIR is the eval kit: three test cases, each an idea and a board, the repo notes, and the strict ticket rubric. The eval needs an edd-platform with its suite gate, started with a live model key, at http://127.0.0.1:8021/api unless you give --api. In it, the script makes an agent with the kit's three tests. It adds one version with the brief last judged and one with the brief now, runs each version's whole suite live, and compares the two suites. If a test passed with the old brief and fails with the new one, the eval got worse: the script exits 1 and leaves the file as it was, so npm test keeps failing. Otherwise it writes the new brief and the result, with each test's score and outcome, into the file, and you commit it with the change. Each rerun costs six live runs and six live judge calls. Exit 2 means the eval could not run, such as a missing kit file or an edd-platform it could not reach, and the file stays as it was. CI runs only the check of the text, since it has no edd-platform and no key.

Setting priority and order. A card in Triage or Ready has a priority list and Up and Down. Pick a new priority and the ticket goes last in that priority. Up puts it above the card before it in the same column with the same priority, and Down below the card after it. With a filter on in the Board's own tab, those are the cards you can see, so a move can pass a hidden card. A new ticket goes last in its priority. A rejected ticket that goes Back to Triage keeps its old place. The work order is the Triage and Ready tickets: a Started ticket is not moved and cannot be moved next to. The place is a number on the ticket, its rank, that sorts after priority. A ticket saved before ranks has none, so it keeps its place by its age: the oldest first, as before. Only you can set priority or order, and a PM or Lead you let set it (below). Any other session's token gets 403. A card says who last set its priority or place, such as place set by the PM, priority set by the Lead or priority set by you. A ticket that nobody has set since it was filed says nothing.

Editing a ticket. Until a ticket starts, in Triage or Ready, press Edit on its card to change its title, its body and its priority, then Save. The limits are those of filing one: a title of 1 to 80 characters and a body of up to 8000. Only the fields you changed are sent. A title that another open ticket in the repo has on the same branch is refused, so pick another or use that ticket. For the PM and the Lead, a title you rejected is refused too, so they cannot bring it back by renaming. If someone else changes a field while your form is open, Save leaves it as they set it, unless you changed that field too. A new priority puts the ticket last in that priority, as the card's priority list does. Once a ticket is starting or has started, is done or is rejected, it cannot be edited. The PM and the Lead can edit too, with node relay/ticket.js edit T-5 --title "New title" --body - <<'EOF' (see ticket.js). Neither needs a switch for the title and body, but a new priority needs Let the PM set the order or Let the Lead set priority, and without it the relay refuses the whole edit. When the PM or the Lead changes the title or body of a Ready ticket you approved, your approval goes, since you approved other words: the card says it is not approved by you, and Approve all Ready offers it again. Your own edits keep your approval. No worker or reviewer can edit a ticket. Each edit is a step in the ticket's history, with who made it, when, and which fields changed.

Proposals to replace, merge or close a ticket, or to change its blockers. The PM cannot reject a ticket, and neither the PM nor the Lead can change a ticket's blockers, but both can propose it, and you decide. Four kinds, each for a ticket in Triage or Ready: replace names the tickets that take its place, merge names the one ticket that has the same work, close names none, and blockers gives the whole new list of tickets it waits for, which can be empty. Each can carry a reason of up to 500 characters. The card shows the proposal in one line, such as The PM proposes to replace T-10 with T-18, T-19. Why: Split into two., with Approve proposal and Decline proposal, and in the Board's own tab the ticket is in the waiting line at the top. Nothing changes until you press one. While a proposal waits, the ticket is held back, so Autopilot and the Lead do not start it. When you approve a replace, merge or close, the ticket moves to Rejected, and the Rejected list says replaced by T-18, T-19, merged into T-8 or closed. Its chat channel is archived, as for any rejected ticket. When you approve blockers, the ticket waits for the new list. The relay checks the proposal again when you approve it: a ticket it names that is gone or rejected, a ticket that waits for this one and so cannot block it, or a ticket that has started is refused, and the proposal stays for you to decline. A new proposal on a ticket takes the place of the old one. If the ticket is rejected, marked done or started some other way, its proposal goes. Its history shows the move, or for a start, that the proposal was dropped when the ticket started. The PM and the Lead run node relay/ticket.js replace T-10 --by T-18,T-19 --why 'Split into two', merge T-24 --into T-8, close T-5 or blockers T-19 --blocked-by T-18 (see ticket.js). No worker or reviewer can propose. Each proposal, and your answer, is a step in the ticket's history.

The PM sets the order. With Let the PM set the order on, in Settings under COO and PM, the PM can set the priority and place of a ticket in Triage or Ready with node relay/ticket.js priority T-5 high and node relay/ticket.js order T-5 --before T-4 (or --after T-4), the same rules as your picker and Up and Down. It is off by default. The relay keeps it in the settings file, so it stays off after a restart until you turn it on, and it stays on until you turn it off. The PM's token gets 403 while it is off, for a ticket that is started, done or rejected, and for any move, start or change of base, whether the switch is on or off. If more than one PM is running on the channel, only the one that started last can set the order. The relay's log says each change the PM made. You can still set any ticket's priority or place, and the card then says it was you. Its brief tells it to give each ticket it files a priority, and to order work by the goal in the constitution: stronger checks first, then fewer decisions for you, then a truer room, then looks. With the switch on, the brief tells it to run ticket.js list, place its new tickets among the Triage and Ready tickets of the same priority, reorder Triage and Ready tickets, leave alone any ticket whose priority or place you set last on the Board (the list marks it (set by the person); a ticket you filed with a priority is not marked, and the mark goes once the PM or Lead sets that ticket, so it is not a lock), and end with one short list of what it changed and why. With the switch off, the brief tells it not to run priority or order, and to recommend an order in its reply instead. The relay reads the switch when you press Ask the PM, so a PM asked while it was off still has the brief that says off. Ask a new PM after you turn it on.

The Lead sets priority. With Let the Lead set priority on, in Settings under The Lead, the Lead can set the priority and place of a ticket in Triage or Ready with the same two commands as the PM, node relay/ticket.js priority T-5 high and node relay/ticket.js order T-5 --before T-4. It is apart from Let the Lead move the board: it does not need it, and it does not let the Lead move, start or change the base of a ticket. It is off by default. The relay keeps it in the settings file, so it stays off after a restart until you turn it on, and it stays on until you turn it off. Like Let the Lead stop sessions, it stays on when you make a different session the Lead, and then only the new Lead can use it. The Lead's token gets 403 while it is off and for a ticket that is started, done or rejected. The relay's log says each change the Lead made, and the card says set by the Lead. You can still set any ticket's priority or place, and the card then says it was you. While it is on, the Lead's brief says it may order Triage or Ready tickets with those two commands when you ask, and must never undo a ticket you set, which ticket.js list marks set by the person. While it is off, the brief says nothing of it. Turning it on or off types the brief to the Lead again. Only the brief stops the Lead from setting a ticket you set: the relay does not check it.

The Lead starts a review. With Let the Lead start reviews on, in Settings under The Lead, the Lead can ask the relay for a review of a task's PR with node relay/ticket.js review https://github.com/owner/repo/pull/12. The relay starts the reviewer that Get a review starts on a session with a PR: the same brief, in its own checkout of the PR's latest commit. It takes a desk, shows on the Floor, posts its findings on the PR without asking, and leaves. The PR's Dev is told the review started, as for every review. The relay refuses a PR that is not a task's PR, a PR that a reviewer is already reviewing, an ask when no desk is free, and a PR that has had Automatic reviews per PR (3): the Lead's reviews count with the automatic ones, so the loop stops at the same limit, and the next review is yours. A review the Lead asks for takes the place of a first review that waits for the pipeline, or a follow-up that waits, so the PR does not get two. The Lead's brief says to start reviews this way and never to review in its own session, itself or with a subagent, since the Floor cannot see that. The switch is off by default. While Autopilot is on, the Lead may start reviews as if the switch were on, and Settings says on while Autopilot runs beside it. When Autopilot is off, the switch decides again. The relay keeps it in the settings file, so it stays off after a restart until you turn it on. It stays on when you make a different session the Lead, and then only the new Lead can use it. It does not need Let the Lead move the board, and it does not let the Lead move, start or merge anything. The task's history says the Lead asked for the review, and the ticket's history says the Lead started the reviewer.

Work that merged outside the room. If someone delivered a Triage or Ready ticket's work in a PR the room did not start, press Merged elsewhere on its card, paste the PR link, and press Mark done. The ticket goes to Done with that PR, nobody can start it again, and anything waiting for it is freed. Only you can do this, or a Lead you have let move the board. The relay refuses a PR that already belongs to another task or another ticket, and names it, so one PR cannot close two tickets. When you press Clean up on a task, its ticket keeps every PR the task gave, so those PRs stay refused after the task is gone. If the ticket store cannot keep them, such as a GitHub issue whose note another key signed, Clean up still finishes, and the relay's log says those PRs will not be refused. When the Lead does it, the relay also asks gh pr view about the PR first, and refuses it unless it merged and its repo is one of the GitHub remotes of the ticket's repo, since a Lead can paste the wrong link. If the ticket changes while the Lead's move waits, from one that may not move to Done into one that may, such as from Rejected back to Triage, the relay refuses the move and the Lead moves it again, so no link skips that check. A remote counts by its fetch or push URL, after any insteadOf rewrite in your git config, and a repo renamed since counts under its old name too. A remote through an SSH host alias, such as git@github-work:owner/repo.git, does not count, so mark that ticket Done yourself. It refuses too when gh cannot read the PR. The relay's log line says which PR the Lead gave. Check the link first: Done cannot be undone from the Board.

A ticket that has started cannot be rejected. The only way to end it is to stop the worker and set its task to Done, and that records it as finished, as if the work had been completed. Anything waiting on it is freed and can start, so check those first. Setting the task back reopens it, until Clean up.

Tasks without tickets. New task in the Tasks panel starts work right away with no ticket, so it never shows on the Board. It does show on the board on the brick wall, which lists tasks, not tickets. The wall board also shows a "needs you" note for anyone with a hand up. When there are no tasks at all it shows what each person is doing instead.

Filing. You file with Add ticket. Ask the PM uses the same boxes for your idea. Filing the same title twice from the same branch gives you the first ticket back, and what you typed stays in the form. Only a worker or the PM can make a ticket wait for another, with --blocked-by. The relay refuses a blocker id that no ticket has. A ticket the PM files needs a body with the parts What to build, Acceptance criteria, Blocked by and Out of scope, each at the start of its own line. The relay refuses one without them and names the missing parts. Your tickets and other sessions' tickets can have any body, since a short follow-up does not need four parts. Workers and the PM can have at most 20 tickets in Triage. Which branch a ticket starts from is in Copies of the repo, and branches.

Likely duplicates. Two sessions sometimes file the same work under different titles. So when a ticket is filed, the relay compares it with the open tickets of the same repo, those in Triage, Ready or Started (relay/ticket-twins.js). It takes the words of each title, and the words of each title and body together, and leaves out small common words such as the, to and fix. Two tickets look like the same work when they share at least 2 words and those shared words are at least 40% of all the words in the two, for the titles or for the titles and bodies. For example, Fix the hang in tickets.test.js and tickets.test.js hangs on the github store share hang and tickets.test.js, 2 of their 4 words, so they match. The relay names up to 3, the closest first. This is only a warning: the ticket is filed all the same. ticket.js create prints the likely duplicates under Filed, and says that one of the two should be rejected: the Lead rejects it with ticket.js move, and any other session tells @Lead. When you file with Add ticket, the note under the form names them, and you reject one if it is the same work.

Kind. A ticket can have a kind, which says what sort of work it is: docs, tests, bug, feature, or one you added. A worker or the PM sets it when they file, with --kind, and may use only a kind there is already; ticket.js kinds lists them. You add a kind by giving it to a ticket. A kind is one short word: a lowercase letter, then letters, digits or dashes, up to 24 in all. A ticket filed with Add ticket or without --kind has no kind, and its card says no kind. Until it starts, in Triage or Ready, press Change kind on its card, type a kind or pick one, and press Save (POST /tickets/{id}/kind). An empty box takes the kind away. Only you can change it, and once the ticket starts its kind stays. The COO counts each run under its ticket's kind. Nothing else acts on the kind yet.

Labels. Labels sort a long Board. A ticket can have up to 5, each one short word in the same form as a kind, such as flaky or follow-up. Nothing in the room acts on them: they only fold and filter the Board. Press Labels on a card, type the labels with commas between, and press Save (POST /tickets/{id}/labels). What you save replaces the labels the ticket had, and an empty box takes them all away. The box names the labels in use. You can change labels at any status, since no measure counts them. A card says its labels after its kind. A label is in use while a ticket has it, and the Board offers only those. You add a new one by giving it to a ticket. A worker or the PM can give labels already in use when they file, with --label flaky,follow-up, but cannot add a new one or change a ticket's labels; ticket.js labels lists them. With the GitHub store, labels are kept in the issue's hidden note, not as GitHub labels.

On hold, replaced, and design tickets. Sometimes a Ready ticket should not start yet: you paused it, a newer ticket took its place, or a design ticket is still deciding its shape. You mark it so, and Autopilot and the Lead start none of these until the mark is cleared or the design ticket is done or rejected. You can still press Start yourself. The card says why, such as On hold. Nothing starts it by itself until you clear the mark. or Waiting on design ticket T-15, which shapes it. The rule is heldBack in relay/autopilot-plan.js.

How assignment really works

Who has a ticket, and who worked on it

On the card. Each card on the Board says who has the ticket now, such as with Priya, Dev, or Unassigned. The Dev has it while its task is in Building or Changes requested. In review, the reviewer has it: one running now, or else the latest one. With no reviewer yet, the Dev still has it. While its task is in Waiting on you, you have it. Before it starts and once it is done, nobody has it. If that person's session has ended, the card says (session ended).

In the card's detail. Open a card to see each step, oldest first, with its time: who filed it, who approved it, who started it (you, the Lead or Autopilot), each Dev session, each reviewer with whether you or an automatic review started them, each move, with who made it, and each edit, with who made it and which fields changed: title, body or priority. A step by the Lead names the Lead's person too. Each step that was a session shows:

After /clear or /resume, a Dev or a reviewer is a new session in the same terminal, so it gets a new step with its new id, and the step before it shows that session as ended. A reviewer started after its task's Clean up is still a step on the ticket: the relay finds the ticket from the PR, which the saved history keeps on each reviewer and on each move made once the task had its PR.

There is no web page for a session on this computer, so nothing here links to one. A session's conversation is saved by Claude Code on this computer, and the Board does not show it.

Where the names come from. The relay names each session it seats (see Which person gets it). It keeps each name against the session's id when it arrives, in RELAY_TICKET_HISTORY_FILE. So a reload, another tab and a relay restart show the same names, and a session that has ended keeps its name. A session the relay never named shows its role with no name recorded.

What is kept. The history is kept apart from the task, so it stays through a relay restart and through Clean up, which removes the task. A ticket from before histories were kept shows only what its ticket and task still say: who filed and approved it, who started it, the Dev's session and the task's moves. A step with no time recorded says time not recorded, and no names are guessed.

Who does what

WhoWhat they doWhat they cannot do
YouFile, approve, reject and start tickets. Move tasks. Answer workers. Merge, and take back the Lead's right to merge with a PR. Stop and clean up. Give the Lead each of its permissions, and take them back.Type into a session started from another terminal. You can only watch those.
The LeadWatches open PRs and the board, passes decisions along, checks that Devs act on the reviews the relay gives them (see How findings get back to the Dev), keeps tickets moving, marks PRs ready to merge with a note and a label, tells you what is waiting on you, and checks claims against the code and the pipeline before calling work ready. With the permissions you give it, it also moves the board, merges under the merge rung, stops sessions, starts tickets and starts reviews of a task's PR. See The Lead.Take ticket work: it is told not to. Clean up a task, or start sessions, except the worker for a ticket it starts and the reviewer of a task's PR it asks the relay for. Review code in its own session: it is told not to. Do any of the moves in The Lead that you have not let it do. Set a ticket's priority or place, unless you turned on Let the Lead set priority, and then only for tickets in Triage or Ready.
A Dev (task worker)Builds in their own copy of the repo, on their own branch. Is told to push and open a PR against the ticket's base, with a title that starts with the ticket number and a colon, as in T-12: A help page on how work moves, and can list and file tickets. Is told to file a ticket with its body on stdin in a quoted heredoc. A task with no ticket, from New task, has no number, so its brief does not ask for one. Is told to run npm run lint before it pushes and do what its messages say, and never to change eslint.config.js, eslint-local.js or eslint-suppressions.json to pass it. Is told to keep CLAUDE.md and docs/constitution.md out of its PR, so Autopilot can merge the code (see CLAUDE.md and constitution updates).Move the board or approve their own ticket. Is told not to merge. After a review that asks for fixes, it fixes each blocking and fix-now finding in the same PR. After a review whose verdict says merge, it does not push for it, and files a ticket only for a finding that is a real bug or risk outside the PR (see How findings get back to the Dev). Its checkout then refuses a push, except a merge of main, until a later review or you say fix (see The push hold).
A reviewerReads a PR and posts findings as a PR comment, then leaves by itself. With Get a review on a session with no PR, reports in their own terminal and stays.Move the board. Is told to change nothing, commit nothing and merge nothing.
The PMStarted by Ask the PM. Is told to read the repo's CLAUDE.md and docs/constitution.md, each if there is one, then split your idea into tickets, which wait in Triage. Is told to write each ticket in four parts: What to build, Acceptance criteria that name the seams to test at, Blocked by, and Out of scope, describing behavior rather than file paths. The relay refuses a PM's ticket whose body lacks one of those parts at the start of a line, such as Blocked by: none or a ## Blocked by heading, and names the missing ones. Is told to file each body on stdin in a quoted heredoc (see ticket.js). Is told to file code tickets without changes to CLAUDE.md or docs/constitution.md, and to gather those changes into one ticket (see CLAUDE.md and constitution updates). Is told to give each ticket a priority, and to set or recommend an order (see The PM sets the order). Is told to read the PM notes for the repo first, to rewrite them before it stops, and to rewrite them again each time you tell it something worth keeping after that. Reads the branch of the folder you typed, the way a worker would start from it: the relay fetches, and the PM works in a checkout of its own at the remote's latest commit of that branch. So asked from a folder that is behind, the PM still reads the newest rules, and asked from a linked worktree, it reads that branch. Their tickets record that branch as their base. That includes a task's checkout under .worktrees, whose branch goes away when the task is cleaned up, so ask from the main folder or your own worktree. The branch is read once, when you ask, so if you switch that folder's branch while the PM runs, their tickets still record the branch it had. Asked from a subfolder, the PM reads the branch of the checkout that holds it, and starts at the top of its own checkout. A folder on no branch is refused.Move the board or approve their tickets. Set a ticket's priority or place, unless you turned on Let the PM set the order, and then only for tickets in Triage or Ready. Is told not to change code, commit or open a PR.
The COOStarted by Ask the COO. Reads the room's measures and writes a one-page report on how the room runs and how close it is to running itself, with at most 3 recommendations. Has its card in the Officers row of the org chart. See The COO.File tickets: the relay refuses them from its token. With its token, read anything but the measures and the tickets, or save anything but its report. Is told to propose only: to change no code, open no PR, and never start, stop or merge work, move the board or change a switch.
The security officerStarted by Ask security. Reads what access the room's sessions run with, by name only, and writes a one-page report against article 7, with at most 3 recommendations. Frames the risk and says when to escalate. Has its card in the Officers row of the org chart. See The security officer.File tickets or read the chat board: the relay refuses them from its token. Save a report that holds a key. With its token, read anything but its measures and the tickets. Is told to propose only and not decide: to change no code or access, open no PR, and never start, stop or merge work or change a switch.

"Is told" means the words in their brief. The brief is words, not a lock: it cannot stop a session doing something else if you ask it to.

CLAUDE.md and constitution updates. Only a person merges a PR that changes CLAUDE.md or docs/constitution.md, so Autopilot hands such a PR to you, code and all. To keep code from waiting on wording, these changes go to one open ticket titled CLAUDE.md and constitution updates, and code PRs leave both files out. A Dev whose change also needs one of them updated is told to write the exact change in its PR body and leave both files out of its PR. Once the PR is open, it runs ticket.js create "CLAUDE.md and constitution updates" with a body that names its ticket, the PR and the change. If none has that title, that files it. If one is in Triage or Ready, ticket.js says Already filed with (triage) or (ready), and a Dev cannot edit a ticket, so it posts in its own ticket's chat channel, starting with @Lead and naming that ticket and the PR, and the Lead can add the change with ticket.js edit. A task with no ticket has no chat channel, so its Dev says so in the PR instead. Already filed also answers for a ticket of that title that has started or that you rejected, which nobody can edit. Then the Dev files the change as its own ticket, titled CLAUDE.md and constitution updates for T-12 with its own ticket's number, blocked by the started one. The PM is told to file code tickets without changes to the two files, and to add each change to the open one, the ticket in Triage or Ready whose title starts with CLAUDE.md and constitution updates, with ticket.js edit, not one ticket per change. If none is open, it files one. If that title has started or you rejected it, the PM adds today's date to the title, and blocks the new ticket by a started one. Each change added to a ticket you approved takes your approval back, so the ticket waits for you again. Once you merge that ticket's PR, the next change starts a new one. Only a code change that cannot ship without the wording, because the constitution must describe what the code does, carries it in its own PR, which says why, and that PR then waits on you as before.

Skills and models. Each role's brief, the Lead's, a Dev's, a reviewer's, the PM's, the COO's and the security officer's, ends with one paragraph that names the skills set for that role in Settings, under Models and skills, such as mattpocock-skills:tdd. It tells the session to use them where they fit, to read the SKILL.md of a skill only a person can run and follow it, to carry on without one that cannot be called or read, and that the repo's rules win where a skill and CLAUDE.md or the constitution differ. It names only skills installed on this computer, and none when the list is empty. The PM's paragraph comes before its idea, so the idea is still last. A skill changes how a session does its job, not what the job is, so the rest of the brief, with its limits, is the same (the constitution, article 6). Each role can also have its own model, which a new session for that role starts on.

The Lead

Choosing it. The Lead is the session you choose with Make this the Lead, with it on screen. Only a plain session can be chosen, not a task, the PM or a reviewer, and sitting at the Lead's desk does not make anyone the Lead. There is one at a time, and a new one replaces the old. When the relay starts, it gives the room a Lead by itself (see When the relay starts).

Its brief. The relay types the Lead's brief as a prompt. It gets the brief again after /clear, after its conversation is compacted, and after Bring back, which spends a turn each time. It is a first brief: nothing else is typed into the Lead before it. The brief goes in only when the session's hooks say it is idle, or a new conversation has begun, and never because of silence or a timer, since typing at an open question would answer it. So after an interrupted turn, or Esc at a question, it waits until you send any prompt and that prompt finishes, or until you run /clear. A note under the room bar says so while it waits. With no hooks reaching the relay, a session you have spoken to is not briefed at all.

When the relay starts. The relay saves the Lead (RELAY_LEAD_FILE). When it starts, once it has taken back and brought back its sessions, it gives the room's channel (the channel in office/world.json) a running Lead by itself:

The relay's log says which it did. It starts no Lead while an update is under way, or when every desk is taken. Since there is then a Lead, the panel offers nothing back. RELAY_LEAD=0 turns this off, and RELAY_RESUME=0 starts the relay with nobody, the Lead too (Settings). With RELAY_LEAD=0, the panel offers the saved Lead back after a restart, keeping the Lead's desk until you answer. Only Bring back makes it the Lead again. If you answer Not now, or put its id in Resume, it is a plain session until you choose it.

When the Lead's session ends. Stopping the Lead loses its turn in progress, and no session is the Lead until it comes back. Only its handoff notes carry over. So it is hard to stop by accident:

If the Lead's session ends anyway, because you confirmed the stop, it ended by itself or it crashed, the panel says so at once. The page notes and a line above the Floor say that no session is the Lead now and offer Bring back as the Lead, which resumes the same conversation as the Lead, with its permissions. ticket.js floor prints the same line. Not now takes the offer away until the next relay restart. The offer shows only while no session is the Lead, so once the relay or you make a new Lead, the old one is not offered. A Lead that never had a conversation is not saved, so it cannot come back: the panel says so, and you make another session the Lead.

A session you make the Lead overwrites the saved one once it has a conversation, and starts without the permissions below. A saved session has permission to move the board or start tickets only if you had already granted it.

Its permissions. Each is separate, and each is off until you turn it on. Moving the board and starting tickets stay through /clear, Bring back and a relay restart, and end when you press their button again or make another session the Lead. After /clear, they are saved again when the brief goes in, so they are lost if the session ends or the relay stops before then.

Its regular check. The relay types a check prompt into the Lead every Lead check every minutes, in Limits and timings under Work (leadCheckMinutes, 5 unless you set it, RELAY_LEAD_CHECK_MS). 0 turns it off. The prompt says it comes from the relay's timer and grants nothing, and asks the Lead to look for a stuck reviewer, a failed pipeline, a PR with no review, or a merged PR whose Dev still holds a desk, and to pass on what it finds. It also tells the Lead not to make its own scheduled check. It comes only while tasks are worked: at least one task is building, in review, has changes requested or is waiting on you. While every ticket is in Triage, Ready or Done, nothing is sent. A check still waiting is taken back at once when the last worked task moves to Done, when you set 0, and when the relay starts with nothing worked or with the check off. It is a saved message for whichever session is the Lead, so it goes in only when the Lead is idle, has had its brief, and has nothing typed in its prompt and no question on screen. A check that comes due while the last one still waits is dropped, not queued, so a busy Lead gets one check when its turn ends, not several. The timer is the relay's (relay/lead-check.js), so the check goes on after /clear, after you make another session the Lead, and after a relay restart, where a check still waiting is kept in RELAY_DELIVERIES_FILE. After a restart, the first check comes one interval after the relay starts.

Moving the board

Until you press Let the Lead move the board in Settings, the Lead cannot move anything. Then it can move tasks and tickets, including accepting from Triage and Merged elsewhere, with relay/ticket.js move, tasks and task (see ticket.js). It still cannot clean up a task or start sessions, except the worker for a ticket it starts. Press the button again to take it back. Taking it back also takes back stopping sessions.

The Lead under Autopilot. While Autopilot is on, only the relay starts and merges work. A Lead keeps three rights: stop a session the Floor calls safe to stop, move a task to Done once its PR has merged, and ask the relay to review a task's PR. The stop is the one in What the Lead stops, with the same switch, verdict and hourly limit. The review is the one in The Lead starts a review, with the same limits, and the Lead may ask for it while Autopilot is on even when Let the Lead start reviews is off. A task's ticket follows it to Done. The relay has seen a PR merge when the task's history says so, or gh pr view said it merged (How the relay hears about PRs). Every other move of a task or a ticket, accepting from Triage, a move to Done before the relay has seen the PR merge, and every start are refused with 403 and autopilot, even when Let the Lead start tickets is on. The relay does not check merges, so the Lead's brief says never merge, even when Let the Lead merge is on. When Autopilot turns on or off, by you or by itself, the Lead gets its brief again with the new words.

The merge rung

The Lead's brief sends it to the merge rung in docs/constitution.md, article 5, which lets it merge a PR with gh pr merge --merge, but only when all of these hold:

It never merges a PR that changes CLAUDE.md, docs/constitution.md or the lint rules, eslint.config.js and eslint-local.js. When it merges, it says on the PR why and which hand checks are still open, and tells you. Restarting the relay after a merge stays with you. A PR from work it started merges like any other.

There is no button to take this back yet (T-50). Telling the Lead to stop merging lasts only until its next /clear, compaction or Bring back, because each of those types the brief again. The lasting way is a PR that takes the merge sentence out of the brief and the merge rung out of the constitution.

Ready to merge: the note and the label

When the Lead finds a PR ready to merge, it marks it on GitHub. Then you can tell from the PR itself, and from the PR list, that it has been through every review. You do not have to read the whole comment thread. The Lead's brief says to run node relay/ticket.js ready. Run with nothing after it, that prints what to check and what to write, so the brief stays short. The PR watch, when it tells the Lead a PR is ready, names the same command.

What the Lead checks. A review of the PR's current head is posted, every blocking and fix-now finding is fixed and the Lead checked each fix in the code, and no decision is left for you. The relay cannot check these, so the note says how the Lead did.

What the relay checks. Before it posts anything, the relay asks gh pr view and refuses with Not marked: and the reason when any of these fails: the PR is open, its base is main, its head is the commit the Lead named, its pipeline is green on that head, GitHub says it merges cleanly, and its Dev has no merge hold. If the relay cannot read the Floor to check for a merge hold, it refuses too. A note that leaves out one of its three parts is refused as well.

The note. One comment headed Ready to merge. It names the head commit and who merges it, then the Lead's three parts:

The relay works out who merges it at the time the note is posted, from every file the PR changes or renames, and from the switches then:

A switch you change after the note does not change the note, so read it as of the time it was posted. The note starts with <!-- office:ready -->, so it is not a review: the Dev is not told about it and its card does not move (How findings get back to the Dev).

The label. The relay adds the ready to merge label, and makes the label in the repo first if it has none. It keeps the PR and its head in RELAY_READY_FILE. Every Check each PR's pipeline every seconds (pipelinePollSeconds) it asks gh pr view for the head again. While that setting is 0, it asks every RELAY_READY_POLL_SECONDS (60) instead, so the label still comes off. When a new commit lands, it takes the label off and says so in #office and in the ticket's chat channel, so the label never points at an old head. The note stays as history, and names the commit it was about. After new commits the Lead checks them and marks the PR again, which posts a new note. A PR that merged or closed keeps its label and is no longer watched. So is one whose label someone took off.

Marking again. A second mark at a head that is already marked posts no second note. It only puts the label back if the label is off. If gh posted the note but could not add the label, the relay still watches that PR, so the Lead can run the same command again to add the label without a second note. Marking and the label check take turns, so a mark made while the relay reads that PR is not undone.

Who can mark. Only the Lead's token, or you with the relay key, through POST /ready. The note and the label go up with your GitHub login, as every session's gh does. Marking merges nothing.

What the Lead sees

The Lead runs node relay/ticket.js floor, which reads GET /floor. Its brief says to run it whenever you name someone, and to answer with the names the Floor shows. Only the Lead's token reads it. It prints one line for each running session the room started. Sessions the page only hears through global hooks, such as one started in another terminal, are not on it.

Theo · reviewer of PR 31 · idle · last hook 20 min ago · safe to stop: its review is posted, idle 20 min
Priya · Dev, T-14 · waiting on the person · last hook 2 min ago · not safe to stop: it is waiting on the person: Claude needs your permission to use Bash
Pam · PM · idle · last hook 45 min ago · not one the Lead may stop: it is the PM
Ada · Dev, T-83, PR 44 · stuck: told 27 min ago and did not start, a menu is open on its screen · last hook 28 min ago · not safe to stop: Enter was pressed 27 min ago and no turn began, so the prompt did not go in

Each line has the name the relay gave that session (see Which person gets it), its role (Lead, Dev, reviewer, PM, or session for a plain one), its ticket and PR, its state (working, waiting on the person, idle, quiet or stuck with how long there was no hook or output, or stuck with how long ago it was told and why), the minutes since its last hook, and whether the Lead may stop it, with the reason. The Lead's own line also says how tired it is. not safe to stop means someone may need it (the verdict below). not one the Lead may stop means the verdict calls it safe, but it is not one of the two kinds the Lead stops, so it is yours to stop. GET /floor has both: safe is the verdict, and canStop is whether the Lead may stop it. A session with no name, as when the relay found no roster, shows as Session and the start of its id, and ticket.js floor adds (no name). Each row also has its desk, which the page draws on the Floor (What each desk says).

A Dev whose PR is open, not merged and whose task is not Done may have a merge hold: why a merge now would leave its work out of the PR (relay/merge-hold.js). ticket.js floor prints it as merge hold: and the reason, and GET /floor has it as mergeHold, or null. There is a hold when an automatic review of the PR was posted with its verdict and no comment check has listed that review yet, so its Dev was not told of it. GitHub may list a new comment a little late, so a check that works but does not list it keeps the hold until a later one does. This hold waits even when the Dev's session has ended, since that check decides what is left. A posted review starts the check at once, rather than at the next poll. With the comment check off (reviewPollSeconds at 0) there is no such hold. There is also a hold when the Dev has review news the relay has not told it yet, when the Dev is working, quiet, stuck, at a question, running a job (such as npm test in the background) or has not begun a turn since the relay last typed a note into it, for up to 15 seconds after the note (RELAY_TOLD_HOLD_MS, the same wait delivery gives a note before it types another), since it may still be answering the latest review, or when its checkout has uncommitted changes (untracked files count) or commits that are on no remote. A checkout that is gone holds nothing. Autopilot asks the same before each merge. The relay does not stop the Lead's own gh pr merge: the hold is in its brief only.

The verdict comes from relay/stop-verdict.js. It never says safe for a session that:

Anyone else idle is safe to stop, with the reason. Safe is not enough for the Lead: see What the Lead stops.

What the Lead stops

A Lead you let move the board can stop one session with node relay/ticket.js stop <who>, where <who> is the name the Floor shows (in any case), a task id, or a desk's id. It works only while Let the Lead stop sessions is on, in Settings, or the relay runs with RELAY_LEAD_STOPS=1. It is off by default, takes effect at once, and a value set in Settings stays through a restart. Taking back Let the Lead move the board also takes this back.

$ node relay/ticket.js stop theo
Stopped: Theo (reviewer, session b299ee24-0c4c-4507-afb7-bb2625eeb192): its review is posted, idle 20 min
To bring it back: Resume with session id b299ee24-0c4c-4507-afb7-bb2625eeb192.

The relay asks the same verdict as the Floor at that moment, and refuses with its reason any session the Floor calls not safe to stop: one that is working, waiting on you (a raised hand, a question or a menu on its screen), the Lead itself, or the PM while you talk to it. A name that fits two sessions, or none, stops nobody.

Then it stops only two kinds of session, whatever the verdict says:

It refuses any other session with not one the Lead may stop and the reason: one you just added, a plain session, a reviewer that has not posted (you may be reading its report), a Dev whose PR is still open, a Dev with work that is not pushed, the PM and the COO. Those stay yours to stop. It stops at most 6 sessions an hour on each channel (RELAY_LEAD_STOP_LIMIT), then gives the rest to you.

Stopping is the same as Stop this session on the page. A task worker keeps its checkout and branch, and Bring back on the task returns it in the same conversation. The task's history says the Lead stopped it, and why. #office on the chat board says who it stopped, with the session id, and so do the reply and the relay's log. A session the Lead stopped is not brought back when the relay starts again, the same as one you stopped. One that is not a task's worker, such as the PM or a reviewer, comes back only with Resume and its session id, so the reply and ticket.js stop print it.

Its brief tells it to stop reviewers that have posted and idle Devs whose PR has merged, and to tell you who it stopped. The relay holds it to those kinds and checks that nobody is waiting on them.

The Lead starts tickets

Only you start tickets until you let the Lead. In Settings, pick two numbers beside Let the Lead start tickets and press it. The first is how few tasks must be building for the Lead to start one, from 1 to one under the WIP limit (RELAY_WIP_LIMIT, 3 unless you set it), so 1 or 2 with the usual limit. The second is how many it may start in all, from 1 to 20 (POST /terminals/lead with starts and total). The Lead then runs node relay/ticket.js start T-4, and the relay refuses a start, with the reason, unless all of these hold, whatever the brief says:

Each start uses one of the total. The last one turns the permission off, and the panel says so. The task records by: "Lead", and its card on the Board says started by the Lead with the time. The Board's header shows your number and the starts left. The Claude Code panel announces each start with the ticket and the starts left, from the Lead's lastStart in GET /terminals, and the relay's log says The Lead started T-4. The panel tells only a page that is open, so the Board's cards are the record.

Stop the Lead starting tickets takes it back sooner. The Lead starts nothing more, and work it started keeps running. Like moving the board, it is a separate permission, and stays through /clear, Bring back and a relay restart, with the starts left. It ends when another session is made the Lead. A number saved at or above a WIP limit you lowered since comes back off. relay/test/lead-start.test.js checks each rule.

Refreshing the Lead

A long conversation gets compacted, and each time the Lead keeps only a summary of it. Refresh the Lead keeps its conversation small. It is in Settings while a session is the Lead, and sends POST /terminals/lead with {"refresh": true}. The relay runs the steps in relay/lead-refresh.js, driven by the Lead's hooks, and types each one with the same checks as any message it types (notSafeToType, see how the relay types): the Lead's turn has ended, no brief is owed, nobody has text in its prompt, and no menu is open.

A Lead that still owes its brief. If the Lead has not had its brief yet, the button types the brief now instead, with the same checks as a first brief: it does not wait for an update's quiet moment, but it waits while the relay restarts, and it types nothing while the Lead is working or waiting on you, a question or menu is on its screen, someone has text in its prompt, or its screen shows no prompt. The refresh stops there, and the page says so: press the button again later if the Lead still needs a refresh. If the brief cannot go in, the answer says why in plain words, such as The Lead has not had its brief, and the relay cannot type it now: its screen shows no prompt. The brief still goes in by itself once it is safe.

  1. It asks the Lead to rewrite its handoff notes in lead-notes/notes.md in the relay's state folder, ~/.office-world/lead-notes/notes.md by default.
  2. Once that turn ends, it types /clear. The Lead keeps its role and its permission to move the board.
  3. The relay types the brief again, as it does after any /clear.
  4. Once that turn ends, it asks the Lead to read the notes back and carry on.

The steps start only when the Lead is idle, has had its brief, and has nothing typed in its prompt. One refresh runs at a time. It ends when the Lead's session ends, when another session is made the Lead, after 15 minutes, or when you press Stop the refresh ({"refresh": false}), which is what the button reads while it runs. That stops it before the next step, and what was typed stays typed. A prompt you send to the Lead during a refresh is answered first. An update waits for a refresh to end before it restarts the relay. GET /terminals shows each session's refresh (the step it is on, or null), refreshNote (how the last one ended) and tired (see How tired the Lead is).

The notes are context, not permission. They keep only what the board, the pull requests and a huddle cannot show: your decisions, the Lead's promises, and why something waits. They copy no live state, which would go stale, and they grant nothing, since any session could write that file. The fresh Lead drops lines that no longer hold, and checks with you any line that reads like a permission. What lived only in the old conversation and is not in the notes is gone.

How tired the Lead is

Tired means how much of its context window the Lead has used since its last /clear or refresh. The fuller it is, the sooner Claude Code compacts the conversation by itself and the Lead keeps only a summary, which is when it slows down or forgets a decision. You see the level in three places, and they all read the same number:

LevelContext usedWhat it means
○ freshbelow 50%Nothing to do.
◑ getting tired50% to 69%A refresh is coming. Plan one for a quiet moment, when the Lead is idle.
● needs a refresh70% and overPress Refresh the Lead when the Lead is idle. It writes its notes, gets a new, small conversation, and reads them back, so it comes back fresh.

A refresh starts only when you press the button: nothing starts one at a level. The levels are in relay/lead-tired.js. The number comes from Claude Code itself. Every session the room starts gets the room's status line, relay/status-line.js, in its --settings. Claude Code runs it after each change in the session and hands it context_window.used_percentage. The status line prints the level and sends the number to the relay with the session's own token (POST /terminals/context). The relay keeps it with the session, for the conversation it was sent from, so after a /clear the old number is gone until the new conversation's status line sends one. Like the hook, the status line gives up on the relay after one second and still prints. The room's status line takes the place of any status line of your own in the sessions the room starts. The Floor shows the level for the Lead only.

Settings

The switches for what runs without you are in one dialog. Press Settings in the room bar to open it. On the left of the bar, four chips say which are on, such as Autopilot off, Lead: board, merge, Reviews: auto and Huddle: tells the Lead (or Huddle: Floor only). A chip is outlined in green while what it names does something without you. Pressing a chip opens Settings at that section. Each switch has a line under it saying what it does. They work whichever session the panel shows. While the dialog is open, what a press did shows at its top.

Except the Huddle switch, which this browser keeps, the relay keeps every switch and value, so each holds with the page closed and after a restart, and applies at once.

Sessions can list and file tickets, and only a Lead you chose can do more

Each session the room starts gets a token good only for that, used by relay/ticket.js. A Lead's token can do what you let it do, and so can a PM's token while Let the PM set the order is on, and nothing else. While Let the Lead set priority is on, the Lead's token can also set priority and order (see which routes each token reaches). Sessions run with your normal permissions, and one could read the relay key from your hook settings, so this is a check on process, not a security boundary.

Autopilot

With Autopilot ticked (it starts unticked, and the relay keeps it in RELAY_AUTOPILOT_FILE), the relay takes tickets from Ready to merged by itself, with nobody pressing anything (relay/autopilot.js, rules in relay/autopilot-plan.js). It is rungs 3 and 4 of article 5 together, in the constitution. The box under it in Settings limits it to the tickets you list, such as T-12, T-15, to the tickets with a label you list, such as flaky, or both, such as flaky, T-12. A label lets in every ticket that has it, also one you label while Autopilot runs, and still only the Ready tickets a person approved. Only you set labels, so no session can add a ticket to the list. Leave it empty for every Ready ticket. When you turn Autopilot off, the list is cleared, so a list is for one run only. When Autopilot turns itself off, it keeps the list. When a list is set and no ticket on it can start, the line next to the switch says why each one in Triage or Ready waits, and names each one rejected, in Board order, such as No ticket you allowed can start. T-12: On hold. T-15: Waiting for T-9. The reasons are Rejected, In Triage, Not approved by you, Waiting for its blockers, the hold, replacement or design ticket, and No repo. Only when every ticket on the list is started or done does it say Every ticket you allowed is started or done., and when no ticket has an id or label on the list, it says so. Every RELAY_AUTOPILOT_TICK_MS (20 seconds) it does this:

  1. Start. While fewer than RELAY_AUTOPILOT_AT_ONCE tasks (1) are open, it starts the next Ready ticket that a person filed or moved to Ready, whose blockers are all done, and that is not on hold, replaced, or waiting on a design ticket, in Board order. While the latest CI run that a push to that ticket's base branch started failed, it starts nothing, and the line next to the switch says Main is red, so T-5 waits: and which run failed (A red main). The task says it was started by Autopilot. A task is open until it is Done or Waiting on you. Its own count is only of tasks it started, while the WIP limit counts every task being built. So when tasks you or the Lead started fill the WIP limit, Autopilot waits, says Waiting for room under the WIP limit in Settings, and starts the ticket once a task finishes. It does not turn itself off for this. While an automatic review waits for a desk, it starts nothing, and the line next to the switch says Waiting for a free desk: the review of PR #N goes first., since a review frees the desk it needs by itself (A review frees a desk). If the start fails because all 9 desks are taken, it waits up to 5 seconds for a session that is already ending, and tries once more. If none ends, it stops one of its own sessions that the Lead may stop (the same verdict): the Dev of a task it started, whose PR merged or whose task is Done, with nothing uncommitted or unpushed in its checkout, or a reviewer that has posted on the PR of such a task, automatic or from Get a review. It waits up to 5 seconds for that one to end, then tries once more. It stops the one idle the longest, and only one, since a start needs one desk. If the WIP limit fills while it frees a desk, so the next try is refused for it, that is the same wait for room under the WIP limit. Its note, the chat and the task's history say who it stopped and why. It never stops a session on a task it did not start, so those stay yours. Let the Lead stop sessions and the Lead's hourly limit do not apply. When no desk comes free, that is a wait, not a failure, as for the WIP limit. Autopilot stays on, and the line next to the switch says what it waits for, such as Waiting for a free desk: 9 of 9 taken, none safe to stop. The reason can also be that a session did not end in time, or that another session took the freed desk first. It writes one note when the wait starts, not one at each look. At each look it goes through the same steps again, and starts the ticket as soon as a desk is free, such as when a session ends. There is no time limit on the wait.
  2. Review. The Dev opens the PR, and the first review starts as in Automatic review. While Autopilot is on, every push to a reviewed PR also gets its follow-up, as if Review again after each push were ticked. Each review of a PR, automatic or from Get a review, with Autopilot on or off, asks the reviewer to mark each finding with one of three kinds, blocking, fix now or follow-up, and to run ticket.js verdict merge or ticket.js verdict fix before it posts. It says merge only when no finding is blocking or fix now. A verdict from Get a review counts like any other: when it says merge, the checks passed and GitHub can merge the PR, Autopilot merges it.
  3. Fix once. Review comments reach the Dev as before. The Dev fixes the blocking and fix-now findings together, and pushes. A follow-up review checks only the commits since the last review that was posted with a verdict, and for a merge of main only how its conflicts were resolved. With no such review yet, it reviews the whole PR.
  4. A Dev that is not running. When the latest posted verdict says fix for the PR's head, or GitHub reports a conflict with main, and the task's Dev is not running, such as after a stop before a relay restart, Autopilot brings it back as Bring back does: the same checkout and the same conversation. The saved review news, or the ask to merge main, then goes in. Its note says its Dev was not running, so Autopilot brought it back for the fixes the last review asks for, or for a merge of main. A Dev that pushed after the fix verdict and then ended is not brought back: the follow-up review checks its commits. While the WIP limit is full or every desk is taken, Autopilot waits, says why next to the switch, and tries again at each look. If it cannot bring the Dev back for another reason, such as a checkout that is gone, or if the Dev it brought back for that same commit is not running again, the task goes to you with the reason and the step: press Bring back on its task, then move its card back.
  5. Merge. It merges with gh pr merge --merge when the latest posted verdict says merge for the PR's current head, every check on that head passed, and GitHub can merge it. It names that commit with --match-head-commit, so GitHub refuses the merge if a commit arrived since it looked. First it asks whether the PR holds all its Dev's work (the merge hold). While no comment check has listed its latest posted review, while the Dev has review news it was not told, or while it is working, quiet, stuck, at a question, running a job, or told something in the last 15 seconds it has not started on, Autopilot waits, since the Dev may still be answering the latest review. Once the Dev is idle or gone, uncommitted changes or unpushed commits in its checkout send the task to you, and so does review news its ended session was never told. A branch behind main is fine, since main does not ask for branches to be up to date, so nobody merges main into a PR for that. Just before it merges, it reads the PR's comments once more (How findings get back to the Dev): if they could not be read, it waits for the next look; if they hold a Dev's reply with <!-- office:hold -->, the task goes to you; if they hold new review news, the Dev hears it first. If GitHub reports a conflict, it asks the Dev to merge main, keep both sides, and push only that merge, not fixes for the review's non-blocking findings. That push gets a follow-up review. If a turn of the Dev begins after the ask went in and ends, and the PR still conflicts at the same head, Autopilot asks once more at its next look, and its note says its Dev was asked once more. If a turn ends after that second ask too, the task goes to you: Its Dev was asked twice to merge main into PR #N at <commit>, and each turn ended without it. A new head starts the count again. It does not wait for the stall time (autopilotStallMinutes) for this.
  6. Done. Once the PR has merged, its task goes to Done, its ticket follows, and the Dev's session stops if it is not in a turn. A Dev still in a turn then may be stopped later, while Autopilot is on and a start needs its desk. The relay then pulls main into its own folder, as Update does, and restarts once no session is busy if relay files changed. While that update waits for a quiet moment, Autopilot goes on: it still reads PRs, merges, moves tasks and starts tickets. A new Dev gets its brief at once: an update holds a task's brief only while the relay restarts, and then waits for that Dev's turn too. Other saved messages, such as review findings for a Dev, are held only for the first 10 minutes of the wait (While an update waits). A PR it merges in that wait is pulled into the same update, so the restart runs it too. Autopilot stops only once the restart itself begins.

It hands a task to you, in Waiting on you with the reason on the card, and then leaves it alone, when:

Autopilot works only on tasks it started. A task it handed to you stays yours, even when the relay moves its card for a new review comment. Until you move the card, its desk on the Floor says Waiting on you: and Autopilot's reason, with the link to the comment when a Dev's reply with <!-- office:hold --> held it, such as Its Dev says a finding the review marked non-blocking is a bug and the link. Its status says waiting on you, and Needs you lists it. Neither shows what GitHub last said about the PR, such as GitHub says the PR is unknown, since that is not what waits, except for a PR only you merge. Move the card yourself and Autopilot takes it back, with its review rounds counted from 0 again. For a hand-over from a Dev's reply with <!-- office:hold -->, that means merge it: the hold works once, and if the latest merge verdict still covers the PR's head, Autopilot merges on it at its next look, with no new review. To have the finding fixed first, tell the Dev, or leave the card where it is. Autopilot also takes it back by itself when a newer commit answers the hand-over. This happens when a review of a newer commit than the one handed over is posted with a merge verdict, and the hand-over came from CI that failed on the reviewed commit, or from a Dev's reply with <!-- office:hold -->. For a Dev's reply, the newer commit must also hold a commit of the branch's own that is not a merge, since a merge of main does not answer the finding. The reviewer's checkout tells which, when it gives its verdict. The card goes back to In review, a note says which commit the review read, and Autopilot merges as usual. A merge review of the same commit keeps the hand-over, and so does one of a merge of main after a Dev's reply. Any other hand-over, such as one for too many review rounds, waits for you to move the card. If you merge its PR instead, Autopilot still marks the task Done and frees its Dev's desk, as for any other of its tasks. A verdict counts only once its review is posted (see Reviewers leave), and only for the commit the reviewer's checkout is at. A review posted with no verdict does not count, automatic or from Get a review, and the next push brings another. A verdict comes only from a reviewer's own token: a Dev cannot give one. It merges at most 10 PRs a day, then waits for tomorrow or for you. It merges each PR once and counts it once. While GitHub still shows a PR open just after Autopilot merged it, Autopilot leaves it alone. If that lasts RELAY_AUTOPILOT_STALL_MS (30 minutes), the task goes to Waiting on you. If it cannot start a ticket for any reason but a full WIP limit or a full Floor, it turns itself off and says why. Turning it off stops nothing that is under way. What it is doing shows next to the switch, and in GET /autopilot, which only the room page reaches.

A PR only you merge. A PR handed to you only because it changes CLAUDE.md, docs/constitution.md, eslint.config.js or eslint-local.js still gets its reviews, and Autopilot keeps looking at it at each look. It never merges it. Its reason on the card, in Needs you, next to the switch and in the task's history follows the PR: It changes CLAUDE.md, which only a person merges. Waiting for its review., then The review of 0fdd14b says fix, so its Dev fixes it first., Waiting for a review of the new commits., Waiting for CI., CI failed on the reviewed commit., GitHub says the PR is blocked., or The review of 0fdd14b says merge, but it conflicts with main. Once the latest posted review says merge for the PR's current head, every check on it passed, GitHub can merge it, and the PR holds all its Dev's work, the reason says Ready for your merge: the review of 0fdd14b says merge, CI is green, and GitHub can merge it. That is the same test Autopilot uses before its own merges. Autopilot's note says it once for each head, and the room page says it once for each head in the status line under the Floor, also after a reload. A new push takes the reason back to waiting for a review. The task stays in Waiting on you the whole time. When you merge the PR, Autopilot marks the task Done. GET /autopilot gives the PR a ready with the head commit while it is ready, else null.

A stuck session. When a task goes to Waiting on you because its Dev or a reviewer is stuck, the card and Autopilot's note say which session and why, such as Its Dev Ada at a question (Claude needs your permission to use Bash) for 30 minutes, or Its Dev Ada has sent no hook and printed nothing for 30 minutes. Autopilot does not stop that session: it stays open at its desk, so you can look at it and answer it there. In Waiting on you the task no longer counts toward Autopilot's tasks at once or the WIP limit, so Autopilot starts the next Ready ticket. Desks are the real limit: the stuck session keeps its desk, and once every desk is taken Autopilot waits as it does for any start. When you answer and the session moves again (a hook says it did something, and it is not at a question), Autopilot moves the task back to where it was, Building for a Dev, and takes it back, even if that is over the WIP limit for a while. The session never left its desk and is at work again, so the limit does not hold the task in Waiting on you. It holds only Autopilot's next start, until fewer tasks are being built than the limit. Its review rounds are not counted again. If you move the card yourself first, the task is yours to move, as for any task Autopilot handed to you. Autopilot looks for this only while it is on. If an update restarts the relay before you answer (it does not wait for a session at a question), the session stays at its question in the session host, and you answer it there as before. If the relay is stopped before you answer, the session comes back with its conversation but without its question, and sends no hook until it gets a prompt. So the task stays in Waiting on you: tell the session to go on, and the task comes back once it moves, or move the card yourself. The note on the card says so. A reviewer that the relay typed its brief into, but whose hooks never reach the relay, is not counted as one that has not started.

A nudge before it parks. When a task has no PR and its Dev has been idle for RELAY_AUTOPILOT_STALL_MS (30 minutes), Autopilot does not hand it to you at once. It sends the Dev one saved message: Your task has no PR yet. If a test run was lost, run it again in the foreground and open the PR. If you are blocked, say why. Its note says Autopilot nudged its Dev, which stopped without a PR. The task then gets one more stall time. If the Dev is still idle with no PR at the end of it, the task goes to Waiting on you, and the card says what is true: its Dev has been idle for 30 minutes with no PR, and did not start a turn after Autopilot nudged it 30 minutes ago, or and took a turn after Autopilot nudged it 30 minutes ago if it took one. The minutes since the nudge count from when it was typed in. A saved message is typed only when the session is safe to type into, so a nudge can expire unsent, and then the card says and the nudge Autopilot saved for it 30 minutes ago was never typed in. The idle minutes count from the Dev's last hook, or from when its session started if it has sent none. Only a Dev whose session has ended is not nudged, and the card says so: its Dev's session ended, and there is no PR. A Dev running a job, at a question or in a turn is not nudged. There is one nudge per task each time it stalls, and a relay restart does not send a second one. Autopilot forgets the nudge each time it sends the task to Waiting on you, for any reason, such as a Dev at a question. So when the task comes back and stalls again, the Dev is nudged again.

When nothing moved it. A task that went to Waiting on you because nothing moved it comes back to Autopilot by itself as soon as something does, after the move to Waiting on you: its Dev opens a PR for it, its Dev sends a hook that says it did something (and it is not at a question), or a review of its PR is posted with a verdict. The task goes back to where it was, Building for a Dev, even if that is over the WIP limit for a while, as for a stuck session, and Autopilot reviews and merges it as usual. The card and Autopilot's note say why, such as its Dev opened PR #153, so the task is back, its Dev Ada moved again, so the task is back, or a review of PR #153 was posted with the verdict merge, so the task is back. Its Dev is the session at its desk now, which can be one you brought back. If you move the card yourself after the move to Waiting on you, the task is yours, as for any task Autopilot handed to you. Autopilot looks for this only while it is on. The COO counts such a task as no wait on you.

What it keeps of each run. For each ticket Autopilot starts, the relay keeps one run record in RELAY_AUTOPILOT_FILE, so it lasts through a relay restart and is not cut like the notes, which keep only the last 30 lines (relay/autopilot-runs.js). A record has the task and ticket ids, the ticket's kind when it started, and the PR link. It has the time of each step, each kept once: when the task started, when its Dev got the brief, when its PR opened, each posted verdict with its commit and time, when it merged and whether Autopilot or a person merged it (a merge Autopilot did not make is a person's, also when the task reached Done by another move), and when it went to you, with a reason word. The steps come from the task's history and from Autopilot's own merges and hand-overs. While Autopilot is off, a record is filled in at its next look once it is on again. A record holds no key, prompt, ticket title or ticket body: only ids, times, verdicts and reason words from a fixed list. Each record is kept for 90 days from its start, then dropped at the first look of a new day. Its outcome is one of the four that article 5 names for rung evidence, in this order:

A run with none of these yet is open. Next to the switch in Settings, the line says how the runs started today ended so far, by outcome and by ticket kind, and the median minutes from start to merge of today's runs that merged. A ticket with no kind counts as none. Today is the day in UTC, as for the day's merges. GET /autopilot has the same in runs.today, and the last 10 records with their outcome in runs.recent.

The PR watch

With Watch each open PR on, in Settings under PR watch, the relay keeps each open task PR moving by reading where it stands on a timer, not by waiting for a hook (relay/pr-watch.js, rules in relay/pr-watch-plan.js). It is off by default. The relay keeps it in the settings file, so it stays off after a restart until you turn it on, and it stays on until you turn it off. A missed hook, a closed page, a relay restart or a push the relay did not hear then costs one look, not a night. It merges nothing.

Every Watch PRs every seconds (120, RELAY_PR_WATCH_SECONDS), and 5 seconds after the relay starts, it reads each task that has a PR and is not Done: the PR from GitHub with gh pr view (its head commit, its checks, and whether it merges cleanly), what the relay keeps about its reviews and their verdicts, its Dev's session, and the commits in its Dev's checkout that the PR does not have. A PR that merged or closed is dropped. It then decides who owes the next move, in this order, and acts on it:

  1. Its task is in Waiting on you: it waits on you, and the watch does nothing. A task Autopilot started, while Autopilot is on, waits on Autopilot, and the watch leaves it to Autopilot.
  2. Its Dev's checkout has commits the PR does not have (past the PR's head, or on no remote when git does not have that commit), and the Dev is idle: the watch tells the Dev to push them with a plain git push. This comes before a review, which would read code that is about to change. With the Dev's session gone, it waits on you.
  3. Its Dev is at work: it waits on the Dev. At a question, or stuck: it waits on you, and the Dev is not told anything more.
  4. It conflicts with main, or a check failed on its head: the watch tells the Dev. A failed check that the relay already told the Dev about, while its review waited on the pipeline, is not told again. Checks still running: it waits on CI.
  5. No review read its head, and none runs: the watch asks for one, as if the PR's hook or push had been heard. A PR the relay has no review record of, such as one opened while the relay was down or before it kept records, gets its first review. One with a record gets a follow-up, even while Review again after each push is off. Each counts against the automatic reviews per PR (3): past that, or with Review PRs automatically off, it waits on you.
  6. The review of its head has a verdict that asks for fixes: the watch tells the Dev to fix each blocking and fix-now finding and push, and not to push for its follow-up findings. A review with no verdict waits on you. A verdict given but not posted waits on the reviewer.
  7. The review of its head says merge, its checks are green, and GitHub says it merges cleanly: the watch tells the Lead, which checks it and marks it ready to merge, then merges it if it may (the merge rung), or tells you it is ready. It waits on the Lead while a Lead runs that may merge, and on you otherwise. A PR that changes CLAUDE.md, docs/constitution.md, eslint.config.js or eslint-local.js waits on you, and the Lead is not told.

Each message is a saved message, so it goes in only while the session is idle. After it goes in, the relay checks that the Dev started a turn, and if not, the Dev shows as stuck. Each action is kept by PR, head commit and cause, in ~/.office-world/pr-watch.json (RELAY_PR_WATCH_FILE), so the next look, and a look after a restart, does not do it again. A new head starts afresh. A push is kept by the commit to push too, so new local commits are told again.

Each PR has one line: who it waits on, and for how long. ticket.js floor prints it on its Dev's line as PR waits on the Dev for 12 min: and the reason, GET /floor has it as waitsOn, and the PR's ticket card on the Board says it too. The wait counts from when the owner or the reason last changed, and starts again after the watch was off. A PR that waits on its Dev, a reviewer, CI or the Lead for Give you a PR that waits after minutes (60, RELAY_PR_WATCH_WAIT_MS) waits on you, and its ticket's chat channel and #office say so once for that head and reason.

The answers to article 5's five questions, for this switch:

  1. What starts it? The relay's timer, while you have the switch on.
  2. What does it read and write? It reads each open task PR with gh, the relay's review and verdict records, the Dev's session and its checkout with git. It writes a saved message to the Dev or the Lead, a review request to the automatic reviews, a post on the chat board, and its own record.
  3. What does it start next? At most one review of a PR's head, within the limit on automatic reviews. Nothing else: a message starts no session, and it merges nothing.
  4. Where does the person come back in? The line on the Floor, the Board and ticket.js floor, every PR that waits on you, the chat post when a wait goes to you, and the switch.
  5. What stops two sessions from doing the same work? Each action is done once for each PR, head commit and cause, kept through a restart. A review is asked for only when no review read the head and none runs, and the automatic reviews count it. A task Autopilot moves is left to Autopilot.

Reviews

Automatic review

The relay starts the automatic reviews (relay/reviews.js), so they start with the room page closed. With Review PRs automatically ticked (it starts ticked, and the relay keeps it in RELAY_REVIEWS_FILE), a session that opens a PR with gh pr create gets a second worker, titled "Review PR #N", who posts a PR comment. They work in a copy of the repo at the PR's latest commit (relay/checkouts.js), which goes away when their session ends, if they left nothing in it. If they did, it waits in the panel for Clean up, the panel says what is in it, and any commits are kept on a branch kept-<id>. A Clean up pressed just as the session ends waits until the relay has looked, so the two never both remove the copy. If the relay stopped first, the copy goes at the next relay start, under the same rule.

It only starts if all of these hold at that moment:

It also waits for the PR's pipeline to be green, as in A clean pipeline before review. It starts once per gh pr create, and the relay keeps a review that could not start, so a restart keeps it too:

A follow-up review that could not start 3 times waits on you the same way.

Turning Review PRs automatically off while a review waits for a desk or its next try drops it. A review that gave up stays waiting on you.

A review frees a desk. Idle Devs whose PRs wait on a review can hold every desk, and then the reviews wait for a desk while the Devs wait for the reviews. So an automatic review, first or follow-up, that waits for a desk frees one by itself. Each second, while every desk is taken, the relay stops one session for the review that has waited longest. It picks, in this order, the one idle the longest of each kind:

It stops only a session the Floor calls safe to stop (the same verdict), so never the Lead, a session in a turn or waiting on you, a session with text typed in its prompt, or one with a job running. It stops one at a time, and waits up to 10 seconds for a session that is ending before it stops another. This is not the Lead's stop: Let the Lead stop sessions and the Lead's hourly limit do not apply, and it is not only Autopilot's own sessions. The panel and the relay's log say The relay stopped Eli (Dev, task 3758c1) to free a desk for the review of PR #2: its PR waits on a review, idle 41 min, and Bring back returns it to the same checkout. The chat says it too, and so does the task's history. For a task Autopilot started, its PR's line in Autopilot and Autopilot's notes say it as well.

When it may stop none of them, the panel says No desk is free for the review of PR #N, and the relay may stop no session for it. Stop one yourself. once, and Needs you names the wait. It goes on looking each second, and stops one as soon as one may be stopped, such as when a Dev's turn ends. freeForReview in relay/floor.js stops it, and forReview in relay/stop-verdict.js picks it.

The Dev is told when a review starts. Each review of a PR that starts, the first one, a follow-up or one from Get a review, is told to the PR's Dev as a saved message: A review of your PR <link> started. Ada is reviewing commit <commit>. You need not do anything now. Its findings come as a comment on the PR. The commit is the one the reviewer's checkout is at. The name is the one the relay gave the reviewer as it started it, with no page open too. A reviewer with no name, as when the relay found no roster, is A reviewer. The Dev is the session whose task has that PR, or that opened it. With none, nobody is told and the relay's log says so. A start that is not typed yet is replaced by a newer start of the same PR, and is dropped after an hour. The Dev's desk on the Floor shows it too: see the status icon.

Reviewers leave once they have posted

A reviewer that relay/checkouts.js started for a PR gives its desk back by itself. The relay waits for two hook events from it: a PostToolUse that says a gh pr comment or gh pr review to that PR worked, and then Stop. It then waits RELAY_REVIEW_GRACE_MS, about 30 seconds, and stops the session. Its checkout goes if nothing is left in it. Otherwise it waits for Clean up, and the panel says what is in it. The panel also says who finished, with a link to the comment, or to the PR after gh pr review, until you press OK, and GET /terminals lists them as finished. reviewDone in relay/terminal.js is the one place this ending happens.

Review again after each push

With Review again after each push ticked (it starts unticked, and the relay keeps it), a PR that has had a review gets a follow-up review once its latest commit is not the one its last review read. The relay starts it, so the page need not be open. Each second it compares the latest commit that the pipeline check last heard from GitHub with the commit the last review read. So a push counts even when its hook never reached the relay, for example during a restart: the review comes at most one pipeline check later. A git push hook only makes the relay ask GitHub at once. Any way of writing the push counts, quiet, piped or inside an if, a loop or { } too. A push that sends no commits to a branch does not: --dry-run, --delete, a refspec :branch, which deletes (a bare : still counts), --tags with no branch named, --mirror, and one that printed Everything up-to-date with no line of a branch it moved. A PR the relay never reviewed, a PR whose first review still waits, and a PR that merged or closed get no follow-up. The relay also starts nothing for a PR until it has heard from GitHub after its last review started, so an older answer cannot bring a review of a commit already reviewed. With Check each PR's pipeline every at 0 the relay knows no commits, so only a session's git push brings a follow-up, of the session's PR: its task's PR, or the one the relay saw it open with gh pr create. Before the review starts, the relay fetches the PR and compares its latest commit with the one the last review read (unlessAt on POST /checkouts). If they are the same, for example after a push that failed or sent nothing, no review starts, nothing is counted, and the panel says so. A commit that could not start its review, or that the fetch found unchanged, does not bring another try by itself: the next new commit does, or Get a review.

While Autopilot is on, this runs even when the box is unticked. The follow-up reviews only the commits since the commit the last review read, and for a merge of main only how its conflicts were resolved, with git show --remerge-diff.

It starts once the Dev's turn ends, since it may push again, and not while it waits on you. The Dev is the running session whose task has that PR, or that opened it. With none, the review does not wait for a turn, and its checkout is made from the folder of the PR's earlier reviews, or its task's repo. It also waits for the pipeline on the new commit, as in A clean pipeline before review. It also waits while any review of that PR is running, since that review read an older commit. Several pushes in that time bring one review, of the latest commit. The reviewer posts a PR comment, says for each finding of the earlier review whether the new commits fix it, and then leaves, like the first one.

Each PR gets at most 3 automatic reviews, the first one included, unless you change Automatic reviews per PR in Settings. Reviews the Lead asks for (The Lead starts a review) count toward the same limit. A new commit after that starts nothing, and the PR waits on you: its Dev's row on the Floor says PR waits on your review, ticket.js floor tells the Lead the same, and the Lead gets a saved message asking it to tell you. The next review is yours to start with Get a review, which also ends the wait. Reviews from Get a review are not counted. The relay keeps the counts, the switches, the commit each PR's last review read, and a push still waiting for its review, so a restart or a reload loses none of them. A waiting push keeps its Dev's session id too, so when a restart brings that Dev back at a new desk, its review still waits for the end of that Dev's turn. With no desk free it waits for one, as a first review does (A review frees a desk), and that is not a try. If a review cannot start for another reason, it tries again a minute later (RELAY_REVIEW_RETRY_MS), with 3 tries in all, the first one included, and then the panel says so. A PR reviewed before the relay kept these records has none, so its next push starts no follow-up until it has a review from the relay. office/reviews.js decides which review each button starts, writes their briefs, and decides when a PR owes another review (followUpOwed) and when it starts (followUps). relay/reviews.js starts them.

A clean pipeline before review

Nobody reviews a PR, and nobody is asked to merge one, until its checks pass on its latest commit. relay/pipeline.js asks gh pr view --json state,headRefOid,statusCheckRollup about each open task's PR, each PR whose review waits, and, while follow-up reviews are on, each open PR that has had a review, every 15 seconds (Check each PR's pipeline every in Settings, or RELAY_PIPELINE_POLL_SECONDS). It also asks at once when a PR opens or a push arrives. A pipeline is green when every check passed or was skipped, red as soon as one failed, pending while one is running, and none when the PR has no checks at all.

A red main

Two PRs that each pass CI can break main when they merge minutes apart, since neither was tested with the other. So CI runs on each push to main, as it does on each PR, and the room shows when main is red. Main here means the base branch of a task or ticket, which is main for most.

relay/main-ci.js asks gh run list --branch main --event push every 2 minutes (Check main's CI every in Settings, or RELAY_MAIN_CI_POLL_SECONDS). It asks once for each repo and base branch that a task in the room uses, and for the repo of the ticket Autopilot is about to start. It asks about one branch again only once its last answer is that old, so it adds one GitHub call a branch each time, fewer than the pipeline check makes for one PR. For each workflow it takes the newest finished run that a push started and that was not cancelled. The weekly run and a run you start by hand also test Node 18, so they do not count: a failure there does not make main red, and a pass there does not clear it. Main is red when one of those push runs failed, timed out or could not start. A run still going changes nothing, so main stays red until a push run passes.

While main is red:

When a push run on main passes, the line clears at the next check, and Autopilot starts work again. While gh cannot answer, main is not shown as red and nothing waits for it. With Check main's CI every at 0, the relay asks nothing and shows no red main.

Getting a review by hand

Get a review shows while a session is on screen. If the session has a PR, it starts the same review as the automatic one. A session has a PR when its task has one, when this page saw it run gh pr create, or when its PR waits on your review. This page knows the PR by the session's id, from a hook it heard, whether or not the session had a desk then. Nothing else keeps that PR, so a reload of the page forgets it, for an Add worker session or a session with no desk. A task keeps its PR. Then it starts a worker in their own copy of the PR's latest commit, who posts a PR comment without asking first and then leaves, like an automatic reviewer. So push before you press it, because work that is not pushed is not reviewed. They are asked for a verdict too, with the same words, so a review that finds nothing blocking counts for Autopilot. This review is not counted toward Automatic reviews per PR: only the reviews the relay starts are. For any other session, it starts a worker in that same folder, since they have to see its uncommitted work, and they report in their own terminal. The page sends their brief with the start, and the relay types it once their session shows its prompt, however long Claude Code takes to start (see a first prompt).

How findings get back to the Dev

Three kinds of finding. The verdict ask in each review of a PR tells the reviewer to mark each finding with one kind (relay/autopilot.js):

A review with any blocking or fix-now finding gives the verdict fix, so the Dev fixes those findings in the same PR and pushes, and the follow-up review checks them. That review counts toward the same limit of automatic reviews as any other. A review gives the verdict merge only when every finding is follow-up, or there are none. The Dev files a ticket for a follow-up finding only when it is a real bug or risk outside the PR. Polish not worth a ticket gets a reply on the PR and is dropped. When a follow-up review reads only the new commits, a new finding there is blocking only if it is a bug in them, and fix now only if it is in them. A blocking or fix-now finding they do not fix keeps its kind.

The relay checks the PR of every task that has one and is not Done, and of every session with no task that opened one, about once a minute (RELAY_REVIEW_POLL_SECONDS), and at once when an automatic review of that PR is posted with its verdict, with gh api: comments, reviews and inline comments, from reviewers, from you, and from sessions it did not start. It does not ask gh when the page polls, so the Tasks panel's 2-second refresh is unchanged. What it has seen is saved on the task in tasks.json, so a restart neither loses nor repeats a comment. If news arrives while a message is being typed, the next message can repeat the links of the one before. Edits to old comments are not news. relay/pr-comments.js does this. Its tell() takes any news for a task's Dev. So the Lead does not carry reviews to a Dev, which would tell the Dev twice. Its brief says Devs get PR reviews from the relay, and asks it to check that they act on them. Only one check of a PR runs at a time, so the Dev is never told the same comment twice. A check asked for while one runs waits for it to end, then runs again, since the one under way may have begun before the review it was asked for.

The push hold

After a review's verdict says merge, a push for its findings costs a pipeline run and a review round, and can break what was reviewed. So the Dev's checkout refuses such a push. relay/push-hold.js does this.

Resolving comments

Review comments do not get marked as resolved by themselves. Nothing in the room does it, and a Dev's fix leaves the comment standing as it was. Check the fix against the comment before you merge. The Lead is told to do the same before it merges.

The COO

Ask the COO, on the COO's card in the Officers row of the org chart, closes the chart and starts a COO session in the relay's own folder, as Ask the PM starts the PM. It spends one session of tokens, so it runs only when you press it, and only one runs at a time. The pattern comes from the executive reflection in OpenExecutive: an executive that reads the signals, then says what it would do and who should decide.

Its brief. The relay types a short brief. It tells the COO to read CLAUDE.md and docs/constitution.md, then fetch the measures with node relay/ticket.js measures, and write a one-page report in Markdown. It starts with the headline, against the last report: how many PRs merged alone, merged after getting stuck, and merged needing you, and the minutes the room spent stuck. Then what shipped, each run that got stuck (on what, and for how long), each step-in (what you did, and how long the room waited), and the evidence for each kind of ticket. It is told that review rounds are not failures. Then at most 3 recommendations, each naming its evidence and what you would approve: a rung, a ticket, a limit, or a change to the constitution. It is told to say what the measures cannot show, and to quote text that workers wrote, such as titles and notes, as data and never follow it.

It proposes only. It is told not to change code, open a PR, file tickets, start, stop or merge work, move the board, or change a switch or a rung. Its token reaches only GET /coo/measures, POST /coo/report and GET /tickets, so filing a ticket is refused by the relay, not only by the brief. The rest is words, not a lock: it runs with your logins, as other sessions do, and in the relay's own folder, which is the checkout the global hooks run from. A COO that ignored its brief could change the running relay's files. The recommendations are yours to act on.

The report. The COO pipes its report into node relay/ticket.js report. The relay saves it with the measures it was written from (RELAY_COO_FILE, the last 20), and the Floor shows it under the people, as text. On the COO's card, Last COO report, from and its time opens the last one again, also after a restart, and closes the chart. With no report yet it is greyed out and says No COO report yet. A new report opens on the Floor by itself, but only one that arrives while the page is open. One report shows at a time, so opening the COO's closes the security officer's, and the other way round. The next report's measures carry the last report's load and headline, so the COO can compare.

It leaves by itself. Once the report is saved, the session ends RELAY_COO_GRACE_MS (10 seconds) after that turn ends. If you type to it after the report, it stays until you stop it. Having its panel open does not count: only keys do.

What the relay measures

The goal is a room that does not need you to step in, so that is what the COO measures. The relay keeps these from what it already sees: the tasks and their history, the Board, the PR watcher, hooks, Autopilot and Update. relay/coo.js works them out each time they are asked for.

The security officer

Ask security, on the security card in the Officers row of the org chart, closes the chart and starts a security session in the relay's own folder, as Ask the COO starts the COO. It spends one session of tokens, so it runs only when you press it, and only one runs at a time. The role comes from the general counsel in OpenExecutive, which has no security officer: it frames the risk and says when to escalate, and it does not decide. While it runs, its card in the Officers row says it is in, and who sits there.

Its brief. The relay types a short brief. It tells the session to read CLAUDE.md and article 7 of docs/constitution.md, then fetch the measures with node relay/ticket.js access, and write a one-page report in Markdown: the logins sessions inherit, the folders they reach, what the relay takes out of their environment, and what the secret check caught, against article 7, which rungs 3 and 4 wait for. Then at most 3 recommendations, each a ticket, a limit or a change to the constitution for you to approve, with its evidence. It is told to say what the measures cannot show, and to give names only: never to print or copy the value of a variable, a token or a key file.

It proposes only. It is told not to change code or anyone's access, open a PR, file tickets, start, stop or merge work, or change a switch. Its token reaches only GET /security/measures, POST /security/report and GET /tickets, so filing a ticket or reading the chat board is refused by the relay. The rest is words, not a lock: it runs with your logins, as other sessions do, in the relay's own folder. Each change to a session's access is its own ticket.

The report. The session pipes its report into node relay/ticket.js access-report. The relay refuses a report that the secret check says holds a key, or that holds the relay's key, a session's token, or the value of a variable the measures name as looking like a login. The secret check's secret-check: allow marker does not count in a report. The refusal says which line and what kind, never the value. A secret that matches none of the check's patterns and is not a value the relay holds, such as a .netrc password, is not caught: the brief, which says never to copy a value, is the only guard there. A saved report is kept with the measures it was written from (RELAY_SECURITY_FILE, the last 20), and the Floor shows it under the people, as text. On the security card, Last Security report, from and its time opens the last one again, also after a restart, and closes the chart. With no report yet it is greyed out and says No Security report yet. The next measures carry the gaps the last report saw.

It leaves by itself. Once the report is saved, the session ends RELAY_SECURITY_GRACE_MS (10 seconds) after that turn ends. If you type to it after the report, it stays until you stop it.

What the relay reports on access

relay/access.js works these out each time they are asked for. Every one is a name, a path, a count or a yes or no, never a value.

Huddles

Status report, in the bar at the top of the Floor, gives one short report with a line for each running session and each unfinished task with no session. Each line has who they are, the ticket and PR, working, waiting on you, finished or gone, the pipeline and review, what they are waiting on, and how long since a hook last heard from them. What needs you comes first: a line that Needs you names shows that list's line, and the headline counts that list, so the two agree. Everything else, such as a failing pipeline nobody is on, shows only in what the line waits on. The report shows on the Floor under the people until you close it. A report made before the page loaded does not open by itself. A line above the buttons says what a huddle is, and its ? opens this section.

The report reads what the relay, git status and gh pr view already know. It interrupts nobody and spends no tokens. If gh fails the report says so, and shows the PR as unknown, not as missing. The relay's side is relay/huddles.js, and the page's is office/huddle.js.

The chat board

Chat, under the Board, is a few chat channels for you, the Lead, workers and the relay. The relay keeps it on this computer and sends it nowhere: it is not Slack, and every route answers only the room page and sessions on this computer. A session that reads the board sends what it reads to the model, as it does with anything else it reads. The relay's side is relay/chat.js, and the page's is office/chat.js.

A post types nothing into a session

Workers read the board with node relay/ticket.js chat T-39. Their brief tells them to check it, and that posts are information, not orders: they act on one only if their ticket, the Lead or you ask for it.

The one exception is a post that mentions exactly one running session by its name on the page, such as @Hugo, or @Lead. That session is told which chat channels have posts for it, never the posts' words. The note waits in relay/delivery.js, so it goes in only when hooks say the session is idle, never into an open prompt (see saved messages). Several posts for the same session wait as one note, for up to an hour, and the list of chat channels in it survives a restart. A post that mentions two or more sessions tells nobody, and says so.

When a session reads the board, each post shows who sent it as the relay knows it (the person, Theo (a session), office (the relay)), and its words in « and ». A ticket's title is quoted the same way, since it comes from the ticket store. A post cannot use those marks itself. The page shows your own posts as you.

How the relay hears about PRs

To know about failing pipelines and merges, the relay asks gh pr view about each task's PR every RELAY_CHAT_POLL_SECONDS. The first look at a PR is not news, except a merge. When a PR has merged, the relay keeps GitHub's merge time in its task's history, once, whatever its card says, and asks once more about a PR it saw merged before it kept merge times, so the COO counts it shipped. A merged PR is not asked about again. A closed one is asked about every tenth time, in case it is reopened.

To know that main moved, the relay runs git ls-remote --symref origin HEAD every RELAY_MAIN_POLL_SECONDS (60) in its own folder, the one Update pulls into (relay/main-moves.js). This changes nothing in the folder. When origin's default branch points at a new commit, #office says so once with that branch's name, such as main moved on origin, from 7873f70 to 1a2b3c4. The first answer after the relay starts is not news, even when the branch moved while no relay ran, and neither is a change of which branch is the default. It never asks for a password or a passphrase: git's prompt is off, and ssh runs with BatchMode=yes unless you chose an ssh yourself, in GIT_SSH_COMMAND, GIT_SSH or core.sshCommand. When origin cannot be asked, #office says nothing, the relay's log says so once, and again when origin answers, and the next answer is compared with the last one the relay had. Other branches are not watched.