rootiest/fish-config
1
1
Fork 0
Code Issues Pull Requests Actions Wiki Activity

docs(manual): agents-cleanup nested repos, link edge cases, non-git root
CI / test (pull_request) Successful in 2m36s
Details
CI / github-mirror (pull_request) Skipped
Details
CI / docs (pull_request) Successful in 1m18s
Details

Browse Source
This commit is contained in:
rootiest
2026-09-30 17:29:07 -04:00
parent 5e4d0fa4c8
commit 88b43d582f
2 changed files with 52 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/fish-config.md
+32 -19
View File
@@ -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 <bundle> 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
docs/manual/16-agent-tooling.md
+20 -13
View File
@@ -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