Orca CLI Agent Environment

One consolidated skill for the Orca agent environment. Each sub-scenario is a reference file; the shared rules live here once.

Resolve the CLI for this session

Choose the executable once and reuse it for every later command:

• If the ORCA_CLI_COMMAND environment variable is set, use its value. Orca exports this for managed WSL sessions.
• Otherwise, in a dev checkout whose session exposes ORCA_DEV_REPO_ROOT, use orca-dev.
• Otherwise, on Linux outside an Orca-managed terminal, use orca-ide. Never run bare orca there — outside Orca's terminals it normally resolves to the GNOME Orca screen reader (/usr/bin/orca) and starts speech on the user's machine.
• Otherwise, use orca.

Below, ORCA is a placeholder for the executable you resolved. Substitute it before running anything; do not create a shell variable or run ORCA literally. This works the same way in POSIX shells, PowerShell, and cmd.exe.

If the selected executable cannot run, report its exact error and stop. Do not fall through to another executable, which could silently target a different Orca build.

Load the version-matched guide before running Orca commands

Each reference file names the guide its scenario loads. Prefer ORCA skills get <skill-name> --json. Use the selected executable's --help for commands or flags the guide does not cover.

If a command reports that Orca is not running, start it with ORCA open --json and retry. If it fails with runtime_access_denied, your sandbox blocked the connection: re-run it with escalated permissions, and do not run ORCA open or restart Orca. If skills get is unknown, explain that updating Orca restores the guide; use --help for read-only discovery and do not guess unsupported commands.

Scenario routing

Grok Build in Orca worktrees (agent slot)

Attach Grok Build to a worktree with orca worktree create ... --agent grok --no-parent — the Grok TUI runs in the worktree's first terminal (--surface terminal; --surface chat for pure read-only analysis). Two ways to use that slot:

• Supervised (default for /implement, /execute-plan runs): subagents bind to the worktree via cwd; task text is NEVER sent to the TUI (--prompt stays off). The TUI is the orchestrator's monitoring surface only. A monitoring TUI that stays idle or holds unmerged local changes blocks later worktree rm --force — kill the terminal or retire the worktree before assembly/teardown.
• Full handoff: send the brief via orca terminal send after orca terminal wait --for tui-idle; confirm accepted: true, then stop driving it. Hermes-style agents (Hermes orchestrating a Grok Build TUI in the worktree) use this mode exclusively: plan the brief, drop it once, wait for idle, then verify the worktree state and ship (commit/push/PR) themselves.

Full-handoff pitfalls — these cost rework when ignored:

• tui-idle is not a reliable progress signal. The terminal stream can stay empty (tail: [], 0 returned lines) while Grok is actively writing files and committing in the worktree. Never assume idleness from an empty orca terminal read output. Verify progress directly in the worktree directory: git log --oneline -3, git status --short, git show --stat <head-sha>, and ls <expected-new-file>.
• orca terminal wait promotes past the 600s cap. When a wait exceeds the foreground cap it becomes a tracked background process with notify_on_complete=true instead of being refused. Do not re-run the wait; poll with process_manage(action="poll", session_id=<session_id>) or wait for its completion notification.
• After orca terminal send returns accepted: true, stop driving. Grok owns the worktree from there; continued sends interleave with its work. Confirm acceptance, then disengage and verify via worktree state.
• Grok can omit pieces it considers incidental. Grok may drop functions or methods it thinks are "legacy" (e.g. load_rows, read_catalog_text) while keeping callers that need them. Always run the full test suite in the worktree before declaring done — not just the subset Grok mentions — and git show --stat <head> to confirm exactly which files changed.
• Base the worktree intentionally. worktree create bases on origin/main regardless of --prompt. For a task stacked on a sibling feature branch, check git log --oneline -3 in the worktree and git reset --hard <base-sha> (or recreate) before sending the brief — otherwise the work conflicts or misses predecessor commits. The full handoff contract — including what to put in the brief, how to wait, and how to verify + ship after Grok finishes — is codified in the agents-arwaky repo skills implement and execute-plan under references/hermes/ (their Hermes lane). Load those step files before running a /implement or /execute-plan handoff; they are the authoritative procedure for that class of task.

Mutually exclusive per worktree — pick one per worktree, never both. The implement and execute-plan skills in the agents-arwaky tree use the supervised mode; their step files are the authoritative protocol for that class of task.

Handoff vs. supervision boundary

Full ownership handoff — "hand off", "handover", "give this to another agent", "another worktree" — routes to cli.md and stops after the prompt is accepted. Supervised orchestration — the user asked to monitor, coordinate a DAG, use decision gates, or manage ask/reply — routes to orchestration.md and keeps the original agent in control. The two are mutually exclusive.

Headless vs. TUI launch — agent slot must go through this skill

Hermes delegates to Grok Build only through this skill (orca). When a user-facing agent (Hermes or a Grok-style orchestrator) wants a headless Grok run, the canonical pattern is:

# 1. Orca worktree with the Grok agent slot
$ORCA worktree create --repo path:<repo> --name <task-slug> --agent grok --no-parent --json

# 2. Drive Grok headless INSIDE that worktree (the worktree is the launch context)
cd <worktree_path> && grok -p '<brief>' --cwd <worktree_path> --always-approve --max-turns <n>

# 3. Collect Grok's output, then retire/verify the worktree