From 1d714a84d07d2e44a2368f18fcfc942b9ab8f790 Mon Sep 17 00:00:00 2001 From: Rootiest Date: Wed, 23 Sep 2026 22:10:36 -0400 Subject: [PATCH] docs(agent-tooling): add scenario reference table, cross-reference from code Adds a 'Scenario reference' subsection to docs/manual/16-agent-tooling.md: two ruled tables covering every combination of what a directory can hold (only AGENTS.md, only CLAUDE.md, both identical, both different, an inverted mirror, an already-settled symlink) crossed with whether the file is deliberately git-tracked, plus the settled-mirror/later-arrival case separately. Verified against build-manual.py's actual table parser and the generated Starlight site output, not just visual inspection. Also closes the gap this section itself pointed out: nothing previously linked a reader of agents-init.fish or agents-vault.fish's own doc-header to this page, and nothing told a future contributor the page has to be kept in sync. Adds: - CONTRIBUTING.md: a new 'Dedicated manual sections for complex subsystems' subsection documenting the pattern in general (when to use one, and the update-it-in-the-same-change obligation verify-manual.py cannot check for you). - functions/agents-init.fish, functions/agents-vault.fish: a NOTES pointer to the section from each function's own header, so a reader who only sees the header still finds the fuller page. --- CONTRIBUTING.md | 25 ++++++++++++++++++++ docs/manual/16-agent-tooling.md | 42 +++++++++++++++++++++++++++++++++ functions/agents-init.fish | 9 +++++++ functions/agents-vault.fish | 7 ++++++ 4 files changed, 83 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6f66bc1..a019c4d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -455,6 +455,31 @@ via `command`/`builtin` (`bypasses-shadow(cat)`), and general hazards — `destructive`, `network`, `blocking-prompt`. Full tag definitions and placement rule: [`docs/function-classification-schema.md`](docs/function-classification-schema.md). +### Dedicated manual sections for complex subsystems + +A doc-header's `DESCRIPTION` is for that one function's usage — it stops +being the right place once a subsystem spans several functions, has its +own file layout, or has enough behavior (a decision table, a safety +model) that cramming it into one function's header would make that +header useless as a quick reference. When that happens, give the +subsystem its own numbered top-level section under `docs/manual/` +(follow the sibling sections' frontmatter shape: `title`, `manTitle`, +`sidebar.order`, `helpKeywords`) instead of stretching the header. +`docs/manual/16-agent-tooling.md` (`agents-init`/`agents-vault`/the +`AGENTS/` sub-repository) is the existing example — its own doc-headers +stay short and point there for the full picture, the same way this +document points at other reference files rather than repeating them. + +This is a genuine exception to "the doc-header is the single source of +truth" above, and it comes with an obligation `verify-manual.py` cannot +enforce for you: nothing checks that a dedicated section still describes +the function's *current* behavior. **Whenever you change what one of +these functions does, update its dedicated section in the same commit or +pull request** — not as a follow-up. A function with a dedicated section +should say so in its own `# NOTES` (see `functions/agents-init.fish` for +the pattern), so a later reader of just the header still finds the fuller +page. + ### Private/internal helper functions Functions named with a leading `_` (e.g. `_agents_init_ensure_gitignore`, diff --git a/docs/manual/16-agent-tooling.md b/docs/manual/16-agent-tooling.md index 205a9f9..30cb976 100644 --- a/docs/manual/16-agent-tooling.md +++ b/docs/manual/16-agent-tooling.md @@ -220,6 +220,48 @@ warning naming the file and explaining why, rather than staying silent about a directory it chose not to touch. +## Scenario reference + +Every combination of what a directory can hold, laid out directly. "No" +in the tracked column also covers a tracked file in a project with no +populated `.gitignore` (the bootstrap case, above) — both behave the same +way. Whenever the tracked column reads "Yes", that reason always wins +over the identical-or-different comparison below it, and the warning +printed names the file as tracked rather than as differing — the outcome +(left alone) is the same either way, only the explanation differs. + +Settling a directory for the first time — a real `AGENTS.md`, a real +`CLAUDE.md`, both, or neither, discovered fresh: + + Found Deliberately tracked? Result + -------------------------------- --------------------- ----------------------------------------------- + Only AGENTS.md (real) No Adopted into AGENTS/, symlinked back. + Only AGENTS.md (real) Yes Left exactly as it is; not adopted. + Only CLAUDE.md (real) No Adopted, renamed to AGENTS.md, symlinked back. + Only CLAUDE.md (real) Yes Left exactly as it is; not adopted or renamed. + Both, byte-identical No AGENTS.md adopted; duplicate CLAUDE.md dropped. + Both, byte-identical Yes (either) Left exactly as they are; neither touched. + Both, different content n/a Neither touched; warns, resolve by hand. + Mirror has CLAUDE.md (real) n/a Flipped in place: renamed, nothing lost. + Correct AGENTS.md symlink exists n/a Nothing happens -- already settled. + +A new real file appearing after a directory's mirror has already settled +— an agent's own `/init`-style command, for instance, writing a fresh +`CLAUDE.md` where an `AGENTS.md` is already symlinked: + + New file vs. mirror Deliberately tracked? Result + ------------------- --------------------- -------------------------------------------------------- + Byte-identical No Adopted as a duplicate; the new file is dropped. + Byte-identical Yes Left as it is; not adopted, even though content matches. + Different content No Left as it is; warns that it differs, resolve by hand. + Different content Yes Left as it is; warns that it's tracked, not adopted. + +And whatever a directory holds, it never gets this far at all if +discovery pruned it outright — see the containment rules above: nested +repositories, dot-directories, `node_modules/`, generated-output +directories, and any directory literally named `AGENTS`. + + ## plans/, specs/, and devlogs/ `agents-init --plugins` (the second half of what a bare `agents-init` run diff --git a/functions/agents-init.fish b/functions/agents-init.fish index dd3a4ed..6688ad9 100644 --- a/functions/agents-init.fish +++ b/functions/agents-init.fish @@ -110,6 +110,15 @@ # agents-init --agents # agents-init --plugins # agents-init --quiet +# +# NOTES +# This header covers usage only. The full concept/behavior/purpose +# write-up -- the AGENTS.md convention, the AGENTS/ sub-repository, the +# discovery and safety model, and a complete scenario-by-scenario +# reference table -- lives in its own manual section: +# docs/manual/16-agent-tooling.md. Update that section in the same +# change whenever this function's behavior changes; see "Dedicated +# manual sections for complex subsystems" in CONTRIBUTING.md. function agents-init --description 'scaffold AGENTS/ sub-repo with agent spec files and plugin dirs' __fish_palette diff --git a/functions/agents-vault.fish b/functions/agents-vault.fish index 125d9f9..a5183a4 100644 --- a/functions/agents-vault.fish +++ b/functions/agents-vault.fish @@ -188,6 +188,13 @@ # machine that has a real global memory directory would move it into a # throwaway directory and leave a dangling symlink behind, which is # strictly worse than having had no backup at all. +# +# This header covers usage only. The full concept/behavior/purpose +# write-up -- how this relates to the per-project AGENTS/ repository +# agents-init manages, and where each kind of agent state actually lives +# -- is in docs/manual/16-agent-tooling.md. Update that section in the +# same change whenever this function's behavior changes; see "Dedicated +# manual sections for complex subsystems" in CONTRIBUTING.md. function agents-vault --description 'track curated agent memory in a host-scoped vault repo' __fish_palette