Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
167 commits
Select commit Hold shift + click to select a range
b1de8a8
feat(send): route secondmate replies for firstmate requests (#93)
kunchenguid Jun 26, 2026
37c694c
fix: recognize squash-merged work as landed (#96)
kunchenguid Jun 26, 2026
fe3c867
fix: harden no-mistakes validation contract (#97)
kunchenguid Jun 26, 2026
9391e90
fix(watch): assert watcher liveness during wake drain (#101)
kunchenguid Jun 26, 2026
362fb54
fix(brief): slim no-mistakes contract behind version floor (#102)
kunchenguid Jun 27, 2026
ba62f03
fix(send): settle codex skill popups before submit (#103)
kunchenguid Jun 27, 2026
be0cc0c
feat(supervise): add deterministic crew state helper (#104)
kunchenguid Jun 27, 2026
0426607
feat(bin): absorb benign watcher wakes (#107)
kunchenguid Jun 27, 2026
c80396f
feat: firstmate listens and replies on X (inert-by-default client) (#87)
kunchenguid Jun 27, 2026
13f0d43
fix: clarify X-mode owner mention handling (#109)
kunchenguid Jun 27, 2026
0869131
fix: recover safe fleet sync drift (#111)
kunchenguid Jun 27, 2026
7029592
feat(x-mode): add X mention completion follow-ups (#113)
kunchenguid Jun 28, 2026
1fb4226
feat(x-mode): dismiss skipped X mentions through the relay (#120)
kunchenguid Jun 28, 2026
81c94db
feat(watcher): absorb wakes only when the crew is provably working (#…
kunchenguid Jun 28, 2026
2a661da
feat: add grok crewmate harness support (#143)
kunchenguid Jun 29, 2026
0c65b48
feat(harness): split secondmate harness configuration (#144)
kunchenguid Jun 30, 2026
5008513
feat(backlog): default backlog operations to tasks-axi (#145)
kunchenguid Jun 30, 2026
a077cd5
fix(spawn): set per-task GOTMPDIR so interrupted Go builds don't leak…
e-jung Jun 30, 2026
2f57269
fix: accept landed squash-merged PR heads (#149)
kunchenguid Jun 30, 2026
20efee2
feat(dispatch): add dynamic crew profiles (#154)
kunchenguid Jun 30, 2026
008d65c
fix: harden crew dispatch profile enforcement (#159)
kunchenguid Jun 30, 2026
ea0c4af
feat: add live secondmate config push (#161)
kunchenguid Jun 30, 2026
0cbbcae
feat: support image attachments in X replies (#162)
kunchenguid Jun 30, 2026
02f50a3
fix(teardown): make landed PR detection robust (#167)
kunchenguid Jul 1, 2026
e936203
fix: parse PR merge URLs for gh-axi (#168)
kunchenguid Jul 1, 2026
1bc8842
feat(bin): pin secondmate model and effort (#180)
kunchenguid Jul 1, 2026
309f269
feat(bin): add runtime backend interface (#183)
kunchenguid Jul 2, 2026
34e2472
feat(bin): add experimental Herdr runtime backend (#186)
kunchenguid Jul 2, 2026
30a89bc
feat(bin): auto-detect runtime backend (#188)
kunchenguid Jul 2, 2026
30ee4ef
feat(stow): add operational memory capture (#197)
kunchenguid Jul 2, 2026
7d85107
fix(tests): protect herdr smoke cleanup from default sessions (#199)
kunchenguid Jul 2, 2026
34f402c
feat(bin): route herdr secondmates into per-home workspaces (#200)
kunchenguid Jul 3, 2026
6a8b305
fix(backends): rename Herdr secondmate workspace labels (#203)
kunchenguid Jul 3, 2026
01bd2cf
feat(bin): add unified session start digest (#201)
kunchenguid Jul 3, 2026
951f5cf
fix(bin): corroborate herdr idle crew state (#207)
kunchenguid Jul 3, 2026
7af373e
fix(backends): reuse the herdr firstmate workspace instead of leaking…
Bre77 Jul 3, 2026
66f12e9
fix(backends): make Herdr default-tab pruning safe (#215)
kunchenguid Jul 3, 2026
1ff50b1
fix(brief): remove apostrophe breaking bash -n and guard bash 3.2 set…
nilushan Jul 3, 2026
e16f1d8
feat: add experimental zellij runtime backend (#217)
kunchenguid Jul 3, 2026
51f7186
docs: document Orca backend adapter contract (#209)
Jul 3, 2026
df19b71
feat(backends): add Orca primitive backend support (#210)
Jul 3, 2026
c7f85d3
fix(backends): submit herdr slash commands reliably (#223)
kunchenguid Jul 3, 2026
fa090fe
feat(skills): publish public stow skill with internal-skill hiding (#…
kunchenguid Jul 3, 2026
5c3fcb4
feat(skills): clarify public stow resume and fallback routing (#225)
kunchenguid Jul 3, 2026
233a072
docs: clarify note hygiene guidance (#226)
kunchenguid Jul 3, 2026
b54426e
feat(backends): add Orca task lifecycle support (#228)
Jul 4, 2026
ce5e3e0
fix: use PR head for review diffs (#229)
kunchenguid Jul 4, 2026
6a85eed
fix: make backend matching shell-portable (#230)
kunchenguid Jul 4, 2026
36322e8
fix(backends): make herdr respawn idempotent (#231)
kunchenguid Jul 4, 2026
70f646e
fix: absorb stale wakes during active validation (#233)
kunchenguid Jul 4, 2026
4b900b1
docs: clarify no-mistakes evidence commit handling (#232)
kunchenguid Jul 4, 2026
0407109
fix: tighten Orca backend parsing (#237)
Jul 4, 2026
c1eba8f
docs: add backend setup guides and slim README (#238)
kunchenguid Jul 4, 2026
a1461cb
Document herdr dual license in docs and install hint (#239)
kunchenguid Jul 4, 2026
a80b62d
feat: support multiple X-mode follow-ups (#241)
kunchenguid Jul 4, 2026
4a12844
feat(backends): add experimental cmux runtime backend (#246)
kunchenguid Jul 4, 2026
3fb5334
feat(agents): add firstmate coding guidelines skill (#248)
kunchenguid Jul 4, 2026
1b68a69
fix: add turn-end supervision guard (#249)
kunchenguid Jul 4, 2026
bc468e1
feat(backends): auto-detect cmux runtime (#250)
kunchenguid Jul 4, 2026
74a6973
fix(afk): support herdr away-mode injection (#251)
kunchenguid Jul 4, 2026
2db0a5d
docs(agents): move X-mode procedures out of AGENTS (#253)
kunchenguid Jul 4, 2026
207e776
docs: trim duplicated harness guidance (#255)
kunchenguid Jul 4, 2026
2c16f97
fix: anchor turn-end Stop hook to project root (#256)
kunchenguid Jul 4, 2026
56ee51b
docs: trim firstmate agent guidance duplication (#258)
kunchenguid Jul 4, 2026
aaf7de2
feat(backends): improve cmux detection and socket-mode guidance (#259)
kunchenguid Jul 4, 2026
dc37d58
fix(backends): scope zellij tabs by firstmate home (#252)
kunchenguid Jul 4, 2026
65bb62e
fix: sync project clones after merged PR wakes (#293)
kunchenguid Jul 6, 2026
23f2e9c
fix: canonicalize spawn worktree path checks (#294)
kunchenguid Jul 6, 2026
e04902d
docs: add Orca operator skill (#276)
Jul 6, 2026
295c13d
fix: surface green PRs during CI monitoring (#297)
kunchenguid Jul 6, 2026
678f2b5
fix(teardown): recover provably stale git index locks (#296)
kunchenguid Jul 6, 2026
138a9d0
feat(bin): encode project AGENTS.md authoring bar with canonical self…
kunchenguid Jul 7, 2026
463cb51
feat(skills): add captain-invocable bearings status-report skill (#300)
Ballestar Jul 7, 2026
49ffe5d
fix(watcher): make PID identity locale-invariant (#285)
pchuri Jul 7, 2026
0a7cb88
docs: document codex app backend contract (#222)
Jul 7, 2026
a790a20
docs: add Codex Desktop coordination skill (#275)
Jul 7, 2026
f5e89b9
fix(afk): stop herdr escalation redelivery loop (#317)
kunchenguid Jul 7, 2026
01dca33
fix(backends): confirm Herdr submits with native agent state (#323)
kunchenguid Jul 7, 2026
7a42707
feat: add quota-balanced crew dispatch selection (#327)
kunchenguid Jul 8, 2026
121b902
fix(session-start): respawn dead secondmate agents conservatively
kunchenguid Jul 8, 2026
28a3b0e
fix: emit stable secondmate nudge selectors (#331)
kunchenguid Jul 8, 2026
c9e5ba3
feat: require bootstrap detection for AXI tools (#332)
kunchenguid Jul 8, 2026
2061c37
bearings: delete today's report before recreating (#333)
kunchenguid Jul 8, 2026
228963d
feat: guard primary turn ends across harnesses (#339)
kunchenguid Jul 8, 2026
a894c3a
fix: resolve backend selectors by exact task id first (#342)
kunchenguid Jul 8, 2026
091384b
fix: scale bootstrap fleet-sync timeout (#341)
kunchenguid Jul 8, 2026
0f9b7cc
feat: add fleet snapshot and view commands (#343)
kunchenguid Jul 8, 2026
d8a2ff1
fix(fm-send): fail loudly on unresolvable send targets (#254)
mielyemitchell Jul 8, 2026
95dd1a0
fix: deliver AFK escalations through herdr supervisors (#353)
kunchenguid Jul 8, 2026
090483e
feat: add harness-aware supervision (#367)
kunchenguid Jul 8, 2026
4790bc5
fix: split X-mode replies by platform (#369)
kunchenguid Jul 8, 2026
af5361e
fix: make stow memory writes inspect before update (#372)
kunchenguid Jul 9, 2026
7302a95
fix(watcher): wait when arm attaches to a healthy watcher (#375)
kunchenguid Jul 9, 2026
1b5a9f5
feat(pi): simplify primary session launch (#386)
kunchenguid Jul 9, 2026
766f772
feat(supervision): prevent unsafe watcher-arm commands (#387)
kunchenguid Jul 9, 2026
80ecc8d
fix(pi): restore primary watcher supervision lifecycle (#397)
kunchenguid Jul 10, 2026
7525a37
fix: keep persistent secondmates out of the main backlog (#398)
kunchenguid Jul 10, 2026
600075e
fix(backlog-handoff): move full item blocks including indented bodies…
kunchenguid Jul 10, 2026
4bc0824
feat(herdr): make Herdr lab lifecycle safety deterministic for briefs…
kunchenguid Jul 10, 2026
22b1d71
fix(watcher): classify arm-command seatbelt by execution position (#403)
kunchenguid Jul 10, 2026
96244f4
fix: reconcile existing AGENTS.md safely (#405)
kunchenguid Jul 10, 2026
08453f9
feat: support project-less secondmate homes (#409)
kunchenguid Jul 10, 2026
31afb8c
fix: delegate backlog handoffs to tasks-axi (#411)
kunchenguid Jul 10, 2026
171207c
fix: ignore secondmate home marker during sync (#417)
kunchenguid Jul 10, 2026
a955a05
fix(composer): prevent dead-shell message injection (#416)
kunchenguid Jul 10, 2026
7788fa3
feat(watcher): add paused external-wait supervision (#421)
kunchenguid Jul 10, 2026
5f808cc
fix: preserve X-mode follow-up platform limits (#425)
kunchenguid Jul 10, 2026
0eaf293
fix(composer): handle ANSI ghost text safely (#429)
kunchenguid Jul 10, 2026
6d90240
fix(spawn): make tmux window handling robust under non-default config…
Deeds67 Jul 10, 2026
3e3dff6
test: isolate session-start suite from ambient harness markers (#432)
kunchenguid Jul 10, 2026
38086ea
fix(teardown): retry transient index locks during worktree return (#435)
kunchenguid Jul 10, 2026
492c937
fix: complete brief help and consolidate documentation (#438)
kunchenguid Jul 10, 2026
bc558c6
fix: detect Git and centralize backend configuration (#445)
kunchenguid Jul 10, 2026
52241a5
feat(daemon): add backend-independent wedge alerts (#444)
kunchenguid Jul 10, 2026
8cd90fe
docs: centralize firstmate operating contracts (#447)
kunchenguid Jul 11, 2026
3f549c1
fix(cmux): close last workspace during teardown (#449)
kunchenguid Jul 11, 2026
0daf674
fix: recover orphaned packed-refs locks during fleet sync (#453)
kunchenguid Jul 11, 2026
1fb1e30
feat(herdr): escalate blocked panes immediately (#472)
kunchenguid Jul 11, 2026
ad39e49
docs(readme): reposition firstmate as an agent distro (#473)
kunchenguid Jul 11, 2026
a6508b7
feat: add deterministic bounded bearings snapshots (#475)
kunchenguid Jul 11, 2026
78f9cce
fix: enforce deterministic ShellCheck parity (#481)
kunchenguid Jul 11, 2026
88e38ea
feat: guard primary shells from persistent cd commands (#483)
kunchenguid Jul 12, 2026
cb6e8ed
brief: add no-mistakes shared-daemon rule to ship and scout scaffolds…
mielyemitchell Jul 12, 2026
9ecd7c4
feat: make bearings concise and accurate (#485)
kunchenguid Jul 12, 2026
ad9f3a7
fix: harden away-mode daemon lifecycle (#490)
kunchenguid Jul 12, 2026
6556882
fix: prevent no-mistakes gate agents from driving the fleet (#518)
kunchenguid Jul 13, 2026
2364817
fix: guard secondmate primary sessions from blind turn ends (#505)
kunchenguid Jul 13, 2026
547acd7
fix: make bootstrap diagnostics backend-aware (#519)
kunchenguid Jul 13, 2026
b708731
fix: preserve follow-up platform context after inbox cleanup (#520)
kunchenguid Jul 13, 2026
85b7a29
fix: preserve secondmate routing markers in terminal sends (#533)
kunchenguid Jul 13, 2026
8c0d9eb
fix: align Grok effort handling with 0.2.99 (#527)
korallis Jul 13, 2026
8934c17
fix: derive bearings from authoritative secondmate state (#555)
kunchenguid Jul 14, 2026
eb9ee2f
fix: restore fleet snapshots on stock macOS Bash (#578)
kunchenguid Jul 14, 2026
1811b89
fix(afk): make Pi escalation and return catch-up reliable (#587)
kunchenguid Jul 15, 2026
f8c5941
feat: support Pi max reasoning profiles (#537)
korallis Jul 15, 2026
e063ca5
chore: no-mistakes(document): Clarify yolo response ownership (#595)
kunchenguid Jul 15, 2026
fcb9e8a
feat: establish instruction ownership foundation (#619)
kunchenguid Jul 15, 2026
71db4be
fix: compress Firstmate contract and enforce delivery rigor ownership…
kunchenguid Jul 16, 2026
cd218f2
feat: add durable captain decision holds (#593)
kunchenguid Jul 16, 2026
064aa67
fix(bin): harden PR check artifacts (#556)
kunchenguid Jul 16, 2026
815f7af
fix(bin): compact session-start backlog digest (#636)
kunchenguid Jul 16, 2026
2406354
fix: dedupe stale watcher guard banners (#637)
kunchenguid Jul 16, 2026
c115561
fix(bin): balance bearings landed baseline (#640)
kunchenguid Jul 16, 2026
a5d3652
fix: clarify captain-facing translation contract (#644)
kunchenguid Jul 16, 2026
1346ff7
fix(bin): make bootstrap output and nudges deterministic (#646)
kunchenguid Jul 16, 2026
508a6b7
docs(secondmate-provisioning): clarify concise registry ownership (#649)
kunchenguid Jul 16, 2026
024b96b
fix(bin): strip quoted blocked_by values during decision hold resolve…
kunchenguid Jul 17, 2026
e6f240c
feat(secondmate): inherit shared captain preferences (#656)
kunchenguid Jul 17, 2026
c27135c
feat: gate local agent secret injection (#658)
kunchenguid Jul 17, 2026
85643ee
test: isolate Herdr autodetect smoke sessions (#662)
kunchenguid Jul 17, 2026
5bf59ba
docs: adopt under way for active work (#666)
kunchenguid Jul 17, 2026
6de9278
Revert "feat: gate local agent secret injection (#658)" (#668)
kunchenguid Jul 17, 2026
46e4201
fix(pi): distinguish stale locks when arming watcher (#681)
kunchenguid Jul 17, 2026
1182883
fix: accept secondmate house vocabulary (#685)
kunchenguid Jul 18, 2026
d939c49
fix(bin): parse handoff homes after registry parentheticals (#686)
kunchenguid Jul 18, 2026
3ebb219
feat: add native session-start nudges (#687)
kunchenguid Jul 18, 2026
6bdeb3a
docs: call built-in defaults the firstmate repo, not template (#688)
kunchenguid Jul 18, 2026
bc1a21b
fix(bin): repair fm-brief.sh parse error and harden set -u array expa…
Ballestar Jul 18, 2026
3729081
fix(bin): keep watcher supervision continuous across child cycles (#693)
kunchenguid Jul 19, 2026
b2bf95f
fix: fetch current PR head for review diffs (#722)
kunchenguid Jul 19, 2026
7a9b4dd
docs: resolve five contract contradictions across AGENTS.md, README, …
ICGNU3 Jul 19, 2026
15b0fb9
docs(harness): correct Grok exit guidance (#742)
kunchenguid Jul 19, 2026
ab8cea6
fix(watcher): bound stale wakes for parked crew (#743)
kunchenguid Jul 19, 2026
68c6110
fix(supervision): distinguish ordinary wakes from recovery (#744)
kunchenguid Jul 20, 2026
c12bdea
fix(x-mode): dedupe pending mention wakes (#745)
kunchenguid Jul 20, 2026
4ab61fa
feat(wake): enrich drained signals with bounded status context (#747)
kunchenguid Jul 20, 2026
708711e
fix(send): treat opencode busy-queued composer state as submitted
KostadinP Jul 20, 2026
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
202 changes: 115 additions & 87 deletions .agents/skills/afk/SKILL.md

Large diffs are not rendered by default.

81 changes: 81 additions & 0 deletions .agents/skills/bearings/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,81 @@
---
name: bearings
description: Generate a "pick up where I left off" status report from firstmate's live fleet state. Use when the captain invokes /bearings or asks for a bearings report, morning brief, status report, catch-up, "where did I leave off", or "what's in the works". Reads bounded local fleet state cheaply, optionally checks open PRs when requested, composes a scannable dated report to data/status-report-<YYYY-MM-DD>.md, and surfaces a concise version in chat; it is read-mostly and must not tear down, merge, or mutate task state as a side effect of producing the brief.
user-invocable: true
metadata:
internal: true
---

# bearings

Generate a complete standalone snapshot from the fleet's current state, so the captain can resume in one read after a break, a night, or a context reset.
The deliverable is a dated markdown file plus a concise chat summary that each stand on the current snapshot rather than an earlier report.
This skill is read-mostly.
It reads fleet state and writes exactly one report file.
It never tears down a task, merges a PR, dispatches new work, or mutates any task state as a side effect of producing the brief - those belong to the captain's explicit word and the normal task lifecycle.

## What it does

1. **Gather live fleet state with one deterministic command.**
Run `bin/fm-bearings-snapshot.sh` and read its compact output.
It is the single bounded, deterministic source for this report and renders TOON by default.
Do not hand-probe the snapshot schema and do not make ad-hoc `gh-axi`/`gh` calls to assemble fleet facts; this command already assembles them.
The command's header and `--help` output own its exact fields, bounds, opt-ins, and output contract.
When the captain asks to include PRs, use the command's live-PR opt-in; otherwise keep the default local-only read.
If the command is unavailable, fall back to `bin/fm-fleet-snapshot.sh --json` and `bin/fm-crew-state.sh <id>`; never infer current state from a raw `tail` of `state/<id>.status`, which is append-only wake-event history whose last line goes stale.
For registered secondmates, use the snapshot's structured-home classification and provenance; a parent event or bounded terminal contradiction is fallback evidence, never authority over readable structured home state.
Structured captain-held decisions come from `decision-hold-lifecycle` and appear under `decisions_open`; do not scrape reports or visual-review artifacts to supplement them.
A queued item under `gates` only becomes "next work" when its blocker is gone and its time/date gate has arrived; until then it stays queued with the reason.

2. **Compose the detailed report file around the four-section spine, adding the richer detail the chat leaves out.**
The gather step is deterministic; your judgment is scoped to the last mile only - ranking the command's facts by what matters right now and writing the scannable prose.
Never read an earlier `data/status-report-*.md` to decide what to omit, include, describe as changed, or call current.
The report uses the same four complete sections as the chat (see the chat-response contract below), in the same order, each always present, and adds the detail the chat omits:
- **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`.
- **Recently Landed** - the bounded current recent-completions baseline from structured state across the main fleet and every registered secondmate home, rendered in full on every run.
- **Underway** - each live direct report making progress, with its current state, and the plans / main pickup pointers worth reopening (`data/<id>/report.md` files, `.lavish/*.html` boards).
- **Charted Next** - queued or gated next work, with each item's blocker or date reason.

3. **Write the dated report file so it persists, then surface the mandatory four-section digest in chat.**
- Write the full report to `data/status-report-<YYYY-MM-DD>.md` using today's date.
This is the required artifact; it lives in gitignored `data/`.
If today's file already exists, delete it first, then create a new file from scratch.
- The chat response is the concise four-section digest defined by the contract below: materially shorter than the report file, complete as a current snapshot, internally consistent with the file, and linked to that file for the full picture.
- For a richer review surface, optionally offer a Lavish board with `lavish-axi` when the report has enough structure to deserve one, but the markdown file is the required artifact and the four-section chat digest is the required minimum.

## Chat-response contract

This skill is the one owner of the `/bearings` chat-response format; the snapshot and classifier own the data that feeds it, and no other file restates this contract.
Every `/bearings` chat response renders EXACTLY these four sections, in THIS order, and nothing else structural (there is no At Anchor section):

1. **Captain's Call** - ONLY items that need the captain's own action now: a decision to make, a PR to approve or merge, a credential or login to provide, or a blocker only the captain can clear.
Empty-state: "Nothing needs your action right now."
2. **Recently Landed** - the bounded current recent-completions baseline: merged PRs, completed scouts, and finished local-only merges across the main fleet and every registered secondmate home.
Empty-state: "No recent completions are in the current baseline."
3. **Underway** - live work progressing on its own, one line of current state per direct report.
Empty-state: "Nothing is underway."
4. **Charted Next** - queued or gated work waiting on the fleet or a date, never on the captain.
Empty-state: "Nothing is queued."

Rules that keep the contract unambiguous:

- Every section ALWAYS renders, even when empty, with its short empty-state sentence; never omit a section.
- Every report and chat digest is a complete current snapshot, never a delta against a prior report.
- Recently Landed always renders the bounded current baseline, even when the same completions appeared in an earlier report.
- The four buckets are mutually exclusive, so every item is forced into exactly one: needs-your-action is Captain's Call, done is Recently Landed, self-progressing is Underway, not-yet-started is Charted Next.
- The strict boundary keeps action-free items OUT of Captain's Call: a working or validating task, a queued item blocked on another task or a date, landed work, a completed scout's report pointer, a declared `paused:` external wait, and a bare recorded PR with no merge-ready signal each belong to one of the other three sections, never Captain's Call.
- A secondmate appears Underway only for `active_child_work`; `externally_held` belongs in Charted Next, and `unknown` belongs there as an unavailable-state gate unless its reason requires the captain's action.
- The chat follows `AGENTS.md` section 9 and carries one scannable line per item, each PR as the full `https://...` URL; detailed decisions, plans, full gate reasons, and evidence live only in the report file, which the chat links to, so the chat stays materially shorter than that file.

## Tone and content rules

- This report is a private, captain-facing internal artifact that lives in gitignored `data/`, so unlike normal captain chat it MAY reference task ids, PR URLs, and repo names - the captain works with these directly and needs them to resume; keep it organized and scannable, not a raw dump.
- Every PR reference is a full `https://...` URL, never a bare `#number`; a shorthand `#number` is fine only as a back-reference after the full URL has already appeared in the same report.
- Never include PHI or secret values; the report is an operational artifact, but it is still subject to the same security and compliance rules that govern everything else in this fleet.

## Supervision discipline

This skill is read-mostly and changes no fleet state.
Do not tear down a task, merge a PR, dispatch queued work, or mutate any `state/` or `data/` file other than the single report file as a side effect of generating the brief.
If the state you read suggests an action - a PR ready to merge, a queued item whose gate has arrived, a needs-decision finding - name it in its section (a captain action under "Captain's Call", queued or gated work under "Charted Next") and let the captain decide, rather than taking the action from inside this skill.
52 changes: 52 additions & 0 deletions .agents/skills/bootstrap-diagnostics/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
---
name: bootstrap-diagnostics
description: >-
Agent-only handling playbook for session-start bootstrap diagnostics.
Use whenever the session-start digest's bootstrap section prints an actionable diagnostic line - MISSING, MISSING_MANUAL, BACKEND_INVALID, NEEDS_GH_AUTH, TANGLE, CREW_DISPATCH invalid, FLEET_SYNC, PR_CHECK_MIGRATION, SECONDMATE_SYNC, SECONDMATE_LIVENESS, NUDGE_SECONDMATES, or FMX - or when a standalone bin/fm-bootstrap.sh run prints one of those lines.
A silent bootstrap section, or a BOOTSTRAP_INFO fact, means no skill load.
user-invocable: false
metadata:
internal: true
---

# bootstrap-diagnostics

Handle each printed line as below, before dispatching work that depends on it.
The line formats themselves are owned by `bin/fm-bootstrap.sh`'s header; this playbook owns the response to actionable lines.
The inline rules in `AGENTS.md` section 3 still bind: detect, then consent, then install - never install anything the captain has not approved in this session - and no work is dispatched until the tools it needs are present and GitHub auth is good.
When any diagnostic needs captain attention, report the plain consequence and requested action using `AGENTS.md` section 9's captain-facing translation contract; do not name the diagnostic label unless the captain needs to paste it into a command or issue.

- `MISSING: <tool> (install: <command>)` - list the missing tools to the captain with a one-line purpose each plus the printed install commands, wait for consent (one approval may cover the list), then run `bin/fm-bootstrap.sh install <approved tools...>`.
For `treehouse`, this also covers an installed version whose `treehouse get` lacks `--lease`; treat it as an upgrade request.
For `no-mistakes`, this also covers an installed version older than 1.31.2, because crewmate validation briefs delegate gate mechanics to no-mistakes' version-matched guidance.
For `tasks-axi`, this also covers an installed build that fails the compatibility probe (`docs/configuration.md` "Backlog backend" owns the definition); `config/backlog-backend=manual` only suppresses the verbose `BOOTSTRAP_INFO: tasks-axi available` fact, not this missing-tool report.
For `quota-axi`, bootstrap requires it because crew-dispatch `quota-balanced` may call it; `bin/fm-dispatch-select.sh` still degrades at runtime when quota data is unavailable.
- `MISSING_MANUAL: <tool> (instructions: <url>)` - tell the captain why the tool is required and give them the printed instructions URL, but do not pass the tool to `bin/fm-bootstrap.sh install`; wait for the captain to complete the manual installation, then rerun session start to confirm the dependency is present.
- `BACKEND_INVALID: <name> (known: <names>)` - the resolved runtime backend has no verified dependency or lifecycle contract, so do not dispatch work until the invalid `FM_BACKEND` or `config/backend` value is corrected to one of the listed backends.
- `NEEDS_GH_AUTH` - ask the captain to run `! gh auth login` (interactive; you cannot run it for them).
- `TANGLE: <remediation>` - the primary checkout is stranded on a feature branch instead of its default branch; `AGENTS.md` section 8 explains why this guard exists and what it protects.
The work is safe on that branch ref; restore the primary to its default branch with the printed `git -C <root> checkout <default>`, then re-validate that branch in a proper worktree.
This is the only sanctioned firstmate-initiated git write to the primary, and it is a non-destructive branch switch that strands nothing.
- `CREW_DISPATCH: invalid config/crew-dispatch.json - <reason>` - the optional dispatch profile file exists but failed low-cost bootstrap validation; continue with the normal fallback chain, resolve and pass the chosen fallback harness explicitly while the file remains present, fix the malformed schema, unverified harness name, unknown selector, or invalid harness/effort pair when convenient, and do not select a bad profile.
- `FLEET_SYNC: <repo>: skipped: <reason>` - a benign one-off skip (offline, no origin, local-only); bootstrap continued, investigate only if it blocks work.
A skip can also report the bounded fleet-refresh timeout (`FM_FLEET_SYNC_BOOTSTRAP_TIMEOUT`, or a fleet-size-aware default with a 20 second floor); a timeout never blocks startup.
- `FLEET_SYNC: <repo>: recovered: <detail>` - the clone had drifted onto a clean detached HEAD holding no unique commits and the sync self-healed it (re-attached the default branch and fast-forwarded); no action needed, it is reported only so the self-heal is visible.
- `FLEET_SYNC: <repo>: STUCK: on <state>, N commits behind <base> - needs attention` - the clone is dirty, on a non-default branch, detached with unique commits, or diverged, so the sync left it untouched (never forcing or discarding); it will keep falling behind until you look.
A loud STUCK, especially a growing N across bootstraps, means that clone needs hands-on attention; dispatch a crewmate or resolve it before it strands work.
- `PR_CHECK_MIGRATION: canonical polls rebuilt and armed; resume supervision for this home` - the non-executing migration rebuilt canonical task polls from validated metadata, and those polls are already armed.
Independently verify the private per-task outcome record, then resume the emitted supervision protocol after finishing the session-start wake handling.
- `PR_CHECK_MIGRATION: validated replacement polls armed; resume supervision for this home` - a retry proved canonical publication provenance, metadata identity binding, and single-link integrity for a replacement poll resolving an earlier ambiguous migration outcome.
Independently verify the private per-task outcome record, then resume the emitted supervision protocol after finishing the session-start wake handling.
- `PR_CHECK_MIGRATION: quarantined polls remain unarmed; review state/.pr-check-migration.log before rearming` - one or more ambiguous or invalid task polls were quarantined without execution and remain unarmed.
Read the private mode-`0600` per-task outcome record, verify the task's recorded PR independently, and rearm only through `bin/fm-pr-check.sh` with canonical inputs.
- `PR_CHECK_MIGRATION: migration completed safely; resume supervision for this home` - migration crossed the update boundary without rebuilding or quarantining a task poll after pausing the prior watcher.
Resume the emitted supervision protocol after finishing the session-start wake handling.
- Any other `PR_CHECK_MIGRATION:` refusal means migration did not complete safely, whether because watcher exclusion, a private path, a diagnostic, quarantine validation, or marker publication could not be proved.
Keep each affected poll unavailable, inspect the named private state path, and do not bypass the migration or execute a quarantined artifact; a completed safe-scan marker allows unrelated authenticated polls to continue while private repair remains pending.
- `SECONDMATE_SYNC: secondmate <id>: skipped: <reason>` - the local-HEAD secondmate sync left a live secondmate home on its existing checkout because the home was dirty, diverged, unsafe, on the wrong branch, missing the primary target commit, or otherwise not fast-forwardable, or because inherited local-material propagation failed; bootstrap continued, but inspect the reason because the secondmate's tracked instructions, inherited settings, or shared captain preferences may be stale after a primary update.
- `SECONDMATE_LIVENESS: secondmate <id>: skipped: <reason>|respawn failed: <reason>` - the session-start liveness sweep could not guarantee that a live secondmate's recorded endpoint is running a real agent process.
Investigate the reason because that secondmate is not guaranteed live.
- `NUDGE_SECONDMATES: secondmate <id>: send failed: <reason>` - the secondmate sweep fast-forwarded a running secondmate home and its loaded instruction surface (`AGENTS.md`, `bin/`, or `.agents/skills/`) changed, but the deterministic `fm-send.sh fm-<id>` re-read nudge failed.
Inspect the reason, keep the pending marker under `state/.secondmate-nudge-pending/` intact, and rerun session start after the endpoint or metadata issue is fixed so bootstrap can retry the exact same marked send.
- `FMX: X mode on ...` / `FMX: X mode off ...` - bootstrap confirmed or removed the local X-mode poll artifacts (`docs/configuration.md` "X mode (.env)").
Only when a running watcher needs the cadence transition applied immediately, restart the home-scoped watcher through the emitted harness supervision protocol; bootstrap deliberately never restarts the watcher itself.
Loading
Loading