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
20 changes: 12 additions & 8 deletions .agents/skills/bearings/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,13 +14,14 @@ metadata:
Generate a complete current snapshot from the fleet's current state, so the captain can resume in one read after a break, a night, or a context reset.
Plain `/bearings` returns only the concise four-section chat digest.
Only `/bearings file` writes the dated markdown report artifact and then returns the concise four-section chat digest linked to that report.
This skill is operationally read-only in both modes.
It never tears down a task, merges a PR, dispatches new work, steers a worker, answers a decision, cleans up work, mutates backlog or task state, or writes any file except the single dated report in explicit file mode.
This skill is operationally read-only in plain mode and custody-preserving in file mode.
It never tears down a task, merges a PR, dispatches new work, steers a worker, answers a decision, cleans up work, or mutates backlog or task state.
Explicit file mode may write only the dated report plus the version and receipt for a prior same-day report through `bin/fm-bearings-report.sh`.

## Invocation modes

- Plain `/bearings` gathers a fresh bounded snapshot and renders the four-section chat digest without creating, deleting, reading, or replacing `data/status-report-<YYYY-MM-DD>.md`.
- `/bearings file` gathers a fresh bounded snapshot, replaces today's `data/status-report-<YYYY-MM-DD>.md` from scratch, and renders the four-section chat digest with a link or path to that report.
- `/bearings file` gathers a fresh bounded snapshot, versions any prior same-day report before replacement, and renders the four-section chat digest with a link or path to that report.
- Treat `file` only as an explicit invocation option in the slash command.
- Do not treat natural-language requests such as "write a report", "save this", "persist it", or "make a file" as file mode unless the invocation explicitly includes the standalone `file` option.
- When the captain asks to include PRs, pass the snapshot command's live-PR opt-in.
Expand Down Expand Up @@ -49,12 +50,14 @@ It never tears down a task, merges a PR, dispatches new work, steers a worker, a
The chat response uses the four complete sections in the chat-response contract below, in the same order, each always present.
Plain mode stops here and writes no report artifact.

3. **In explicit file mode only, compose and replace the detailed report file.**
3. **In explicit file mode only, compose and custody-preserve the detailed report file.**
The report uses the same four complete sections as the chat, in the same order, and adds the detail the chat omits.
Never read an earlier `data/status-report-*.md` to decide what to omit, include, describe as changed, or call current.
Write the full report to `data/status-report-<YYYY-MM-DD>.md` using today's date.
If today's file already exists, delete it first, then create a new file from scratch.
This is the only write allowed by the skill.
Compose the full report in a temporary draft outside `data/status-report-*.md`, then install it with `bin/fm-bearings-report.sh <complete-draft.md>`.
The installer writes `data/status-report-<YYYY-MM-DD>.md` using today's date.
If today's file already exists, the installer first copies its exact bytes to a create-exclusive unique path under `data/status-report-versions/` and writes a pre-transition receipt containing its digest, byte count, source ref, custody class, and timestamp.
Never delete, truncate, or directly overwrite the dated report, and never hand-write the custody receipt.
The version and receipt preserve evidence only; never read them to decide what belongs in the new current report.
The detailed report includes:
- **Title** - `# Bearings - <day> <YYYY-MM-DD>` (use "Morning status" only when the captain specifically asks for a morning brief), followed by two or three sentences framing where things stand.
- **Captain's Call** - every open decision summarized with its options from the structured decision record, plus each PR ready to merge and each needed credential or login, every PR with the full `https://...` URL, never a bare `#number`.
Expand Down Expand Up @@ -103,5 +106,6 @@ Rules that keep the contract unambiguous:
## Supervision discipline

