orca-pstack

---
name: orca-pstack
description: >-
  Run a pstack role on the harness that has its model. Use when poteto-mode,
  arena, swarm, how, why, architect, interrogate, reflect, show-me-your-work,
  or setup-pstack is about to spawn a subagent whose model this harness cannot
  run. Dispatches an Orca orchestration worker on any agent that worker can
  launch, and replaces pstack's same-family fallback. Also use for /orca-pstack.
---

# Orca pstack

pstack assigns a model per role. A harness can spawn only the models its own subagent tool accepts. This skill runs every other role as an Orca worker, then brings the result back to this chat.

Orca's orchestration skill is not in this repo. Load it from the `orca` binary and follow it for the coordinator loop: receipts, ending the turn, `send`, wakes, and failure recovery. This skill only decides which pstack seat is a worker, and the agent, model, and effort to start it with.

## Runtime tool adapter

Before translating any native spawn or lifecycle operation, read [the runtime adapter contract](references/runtime-adapter.md). It governs Cursor-style tool names and arguments throughout pstack. `swarm` and `arena` are workflows; their workers may use native tools or Orca. Never drop required model selection, access constraints, or isolation merely because the local tool lacks a field.

## When this applies

Do this before every pstack spawn. That includes a playbook delegate, an arena runner or judge, a swarm worker, a how explorer or explainer, a why investigator or synthesizer, a reflect reviewer or synthesizer, an interrogate adversary, an architect runner, and the show-me-your-work reviewer.

1. Resolve the slug the way the calling skill says. Use the settings line, else that skill's default. Adjust effort the way poteto-mode's Subagents section says, and keep the family.
2. `inherit-parent` or `auto` runs on the parent model. Spawn it locally and omit `model`, or perform the step directly if no local subagent tool exists. Stop.
3. The prompt already says you are the pstack delegate for this role. Do the work. Do not dispatch a worker to rerun it.
4. Normalize the role with **Map the slug** first. Stay local only when the current subagent tool can select that model, or inheritance is proven to use that exact model. A CLI catalog is not proof that the subagent tool accepts a model. Cursor may accept several providers; Claude Code may accept aliases; inspect the actual tool schema. Codex model overrides must follow its tool contract, including `fork_turns: "none"` when required; put the full brief in the new context. Grok's tool has no model argument, so a requested Grok model different from, or unverified against, the parent goes through Orca too. If no local subagent tool exists, dispatch through Orca. Stop only after a valid local spawn.
5. Otherwise the seat is cross-harness. Dispatch it below. Keep the family. Any agent enabled on the selected worker server is eligible. A CLI missing here does not rule out another configured execution host, but help examples alone do not prove launch availability. Use the placement guide before choosing another host.
6. If the requested model cannot be launched, mark the seat unavailable with the exact reason. Continue independent work, but do not replace the seat with the parent model, another family, or an agent's unspecified default. Report incomplete panel coverage and any required verification still outstanding. A substitute requires a user-configured alternative or an explicit user choice. This rule overrides fallback instructions in calling skills. An unknown start is pending recovery, not an unavailable seat; never launch a replacement while it might still run.

A panel mixes the two. Decide each entry on its own.

Model family and agent are different. For diversity checks, derive the family from the resolved model/provider: Claude is Anthropic, GPT/o-series is OpenAI, Grok is xAI, Gemini is Google, and Composer is its own family. Cursor and OpenCode can host multiple families. A bare agent id or an opaque model has unknown family until runtime evidence identifies it. Unknown is not different: do not count it as a cross-family judge or verified panel diversity. Keep a per-seat record of requested model, route, task/dispatch ids, reported actual model (or unknown), status, and evidence.

## Resolve the CLI, then load orchestration

Pick the executable once. `ORCA_CLI_COMMAND` when it is set, otherwise `orca-dev` when `ORCA_DEV_REPO_ROOT` is set, otherwise on Linux outside an Orca-managed terminal `orca-ide` (bare `orca` there is the screen reader), otherwise `orca`.

