br1anchen/pstack-trio

Read the runtime adapter before following this workflow. Its runtime mappings apply to all referenced playbooks and scripts.

Pstack trio

Three agents, one Herdr or Rex session, one repository. The master owns judgment, the sidekick owns the working tree, and the consultant owns the second opinion. Every message between them is a file in the trio store plus a one-line prompt that names the file. The terminal is never the record, because agents on the alternate screen leave no scrollback.

The trio is pstack-pair with a consultant added. The pair's plan rounds, briefs, check-ins, steers, and reviews are unchanged; the consultant joins every plan round and answers consults when a finding changes the design. It never messages the sidekick and never writes the shared tree.

Preconditions

1. Inside Herdr (test "${HERDR_ENV:-}" = 1) or Rex (REX_BLOCK set). Outside both, say so and stop.
2. Load the multiplexer's skill for pane and agent control: Herdr's ~/.agents/skills/herdr/SKILL.md (or herdr --skill when that file is absent), or Rex's rex skill show. Its safety rules apply throughout. In Rex, read Running in Rex.
3. herdr or rex, and Python 3.11 or later (python3), on PATH. scripts/pair.sh help lists every store and channel operation; use it instead of hand-built herdr or rex calls for the trio.
4. At least two distinct agent kinds among master, sidekick, and consultant. pair.sh spawn reads the master's kind from the multiplexer and exits 8 when all three would match; tell the human to pick another kind or use pstack-pair. Sidekick and consultant may share a kind.
5. Start the master in auto mode. Devin defaults to bypass permissions with --permission-mode dangerous. Other kinds inherit the master's mode. pair.sh permission prints the detected master mode. --permission <mode> overrides both spawned roles; --consultant-permission <mode> overrides only the consultant. Native permission flags after -- override the default for every role spawned by that call. --permission auto selects Devin smart mode. Kinds without a translation take native flags after --. spawn also skips each kind's folder-trust prompt, which would hang an unattended agent in a folder it has not seen: pi gets --approve, Devin --respect-workspace-trust false. A trust flag after -- overrides it. A spawned Claude also starts with no MCP servers (--strict-mcp-config and an empty configuration), since each server is a process per session; a --mcp-config after -- keeps yours. Claude and Codex instead ask to trust a folder they have not seen; that decision is the human's, so spawn declines the dialog and stops with what to do: open that agent in the repo once and trust it.

Roles

	Master	Sidekick	Consultant
Owns	plan, briefs, consults, review, decisions, the human	the working tree, tests, diagnosis, evidence	design critique, second reads, prototypes
Runs pstack as	poteto-mode framing, how, architect, review skills	the playbook each brief names, with its todolist	how, why, architect alternatives, interrogate stance, blast-radius on diffs
Writes	the trio store only	files inside the brief's Scope, plus its progress log and reports	advice files, and a scratch worktree it removes
Reads the tree	always, read-only; runs checks in scratch at a commit	always	always, read-only
Speaks through	plans, briefs, steers, consults, reviews, standing orders, gates	progress lines, reports	advice

Enter your role. Master: references/master.md. Sidekick: references/sidekick.md. Consultant: references/consultant.md.

Trio store

${XDG_STATE_HOME:-$HOME/.local/state}/pstack/trio/<slug>/, created by pair.sh init. One writer per file.

