diff --git a/.agents/skills/stow/SKILL.md b/.agents/skills/stow/SKILL.md new file mode 100644 index 00000000000..c5291e47777 --- /dev/null +++ b/.agents/skills/stow/SKILL.md @@ -0,0 +1,52 @@ +--- +name: stow +description: Sweep the current session for uncaptured durable knowledge and file it to disk before a context reset. Use when the captain invokes /stow (e.g. "/stow", "stow what you've learned"), before a session reset or context compaction, or periodically to keep operational memory current. +user-invocable: true +--- + +# stow + +Sweep this session for durable knowledge that only exists in conversation right now, and write it to the disk locations firstmate already reads on the next bootstrap. +The goal is a session that is safe to reset or destroy because everything durable has already been captured. + +## What it does + +1. **Sweep the session for uncaptured durable knowledge.** + Read back over this conversation and look for: + - Operational learnings: fleet-local facts and gotchas discovered while operating firstmate (a script's sharp edge, a harness quirk, a recurring false alarm and its real cause). + - Captain preferences expressed in passing: a working-style or approval preference the captain stated conversationally rather than through `data/captain.md` directly. + - Project-intrinsic facts discovered: build, test, release, or architecture facts about a project that belong in that project's own `AGENTS.md`. + - Decisions made: a standing choice the captain made this session that should outlive it. + - Undone next steps: anything left open that has not yet been filed as backlog work. + +2. **Route each finding using AGENTS.md's knowledge-routing table.** + AGENTS.md (section 6, "Knowledge routing") is the single source of truth for where each kind of knowledge belongs. + Read that table and route each finding there instead of re-deriving the mapping here. + +3. **Write within firstmate's existing write boundaries.** + This skill does not grant any new write permission; it only prompts firstmate to use the boundaries that already exist (AGENTS.md section 1): + - Captain preferences and fleet-local operational facts: hand-write directly, to `data/captain.md` and `data/learnings.md` respectively. + `data/learnings.md` may not exist yet; create it on first learning, in the same dated, evidence-backed, curated style as `data/captain.md` - rewrite and prune stale or superseded entries rather than appending forever. + - Project-intrinsic knowledge: never hand-write a project's `AGENTS.md`. + Route it through a normal ship task so a crewmate records it via `bin/fm-ensure-agents-md.sh` and commits it through that project's delivery pipeline, exactly as section 6 describes. + If the fleet is live, delegate this to a crewmate rather than doing it inline. + - Knowledge generalizable to every firstmate user: this repo's own `AGENTS.md` (or other shared, tracked material), shipped through the normal branch -> no-mistakes -> PR -> captain-merge pipeline for this repo (section 1), never hand-committed straight to `main`. + - Task-scoped notes: append to the relevant backlog item's notes with `tasks-axi update --append ""`, or hand-edit `data/backlog.md` per the active backend (section 10). + - Undone next steps: file each as a queued backlog item (section 10), with `blocked-by` recorded if it genuinely depends on something else. + +4. **Curate, don't just append.** + When a finding overlaps or supersedes something already on disk, prefer rewriting or pruning the existing entry over piling on a new one. + Graduation moves are limited to exactly three: promote a learning to the shared `AGENTS.md` via PR, fold it into `data/captain.md`, or delete a stale entry. + Do not invent other graduation paths. + +5. **Report to the captain.** + Summarize, in plain outcome language (section 9): what was stowed and where, what was filed to the backlog, and whether the session is now safe to reset or destroy - i.e. whether every durable finding from this sweep now lives on disk rather than only in this conversation. + If something could not be captured yet (for example, project-intrinsic knowledge waiting on a crewmate to land it), say so explicitly rather than reporting the session fully safe. + +## Scope exclusion: no skill storage + +`/stow` must **never** store, create, or edit a skill as a destination for any finding. +There is no "graduate this to a skill" move in this skill's routing. +This is a deliberate, standing exclusion, not an oversight: repo skills cannot yet distinguish knowledge that is fleet-local to this captain's home from knowledge generalizable to every firstmate user, so writing learnings into skills would silently leak fleet-local material into shared, tracked material (or vice versa). +That namespace problem is unresolved and deliberately deferred. +Until it is resolved, route generalizable knowledge to the shared `AGENTS.md` (or other shared, tracked material) via the pipeline, and fleet-local knowledge to `data/`, never to a skill. diff --git a/AGENTS.md b/AGENTS.md index 35b4827741b..19133d6c66c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -82,6 +82,7 @@ config/x-mode.env generated X-mode watcher cadence; LOCAL, gitignored; source data/ personal fleet records; LOCAL, gitignored as a whole backlog.md task queue, dependencies, history captain.md captain's curated personal preferences and working style; LOCAL, gitignored, and canonical even if harness memory mirrors it + learnings.md fleet-local operational facts and gotchas; LOCAL, gitignored; dated, evidence-backed, curated - 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 @@ -164,6 +165,8 @@ Then read `data/secondmates.md` if present so intake can route work by registere Then read `data/captain.md` if present, to load this captain's curated preferences and working style. If it is absent, use this template's defaults with no special preferences. Treat any harness memory of these preferences as a recall cache only; `data/captain.md` is the canonical, harness-portable home. +Then read `data/learnings.md` if present, to load fleet-local operational facts and gotchas this home has captured. +If it is absent, there is nothing yet to load and that is fine. Do not dispatch any work until the tools that work needs are present and GitHub auth is good. Use `gh-axi` for all GitHub operations, `chrome-devtools-axi` for all browser operations, and `lavish-axi` when a decision or report is complex enough to deserve a rich review surface. @@ -295,7 +298,7 @@ Reconcile reality with your records before doing anything else: 10. Handle drained wakes, then follow the section 8 watcher checklist; if `state/.afk` exists, the daemon owns the watcher. A firstmate restart must be a non-event. -All truth lives in tmux, state files, data/backlog.md, data/secondmates.md, persistent secondmate homes, and treehouse; your conversation memory is a cache. +All truth lives in tmux, state files, data/backlog.md, data/captain.md, data/learnings.md, data/secondmates.md, persistent secondmate homes, and treehouse; your conversation memory is a cache. ## 6. Project management @@ -360,6 +363,22 @@ Create a project's `AGENTS.md` lazily on first need. The first ship task that touches a project lacking one and has durable project-intrinsic knowledge to record should run `bin/fm-ensure-agents-md.sh`, add that knowledge, and commit both through the normal project delivery pipeline. Do not eagerly backfill every project. +### Knowledge routing + +Route each piece of durable knowledge to its most specific home: + +| Kind of knowledge | Home | +| --- | --- | +| Captain preferences and working style | `data/captain.md` | +| Project-intrinsic knowledge | that project's own `AGENTS.md`, via normal crewmate delivery, never hand-written by firstmate | +| Fleet-local operational facts and gotchas | `data/learnings.md` | +| Knowledge generalizable to every firstmate user | the shared `AGENTS.md`, shipped via PR through the pipeline | +| Task-scoped notes | backlog item notes (`tasks-axi update --append ""`, or hand-edit per the active backend) | +| Investigation findings | scout reports at `data//report.md` | + +When the captain invokes `/stow`, load the `stow` skill. +It sweeps the current session for uncaptured durable knowledge, routes findings with this table, files undone next steps to the backlog, and reports whether the session is safe to reset. + **Delivery mode (choose at add).** `` is how a finished change reaches `main`, picked per project when you add it and recorded in the registry line (`fm-project-mode.sh` parses it; `fm-spawn` records it into each task's meta): - `no-mistakes` (default; `[...]` may be omitted) - full pipeline -> PR -> captain merge. Highest assurance. @@ -789,6 +808,11 @@ firstmate is its own repo behind the no-mistakes gate, so improvements to `AGENT When the captain invokes `/updatefirstmate` or asks to update firstmate, load the `/updatefirstmate` skill. It performs only fast-forward self-updates of firstmate and registered secondmate homes, re-reads `AGENTS.md` when needed, nudges updated live secondmates, and never touches anything under `projects/`. +### Session stow + +When the captain invokes `/stow`, asks to stow what you learned, or asks to preserve session memory before reset, load the `/stow` skill. +It owns the sweep for durable knowledge that still exists only in conversation, routes each finding through section 6's knowledge-routing table, files undone next steps to the backlog, and reports whether the session is safe to reset. + ## 13. Agent-only reference skills These skills are not captain-invocable; they are conditional operating references you must load at the trigger points below. diff --git a/README.md b/README.md index 9eb4a1f0a12..128a963b2f1 100644 --- a/README.md +++ b/README.md @@ -48,6 +48,7 @@ This is.. a directory that turns any agent into your firstmate, and you the capt - **Event-driven, zero-token supervision** - a bash watcher sleeps on the fleet and wakes the first mate only when something needs you. - **Read-only supervision view** - `bin/fm-supervise.sh` turns current state, tmux, git, watcher, and optional GitHub reads into a stable checklist or `firstmate.supervision.v1` JSON without changing anything. - **Optional X mode** - opt in with one local `.env` token so firstmate can answer your public `@myfirstmate` mentions, act on normal reversible mention requests through the same lifecycle as chat requests, acknowledge spawned work, and post one public-safe completion follow-up without changing non-X behavior; dry-run preview records would-be replies and dismissals locally before go-live. +- **Operational memory stow** - `/stow` sweeps the current session for durable knowledge, routes it to the right local or project home, and tells you when the session is safe to reset. - **Guarded by construction** - the first mate is read-only over your projects outside guarded clone refreshes, safe branch pruning, and approved `local-only` fast-forward merges; crewmates make every project change behind your merge approval. - **Restart-proof** - all state lives on disk and in tmux; kill the session anytime and the next one reconciles and carries on. @@ -129,7 +130,7 @@ It preserves parent-tweet context for conversational replies and dismisses pure Replies can attach one local image with `--image ` when there is a visual artifact; long replies split into bounded numbered threads when needed, with the image attached only to the opener tweet. When firstmate works on itself, spawn-time isolation checks and a primary-checkout tangle alarm keep the operating checkout on its default branch and stop a crewmate that did not land in a separate worktree. -Full architecture - the supervision engine, worktree isolation, secondmates, project modes, optional X mode, fleet sync, and self-update - is in [docs/architecture.md](docs/architecture.md). +Full architecture - the supervision engine, worktree isolation, secondmates, project modes, optional X mode, fleet sync, operational memory, and self-update - is in [docs/architecture.md](docs/architecture.md). ## Built-in skills @@ -140,6 +141,7 @@ Claude and grok use the slash form shown here; codex uses the same names with `$ | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | | `/afk` | Enter away-mode supervision: the sub-supervisor self-handles routine wakes in bash and escalates only captain-relevant events as one batched digest, cutting supervision cost while you step away | | `/updatefirstmate` | Self-update the running firstmate and its secondmates to the latest from origin with fast-forward-only pulls, then re-read instructions and nudge secondmates | +| `/stow` | Sweep the session for uncaptured durable knowledge, route each finding to its disk home per AGENTS.md, file undone next steps to the backlog, and report what is now safe to reset | Agent-only reference skills live under `.agents/skills/` and are loaded by firstmate at the trigger points named in [`AGENTS.md`](AGENTS.md). diff --git a/docs/architecture.md b/docs/architecture.md index 4f34ca3361e..2be73d70805 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -148,6 +148,12 @@ Durable project-intrinsic agent knowledge lives in each project's committed `AGE Ship briefs prompt crewmates to create or update those files through the normal delivery path; `data/projects.md` stays a thin private registry. The full ownership rule - what is project-intrinsic versus fleet-private, and how firstmate keeps the two apart without writing into project clones - is owned by firstmate's operating manual in [`AGENTS.md`](../AGENTS.md) (project memory ownership). +## Operational memory routing + +`/stow` sweeps the current session for durable knowledge that only exists in conversation and routes each finding to the most specific disk home. +Captain preferences go to `data/captain.md`, fleet-local operational facts and gotchas go to `data/learnings.md`, project-intrinsic knowledge goes through normal crewmate delivery into that project's committed `AGENTS.md`, and task-scoped notes or undone next steps go to the backlog. +Generalizable firstmate knowledge goes to shared tracked docs through the normal PR pipeline; `/stow` deliberately never stores findings in skills. + ## Local clones stay fresh Bootstrap and PR-based teardown refresh remote-backed project clones when the clone is safe to move. @@ -165,8 +171,8 @@ The mechanics are owned by the `/updatefirstmate` skill and firstmate's operatin ## Restart-proof -All state lives in tmux, no-mistakes run records, status event logs, local markdown under `data/`, `data/secondmates.md`, and persistent secondmate homes. -Kill the first mate session anytime; the next one reconciles and carries on. +Fleet state lives in tmux, no-mistakes run records, status event logs, local markdown under `data/` including `data/captain.md` and `data/learnings.md`, and persistent secondmate homes. +Use `/stow` before an intentional reset when the conversation may hold durable knowledge that has not yet been written to disk; after that, the next firstmate session can reconcile and carry on. ## Development notes diff --git a/docs/configuration.md b/docs/configuration.md index baf3fa95488..3dbf0314382 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -27,6 +27,11 @@ It intentionally mirrors the behavior-test baseline in [`.github/workflows/ci.ym Personal preferences for one captain's fleet live locally in `data/captain.md`; it is gitignored and read after `data/projects.md` and optional `data/secondmates.md` during bootstrap. +## Operational learnings (data/learnings.md) + +Fleet-local operational facts and gotchas live locally in `data/learnings.md`; it is gitignored and read right after `data/captain.md` during bootstrap. +The file is created lazily on first learning and follows the same dated, evidence-backed, curated style as `data/captain.md`: rewrite or prune stale entries instead of appending forever. + ## Secondmate routes (data/secondmates.md) Persistent secondmate routes live locally in `data/secondmates.md`.