Review panels (several AIs decide one question together)
- A panel is one question, several independent looks, one answer. One to five AI sessions each analyse it alone, then read each other's work and talk, then vote. More than half the panel must agree, so 2 of 2 means both. - Any agent can start one, if it is allowed to start sessions at all: the same permission a spawn needs. It uses the same door as every other review — POST /reviews with "shape":"panel" — or the older POST /panels, which is that door's alias. You never start one yourself. - The members are invisible and then gone. They are silent sessions — never in your sidebar, never in your inbox — and they are archived as soon as the panel files its report. - You hear nothing while it runs. The only two messages a panel sends are "everyone has reported, start talking" and the final report back to the agent that asked. - Four purposes today: a red team (break it), a brainstorm (open it up), a discovery (find what is actually there), and a direction review — a judgment on whether a session's work is really moving its goal forward, on a clock, which can rewrite its strategy and tasks or replace it.
On this page
How a panel runs
- Start. The agent names a purpose — or its
preset, which is the same four names — and a question, and optionally the members as{provider, model}pairs. It may use either door:POST /reviewswithshape: "panel", orPOST /panels, which is the alias and runs the very same code. With no members named, the panel uses your line-up — the members and chair order set in Dev Pipeline → Setup, the same list the mission board used — and falls back to one member on the asking agent's own engine only when no line-up is set. Member 1 is the chair. A member on an engine that cannot start a hidden session (the ones with their own session manager, such as codex) runs on thegptengine instead when that engine offers the same model, and is otherwise refused with a message naming the engine and the alternative. - Apart. Every member gets the same short brief, the question, and nothing else — no roster, no sight of anyone else's work. Each submits one analysis.
- Together. When every member has reported — or 30 minutes pass (90 for a discovery), and whoever has not reported is dropped — each remaining member is sent all the analyses and the roster, and may message the others.
- Propose and vote. The chair posts a proposal. Every member votes agree or disagree, and can change its vote until the panel freezes. A strict majority of the panel agreeing on one proposal freezes it.
- Report once, then leave. A frozen panel, or one that closed without a majority, sends the agent that asked exactly one report, and every member is archived.
What can go wrong, and what the panel does
- A member never reports. The 30-minute deadline drops it from the panel and the rest carry on.
- The computer is busy and a member waits in the start queue. A member whose start is queued counts as on its way, not gone: the panel waits for it like any other member, up to the same 30-minute deadline. If it still has not reported by then, it is dropped and its queued start is cancelled, so it never starts later on its own.
- A member starts after its panel is over. When a panel ends, every start still in the queue is cancelled. A start that was already launching when the panel ended is caught by the panel's own sweep within about five minutes and archived, so it never shows up in your inbox.
- Agent sessions need your approval to start. While "require approval for AI session spawns" is on, a panel refuses to start at all, because an approved member could not find its panel again. The agent that asked is told why; a panel on a clock skips that turn and the FIRST skip cards you once, saying that session's scheduled reviews are not starting and which setting to open. Later refusals of that clock stay quiet — even after you dismiss the card — and the reviews start again by themselves as soon as the cause is gone.
- A member's start failed. A spawn that was queued and then failed is noticed by the panel's own sweep within a few minutes: that member is dropped at once and the rest carry on, rather than waiting out the 30-minute deadline.
- A member dies mid-panel. A member whose session has ended or been archived stops counting toward the majority, toward "everyone has voted", and toward the barrier — so a two-member panel that loses one decides on the one that is left instead of stalling until the three-hour limit.
- The panel splits. At most three proposals. When the third has every vote and still no majority, the panel ends inconclusive and the report still carries that proposal and the reasons given by those who disagreed.
- The chair dies. The next member on the panel becomes chair, with nothing written down.
- Nobody can start. If no member starts at all, the panel is marked failed and the agent that asked is told once. Nothing else happens.
- The whole panel stalls. Three hours is the outer limit: a panel with a proposal closes inconclusive, one with nothing to show closes failed.
The commands
An agent calls these with its own token, naming itself:
| Command | What it does |
|---|---|
POST /reviews |
start one, the same door every review goes through: {"shape":"panel","preset":"redteam","question":"What breaks if we drop the cache?"} → {panelId} |
POST /panels |
the alias of the row above, with the older field name: {purpose, question?, members?, subject?} → {panelId} |
GET /panels/:id |
the panel: status, members, proposals, votes, report |
GET /panels?requester=<id> |
the panels this session asked for, or sat on |
POST /panels/:id/analysis |
a member submits {text} |
POST /panels/:id/proposal |
the chair posts {report, verdict?} |
POST /panels/:id/vote |
a member votes {revision, agree, reasons} |
GET /panels/:id/evidence |
a direction member reads the subject's place, turns, documents and tasks |
POST /panels/schedules |
put a direction review on a clock → {scheduleId} |
Only a panel's own members may submit or vote, only the chair may propose, and only a session that is allowed to start sessions may start a panel. A read is answered only to the agent that asked and to the panel's own members.
Name the panel with preset or with the older purpose — never both. The two accept the same
four names: redteam, brainstorm, discovery, direction. Sending both is refused with
"Send purpose or preset, not both."; sending neither is refused with the four names; and a preset
that is not a panel (an independent one such as code) is refused there too, with the message
naming the four panel presets. Both rows start the same panel through the same code, so every
refusal and every rule is identical whichever one an agent uses.
The limits, so a caller does not have to discover them by tripping them: 1–5 members; a question of 4,000 characters, an analysis of 20,000, a proposal of 30,000; at most 3 proposals per panel; a vote on revision 1–3. A 403 means the caller may not do that thing (start sessions, speak on this panel, propose unless it is the chair, change this schedule). A 409 means the panel is in the wrong state for it — the discussion has not opened, the panel has already decided or ended, or the revision is already at the limit. An analysis may be replaced freely until the barrier is sent; after it, the panel has moved on and a new one is refused with a 409.
The direction review (a judgment on a clock)
A direction review is a panel whose subject is one session. It asks one question — is this session really moving its goal forward? — and the chair answers with a colour and, optionally, changes:
- green — on course. yellow — drifting, fixable. red — a big strategic change, or a replacement.
- The changes it may propose are typed: a document (
{kind:"doc", doc, body, why, baseRevision}), a task ({kind:"task", action:"add"|"rewrite"|"close", ref?, title?, body?}), or a replacement ({kind:"replace", openingNote}). A replacement always runs last and only succeeds if the session has not moved on. - A document change is checked when it is proposed, not after the vote: the document must be the vision or the strategy, and its body must already be what the documents tool accepts — the vision as Markdown bullets only, the strategy as the five-part shape. A proposal that breaks either rule is refused there and then, with the documents tool's own sentence, so the chair can revise before anyone votes.
Who may start one: that session itself, a session above it, or the owner. Only one direction panel can be live per subject; asking again returns the live one.
What happens after the majority agrees depends on one setting, act on its own (on by default):
- On — the tool applies the changes itself, in order, one at a time, recording a receipt for each. A document write goes through the documents tool, and a change that tool refuses (a stale revision, a session with no document set) is recorded in its own words while the other changes still run. Two kinds of change wait rather than run: a later change to the same document when an earlier change to it was refused, and a replacement when anything earlier was refused — both were written for a world the refusals did not create. A rewrite retires the old task as dropped with the replacement named in its outcome, and if that retire is refused the replacement is removed again so no duplicate is left open. Task edits run as the reviewed session, and a replacement runs through keep-alive. After a restart it picks up at the first change that is neither done nor refused.
- Off — you get one card asking you to approve or decline, holding the exact proposal. Nothing is applied until you press Approve, and Decline closes the review with nothing changed.
Either way you get exactly one report card with the colour, the chair's report, how many of the proposed changes were applied out of how many, what changed, and every refused change in the refusing tool's own words — a review that judged well and applied four of five reads as four of five, never as a failed review. When the review changed a document, that report carries a Reverse button: pressing it puts every changed document back to the revision the review started from and closes the card. It is one-shot — pressing it again does nothing.
The reviewed session is told too, once the review has a verdict: the colour, the chair's full report, what was applied and what was refused in each tool's own words — even when nothing was changed or the apply stopped. That message asks it to say which points it will act on, which it will not, and why, and the app watches for that reply. A review that reached no verdict tells it nothing, and a replaced session is not messaged: its successor opens with the review above the hand-over note. The next review of that session is given this one's report and asked what was acted on. The reviewed session never sees who sat on the panel until the panel has ended.
On a clock
POST /panels/schedules {"subject": "<session id>", "everyHours": 8} → {"scheduleId": "..."}
PATCH /panels/schedules/<id> {"everyHours": 4} # the subject may change its own cadence
PATCH /panels/schedules/<id> {"active": false} # pause — a session above it, or the owner
GET /panels/schedules?subject=<session id>
DELETE /panels/schedules/<id>
One schedule per session. Every few minutes the app checks for due schedules, starts one direction panel, and does nothing while a direction panel for that session is still live. A clock starts sessions, so it takes the same permission as starting a panel: an agent that may not start sessions is refused when it asks for one, and a run whose session may no longer start them (unless you set the clock up yourself) starts nothing and waits for its next turn — and the first such refusal cards you once, as described under "What can go wrong", rather than the reviews stopping silently. After downtime it takes at most one catch-up run for that schedule, not one per missed window. It never writes anything into a session on a timer: the only message a session gets is the one a settled review sends.
Discovery proposes, it never applies
A discovery panel finds what is there and writes one report. When the agent that asked owns a document set whose report is written as a strategy (the documents tool's five-part shape), the report is also filed there as an ordinary strategy proposal and the message names it — the proposal waits for you (or a session you delegated) to approve it, exactly like any other strategy change. When the report is not in that shape the message says the proposal was not filed, and why. A discovery panel never rewrites a strategy by itself.
The chair of a discovery panel is asked for that shape up front, in the message that opens the discussion: the five headings — The goal, How we will know it is working, The bet, What we are not doing, What would change our mind — in that order, bullets only under each.
What it is not
A red team, brainstorm or discovery panel does not edit anything — it produces a report (a discovery also files a proposal, which still needs approval). Only a direction review changes things, and only through the tool, never through a member's hand. For a single independent check of a plan or a diff, ask for a review instead — that is one session, no discussion, no vote.
Last verified 2026-11-15