Path	Writer	Content
pair.json	master via pair.sh	agent names, pane ids, kinds, cwd, git root, open scratch list, the sidekick's fallback and failovers, pane placement (split or tab)
standing-orders.md	master	numbered constraints pasted by path into every brief
plans/NNN-<slug>.md	master	one plan round, from the plan template
briefs/NNN-<slug>.md	master	one unit, from the brief template
progress/NNN-<slug>.md	sidekick via pair.sh progress	one timestamped line per completed step or change of approach
steers/NNN-<slug>-s<k>.md	master	mid-brief direction k for unit NNN, from the steer template
consults/NNN-<slug>-c<k>.md	master	question k about unit NNN for the consultant, from the consult template, with a kind: of design, finding, objection, or review
reports/NNN-<slug>-s<k>.md	sidekick	objection to steer k, from the steer response template
reports/NNN-<slug>.md	sidekick	evidence for brief NNN, from the report template, or the agree/object response to plan NNN, from the plan response template
advice/NNN-<slug>.md	consultant	design critique of plan NNN, from the plan advice template
advice/NNN-<slug>-c<k>.md	consultant	answer to consult k, from the advice template
scratch/<id>	consultant or master via pair.sh scratch	link to a throwaway worktree for one consult (NNN-<slug>-c<k>) or review (NNN-<slug>-review), at a commit or the live state, kept outside the repo under ${XDG_STATE_HOME:-~/.local/state}/pstack/scratch/ (PSTACK_SCRATCH_ROOT moves it), which Claude and Codex must trust once per host (kitchen.py doctor checks); removed when done
reviews/NNN-<slug>.md	master	verdict on unit NNN, from the review template; names the advice it drew on and any overrule
gates.md	master	open questions for the human
decisions.tsv	master via pair.sh log	the show-me-your-work trail
status.md	pair.sh status	derived table; never hand-edited
queue	master via pair.sh queue and dispatch	the next brief's path, one slot
steps/NNN-<slug>.tsv	sidekick via pair.sh step	one row per committed step: number, commit, time, notes it resolves, summary
notes/NNN-<slug>-n<k>.md	master via pair.sh new-note and note	review of the unit's steps through step k, from the note template: blocking items and follow-ups
followups.md	master via pair.sh note	follow-ups from every note, for a later brief or an issue
session-handoff.md	master	compact recovery and next-task context, read at bootstrap
sessions/	pair.sh spawn / rotate	prior ready reports; retained session exports and timing evidence
events.tsv	every pair.sh command	one row per message, report, wake, and log entry, read by pair.sh metrics

NNN is a zero-padded sequence shared by plan or brief, report, advice, and review, so the files for one unit sort together.

Messages

Prompt text	Direction	Sender's helper	Receiver's move
bootstrap (names the skill, the role, and the store)	master to sidekick and consultant	pair.sh spawn	bootstrap steps, reports/000-ready.md or advice/000-ready.md, reply READY
pstack-trio PLAN <plan-path>	master to sidekick and consultant at once	pair.sh discuss	sidekick grounds the plan in the code; consultant critiques the design; each writes agree or object, ends the turn
pstack-trio BRIEF <brief-path>	master to sidekick	pair.sh dispatch	run the brief, write its report, run pair.sh finish, then end the turn with the REPORT line
pstack-trio BRIEF <brief-path>, queued	master to a working sidekick	pair.sh queue	the master dispatches it after a fresh session; pair.sh next refuses
pstack-trio STEER <steer-path>	master to a working sidekick, or one paused on an objection	pair.sh steer	read it between tool calls; agree and continue, or object with evidence and end the turn
pstack-trio CONSULT <consult-path>	master to consultant	pair.sh consult	read the named files, prototype in scratch if needed, write the advice, end the turn
pstack-trio REPORT <report-path>	sidekick to master	pair.sh finish (or notify)	read the report, review
pstack-trio ADVICE <advice-path>	consultant to master	pair.sh notify	read the advice, decide
pstack-trio STOP <store>	master to sidekick and consultant	pair.sh stop	pause safely, write a stop report or advice

discuss returns when both agents settle, with one response path and status per role. A sidekick busy on a unit does not hold a round up: the consultant gets the plan at once, the sidekick's half is deferred (exit 4), and running discuss again once the sidekick reports sends only that half. consult returns when the consultant settles into idle, done, or blocked. dispatch and wait return when the sidekick's reply lands, the report written since the message, or when it is blocked; a settle from the multiplexer alone is not trusted: a Devin sidekick shows idle as a prompt arrives and between steps, and in a narrow pane can show done for a whole run, so a settle is checked against the pane's "esc to interrupt" line, and one with no report that holds for a minute ends the wait with report: missing. dispatch and wait also return at the check-in interval with a digest. wait also returns the moment a dispatched brief's report lands, even when the sidekick has already taken the queued brief; running: then names the brief it is on. notify prompts the master only when the master is idle. A message you receive after compaction still names this skill and the file to read, so reload the skill and continue from that file.