This skill changes no fleet state.
Do not tear down a task, merge a PR, dispatch queued work, steer a worker, answer a queued decision, clean up work, or mutate any `state/` or `data/` file other than the single report file in explicit file mode.
Do not tear down a task, merge a PR, dispatch queued work, steer a worker, answer a queued decision, clean up work, or mutate task state.
In file mode, the dated report and its prior-version custody artifacts are the only permitted `data/` writes.
If the state you read suggests an action - a PR ready to merge, a queued item whose gate has arrived, or a needs-decision finding - name it in its section and leave the action to the normal lifecycle and configured authority rather than taking it from inside this skill.
17 changes: 13 additions & 4 deletions .agents/skills/decision-hold-lifecycle/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,10 +18,18 @@ Every unresolved decision that belongs to the captain and is discovered while pr
The agent performs the semantic inventory because scripts must not infer decisions from report prose, visual-review artifacts, terminal output, or chat.
Give each distinct unresolved decision a stable privacy-safe key, register it through `bin/fm-decision-hold.sh hold`, and use the same key on retry so registration is idempotent while different decisions retain different durable identities.
After inventorying the whole report and review surface, run `bin/fm-decision-hold.sh complete` with every unresolved key, or with `--none` only when the reviewed surface contains no unresolved captain decision.
A live originating task may be cleaned up after `complete` retains its report-bound task and dispatch carrier, including for `--none`, binds every unresolved hold to that exact dispatch, and proves each hold reappears in Bearings.
Cleanup does not require the captain to answer in the same session, and it never closes the hold.
Do not hand-write a backlog row, archive row, decision object, or receipt to satisfy this gate; only the script-owned lifecycle is authoritative.
A completed investigation and an ended visual review use this same owner and completion command; a visual tool, including Lavish, never owns a parallel completion policy.
Run the command in the originating work's authoritative `FM_HOME`; main-home work creates main-home holds, and secondmate-owned work creates holds in that secondmate home's backlog rather than copying them into the main backlog.
Do not close a hold merely because the originating investigation completed, its report was archived, its visual review ended, or its task was torn down.
The hold remains the authoritative Captain's Call item until the captain's answer is durably recorded, dependent work is created in the same backlog and blocked by that hold, and `bin/fm-decision-hold.sh resolve` routes the answer by clearing those dependency edges before closing the hold.
Resolution retains a digest-bound decision object and a task-and-dispatch-bound receipt.
For a historical open hold whose exact endpoint dispatch binding survives, re-run `complete` with the full recorded inventory to reconstruct the cleanup receipt from current authoritative state.
If that binding is absent, or if a historical resolved row lacks its script-owned cleanup receipt or canonical decision object, preserve the origin metadata and hold row and keep cleanup refused because no safe automatic migration is shipped.
An exact `resolve` retry may finish a missing resolution receipt only when the script-owned cleanup receipt and canonical decision object both survive.
Never substitute force or discard for the missing historical authority.
Resolved findings, recommendations that need no captain choice, and prose that merely sounds decision-like do not create holds.
Bearings reads the resulting structured state and must never compensate by scraping historical reports, visual-review artifacts, terminal output, chat, or other prose.

Expand All @@ -31,10 +39,11 @@ Bearings reads the resulting structured state and must never compensate by scrap
2. Inventory only genuine unresolved choices that require the captain.
3. For each choice, choose a stable key and use the script's `hold` command with a concise title, reason, and repository.
4. Run the script's `complete` command with the full unresolved-key inventory for that review pass.
5. Relay the choices to the captain as decisions from Bearings' Captain's Call section under `AGENTS.md` section 9; do not use the word hold in captain chat.
6. After the captain decides, record dependent work with normal tasks-axi commands and block it by the hold identity.
7. Put the captain's exact durable decision in a file and use the script's `resolve` command with every routed task.
8. Confirm Bearings no longer shows the closed hold and that routed work remains in structured backlog state.
5. Before cleanup, let the script's read-only `verify` command confirm the task identity, exact dispatch, nonzero object digests, and a fresh Bearings appearance; unresolved or indeterminate evidence refuses and follows the historical remedy above without force or discard.
6. Relay the choices to the captain as decisions from Bearings' Captain's Call section under `AGENTS.md` section 9; do not use the word hold in captain chat.
7. After the captain decides, record dependent work with normal tasks-axi commands and block it by the hold identity.
8. Put the captain's exact durable decision in a file and use the script's `resolve` command with every routed task.
9. Confirm `verify-resolution` accepts the trusted receipt, Bearings no longer shows the closed hold, and routed work remains in structured backlog state.

