From d3b8bc59bb16085b9336e39a560b15fac529f82a Mon Sep 17 00:00:00 2001 From: Rootiest Date: Wed, 30 Sep 2026 17:11:17 -0400 Subject: [PATCH] docs(manual): document agents-cleanup and the agents-init opt-out --- docs/fish-config.md | 162 +++++++++++++++++++++++++++++++- docs/manual/16-agent-tooling.md | 72 +++++++++++++- 2 files changed, 228 insertions(+), 6 deletions(-) diff --git a/docs/fish-config.md b/docs/fish-config.md index 545bbd3..9c5c171 100644 --- a/docs/fish-config.md +++ b/docs/fish-config.md @@ -2470,10 +2470,83 @@ functions). They are active in all interactive sessions. ## 5.12 AI and Developer Tools +### agents-cleanup + + Synopsis: agents-cleanup [-n | --dry-run] [--drop-extras] [--marker-file] + [-v | --verbose] [-q | --quiet] [-s | --silent] [-h | --help] + + Reverses agents-init in the current project, and marks the project so + agents-init -- and therefore every claude/agy launch -- leaves it + alone from then on. + + Every symlink that resolves into AGENTS/ is replaced by the real file + or directory it points to. When two links share a target (docs/plans + and docs/superpowers/plans), the shallower one receives the content + and the other is removed; a link to a target holding only .gitkeep is + removed with nothing put in its place. An AGENTS.md that is exactly + the stub agents-init writes is deleted; any other AGENTS.md loses only + the SYSTEM DIRECTIVE blockquote that pointed agents at AGENTS/AGENTS.md. + No CLAUDE.md is recreated. + + Before anything is moved, pending AGENTS/ changes are committed and + the full history is written to a verified git bundle under + $XDG_STATE_HOME/agents-cleanup/ (default ~/.local/state). AGENTS/ is + then removed, along with docs/superpowers/ and docs/ if left empty, + and every "Added by agents-init" block is stripped from .gitignore. + Nothing is committed to the outer repository. + + Files inside AGENTS/ that no project symlink points to -- other than + agents-init's own .version, .agents-tools/ and .gitkeep files -- stop + the cleanup before anything changes. They are listed; --drop-extras + discards them instead. + + The disabled marker is the per-clone git config key + agents-init.disabled, set on every run. --marker-file also writes + .agents-disabled in the project root, which agents-init honors too and + which may be committed to opt every clone out; it is the only marker + available outside a git repository. In a project with no AGENTS/, only + the marker is set -- a pre-emptive opt-out. agents-init --enable + clears the git key again. + + Re-running is safe: an interrupted cleanup resumes where it stopped, + and a finished one only confirms the marker. + + Arguments: + -n, --dry-run Print the plan and change nothing + --drop-extras Discard unlinked files in AGENTS/ instead of refusing + --marker-file Also write .agents-disabled (required outside git) + -v, --verbose Print all per-step output (default) + -q, --quiet Print one summary line only if changes were made + -s, --silent Suppress all output; errors only + -h, --help Show this help message and exit + + Exit Status: + 0 Cleanup finished, or nothing was left to do + 1 Refused (outside git without --marker-file, unresolved rebase in + AGENTS/, unlinked files in AGENTS/) or a step failed + + Notes: + Restore an archived AGENTS/ with: git clone AGENTS, then + agents-init --enable. The full write-up -- what is kept, what is + removed, and how the markers interact -- is in + docs/manual/16-agent-tooling.md. Update that section in the same + change whenever this function's behavior changes. + + Example: + agents-cleanup --dry-run + agents-cleanup + agents-cleanup --marker-file + +**Dependencies:** `_agents_init_find`, `_agents_init_stub`, `_agents_repo_slug`, `_agents_repo_sync` + +**Classification:** `destructive`, `self-limiting(rm,mkdir,grep)`, `bypasses-shadow(mv)`, `manual-section(16-agent-tooling)` + +**See also:** 16. AI AGENT TOOLING (`docs/manual/16-agent-tooling.md`) + ### agents-init - Synopsis: agents-init [-a | --agents] [-p | --plugins] [-v | --verbose] - [-q | --quiet] [-s | --silent] [-h | --help] + Synopsis: agents-init [-a | --agents] [-p | --plugins] [-e | --enable] + [-v | --verbose] [-q | --quiet] [-s | --silent] [-h | --help] Scaffolds an AGENTS/ sub-repository inside a project directory. Creates a self-contained git repo for agent specifications, moves any existing @@ -2495,6 +2568,13 @@ functions). They are active in all interactive sessions. no-op, so running an agent CLI in an arbitrary directory does not create a repository there. + A project marked disabled is skipped entirely. agents-cleanup sets the + per-clone git config key agents-init.disabled; a .agents-disabled file + in the project root, which a team may commit, has the same effect. + Either one turns every wrapper launch into a silent no-op there. + --enable clears the git key and scaffolds; the file has to be deleted + by hand, because it is a decision shared with every clone. + File layout after setup: AGENTS/AGENTS.md canonical root agent spec (real file) AGENTS//AGENTS.md canonical spec for any subdir with its own @@ -2555,6 +2635,8 @@ functions). They are active in all interactive sessions. -a, --agents Set up AGENTS/ repo + AGENTS.md symlinks (root and every discovered subdirectory) only -p, --plugins Set up AGENTS/ repo + plans/specs/devlogs dirs + docs/ symlinks only + -e, --enable Clear the git key agents-cleanup set, then scaffold as + normal (refused while .agents-disabled exists) -v, --verbose Print all per-step output (default) -q, --quiet Print one summary line only if changes were made -s, --silent Suppress all output; errors only (standard UNIX convention) @@ -2563,7 +2645,8 @@ functions). They are active in all interactive sessions. Exit Status: 0 Setup completed successfully 1 Fatal error (git init failed, move failed, the AGENTS/ commit was - rejected, or an unresolved rebase blocked it) + rejected, or an unresolved rebase blocked it), or --enable refused + because .agents-disabled exists Notes: This header covers usage only. The full concept/behavior/purpose @@ -2580,7 +2663,7 @@ functions). They are active in all interactive sessions. agents-init --plugins agents-init --quiet -**Dependencies:** `_agents_init_sync_instructions`, `_agents_repo_install_tools`, `_agents_repo_sync`, `_agents_init_ensure_gitignore` +**Dependencies:** `_agents_init_find`, `_agents_init_sync_instructions`, `_agents_repo_install_tools`, `_agents_repo_sync`, `_agents_init_ensure_gitignore` **Classification:** `self-limiting(rm,mkdir,grep)`, `bypasses-shadow(mv)`, `manual-section(16-agent-tooling)` @@ -5214,7 +5297,7 @@ Antigravity/agy) working in a project checked out from this configuration: where their instructions live, how they get there, and the safety rules that keep an agent's launch-time bookkeeping from touching a repository's own tracked history. Command-line usage for the functions named here -(`agents-init`, `agents-vault`) is generated from their own doc headers — +(`agents-init`, `agents-cleanup`, `agents-vault`) is generated from their own doc headers — see Section 5. @@ -5479,6 +5562,75 @@ real directory by that name — nothing forces those paths to exist for a project that never used them. +## Opting a project out: agents-cleanup + +`agents-cleanup` reverses everything `agents-init` did in a project and +stops it from happening again. Run it from anywhere inside the project: + + agents-cleanup --dry-run + agents-cleanup + +Every symlink that points into `AGENTS/` is replaced by the real file or +directory it points to, so the project ends up with ordinary files where +the links were. Where two links shared one directory (`docs/plans` and +`docs/superpowers/plans`), the shallower one — the location that existed +before `agents-init` — gets the content and the other link is removed. A +link to a directory holding nothing but `.gitkeep` is simply removed. No +`CLAUDE.md` is recreated. + +A root `AGENTS.md` that is exactly the seed file `agents-init` writes for +a fresh project is deleted, since it never held anything of yours. Any +other `AGENTS.md` keeps its content and loses only the "SYSTEM DIRECTIVE" +blockquote telling agents to edit `AGENTS/AGENTS.md` — a directory that no +longer exists. + +Before anything moves, pending changes in `AGENTS/` are committed and the +whole history is written to a verified git bundle under +`~/.local/state/agents-cleanup/` (or `$XDG_STATE_HOME/agents-cleanup/`). +An `AGENTS/` that is not a git repository has no bundle, so `--drop-extras` +there deletes the files for good. +Then `AGENTS/` is removed, along with `docs/superpowers/` and `docs/` if +they are left empty, and every `Added by agents-init` block is stripped +from `.gitignore`. Nothing is committed to the project itself: the +restored files show up as ordinary changes for you to commit or not. + +WARNING: Files inside `AGENTS/` that no project link points to — notes, +scratch files, anything you put there by hand — stop the cleanup before +it changes anything, and are listed. Move them out yourself, or pass +`--drop-extras` to discard them. `agents-cleanup` refuses to run when +`AGENTS/` is itself a symlink to a directory elsewhere, since removing it +would remove that directory; replace the link with a real directory first. +Discarded files survive only in the bundle, and files `AGENTS/.gitignore` +ignores are not in the bundle at all; the listing marks those. + +### The disabled marker + +`agents-init` skips a project, silently on every `claude`/`agy` launch, +when either marker is present: + +- The git config key `agents-init.disabled`, which `agents-cleanup` always + sets. It lives in `.git/config`: it is never committed, applies to this + clone only, and survives moving or renaming the project. A fresh clone + is scaffolded again on its first launch. +- A `.agents-disabled` file in the project root, written by + `agents-cleanup --marker-file`. It is not committed for you; commit it + to opt every clone out. Outside a git repository it is the only marker + available, so there `--marker-file` is required. + +Running `agents-cleanup` in a project that was never scaffolded only sets +the marker — a way to opt a project out in advance. + +### Undoing a cleanup + + git clone ~/.local/state/agents-cleanup/-.bundle AGENTS + agents-init --enable + +`agents-init --enable` clears the git key and scaffolds as usual, +re-linking the files restored from the bundle. It refuses while +`.agents-disabled` exists: that file is a decision shared with every +clone, so delete it (and commit the deletion) by hand. + + ## The launch lifecycle The `claude` and `agy` wrapper functions each run `agents-init --quiet` diff --git a/docs/manual/16-agent-tooling.md b/docs/manual/16-agent-tooling.md index 30cb976..bb6db7c 100644 --- a/docs/manual/16-agent-tooling.md +++ b/docs/manual/16-agent-tooling.md @@ -6,6 +6,7 @@ sidebar: helpKeywords: - agent - agents-init +- agents-cleanup - agents-vault - AGENTS.md - claude-code @@ -17,7 +18,7 @@ Antigravity/agy) working in a project checked out from this configuration: where their instructions live, how they get there, and the safety rules that keep an agent's launch-time bookkeeping from touching a repository's own tracked history. Command-line usage for the functions named here -(`agents-init`, `agents-vault`) is generated from their own doc headers — +(`agents-init`, `agents-cleanup`, `agents-vault`) is generated from their own doc headers — see Section 5. @@ -282,6 +283,75 @@ real directory by that name — nothing forces those paths to exist for a project that never used them. +## Opting a project out: agents-cleanup + +`agents-cleanup` reverses everything `agents-init` did in a project and +stops it from happening again. Run it from anywhere inside the project: + + agents-cleanup --dry-run + agents-cleanup + +Every symlink that points into `AGENTS/` is replaced by the real file or +directory it points to, so the project ends up with ordinary files where +the links were. Where two links shared one directory (`docs/plans` and +`docs/superpowers/plans`), the shallower one — the location that existed +before `agents-init` — gets the content and the other link is removed. A +link to a directory holding nothing but `.gitkeep` is simply removed. No +`CLAUDE.md` is recreated. + +A root `AGENTS.md` that is exactly the seed file `agents-init` writes for +a fresh project is deleted, since it never held anything of yours. Any +other `AGENTS.md` keeps its content and loses only the "SYSTEM DIRECTIVE" +blockquote telling agents to edit `AGENTS/AGENTS.md` — a directory that no +longer exists. + +Before anything moves, pending changes in `AGENTS/` are committed and the +whole history is written to a verified git bundle under +`~/.local/state/agents-cleanup/` (or `$XDG_STATE_HOME/agents-cleanup/`). +An `AGENTS/` that is not a git repository has no bundle, so `--drop-extras` +there deletes the files for good. +Then `AGENTS/` is removed, along with `docs/superpowers/` and `docs/` if +they are left empty, and every `Added by agents-init` block is stripped +from `.gitignore`. Nothing is committed to the project itself: the +restored files show up as ordinary changes for you to commit or not. + +WARNING: Files inside `AGENTS/` that no project link points to — notes, +scratch files, anything you put there by hand — stop the cleanup before +it changes anything, and are listed. Move them out yourself, or pass +`--drop-extras` to discard them. `agents-cleanup` refuses to run when +`AGENTS/` is itself a symlink to a directory elsewhere, since removing it +would remove that directory; replace the link with a real directory first. +Discarded files survive only in the bundle, and files `AGENTS/.gitignore` +ignores are not in the bundle at all; the listing marks those. + +### The disabled marker + +`agents-init` skips a project, silently on every `claude`/`agy` launch, +when either marker is present: + +- The git config key `agents-init.disabled`, which `agents-cleanup` always + sets. It lives in `.git/config`: it is never committed, applies to this + clone only, and survives moving or renaming the project. A fresh clone + is scaffolded again on its first launch. +- A `.agents-disabled` file in the project root, written by + `agents-cleanup --marker-file`. It is not committed for you; commit it + to opt every clone out. Outside a git repository it is the only marker + available, so there `--marker-file` is required. + +Running `agents-cleanup` in a project that was never scaffolded only sets +the marker — a way to opt a project out in advance. + +### Undoing a cleanup + + git clone ~/.local/state/agents-cleanup/-.bundle AGENTS + agents-init --enable + +`agents-init --enable` clears the git key and scaffolds as usual, +re-linking the files restored from the bundle. It refuses while +`.agents-disabled` exists: that file is a decision shared with every +clone, so delete it (and commit the deletion) by hand. + + ## The launch lifecycle The `claude` and `agy` wrapper functions each run `agents-init --quiet`