firstmate-orca

---
name: firstmate-orca
description: Operate Firstmate with the Orca runtime backend for spawning, supervising, recovering, and safely cleaning up Orca-managed worktrees and terminals. Use when selecting or troubleshooting Orca in a standalone Firstmate installation.
license: MIT
---

# Firstmate Orca

Use Orca as Firstmate's explicit runtime backend without bypassing Firstmate's lifecycle guards.

## Roles

- Firstmate remains the captain-facing coordinator. It owns intake, task identity, briefs, supervision, reconciliation, delivery checks, and guarded cleanup.
- Orca supplies each task's isolated git worktree and terminal endpoint. Orca is a runtime backend, not an agent harness.
- A verified harness such as Pi runs the worker inside the Orca terminal.

Run Firstmate helpers from the root of the Firstmate clone. If the installation uses a separate `FM_HOME`, keep that variable set for every helper call.

## Preflight

Require all of the following:

- macOS.
- A standalone [Firstmate](https://github.com/kunchenguid/firstmate) clone.
- The Orca app running and ready, with the `orca` CLI available.
- A verified worker harness such as Pi.

Check readiness before any spawn:

```sh
orca status --json | ruby -rjson -e '
r = JSON.parse(STDIN.read).fetch("result").fetch("runtime")
abort "Orca is not ready" unless r["reachable"] == true && r["state"] == "ready"
puts "Orca ready"
'
```

Do not treat an open app window alone as readiness. The runtime result must have `reachable=true` and `state="ready"`.

## Select Orca explicitly

Orca is never auto-detected. For persistent local selection, create the literal Firstmate file `config/backend` containing only `orca`:

```sh
mkdir -p config
printf '%s\n' orca > config/backend
```

For one task, Firstmate can pass `--backend orca` to `bin/fm-spawn.sh`; `FM_BACKEND=orca` is also a one-launch override. Existing tasks keep the backend recorded at spawn time.

Before changing the default, inspect active tasks and reconcile watcher wakes. A backend change affects future spawns only.

## Spawn through Firstmate

Let normal Firstmate intake create the task brief and identity. Then use Firstmate's helper, not raw Orca worktree or terminal commands:

```sh
bin/fm-spawn.sh "$TASK_ID" "$PROJECT_DIR" --harness pi --backend orca
```

A successful Orca-backed task records, conceptually:

- the stable Firstmate task alias;
- the backend name;
- the runtime-issued Orca terminal handle;
- the runtime-issued Orca worktree identity; and
- the isolated worktree path.

The Firstmate task ID and its recorded metadata are the routing authority. Orca IDs are backend implementation details. Never fabricate task records or patch an externally created Orca terminal into Firstmate state.

## Supervise and steer

Prefer the helper surface:

```sh
bin/fm-peek.sh "$TASK_ID" 40
FM_HOME="$FIRSTMATE_HOME" bin/fm-send.sh "$TASK_ID" 'Short steering message'
FM_HOME="$FIRSTMATE_HOME" bin/fm-crew-state.sh "$TASK_ID"
```

Use the active Firstmate supervision protocol for the primary harness. Pi normally uses Firstmate's tracked watcher integration. When a bounded foreground checkpoint is appropriate, use:

```sh
bin/fm-watch-checkpoint.sh --seconds 180
```

Keep these evidence types distinct:

1. Status files are sparse, durable event logs. Their last line is not necessarily current state.
2. `bin/fm-crew-state.sh` reconciles the current task state from authoritative run and endpoint evidence.
3. `bin/fm-peek.sh` is a bounded terminal-tail fallback for diagnosis. Scrollback can be stale and must not override recorded identity or current-state checks.

Send short steering lines. If submission fails, peek and reconcile state before retrying; do not repeatedly retype a long instruction into an uncertain composer.

## Recover without duplication

For a missing, stalled, or interrupted task:

1. Keep the existing task ID.
2. Inspect its recorded metadata and sparse status events.
3. Run `bin/fm-crew-state.sh` and `bin/fm-peek.sh` before deciding the worker is dead.
4. Confirm the recorded terminal, worktree identity, and worktree path still agree.
5. Preserve all uncommitted changes and commits in the recorded worktree.
6. Reuse or resume that recorded copy through Firstmate's reconciliation path; do not spawn a second task for the same work.

Stop if identity is missing, unreadable, or mismatched. Do not raw-delete an Orca worktree, manually repair metadata, reset work, or create a replacement while the recorded copy may contain unpublished work.

## Clean up through the guard

After delivery or a completed scout report, run:

```sh
bin/fm-teardown.sh "$TASK_ID"
```

Normal teardown must refuse dirty or unpublished ship work. It verifies the recorded Orca identity and path, closes the exact terminal, and releases the exact worktree through Orca only after Firstmate's landing checks pass.

Treat scouts separately: their deliverable is the recorded report, and cleanup must also pass Firstmate's unresolved-decision completion gate. Never use force merely to silence a refusal; force is only for an explicit decision to discard work.

## Security boundaries

- Review this skill and the upstream Firstmate scripts before granting an agent access.
- Keep credentials and private operator state outside this repository and outside task instructions unless the task explicitly requires them.
- Trust runtime-issued handles only when they match Firstmate's recorded task identity.
- Use Firstmate helpers for mutation. Raw Orca inspection is a last resort; raw deletion is not a recovery or cleanup method.
- Do not expose terminal output, briefs, metadata, or reports publicly without reviewing them for secrets and private project information.

## Current limits

- macOS only.
- Explicit selection only; Orca is not auto-detected.
- The Orca app/runtime must be running and ready.
- Orca exposes no stable protocol or CLI version marker, so readiness and accepted response shapes are the compatibility gate.
- Orca-backed secondmate spawns are unsupported.
- There is no native busy signal in this integration; supervision falls back to harness-scoped terminal-tail evidence when stronger current-state evidence is unavailable.
- Escape is unsupported by the current Firstmate Orca send path; Enter and interrupt are supported.