From 343a17419f05d27f3768fc66a1c8ba7e1c371c1b Mon Sep 17 00:00:00 2001 From: Stephen Brouhard Date: Sun, 5 Jul 2026 17:54:23 -0400 Subject: [PATCH 1/2] docs: add Orca operator skill --- .agents/skills/firstmate-orca/SKILL.md | 91 ++++++++++++++++++++++++++ AGENTS.md | 1 + 2 files changed, 92 insertions(+) create mode 100644 .agents/skills/firstmate-orca/SKILL.md diff --git a/.agents/skills/firstmate-orca/SKILL.md b/.agents/skills/firstmate-orca/SKILL.md new file mode 100644 index 00000000..ae7d648c --- /dev/null +++ b/.agents/skills/firstmate-orca/SKILL.md @@ -0,0 +1,91 @@ +--- +name: firstmate-orca +description: Agent-only operator checklist for Firstmate's Orca runtime backend. Use when switching to Orca, spawning or supervising Orca-backed work, smoke-testing Orca backend behavior, debugging Orca task state, or reconciling Orca-backed task metadata. +user-invocable: false +metadata: + internal: true +--- + +# firstmate-orca + +Use this as the operator checklist for Firstmate's experimental Orca runtime backend. +It does not replace `AGENTS.md`, `docs/orca-backend.md`, or `harness-adapters`. + +Orca is a runtime backend, not an agent harness. +The runtime backend owns the task endpoint and, for Orca, the task worktree. +The harness is the agent process launched inside that endpoint, such as `claude`, `codex`, `opencode`, `pi`, or `grok`. +Load `harness-adapters` for harness-specific launch, interrupt, resume, trust-dialog, and skill-invocation facts. + +Implementation details, metadata fields, teardown guarantees, limitations, and smoke evidence live in `docs/orca-backend.md`. +Prefer the `bin/fm-*` helpers over raw `orca` commands. +Use raw `orca` only when the helper surface cannot answer the inspection question, and keep the recorded firstmate metadata as the task identity. + +## Preflight + +Work from the current firstmate home or repo root. +If `FM_HOME` is set, remember that operational state lives under `$FM_HOME` while the helper scripts still run from this repo's `bin/`. + +Before switching or spawning against Orca: + +- Confirm Orca is intentionally selected through `--backend orca`, `FM_BACKEND=orca`, or local `config/backend`. +- Confirm the Orca app is running and the backend readiness checks pass before expecting spawn to work. +- Inspect active `state/*.meta` records before changing backend selection. +- Treat a backend switch as affecting future spawns only; existing tasks keep their recorded backend. +- Reconcile watcher wakes before unrelated work, especially if Orca tasks are already in flight. + +## Spawn + +Use `bin/fm-spawn.sh` so firstmate creates the brief, worktree, terminal, metadata, status file, and watcher surface together. +Pass `--backend orca` for a one-off Orca task, or rely on the already-selected Orca backend when that selection is intentional. + +After spawn, check the task with firstmate helpers: + +- `bin/fm-peek.sh fm-` for launch failures, trust dialogs, or first output. +- `state/.meta` for `backend=orca`, `terminal=`, `orca_worktree_id=`, and `worktree=`. +- `bin/fm-crew-state.sh ` when the current run state matters. +- `bin/fm-watch.sh` whenever there are tasks in flight and this session owns supervision. + +Do not manually create the Orca worktree or terminal for a normal firstmate task. +Do not manually patch metadata to make an externally-created Orca terminal look like a firstmate task. + +## Supervision + +Use `bin/fm-peek.sh`, `bin/fm-send.sh`, `bin/fm-crew-state.sh`, and `bin/fm-teardown.sh` for routine operation. +For steer messages, send short lines through `bin/fm-send.sh fm- '...'`. +Put long instructions in the task brief or a temporary file and point the crewmate at that file. + +When supervising, treat `state/.meta` as the routing record and Orca's own ids as backend implementation details. +The stable firstmate alias is `fm-`. +The recorded `terminal=` and `orca_worktree_id=` fields are what backend helpers use under the hood. + +If `fm-send` fails to submit, do not immediately repeat the same long instruction. +Peek first, then decide whether the target is busy, waiting on a prompt, stuck behind a popup, or genuinely wedged. +For harness-specific interrupts or exits, load `harness-adapters`. + +## Recovery + +For a messy Orca-backed task: + +1. Read `state/.meta` and the relevant status tail first. +2. Confirm the task is actually Orca-backed before using Orca-specific assumptions. +3. Use the recorded `terminal=`, `orca_worktree_id=`, and `worktree=` as the task identity. +4. Prefer firstmate helpers for peek, send, state, and teardown. +5. Avoid raw deletion of Orca worktrees or manual branch cleanup. +6. Stop and inspect if the recorded worktree path, Orca worktree id, or project checkout no longer matches expectations. + +Teardown remains governed by the normal firstmate landing rules. +Scout work can be torn down after the report exists. +Ship work can be torn down only after the work is landed by its project mode. + +## Smoke Test + +Keep Orca smoke tests focused on lifecycle plumbing: + +1. Select Orca intentionally for a disposable task or scout. +2. Spawn through `bin/fm-spawn.sh`. +3. Confirm metadata records the Orca backend, terminal, Orca worktree id, and isolated worktree path. +4. Verify `bin/fm-peek.sh`, a short `bin/fm-send.sh` steer, watcher wake behavior, and `bin/fm-crew-state.sh`. +5. Tear down through `bin/fm-teardown.sh` after the task is safely disposable or landed. +6. Restore the previous backend selection if Orca was selected only for the smoke test. + +Do not mix a backend smoke test with unrelated feature work. diff --git a/AGENTS.md b/AGENTS.md index 6fdaa675..10b30ca1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -850,6 +850,7 @@ It performs only fast-forward self-updates of firstmate and registered secondmat These skills are not captain-invocable; they are conditional operating references you must load at the trigger points below. - `harness-adapters` - load before spawning or recovering a crewmate or secondmate, handling a trust dialog, sending a harness-specific skill invocation, interrupting or exiting an agent, resuming an exited agent, or verifying a new harness adapter. +- `firstmate-orca` - load before switching to Orca, spawning or supervising Orca-backed work, smoke-testing Orca backend behavior, debugging Orca task state, or reconciling Orca-backed task metadata. - `stuck-crewmate-recovery` - load after a stale wake, looping pane, repeated confusion, an answered-by-brief question, an unresponsive crewmate, or a failed steer. - `secondmate-provisioning` - load before creating, seeding, validating, launching, handing backlog to, recovering, pushing inherited config into, or retiring a secondmate home, and before editing `data/secondmates.md`. - `fmx-respond` - load on an `x-mention ` `check:` wake to handle the mention, on an `x-mode-error ...` `check:` wake to report the X-mode configuration blocker, and on any milestone or terminal wake for an X-linked task before posting its completion follow-up; relevant only when X mode is on. From 07e64370dd1e1e6078332f2c162463877fff5557 Mon Sep 17 00:00:00 2001 From: Stephen Brouhard Date: Sun, 5 Jul 2026 18:08:32 -0400 Subject: [PATCH 2/2] no-mistakes(document): Document Orca checklist --- docs/orca-backend.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/orca-backend.md b/docs/orca-backend.md index 55142998..0d475fd9 100644 --- a/docs/orca-backend.md +++ b/docs/orca-backend.md @@ -2,6 +2,7 @@ Orca is an experimental runtime backend for firstmate. It is distinct from the crewmate harness: the harness is the agent process firstmate launches (`claude`, `codex`, `opencode`, `pi`, or `grok`), while Orca owns the task worktree and terminal endpoint underneath that process. +Firstmate agents operating this backend should load the agent-only [`firstmate-orca`](../.agents/skills/firstmate-orca/SKILL.md) checklist before switching to Orca, spawning or supervising Orca-backed work, smoke-testing, debugging task state, or reconciling Orca metadata. ## Setup