Plan first

Implementation starts only from a plan the sidekick agreed to and the consultant advised on. The master drafts plans/NNN-<slug>.md with the chosen design, the alternatives it weighed, and their pros and cons, then sends it with pair.sh discuss, which reaches both agents at once. The sidekick checks every step against the code and answers agree or object with evidence. The consultant critiques the design itself: data shape, boundaries, what the alternatives table misses, and answers agree or object. The master merges both into the next round or a review with verdict agreed.

The consultant is advisory. An object from the consultant does not block agreed; the master may overrule it with the reason under the review's Overruled section and a decisions row. An advice file for the plan round must exist, though: pair.sh dispatch refuses a feature, bug-fix, refactoring, perf-issue, or pstack-tdd brief whose plan has no consultant advice on file or no agreed review. Read-only and forensic briefs need no plan; a bug's diagnosis brief runs before its plan. Three rounds without agreement become a gate for the human, with all positions in gates.md.

Consults

A consult is the master's question to the consultant outside a plan round. pair.sh new-consult <store> <NNN> --kind <kind> creates the file for unit NNN; pair.sh consult sends it and waits for the advice.

Kind	When	The consultant answers
design	the master weighs a direction before a plan or steer	which way and why, with the trade-offs
finding	a check-in digest, report, or diff surfaced something unexpected	whether it is what it looks like, and what it changes
objection	the sidekick objected to a steer	who is right on the evidence, and the alternative
review	a verdict is contested or a unit is on its second revise	accept, revise, or reject, with findings
glance	a check-in shows the first commit or a sizeable diff on a unit whose revise would cost the most	in five minutes: would the review say revise, and why, or none

Consults are mandatory before: a steer that departs from the agreed design, a superseding steer after a sidekick objection, and a revise verdict on a unit's second try. They are optional elsewhere, and none is sent for the landing unit: every discussion and review ends before landing. Three consults per unit; new-consult refuses a fourth without --force, because a fourth means the design is wrong and belongs in a plan round. A glance sits outside that cap, one per unit, and is never mandatory: the consultant's quota is the scarce one, so spend it where a late revise would cost the most.

Every consult runs at any time, the sidekick working or not. consult stamps the sidekick's state and HEAD on the file; the consultant reads committed work at that head, and anything uncommitted only through a pair.sh scratch snapshot, never a tree that moves under it. Each consult carries a timebox, fifteen minutes by default and five for a glance; past it the consultant writes partial advice and ends the turn.

Check-ins and steers

Unchanged from pstack-pair: the sidekick appends progress lines, dispatch and wait return a check-in digest at the interval, and a steer is the one message that may reach a working sidekick. Two fresh steers per brief, two rounds each. The consultant adds one step: when a digest or objection shows a finding that changes the design, the master consults before it steers, and the steer's Direction cites the advice path.

Task sessions of every kind

A sidekick of any kind (Claude, Codex, Devin, pi, Prime, Muse) uses a fresh conversation for each completed brief. Before spawning, queueing, rotating, or cleaning its storage, read the Devin session lifecycle for Devin or Pi, or the Prime adapter for Prime. Partial and blocked work stays in its session; a completed brief leaves the queue for the master to dispatch. dispatch and discuss rotate the sidekick themselves first (rotated: in their output); pair.sh rotate stays for the master to run by hand. The pstack store persists across sessions.

Prime Agent

Use --kind prime-agent for the sidekick or consultant. Read the Prime Agent adapter for native model arguments, preflight, steering, exact daemon-session cleanup, and provider failover. Prime uses the shared store protocol and requires rotation after each completed brief.

Pi sidekick and fallback

A pi sidekick reports its state to Herdr (and, with the pstack extension, to Rex) through its own events and queues a steer without cancelling the running command. When its model sits behind a route that can fail, spawn it with --fallback devin: spawn checks the model first, and pair.sh failover swaps in the fallback mid-run. Read the Pi sidekick reference before spawning one.

