diff --git a/AGENTS.md b/AGENTS.md index 010e84214..b55b0b4b1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -52,60 +52,9 @@ Each secondmate has a persistent isolated `FM_HOME`, including its own state, ba Tracked files hold shared instructions and tooling; `data/` holds durable private fleet records; `state/` holds volatile runtime records and append-only status events; `config/` holds local operating choices; and `projects/` contains clones that are read-only to firstmate. -``` -AGENTS.md this file (CLAUDE.md is a symlink to it) -CONTRIBUTING.md contributor workflow and repo conventions -README.md public overview and development notes -.github/workflows/ shared CI and PR enforcement, committed -.tasks.toml tracked tasks-axi markdown backend config for the default backlog backend (section 10) -.agents/skills/ firstmate-loaded internal skills, committed; each carries metadata.internal=true for installers -.claude/skills symlink to .agents/skills for claude compatibility -skills/ standalone public installer-facing skills, committed; not loaded by firstmate -bin/ helper scripts, committed; read each script's header before first use -.env optional X-mode pairing token; LOCAL, gitignored; presence-gates section 14 -config/crew-harness crewmate harness override; LOCAL, gitignored; absent or "default" = same as firstmate. Inherited as the literal file: a concrete primary adapter value also controls a secondmate home's own crewmates (section 4) -config/crew-dispatch.json optional crewmate dispatch profiles; LOCAL, gitignored; firstmate-maintained but human-editable natural-language rules that choose a per-task harness/model/effort profile (section 4). Inherited by secondmate homes -config/secondmate-harness harness the PRIMARY uses to launch SECONDMATE agents, optionally followed by a model and effort token on the same line (" [] []"; section 4); LOCAL, gitignored; absent or "default" harness falls back to config/crew-harness then firstmate's own. The primary's own setting; NOT inherited into secondmate homes (secondmates do not spawn secondmates) -config/backlog-backend backlog backend override; LOCAL, gitignored; absent or "tasks-axi" = default tasks-axi backend, "manual" = force routine backlog updates to hand-editing; inherited by secondmate homes (section 10) -config/backend runtime session-provider backend override for new tasks; LOCAL, gitignored; absent = falls through to runtime auto-detection (the runtime firstmate itself is executing inside), then tmux; tmux is the verified reference backend (docs/tmux-backend.md), while herdr, zellij, orca, and cmux are experimental spawn backends (docs/herdr-backend.md, docs/zellij-backend.md, docs/orca-backend.md, docs/cmux-backend.md) - herdr and cmux can also be selected by runtime auto-detection, zellij and orca never are (always explicit), and codex-app is not accepted; see docs/codex-app-backend.md; not inherited into secondmate homes -config/cmux-socket-password optional cmux control-socket password; LOCAL, gitignored; read fresh on every cmux CLI call and passed through without ever overriding an operator's own ambient CMUX_SOCKET_PASSWORD when absent (docs/cmux-backend.md "Setup") -config/wedge-alarm optional away-mode wedge-alarm active-alert directives; LOCAL, gitignored; absent means auto (macOS Notification Center when available); see docs/wedge-alarm.md -config/x-mode.env generated X-mode watcher cadence; LOCAL, gitignored; source before arming watcher when present -data/ personal fleet records; LOCAL, gitignored as a whole - backlog.md task queue, dependencies, history - captain.md captain's personal preferences and working style; LOCAL, gitignored, canonical even if harness memory mirrors it, and updated with inspect-then-update - learnings.md fleet-local operational facts and gotchas; LOCAL, gitignored; dated, evidence-backed, curated, and updated with inspect-then-update - rewrite and prune rather than append forever, the same contract as captain.md; created lazily, absent until this home has a learning to store - projects.md thin fleet navigation registry; firstmate-private, parsed by fm-project-mode.sh (section 6) - secondmates.md secondmate routing table; firstmate-private, maintained by fm-home-seed.sh (section 6) - /brief.md per-task crewmate brief, or per-secondmate charter brief when kind=secondmate - /report.md scout task deliverable, written by the crewmate; survives teardown -projects/ cloned repos; gitignored; READ-ONLY for you -state/ volatile runtime signals; gitignored - .status appended by crewmates: ": " wake-event lines, not current-state truth - .turn-ended touched by turn-end hooks - .grok-turnend-token firstmate-owned grok hook registry token for the task; removed by teardown - .meta written by fm-spawn: window=, worktree=, project=, harness=, model=, effort=, kind=, mode=, yolo=, tasktmp=; kind=secondmate also records home= and projects=; a non-default runtime backend records further backend-specific fields (docs/configuration.md "Runtime backend"; bin/fm-backend.sh, section 8); fm-pr-check, including through fm-pr-merge, records one canonical pr= and GitHub's pr_head= when available; fm-x-link appends x_request=, x_request_ts=, x_followups=, and optional x_platform=/x_reply_max_chars= for an X-mode-originated task (section 14) - .check.sh authenticated slow poll; the watcher dispatches validated PR data and the byte-identified X shim through trusted repository scripts, runs registered custom checks from hash-validated private snapshots, and rejects every other state check without execution - .check-trust private content binding created by fm-check-register.sh for an intentional custom check - .pr-poll private validated data sidecar for the byte-static PR merge poll - .pr-poll-registration private transactional provenance record binding the task, canonical metadata identity, sidecar, and static poll publication - .pr-check-quarantine/ private non-runnable storage for checks neutralized by the non-executing migration - .pr-check-migration.log private per-task outcomes distinguishing rebuilt or canonically registered replacement polls, quarantined unarmed polls, and incomplete migrations - .pr-check-migration-scan-v1 private marker proving the non-executing scan disabled every unsafe legacy check; .pr-check-migration-v1 separately records completed private repairs - x-watch.check.sh generated X-mode relay poll shim; present only when opted in (section 14) - x-inbox/ generated X-mode pending mention payloads; fmx-respond drains it (section 14) - x-context/ generated X-mode durable per-request reply context (platform/budget), keyed by request_id; survives inbox cleanup so a delayed follow-up recovers the original platform (section 14; bin/fm-x-lib.sh) - x-outbox/ generated X-mode dry-run reply and dismiss previews; inspect it when FMX_DRY_RUN is set (section 14) - x-poll.error generated X-mode relay diagnostic dedupe marker - .wake-queue durable queued wakes: epochseqkindkeypayload - .afk durable away-mode flag; present = sub-supervisor may inject escalations (set by /afk, cleared on user return) - .watch.lock .wake-queue.lock watcher singleton and queue serialization locks - .hash-* .count-* .stale-* .stale-since-* .paused-* .wedge-escalations-* .seen-* .hb-surfaced-* .last-* .heartbeat-streak watcher internals; never touch - .watch-triage.log watcher's absorbed-wake debug log (size-capped); never relied on, safe to delete - .last-watcher-beat watcher liveness beacon, touched every poll (including while absorbing benign wakes); guard scripts read it - .subsuper-* .supervise-daemon.* sub-supervisor internals; never touch -.no-mistakes/ local validation state and evidence; gitignored -``` +The tracked root also carries `CLAUDE.md` as a symlink to this file and `.claude/skills` as a symlink to `.agents/skills`. +The exact child files and fields under each directory - task metadata and its backend-specific fields, append-only status-event vocabulary, endpoint and PR-check signals, watcher and wake-queue coordination, away-mode state, generated X-mode artifacts, and every `config/` knob - are owned by `docs/configuration.md` and each producing script's header and `--help`, not restated here. +Two boundaries carry inline because they bind at every turn: `projects/` clones are read-only to firstmate (prime directive 1), and `state/` watcher, sub-supervisor, and wake internals are never hand-edited. A `state/.status` line is a wake event, not current-state truth; `bin/fm-crew-state.sh` owns current-state reconciliation. Treat `data/captain.md` as the canonical portable record of captain preferences and `data/learnings.md` as curated fleet-local knowledge, regardless of harness memory.