`ORCA` below means that executable. Type it in place. Do not invent a shell variable named `ORCA`. If it cannot run, report the error and take step 6. Do not try a different binary.

Before the first dispatch in the session:

```text
ORCA skills get orchestration
```

Follow that guide. It owns receipts, when to end the turn, `send`, and wakes. Load a conditional reference with `ORCA skills get orchestration --reference references/<file>.md` when that guide names one. This skill names two: `references/placement-and-remote.md` for a child worktree or a connected server, and `references/recovery-and-cleanup.md` when a start fails for a reason other than the model correction below.

If a command says Orca is not running, run `ORCA open --json` once and retry it. On `runtime_access_denied`, follow the session permission policy; escalate only if permitted. Otherwise report the blocker. Do not run `ORCA open`.

## Map the slug

Split the role value into an Orca agent, a model id, and an effort.

An explicit value comes first. For a value with two or more tokens, its first token is an Orca agent id when it is not `opus`, `sonnet`, `haiku`, or `fable`. Validate it against worker-server capabilities; an unknown id is unverified, not automatically supported. The id does not have to be a CLI on this machine. The second token is the model id. A third token is the requested effort; validate it against the selected runtime/model capabilities. Preserve supported values such as `ultra` even when absent from the legacy suffix ladder. An unknown or unsupported token must be reported, never silently discarded. A fourth token `fast` is dropped. Do not run the prefix table on an explicit value. When that agent is the current harness and its subagent tool accepts the model id, spawn locally. Pass the model id and the effort, not the whole line.

A single token known as an Orca agent id (including a hyphenated id), other than `inherit-parent`, `auto`, `opus`, `sonnet`, `haiku`, and `fable`, is an agent id and no model flag. Resolve legacy model prefixes and Claude aliases before treating an unknown single token as an agent; bare `o1`, `o3`, and `o4` are Codex models. The worker runs the model from that agent's own config.

Space-separated Claude aliases come next. `opus`, `sonnet`, `haiku`, and `fable`, alone or followed by one effort token, are agent `claude`. The alias is the model id. Pass `--effort` only when the second token is present. These are local seats in Claude Code only when its current tool accepts the alias; otherwise dispatch them through Orca.

Otherwise split a hyphenated slug. Effort tokens, highest first, are `max`, `xhigh`, `high`, `medium`, `low`. When the last token is `fast` and the token before it is an effort token, drop `fast` and keep that effort. A trailing `fast` with no effort token before it stays in the model id. Grok has no `max`. Pass `xhigh` when the slug says `max` and the agent is `grok`.

A provider prefix before a slash maps first. `anthropic/` is `claude`, `openai/` is `codex`, `xai/` and `x-ai/` are `grok`, `google/` is `gemini`. The model id is the part after the slash, with effort and a trailing speed-`fast` removed the same way.

Otherwise the first matching prefix wins. This table is only for legacy slugs. An explicit agent id with no row is still dispatched.

| Prefix | Agent | Model id |
| --- | --- | --- |
| `claude-` | `claude` | Slug with effort and a trailing speed-`fast` removed. If a start refuses that id, one correction uses `opus`, `sonnet`, `haiku`, or `fable`, the name the slug contains. |
| `cursor-grok-` | `grok` | Drop `cursor-`, then drop effort and a trailing speed-`fast`. |
| `grok-` | `grok` | Slug with effort and a trailing speed-`fast` removed. |
| `composer-` | `cursor` | The full slug, effort tokens included. Omit `--effort`. If refused, mark the Composer seat unavailable; Grok is not a Composer alias. |
| `gpt-`, `o1`, `o3`, `o4`, `codex-` | `codex` | Slug with effort and a trailing speed-`fast` removed. |
| `gemini-` | `gemini` | Slug with effort and a trailing speed-`fast` removed. Pass `--model` only when the worker-start note says Gemini accepts it. |

