- Home
- Skills
- DevOps & Cloud
- Agent Repo Hygiene, AGENTS.md Rules and Release Provenance
Agent Repo Hygiene, AGENTS.md Rules and Release Provenance
This kit is the rules that stopped it, written as a template any repository can adopt, plus three scripts that make the rules checkable instead of aspirational.
$29
Works with the AI Agents you already use
Agent Repo Hygiene, AGENTS.md Rules and Release Provenance
Example session with this skill installed
Three of us plus a couple of AI agents commit to the same service repo and it keeps drifting: hotfixes on the server, a README nobody trusts, a 'master' branch someone still deploys from. Give us rules we can enforce and a way to prove what's actually running.
- Read your context and instructions
- Compiled the agent repo hygiene
Summary
Adopted the AGENTS.md rules, put the hygiene check at the end of every session, stamped the deployed release with a tree digest, and found a hand edit on the server on the first verify.
Hygiene check (node scripts/hygiene-check.mjs)
FAIL: repository hygiene
fail: working tree is dirty (3 path(s)): commit or discard before stopping
fail: 2 commit(s) not pushed to origin/main
fail: commit 4f1c9a2e11 "tighten rate limit" changed code without touching README/HISTORY/CHANGELOG: the README is updated with the change, never later
fail: tracked file looks like a secret: deploy/.env
fail: legacy branch master has 7 commit(s) not on main: one track only; merge or archive it
note: merged branches still present locally: feature/limits (delete them, or archive under archived/<name>)
After the fixes (push, README entry in the same commit, .env replaced by .env.example, master merged and deleted): ok: repository hygiene checks passed.
Provenance
node scripts/release-source.mjs stamp --repo . --out RELEASE_SOURCE.jsonat deploy: commita93e..., on main, clean tree, 212 files, digeste6ec....- On the server:
node scripts/release-source.mjs verify /srv/app/current
FAIL: content digest drift: stamp e6ecc338e547, deployed 1b7d0a92c0f1 (212 files on disk, 212 stamped)->src/limits.mjshad been edited by hand on the box. Backported to main the same session, redeployed, verifyok.
History
node scripts/history-append.mjs --file HISTORY.md --zone America/Denver --title "Deployed 1.4.2" --body "rate limit 60/min; verify ok; backup 02:10 UTC" -> entry stamped 2026-10-29 06:12:40 MDT (America/Denver) / 2026-10-29 12:12:40 UTC; CI runs --verify-prefix against the previous commit's copy.
Tests
node --test scripts/hygiene.test.mjs: 5 passed on throwaway git repositories.
Connects securely to your tools. The creator never sees your data.
About this skill
When several sessions and people work in one repository, drift is the default: live code that was never merged, a README that describes last month, two rebuilds of the same product on long-lived branches, deploys nobody can trace to a commit. This kit is the rules that stopped it, written as a template any repository can adopt, plus three scripts that make the rules checkable instead of aspirational.
AGENTS.md template: the default branch is the source of truth (commit and push every session, deploy only from main, backport hotfixes the same session); provenance on every deploy; README updated with the change, never later; one track, no parallel rebuilds, archive superseded work; verify production not the merge (merged is not deployed is not working); never commit secrets; server-derived fields and tests that defend bugs; verify the instrument before believing the reading (the self-matching grep, the line count read as an occurrence count, the path-converted argument, the heredoc that never ran); evidence in files.
hygiene-check.mjs: exit 1 when not on main, the tree is dirty, commits are unpushed, the last code commit touched no README/HISTORY/CHANGELOG, a tracked file looks like a secret or contains a credential value, or a legacy branch has commits not on main; notes for merged branches to delete and a missing stamp.
release-source.mjs: stamp writes RELEASE_SOURCE.json with repository, branch, commit, main head, on-main and dirty flags, time and a digest of the committed tree; verify recomputes the digest from the deployed directory and exits 1 on drift, so a hand edit on the server is caught.
history-append.mjs: entries with local-zone and UTC stamps, append-only by construction (the previous file must remain a prefix), --verify-prefix for CI.
reference/vocabulary-and-evidence.md: the three words, the stamp schema, the evidence folder layout, the failures behind each rule. 5 offline tests on throwaway git repositories. Node 20+, no packages.
Requires Node 20+ and Git. Default branch must be main or explicitly passed. Secret detection uses heuristics. Does not track uncommitted generated assets.
How to use
- 1
Connect your agent to the Agensi MCP
Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup
- 2
Sign in to Agensi
Your agent shows a sign-in link. Sign in and click Allow.
- 3
Ask for what you need
Your agent loads this skill and uses it on your task. It always asks before any payment.
Reviews
No reviews yet
Be one of the first to try it. Every listed skill goes through the trust checks below.
Security scanned
Checked by our 8-point scan before listing
Fresh listing
Recently published to Agensi
Money-back guarantee
Doesn't do what its page promises? You get your money back.
Trust & safety
Security scan
Security scan passed 19 days ago
Requires
Permissions
Shell to run the node scripts, tests and git; read files across the repository and the deployed directory; write files for RELEASE_SOURCE.json and HISTORY.md. No network access beyond git talking to your own remote. No environment variables.