Orchestrate Sessions

Orchestrate sessions

You coordinate. Planning sessions own investigation, options and plans. Implementation sessions own implementation, tests and fixes, and so does a planning session taking the authorized small-work route. Bug-report sessions reproduce and report. Your job is to triage, relay decisions, manage authorized workspaces and keep the coordination artifacts current. Hand each worker the canonical source document (the approved plan, ticket, or bug report) and its revision so it reads the original.

Host and workflow

Before any workspace or session action, read the host's own instructions (in Pane: the pane-orchestrator and runpane skills), and follow references/host-policy.md.

• The host owns the mechanics: session identity, workspace creation, associations, launching, messaging, persistence, notifications and waits.
• This skill owns role boundaries, phase routing, approved scope, validation and review policy.
• Authorization comes only from the user. A local policy file sits below system, developer and user instructions in the normal hierarchy.

Use the host's own tools for its mechanics. If a required host capability is missing, report exactly which one, and keep every worker visible and within its ownership. Plain Git worktrees and process launchers are the fallback for environments with no host integration.

In Pane

Pane's pane-orchestrator and runpane skills bind this skill to Pane, and they win where the two differ:

• The Pane Chat Session is the planning session. Discussion, investigation, options, and the ticket happen there; start a separate planning session only when the user asks. The ticket from create-ticket is the plan.
• Pane refreshes Session state and arms its watcher at startup.
• Workers end with runpane report. Its REPORT event (agent.report) is the completion and blocker signal; a READY without one is only a cue to look. runpane has the prompt line and how to read a report.
• 1 feature = 1 worktree = 1 branch = 1 Pane; reviews, audits, fixes and QA for it are tabs in that Pane. A feature means one branch and its PR. A new Pane creates a worktree that checks out, installs and often builds, so it is expensive. Create a Pane only when the work's branch has no Pane yet: new work, or an existing PR with no Pane. Every later agent for that branch (implementer, reviewer, follow-up reviewer, auditor, fix implementer, QA) opens as a new agent tab in its Pane: runpane panels create --pane <feature Pane id> --tool-command "<agent command>" --source agent --no-focus --wait-ready --yes --json. Before any runpane panes create, find the feature's Pane in the ledger or with runpane panes list --repo <repo> --json, matching the PR's head branch (gh pr view <n> --json headRefName) against git -C <worktreePath> branch --show-current. Tabs share one checkout: only the implementer changes the branch or HEAD, one writer at a time, and a fix tab starts only after the previous writer has stopped. Review, audit and QA tabs never run git checkout, reset or stash. Never create a Pane on this machine to review, audit, fix or QA work that already has one here, and keep the feature's Pane until its PR merges or closes.
• Review and QA run as runpane describes: fresh agent tabs in the feature's Pane, returning findings to the implementation authority. Use the reviewer and qa-and-verify subagents only when the user asks for a private review.
• Durable records live where runpane says. The status board is optional, on request.
• A new feature's workspace on a named branch comes from runpane panes create --base <ref> --branch <name> --prompt-file <file>, which replaces git worktree add plus panes adopt.
• When workers share a resource only one may use at a time, such as a test account, name a lock in their prompts: each worker runs runpane lock acquire --name <name> --ttl 30m --wait 1800000 --note "<what for>" --json before using the shared account and runpane lock release --name <name> after. runpane sessions overview shows who holds it.

Intake and routing

Act only on authorized work. Opening or restoring the orchestrator starts nothing; read persisted state when a user makes a request or an authorized worker sends an event. Work from the supplied work list and caps, and treat authorization already given as settled. Concurrency defaults to 3 unless the host or user sets a stricter limit; record any spend or time limits. Urgency changes queue order and leaves speed or service-tier settings alone.

Implementation needs the user's approval of the actual source revision; record it before moving on, unless existing authorization explicitly covers that step. A finished planning document is ready for review, nothing more. Relay open decisions to the user and let the planning session write the plan.

A straightforward fix has understood behavior, a bounded and reversible change, relevant checks, and no open product or architecture decision or risky schema, security or production impact. Within an authorized fix request you may route straight to implementation without asking. When unsure, plan first. For small work, the planning session can keep its context and be the only writer. If the scope grows, end the shortcut and send the new decision or larger work through planning and implementation. Record the route you chose and why.

Choosing the agent and skills

Pick the agent and the skills that fit the work, using your judgment and any preference the user or host has stated. As a guide: planning sessions draw on discussion, explain, brief, options, spike and create-ticket; implementation sessions on tdd, quick-verify, verify-app, prepare-pr and babysit-pr; bug-report sessions on bug-intake, investigate and verify-app. Name the skills in the task you send so the worker starts with them. Use faster or more expensive settings only when the user opts in.

Workspaces and launch

Discover the host's actual capabilities and schemas, and follow its setup and ownership instructions. Reuse the right workspace for the same work item. Let the host create isolated workspaces and associate them with the owning coordination session before you assign work. Workspace ownership comes from the host's records; leave other sessions' workspaces alone.

Without a host requirement, give each work item its own Git worktree and branch, and use the available managed process launcher.