Do not pass `inherit-parent`, `auto`, or a family name as `--model`.

A slug with no known agent or prefix is unresolved. Report the unavailable seat and request an explicit `<agent> <model-id>` mapping; never guess a local substitute.

Worked splits:

| Role value | Agent | Model | Effort |
| --- | --- | --- | --- |
| `grok-4.7-xhigh-fast` | `grok` | `grok-4.7` | `xhigh` |
| `claude-opus-5-5-xhigh` | `claude` | `claude-opus-5-5`, else `opus` | `xhigh` |
| `claude opus xhigh` | `claude` | `opus` | `xhigh` |
| `opus xhigh` | `claude` | `opus` | `xhigh` |
| `codex gpt-5.5 high` | `codex` | `gpt-5.5` | `high` |
| `codex gpt-6-astra high` | `codex` | `gpt-6-astra` | `high` |
| `cursor-grok-4.7-xhigh` | `grok` | `grok-4.7` | `xhigh` |
| `gpt-5.5-xhigh` | `codex` | `gpt-5.5` | `xhigh` |
| `grok-4.7-max` | `grok` | `grok-4.7` | `xhigh` |
| `zcode` | `zcode` | omitted | omitted |

Cursor keeps effort inside the model slug for a local spawn. An Orca worker takes effort as `--effort`, except Composer on `--agent cursor`, which keeps the Cursor slug.

A trailing speed `fast` is not an Orca flag. The worker runs at standard speed. Say that in the reply when the slug asked for fast.

## Model flags

Read `ORCA orchestration worker-start --help` and follow its Notes. Those Notes decide which agents accept `--model` and `--effort`. A missing CLI on this machine does not remove an agent or a model id. If the Notes you just read disagree with the snapshot below, the Notes win.

On current Orca builds the Notes say `--model` takes opaque provider model ids for Claude, Codex, Cursor, Antigravity, Grok, and Muse, and `--effort` requires `--model`. OMP accepts `--model` only. OpenCode accepts `--model` only on an existing worktree, with a verified execution-host CLI and an available model, and it does not accept `--effort`. Every other agent, including zcode, launches with the model from its own config.

Pass `--model` and `--effort` only for an agent the Notes include. Omit effort when absent or unsupported and disclose that limitation. If an explicit model cannot be passed, mark the seat unavailable instead of dropping `--model`. For OpenCode, a parallel writer with an explicit model needs an isolated existing Orca workspace before dispatch; follow the placement guide to create it, then target its exact selector. Do not silently run its configured default in `new-child`. Bare agent entries explicitly opt into that agent's config; omit both flags and report the actual model as unknown until verified.

## Skills and tool capabilities across runtimes

Orca starts and supervises an agent; do not assume it synchronizes installed skills, MCP servers, credentials, permissions, or chat context. A shared worktree gives access to files, not to the parent's tools. Model routing and tool availability are separate checks.

Before dispatch, include a capability manifest in the brief:

- Required skill entry points and their source revision or content hash, plus referenced prompts, scripts, assets, and interpreter/package requirements. Use the exact orca-pstack copy selected by the coordinator, not another installed upstream skill of the same name.
- Worker-visible input and output paths, the scope snapshot, and access constraints.
- Required operations in domain terms (for example, read the named issue and its comments), their source/account/workspace scope, and whether live access is essential or a timestamped evidence snapshot suffices. Tool names on the parent's runtime are hints, not portable API names.
- For each operation, its planned route: worker tool, coordinator-mediated evidence, or unavailable. Keep unverified routes explicitly unverified until the worker checks them.

**Skills.** On a shared host, pass readable absolute paths and require explicit reads; installing or automatic skill discovery is not necessary. On another host, stage the necessary skill dependency tree with relative references intact in the task workspace and pass those worker-local paths. Include referenced scripts and assets, not only SKILL.md. The worker maps harness-specific tool instructions to its actual tool schema. A missing dependency or unsupported runtime feature is a capability gap, not permission to silently skip that step. Do not change global skill installations as part of dispatch.

