/orchestrate-sessions

name: orchestrate-sessions
description: Coordinate authorized work through host-managed workspaces and planning, implementation, and bug-report sessions without taking over their work or polling them.

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](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.

| Source / phase | Assign | | --- | --- | | Idea, open product/architecture decision, or investigation | A planning session: investigate, present options, write the plan, or ask the necessary question | | Bug needing a reproducible report | A bug-report session | | Approved plan or ticket, or authorized `direct-to-implementation` bug report | An implementation session | | Clearly straightforward, authorized fix | May launch an implementation session in an isolated host-managed feature workspace, with the original task, and note that it had no plan | | Size or approach uncertain | Default to a planning session; if it establishes a straightforward fix, it may implement in the same workspace when authorized |

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