`bin/fm-decision-hold.sh --help` owns command syntax, identity construction, completion attestation, retry behavior, and close ordering.
`docs/decision-hold-lifecycle.md` records the mechanism and regression evidence without restating this policy.
3 changes: 2 additions & 1 deletion .agents/skills/firstmate-codexapp/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,8 +61,9 @@ For a Firstmate-managed task, include an explicit status instruction:

```text
Append supervisor-visible status lines to <absolute-firstmate-home>/state/<task-id>.status.
Use only these prefixes for status changes: working:, needs-decision:, blocked:, paused:, done:, failed:.
Use only these prefixes for status changes: working:, needs-decision:, blocked:, paused:, awaiting-captain:, done:, failed:.
Use paused: only for a deliberate known external wait that should be rechecked later, never for a blocker that needs firstmate to act.
Use awaiting-captain [key=<slug>]: only after work is complete and an unbounded captain answer is required, and close it only with resolved [key=<slug>]: after the captain answers.
Before doing substantive work, append "working: Codex Desktop thread started".
```

Expand Down
6 changes: 5 additions & 1 deletion .agents/skills/stuck-crewmate-recovery/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,10 @@ Load `secondmate-provisioning` instead for `kind=secondmate` recovery.

Treat the digest's endpoint result as a presence signal, not proof that the task's work or validation run is gone.
Read the targeted current state with `bin/fm-crew-state.sh <id>` before deciding to relaunch.
A no-mistakes run matched to the crew's branch and current code remains authoritative when the endpoint is dead: handle a terminal or parked run through the normal lifecycle, and keep supervising an active run instead of creating a duplicate worker.
A pane and a detached pipeline worker are independent supervision subjects: interrupting or exiting the pane affects only the interactive agent, not a headless native agent or its process tree.
A no-mistakes run matched to the crew's branch and current code remains authoritative when the endpoint is dead: handle a terminal or parked run through the normal lifecycle, and keep supervising an active headless worker instead of recording the task stopped or creating a duplicate worker.
When the recorded pipeline step is `running` but its bound native-agent PID is dead or suspended, report that contradiction instead of recording the run as live; use the pipeline's supported abort and custody flow only after its process ownership is reconciled.
If the run record cannot be bound to a native-agent identity, report that limit as indeterminate rather than inferring live or dead from the pane.

When no authoritative run accounts for the task, inspect only its recorded backend and worktree inventory.
Use `treehouse status` for treehouse-backed tmux, herdr, zellij, or cmux tasks, and use the recorded `orca_worktree_id=` and `terminal=` for Orca tasks.
Expand All @@ -42,6 +45,7 @@ Escalate in order:
2. If the crewmate is waiting on a question its brief already answers, answer in one line via `FM_HOME=<this-firstmate-home> bin/fm-send.sh` from an active firstmate session unless `FM_HOME` is already set to the active firstmate home.
3. If the crewmate is confused or looping, interrupt with the adapter's interrupt key, then redirect with one corrective line.
For example, for a single-Escape adapter: `FM_HOME=<this-firstmate-home> bin/fm-send.sh <window> --key Escape`.
Re-read `bin/fm-crew-state.sh <id>` immediately afterward: the interrupt does not stop a detached validation worker, and a still-live headless worker keeps the task working.
4. If the crewmate is genuinely wedged after redirection, exit the agent with the adapter's exit command and relaunch with the same brief plus a `progress so far` note appended to it.
Genuine wedging means looping, unresponsive, repeating the same obstacle, or truly dead.
A low context reading is not wedging; modern harnesses auto-compact and keep going.
Expand Down
Loading
Loading