**Worker preflight.** Before substantive work or edits, the worker reads the manifest, checks required files and executable dependencies, and inspects its own available tool schemas and source scope. A server name or a config file is not proof of a usable connection. Where needed, use a minimal authorized read to verify access. Do not add a separate probe worker; this is the first phase of the requested seat. Include the checks and any gaps in its evidence. Runtime capability errors can also arise later and use the same handling below.

**MCP.** If the worker has an equivalent authorized tool, it uses that tool's schema. Otherwise, when the coordinator can perform the required read and a snapshot is sufficient, the coordinator collects evidence through its own tools and supplies a worker-readable artifact with source links/ids, query scope, retrieval time, and omissions. The worker still performs the assigned reasoning on the requested model. For additional evidence it uses Orca's `ask` protocol, then ends its turn; the coordinator retrieves the evidence and replies with accessible paths or scoped excerpts. Do not poll, invent an MCP proxy endpoint, or assume the worker can call the parent's tools directly.

A coordinator-provided excerpt is not an independent source lookup. Label it as supplied evidence. If the task requires independent retrieval, live interaction, a write, or an unavailable source, do not claim a snapshot satisfies it. Keep that operation pending and report the gap; use another already authorized placement only when it preserves the requested model and required access. Writes require the task's existing authorization and must be executed by the runtime with the appropriate tool and permissions. An evidence request does not authorize a write.

Never copy tokens, credential stores, or complete MCP configuration files to make a worker match the parent. Pass only task-relevant evidence within the authorized destination and scope. Do not broaden access, install servers, or initiate new account connections implicitly. If no authorized route meets a required capability, report the seat as blocked or partial, with the outstanding operation; missing access is not a search with no results.

## Start the worker

### Verify placement before dispatch

Run these read-only checks with the shell working directory explicitly set to the user's task checkout, not the skill installation or this repository:

```text
ORCA worktree current --json
ORCA worktree show --worktree path:<absolute-task-checkout> --json
```

Compare the returned workspace path and execution host with the intended checkout, resolving filesystem symlinks when comparing local paths. For Git work, record the checkout root from `git rev-parse --show-toplevel`; a shared repository or remote URL is not enough because another worktree can hold different code. Retain the exact workspace id returned by Orca and use `id:<returned-id>` for current/existing-workspace launches. Never infer the target from the visible project, a coordinator's inherited environment, a bound Run, or the path written inside the brief.

If `current` fails, identifies a different checkout, or disagrees with the explicit lookup, do not launch with `current` or `new-child`. If the explicit lookup succeeds, inspect that exact workspace and use its id, resolving any coordinator/Run placement conflict through Orca's guide first. If no workspace matches, report that the target project is not registered with Orca. Open/register the intended project through Orca's documented flow before retrying; do not substitute an already open project. These checks apply to external Codex/Claude sessions even when their shell cwd is correct.

For a new child, first verify that Orca's caller workspace is the intended parent on the same host, then follow `references/placement-and-remote.md`. If caller identity cannot be established, resolve it before creating a child. For remote execution, validate an exact selector on the worker host; local `current` is not a remote target.

### Launch and check the receipt

The orchestration guide owns the lifecycle. For a verified existing workspace, the pstack command is:

```text
ORCA orchestration worker-start --spec-file <path> --worktree id:<verified-workspace-id> --agent <agent> --model <model-id> --effort <effort> --task-title "<role>" --json
```

Omit `--model` and `--effort` when the model-flag section says so. Use `--worktree new-child` only after the parent check above; add `--name <short-name>` only for that creation path.

Inspect every start receipt before launching dependent work. Its workspace must match the verified existing workspace, or a child of the intended project on the selected host. A `ready` receipt on another project is a placement failure, not success. Do not use its output or start a replacement while that worker may still run; follow Orca recovery for that Dispatch and report the mismatch.

Write the brief the calling skill would have given the subagent to a file under `/tmp`. Append these lines.