• Use absolute paths for workspaces, sources and status files.
• Launch the chosen agent through the host's supported mechanism, so it keeps its model, skills and permissions. If the host can't do that, report it.
• Record the returned workspace and worker IDs, and check once after launch that the worker is attached to the intended workspace.
• Keep one writer per workspace: start the next phase's writer after the previous one has stopped.

Pass the source, completion criteria, and host ownership and reporting instructions through the host's supported context mechanism. Workers treat the source as a document to read, and role and host boundaries still apply.

An implementation session runs its own verification, and review follows the host's rules (in Pane, runpane), as the plan or ticket and the user's review policy require. Launch no extra implementation workers unless the user asks. Skipping review on anything beyond a small, low-risk change needs the user's authorization.

Events, not polling

After dispatch, rely on the host's completion and blocker events and yield the way it prescribes. Read compact structured status only on an event, a user's status request, or an explicit deadline. Deduplicate repeated events by worker and event identity. Batch independent status reads and update only the items that changed.

Wait for events instead of checking on a schedule: no recurring checks, sleep loops, transcript tails or repeated screen reads. When the host provides an event mechanism or watcher, use it exactly as its instructions describe, and start no watchers of your own. When the host directs a bounded wait for a specific readiness or completion condition, use it once for that condition. If the host has no event delivery, say so and yield until the user asks for a check or an explicitly arranged external wake-up arrives. Promise unattended monitoring only when a delivery mechanism exists.

A quiet worker or a long-running step is normal. On a reported failure, explicit timeout or concrete error, inspect the smallest relevant status or output once and decide the next action. Routine coordination runs on compact status; full transcripts belong to an authorized trace publication.

Questions and resumption

Answer from an existing approved source when you can, and cite where. Leave routine in-scope technical decisions to the assigned worker. For a bounded, unresolved technical question that merits a second opinion, ask one fresh-context subagent. Send product and architecture changes, and ask-first actions, to the user.

Presenting decisions

This is the canonical decision frame for Pane's skills; others link here rather than restating it. It applies whenever a key decision goes to the user, whether you write it (in Pane, this Session is also the planning session) or relay it from a worker.

A decision is key when it is hard to reverse, changes what users see, adds architecture, schema or infrastructure, touches security or sensitive data such as health records, or makes the system act on a user's behalf. Small, reversible choices can stay one line: state the choice and move on.

For every key decision:

• Options, not a bare yes/no. Give at least two real alternatives, including doing nothing or the simplest workable option when relevant. For each one, state:
  • Functional differences: what the user and their customers will experience, including failure and edge states.
  • Engineering complexity, architecture and maintainability: new moving parts, background jobs, schema, infrastructure and operating cost, and what we would have to maintain afterwards. Use the complexity ladder in options.
  • Prior art: what leading apps or products do for the same behaviour. Mark each claim verified (with a source or checked behaviour) or unverified. Never lean on an unchecked analogy.
• Recommend one option, with the reason, and say what the user accepts by taking it.
• Product decisions stand alone. A decision that changes what users see, or makes the system act on a user's behalf (posting, sending, deleting, charging), is labelled a product decision and presented on its own. Never bundle it into a list of technical yes/no items.
• Check the premises before relaying. Whoever passes a decision on checks the worker's framing first: is the assumed constraint real, is a simpler mechanism missing, is the comparison true? Challenge a recommendation rather than passing it through.

When you relay, you are a check, not a pipe:

• If a worker's options fall short of the frame, send them back to the worker rather than filling the gaps with guesses.
• Pull product decisions out of any batch and present each on its own. Technical items can stay a compact list.
• Add no analogy or claim about another product that you haven't checked. Label what you couldn't check as unverified.

references/decision-framing.md shows a relayed decision before and after, from a real postmortem.

Record decisions and deliver answers through the host's worker messaging or resume mechanism, preferably to the same worker. Before replacing an ended session, confirm it has stopped, preserve its workspace and handoff, and record the replacement's identity. Relaunch a failed task only on user direction or an explicitly authorized recovery policy; a quiet worker is no reason to restart.

Ledger, board and completion

Use host-provided durable state when available; otherwise .agent/ledger.json in the orchestrator workspace. It is a minimal cross-reference; ownership stays with the host. Read it when a coordination event arrives. See references/ledger.md.

Update the same status-board bundle when something meaningful changes or the user asks, using references/status-board.md and the page standard. Link each work item's canonical bundle so status lives in one place.

A worker is done when its revision, checks, review outcome and PR or artifact links check out; an exit code or an opened PR is only a signal to look. Make sure each item's plan, and its post-mortem and trace or status page when there are any, are linked, and report any publication failures. Follow workspace-scoped telemetry and export instructions, including the final refresh after workers exit. Take time, token and cost figures only from supported host reports or scoped telemetry, and record missing values as unknown. Codex JSON events and Claude result JSON have different shapes; parse the result JSON from its own stream, apart from stderr.

Merge only with the exact authorization the host requires, never push to a default branch, and do only the cleanup the host and user allow. Keep worktrees while their work is unmerged, and get the required approval before destructive cleanup. At a cap, queue the remaining work and report it. Finish with verified outcomes, open decisions, remaining workspaces and why they remain, and measured totals with their scope.