Keeping the sidekick busy

The sidekick is the critical path: the master turns a report around in minutes, while a unit takes tens of minutes to hours. Three habits keep the sidekick from waiting on the master.

• Queue the next brief. While a unit runs, the master drafts the next one and holds it with pair.sh queue. After a done report the sidekick starts a fresh session and the master dispatches that brief; pair.sh next refuses. The queue has one slot and holds only a unit that does not hinge on the running unit's review, so a revise becomes a follow-up brief, not a rework of the queued one.
• Review at the commit. A brief that writes says commit: yes, and the report's head: names that commit. The master reads it with git show while the sidekick works on the next unit, and reruns checks in pair.sh scratch <store> NNN-<slug>-review --at <head>, never in the shared tree.
• Amend instead of re-planning. An objection the master adopts becomes a numbered amendment in the agreed review. A new plan round is for a changed design, not a narrowed step.

pair.sh metrics <store> reads events.tsv and shows where the time went: sidekick busy and idle, master wakes, review latency, verdicts. Sidekick idle time is the number to drive down.

Draft-PR review

A brief is a draft PR that the master reads as it grows, not a diff it meets at the end. Review that arrives after hours of work returns long finding lists, and each fix round widens the change and reruns every check; review of each step catches the same blockers while they are one commit old.

• The brief's Steps are commit-sized, twenty to forty-five minutes each. The sidekick commits each step, records it with pair.sh step, and goes straight on. It never waits for review.
• The master's wait returns steps: when a step lands that no note covers. The master reads that range, writes a note with pair.sh new-note, and publishes it with pair.sh note, while the sidekick works on.
• A note, like a review, splits its findings. Blocking is only what would make the unit wrong to land: wrong behaviour, a missed consumer of a changed value, data or schema safety, a rollback hazard, a broken contract, a test that does not test its claim. Everything else is a follow-up: note copies those to followups.md, and they never widen the unit or cause a revise.
• At each step boundary the sidekick runs pair.sh notes, fixes the open blocking items first as fixup commits, and records them with pair.sh step --resolves. finish refuses a done report while one is open.
• A problem that would waste the next steps, a wrong design rather than a wrong line, still goes out at once as a steer.
• Each step runs the checks it names, and a brief's Verify runs the targeted tests plus the landing gate's fast checks. The full test battery runs once: in the landing brief, or, where the gate is slow, in the issue's last implementation unit.
• The final review reads only the report's review-delta, the diff since the last note, and accepts unless it finds a new blocking item.

A brief without Steps runs as before, with one review at the end.

Pausing

pair.sh pause <store> --reason <why> stops the work at the next safe point, for a skill upgrade or anything else that needs all agents quiet. Anyone may run it, including the human or another session.

• The sidekick sees PAUSE: in the output of its next pair.sh step, notes, or progress. It commits what is verified, writes the report as partial with where it stopped and the next step, runs pair.sh finish, and ends the turn. finish hands out no queued brief while paused.
• The master's dispatch, queue, and discuss refuse while paused, and so do consult and answer where the skill has them. A wait prints paused:. The master finishes the step it is in, records where the work stands and the exact next step in gates.md, and ends its turn.
• pair.sh resume <store> lifts the pause. The master re-reads the skill if it changed, then re-dispatches the paused brief; the sidekick's step log says where to continue.

pair.sh stop is the immediate variant, for a sidekick that must stop mid-step.

Shared rules

• Facts about panes, agents, and states come from the multiplexer through pair.sh, never from memory or sidebar order.
• Approval dialogs belong to the human unless the standing orders delegate a class of them to the master. No agent answers another's dialogs.
• All three share one working tree. The sidekick writes it. The master and the consultant read it and its history at any time and write nothing in it that git does not ignore. Their builds, tests, installs, and prototypes go to a scratch worktree from pair.sh scratch, at a commit or a snapshot of the live state, removed when done, so they never race the sidekick's edits.
• Sidekick and consultant never message each other. Both read the store.
• Close only panes you created, and only when the human asked.