- You are the pstack delegate for role `<role>` on `<slug>`. Do that work.
- Do not start another Orca worker. If a later step requires another model, report that pending step, its brief, and required role to the coordinator. Do not self-review in place of a cross-model review.
- The capability manifest above, including worker preflight and coordinator-mediated evidence requests.
- Expected checkout path and execution host. Before reading project instructions, running project commands, or editing files, verify your actual cwd against the assigned workspace. For a new child, use the child path supplied by Orca and confirm its project identity. On mismatch, report blocked through Orca without doing repository work; do not merely change directories and continue in a misbound session.
- What you may edit, or that the seat is read-only.
- The evidence that shows the seat is done.
- Absolute paths to the calling skill, its referenced prompts, and (for a poteto-agent role) the installed `poteto-mode/SKILL.md` entry point. Include `agents/poteto-agent.md` only when that plugin resource actually exists; require the worker to read them. Include the user's goal and relevant decisions because workers do not inherit chat history.
- Paths to inputs reachable on the worker host. On another host, transfer the required context and skill files before dispatch. Do not assume the parent's `/tmp`, MCP credentials, or local filesystem exists there.
- Follow Orca's Task/Dispatch preamble and report through `worker_done`. Include evidence and the actual model when available; never claim the requested model was verified merely from the brief.

Worktree, for a seat in this project:

- Read-only seats share the workspace. `how`, `why`, the arena judge, `reflect`, and the show-me-your-work review use the verified existing workspace id. The spec forbids edits.
- One writer on the parent's branch uses the verified existing workspace id. Leave that scope alone until the worker settles.
- Parallel writers use `--worktree new-child`. Arena runners, interrogate adversaries, swarm workers that write, and competing hypotheses are parallel writers. The child is their output location. Do not create a second worktree. A new child stays open after it finishes.

A child checkout does not automatically include the parent's uncommitted changes. Before a parallel worker evaluates the current change, prepare a scope-limited patch and needed untracked inputs, and have the worker apply them in its assigned child before running checks. Record the base revision and input snapshot in the brief. Do not copy credentials or unrelated files. Report the child's path and diff/commit for the parent to review and integrate; a successful child does not update the parent branch.

Connected servers, SSH, and WSL are `references/placement-and-remote.md`.

Start every independent Orca worker, then start any local subagents for the same fan-out, then end your turn. End the turn only when you started at least one Orca worker. A local-only fan-out stays on the calling skill's spawn path. The orchestration guide says why you do not poll.

On every failed or unknown start, load `references/recovery-and-cleanup.md` and inspect `failedStage`, effects, and residual resources before another launch. A model refusal is not an exception to lifecycle recovery. Once the prior attempt is proven settled, a Claude version-to-alias correction may be tried once and must be disclosed; do not drop a required model flag. Retry the same Task with `--task <task_id> --retry-of <dispatch_id>`, repeating the intended placement, agent, model, and effort. Do not retry with `--spec-file`, which creates another Task. Follow the receipt's recovery commands and circuit breaker. If no Task was created, correct a proven pre-launch validation error only; never infer this from an exit code alone.

## When the worker returns

Follow the orchestration guide. Resume the calling workflow at the completed seat, and dispatch any cross-model follow-up the leaf reported. For this seat, summarize the worker's evidence. Rerun a check only for a gap or a contradiction. Review the diff yourself. A worker that stops without `worker_done` is an escalation in that guide. Do not mark that seat done.

## Setup

`/setup-pstack` writes `<agent> <model-id> <effort>`, or a bare agent id when that agent launches from its own config. The agent may be any id `worker-start` accepts. A local CLI probe adds labels and effort ceilings. It does not decide which agents exist. `inherit-parent` and `auto` stay valid. A legacy slug still maps through the prefix table. In the table you show, mark each role `local` or `orca:<agent>`.

• SKILL.md 22 KB
• references/runtime-adapter.md 6 KB