Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 7 additions & 20 deletions .agents/skills/firstmate-orca/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,26 +25,19 @@ Use raw `orca` only when the helper surface cannot answer the inspection questio
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 recovering a task onto Orca:
Before inspecting an Orca-backed legacy task:

- Confirm the task meets the eligibility contract in `docs/orca-backend.md`; new work must use tmux, Herdr, zellij, or cmux.
- Confirm Orca is intentionally selected for this eligible recovery through `--backend orca` or `FM_BACKEND=orca`.
- Confirm the Orca app is running and the backend readiness checks pass before expecting the respawn to work.
- Inspect active `state/*.meta` records before changing backend selection.
- Do not set Orca as the durable backend for a home that launches new tasks.
- Reconcile watcher wakes before unrelated work, especially if Orca tasks are already in flight.
- Do not respawn or destructively tear down an Orca task while the adapter reports that lifecycle authority capabilities are unavailable.

## Spawn

Use `bin/fm-spawn.sh` for an eligible pre-cutover respawn so firstmate creates the worktree, terminal, metadata, status file, and watcher surface together.
New task spawns refuse `backend=orca` before any owned mutation; `docs/orca-backend.md` owns the rationale and exact legacy eligibility rule.

After spawn, check the task with firstmate helpers:

- `bin/fm-peek.sh fm-<id>` for launch failures, trust dialogs, or first output.
- `state/<id>.meta` for `backend=orca`, `terminal=`, `orca_worktree_id=`, and `worktree=`.
- `bin/fm-crew-state.sh <id>` when the current run state matters.
- `bin/fm-watch.sh` whenever there are tasks in flight and this session owns supervision.
New task spawns refuse `backend=orca` before any owned mutation.
Legacy respawn also fails closed until an empirically verified provider capability can bind terminal, task label, worktree, and repository identity and enumerate every terminal attached to a worktree.
`docs/orca-backend.md` owns the evidence and re-enablement contract.

Do not manually create the Orca worktree or terminal for an eligible firstmate recovery.
Do not manually patch metadata to make an externally-created Orca terminal look like a firstmate task.
Expand Down Expand Up @@ -74,18 +67,12 @@ For a messy Orca-backed task:
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 `docs/orca-backend.md`'s eligible legacy task contract; follow its report and landing rules exactly.
Teardown remains governed by `docs/orca-backend.md` and retains resources when lifecycle authority is unavailable.

## Regression Verification

Do not synthesize legacy metadata or spawn a disposable Orca task merely to smoke-test the backend.
Run the focused fake-Orca suite in `docs/orca-backend.md` to verify lifecycle plumbing.
When an actual eligible legacy recovery is already required, verify it through the normal lifecycle:

1. Confirm the task metadata has no `report_required` marker and select Orca for that recovery.
2. Respawn 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.
Do not use an actual legacy recovery to assert lifecycle safety until the required authority capability has empirical evidence.

Do not mix adapter verification with unrelated feature work.
9 changes: 6 additions & 3 deletions .agents/skills/secondmate-provisioning/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -94,6 +94,8 @@ Run `bin/fm-home-seed.sh validate` when checking registry integrity; it refuses

Seeding is transactional.
If validation, cloning, no-mistakes initialization, or registry update fails, generated briefs, new homes, new project clones, and registry edits are rolled back.
Home provisioning, child spawn, and retirement use one canonical home lifecycle lock.
The lock order is home lifecycle, task lifecycle, then registry; recursive retirement acquires parent homes before child homes and holds each home lock through its final state check, removal, and registry update.

Secondmate project lists may include `no-mistakes` and `direct-PR` projects only.
`local-only` projects stay with the main firstmate.
Expand Down Expand Up @@ -159,11 +161,12 @@ Run `bin/fm-teardown.sh <id>` for `kind=secondmate` only when the captain or mai

The safety check is the secondmate's own home.
Teardown refuses while its `state/*.meta` contains in-flight work.
Teardown recursively proves every registered project clone and nested repository clean, stash-free, bound to the corresponding durable source remote, and landed on a surviving remote branch; tags and in-home remotes never count.
When safe, teardown kills the direct tmux window, removes the `data/secondmates.md` route, clears the main home metadata, and removes the retired secondmate home.
Removing a leased home releases its durable treehouse lease via `treehouse return`, so the pool slot is freed for reuse rather than left leased forever.
A plain-clone home with no pool slot is simply removed.
If `treehouse return` fails for a leased home, teardown stops with state intact rather than raw-removing the directory and hiding a held lease.

With `--force`, teardown is the explicit discard path.
It kills child windows, discards child work and state inside the secondmate home, removes the route, releases the lease, and removes the retired secondmate home.
Never use `--force` unless the captain explicitly said to discard the work.
With `--force`, teardown may recursively retire child tasks and nested secondmates.
Every child must first pass the same identity, endpoint-absence, cleanliness, stash, and landed-work proofs; `--force` never authorizes discarding work.
If any child proof fails, retain the child metadata, worktree, home, and parent registration.
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ __pycache__/
.env
config/crew-harness
config/crew-dispatch.json
config/checkout-refresh
config/account-routing-mode
config/secondmate-account-pool
config/secondmate-harness
Expand Down
Loading
Loading