joakimp/pi-extensions
Public Access
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

AGENTS.md: documentation-drift sweep as explicit pre-commit step

Browse Source 
Companion to the same addition in the cloud-init and ansible repos.
Caught real drift in those repos in a recent session only because
the user explicitly asked. Codify the sweep with concrete, repo-
specific drift hotspots rather than a vague 'watch for drift' rule
that gets ignored.

Each AGENTS.md addition lists the doc files most likely to fall
behind code changes here, plus a quick-triage one-liner using
'git diff --name-only HEAD | xargs grep -l ...' so the rule is
actionable not aspirational.
This commit is contained in:
Joakim Persson
2026-05-20 23:12:03 +02:00
parent da34f41798
commit 357fcc6eca
1 changed files with 11 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+11
View File
@@ -400,3 +400,14 @@ pi --ssh user@host --ssh-ask-pass
— same pattern for agent skills rather than extensions. — same pattern for agent skills rather than extensions.
- [`opencode-devbox`](https://gitea.jordbo.se/joakimp/opencode-devbox) - [`opencode-devbox`](https://gitea.jordbo.se/joakimp/opencode-devbox)
— Docker containers; composes toolkits via independent install.sh calls. — Docker containers; composes toolkits via independent install.sh calls.
## Documentation drift sweep
Before committing any non-trivial change, check that prose still matches code. Drift hotspots in this repo:
- `README.md` — the per-extension feature/usage descriptions, the install instructions, the dependency list. When an extension's flags or behaviour change, the README block for that extension is the first thing to update.
- `AGENTS.md` (this file) — the `Extension-specific notes` section is large and easy to leave stale. Each extension has its own subsection; if you change a flag, hook, or default, update the subsection here as well as the README.
- Extension files themselves — the `// description:` comment header pi parses for the extension list view must stay accurate.
- `install.sh` — `--only` / `--skip` defaults, the list of artifacts it knows about, and the symlink targets. If you add a new extension file, the installer's auto-discovery picks it up; if you add a new artifact type that needs special handling, the script must be updated and the README block describing what `install.sh does` along with it.
Quick triage: `git diff --name-only HEAD | xargs -I{} grep -l 'thing-you-changed' README.md AGENTS.md install.sh`. For an extension rename, also grep for the old name across the whole repo.