diff --git a/docs/fish-config.md b/docs/fish-config.md index 9c5c171..9e0acaf 100644 --- a/docs/fish-config.md +++ b/docs/fish-config.md @@ -2482,8 +2482,10 @@ functions). They are active in all interactive sessions. 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 + and the other is removed; a link to a target holding only .gitkeep, a + dangling link, or a link to AGENTS/ itself is removed with nothing put + in its place. Dangling links are removed even when AGENTS/ is already + gone. 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. @@ -2498,14 +2500,17 @@ functions). They are active in all interactive sessions. 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. + discards them instead. A nested git repository inside AGENTS/ is always + refused, --drop-extras or not: the bundle keeps only a pointer to it, so + move it out first. 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 + available outside a git repository, where the project root is taken to + be the current directory -- run it from there. 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, @@ -2523,7 +2528,8 @@ functions). They are active in all interactive sessions. 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 + AGENTS/, unlinked files or a nested repository in AGENTS/) or a step + failed Notes: Restore an archived AGENTS/ with: git clone AGENTS, then @@ -5565,7 +5571,8 @@ 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: +stops it from happening again. Run it from anywhere inside the project +(from the project root when it is not a git repository): agents-cleanup --dry-run agents-cleanup @@ -5575,33 +5582,39 @@ 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. +link to a directory holding nothing but `.gitkeep`, a dangling link, and a +link to `AGENTS/` itself are simply removed; dangling links go even if you +already deleted `AGENTS/` by hand. 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. +longer exists. If the directive was all it held, the file is deleted. 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. +from `.gitignore`. A `.gitignore` that held only those blocks is deleted, +unless it is tracked, in which case it is emptied and the change shows in +`git status`. 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. +`--drop-extras` to discard them. `--dry-run` refuses the same way, unless +you also give it `--drop-extras`. A git repository nested inside `AGENTS/` +is always refused, even with `--drop-extras`: the bundle records only a +pointer to it, so move it out first. `agents-cleanup` also 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. An `AGENTS/` that is not a git repository has no bundle, so +`--drop-extras` there deletes the files for good. ### The disabled marker diff --git a/docs/manual/16-agent-tooling.md b/docs/manual/16-agent-tooling.md index bb6db7c..09ff725 100644 --- a/docs/manual/16-agent-tooling.md +++ b/docs/manual/16-agent-tooling.md @@ -286,7 +286,8 @@ 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: +stops it from happening again. Run it from anywhere inside the project +(from the project root when it is not a git repository): agents-cleanup --dry-run agents-cleanup @@ -296,33 +297,39 @@ 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. +link to a directory holding nothing but `.gitkeep`, a dangling link, and a +link to `AGENTS/` itself are simply removed; dangling links go even if you +already deleted `AGENTS/` by hand. 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. +longer exists. If the directive was all it held, the file is deleted. 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. +from `.gitignore`. A `.gitignore` that held only those blocks is deleted, +unless it is tracked, in which case it is emptied and the change shows in +`git status`. 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. +`--drop-extras` to discard them. `--dry-run` refuses the same way, unless +you also give it `--drop-extras`. A git repository nested inside `AGENTS/` +is always refused, even with `--drop-extras`: the bundle records only a +pointer to it, so move it out first. `agents-cleanup` also 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. An `AGENTS/` that is not a git repository has no bundle, so +`--drop-extras` there deletes the files for good. ### The disabled marker