orca-team

Orca team tooling

This skill complements Orca's orchestration skill. Load its version-matched guide with orca skills get orchestration before coordinating workers; Orca owns that skill and its lifecycle commands. Dotfiles owns the pane and watch helpers here.

In a project with the agent team (it has .claude/agents/elon.md), the default Orca coordinator is the elon role. Elon owns the cross-project objective, cross-role DAG, dispatch and completion review. tech-lead is a teammate that coordinates engineering integration and reports to Elon. Keep this split explicit in task messages and completion reports; CEO recommendations never replace human-owner approval or required independent review.

worker-watch.sh <run_id> next to this file flags STOPPED (provider limit or network error), IDLE (empty input prompt without busy markers), BLOCKED_DIALOG (trust dialog), BLOCKED_APPROVAL (pending tool approval prompt) and LOW_CONTEXT; each exits 4, while OK exits 0. Run it as ~/.claude/skills/orca-team/worker-watch.sh. On IDLE or network STOPPED, send the worker a resume message with orca terminal send --terminal <handle> --text "Resume the assigned task and report its outcome." --enter at once; never leave it waiting. worker-watch.test.sh is its test.

worker-panes.sh <run_id> <coordinator_terminal> [dispatch_id ...] shows workers as colored split panes in the coordinator's tab (coordinator left; the first pane splits it to the right, later panes stack in that right column, and the coordinator is split again only when no worker pane is left) (Orca cannot start a worker as a split pane). Each pane runs worker-pane.sh <dispatch_id> [color], a read-only live mirror of that worker's screen; it shows the final status line when the dispatch ends, waits about 10 seconds (ORCA_PANE_CLOSE_DELAY) and closes its own terminal through ORCA_TERMINAL_HANDLE (skipped when unset), verifying that the handle disappears from orca terminal list and retrying failed or lingering closes after 5, 15, 30, then 60 seconds for up to 30 minutes in a plain shell loop (CLI calls are bounded too), so a pane whose split timed out and was never recorded does not linger. A failing worker-show keeps it running. Each pane's handle is recorded in ~/.cache/orca-worker-panes/<dispatch_id>. Run it as ~/.claude/skills/orca-team/worker-panes.sh; worker-panes.test.sh and worker-pane.test.sh are its tests. The moment the coordinator validates a worker's report (or the worker fails), it runs ~/.claude/skills/orca-team/worker-pane-close.sh --release <dispatch_id>. That runs worker-release, records a released marker (Orca keeps external terminals on release, so the marker lets a later sweep, wrap-up's included, close them while the worktree still exists) and closes the recorded pane and every terminal of the dispatch still in orca terminal list: the handles worker-show reports (agent and setup terminals) and any terminal whose worktreePath matches the linked git worktree the worker created or reused (its .git must be a file, so main checkouts are matched by worker handle only), so a pane whose split timed out is covered too (worker-panes.sh records the one new pane that appears in the tab after a timed out split). A dispatch still running keeps its terminals, and so does a terminal that any dispatch not in a final state also uses (a retry started with --retry-of --terminal reuses the failed dispatch's terminal; the script reads every page of worker-list and keeps such a handle with its record), and the owner's own sessions and other projects' terminals are never matched. Records are removed only after verified disappearance; unfinished closes remain recorded for a later sweep. Only positively ended dispatches authorize closure, including recorded panes: state succeeded, completed, failed, cancelled or released, stage released, or liveness exited. worker_state.py reads the flat Orca JSON first and the older nested shape as a fallback. Release closes at most the agent terminal, so after a confirmed release the script closes the remaining exact handles itself (never the agent terminal, never the caller's own ORCA_TERMINAL_HANDLE). Run with no arguments on every wake to close recorded panes of ended dispatches whose linked worktree no longer exists (a settled dispatch whose worktree is still there may be on a correction pass, so the sweep keeps it; explicit ids skip this check) and discover leftover terminals via every page of worker-list, restricting newly discovered dispatches to the current project's identity from live terminal metadata (discovery is skipped if that identity is unknown), using the same worker-handle and exact linked worktree matching rules; worker-pane-close.test.sh is its test. Pane color comes from the role in the task title (<role> - <job>), looked up in role-colors.tsv next to the scripts (unknown role: grey), so always start the title with the role name. Add a line there for a new role.