AgentGovernanceBootstrap
AGENTS.md2 starsChanged 2 months agoMITView on GitHub
@.agents/repo-guidance.md More specific rules win. Flag a contradiction you cannot reconcile. Before changes, read this file, .agents/repo-guidance.md and .agents/state.md. Before trusting state, compare the local ref with git ls-remote; if unreachable, proceed with a caveat. Hook trust needs an explanation and explicit go. Human request → this file and repo guidance → state, decisions and approved playbooks → code/tests/CI evidence → other docs. Fix the lower source on disagreement, or ask. Read .agents/playbooks/<name>.md on invocation. Ask one unsettled decision: context,…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 31,774 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository12 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- catchupSkill
- codereviewSkill
- decisionSkill
- gitSkill
- handoffSkill
- openreviewSkill
- planSkill
- playbookSkill
- reviewSkill
- toolkitSkill
- update-governanceSkill
The file
We split this AGENTS.md into the rules it gives an agent
8 rules. About 0 are common, 4 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 7
Commit slices with records.
- Distinctive: line 8
Only repo files are durable memory.
- Distinctive: line 20
Never bypass failed checks, guards, ignore rules or refusals unless proven not load-bearing.
- Very specific: line 22
Keep this file portable; repo-specific rules live in .agents/.
- Very specific: line 26
Before changes, read this file, .agents/repo-guidance.md and .agents/state.md.
- Very specific: line 34
Read .agents/playbooks/<name>.md on invocation.
- Distinctive: line 45
Ask one unsettled decision: context, action, consequence, recommendation.
- Distinctive: line 51
Before claiming completion, run repo guidance's verification entry point.
≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Agent Guidance
Prime Invariants
- Answer first; act only on an explicit go for its named scope. Plans, reports and specs aren't a go.
- Code changes require an approved plan. Non-shipped bookkeeping doesn't; if unsure, treat it as code.
- Commit slices with records. Branch work is incomplete until merged into main and its branch deleted. Push policy:
.agents/push-policy.md. - Only repo files are durable memory. Re-read this file under context pressure; hand off before judgment degrades.
Repo-Specific Guidance
@.agents/repo-guidance.md
More specific rules win. Flag a contradiction you cannot reconcile.
Invariants
- Record durable facts, decisions and open questions in
.agents/, understandable without chat; label unverified inferences as assumptions. - One canonical location per truth; pointers over copies.
.agents/state.mdis the sole current-state entry point, kept current by the working agent as work lands. - Never bypass failed checks, guards, ignore rules or refusals unless proven not load-bearing. Otherwise stop or ask.
- Escalate for stalled progress, never duration: after 2–3 attempts without verifiable progress, report the obstacle and proposed next action.
- Keep this file portable; repo-specific rules live in
.agents/. Refresh-governed artifacts are toolkit-owned. Edit toolkit sources, never installed copies. Exclude installed copies from repo lint/format; refresh restores divergence. Seeded policies (.agents/push-policy.md) are repo-owned and editable.
Session Startup
Before changes, read this file, .agents/repo-guidance.md and .agents/state.md. Before trusting state, compare the local ref with git ls-remote; if unreachable, proceed with a caveat. Hook trust needs an explanation and explicit go.
Source of Truth
Human request → this file and repo guidance → state, decisions and approved playbooks → code/tests/CI evidence → other docs. Fix the lower source on disagreement, or ask.
Operator Requests
Read .agents/playbooks/<name>.md on invocation.
catchup— re-ground and report; no other work until the owner responds.handoff— fast state snapshot.decision— record a settled decision in.agents/decisions.md; update affected guidance.plan— draft or update a durable plan.playbook <name>— run it; report if missing.toolkit— list owner verbs, one plain line each.
Owner Gates
Ask one unsettled decision: context, action, consequence, recommendation. Approval stands within scope; silence authorizes nothing.
Verification
Self-review is forbidden unless explicitly requested by the owner.
Before claiming completion, run repo guidance's verification entry point; docs-only changes need git diff --check unless they affect behavior. Prove new tests bite: revert the fix, watch it fail, restore. State checks not run.
Git Safety
Merges, deletion, history rewrites (amend, rebase, squash, force-push) and outward-facing actions each need explicit authority. One finding per commit. Before branch deletion, verify content reached main with git diff; ancestry alone is insufficient. Setup/closeout: .agents/playbooks/git.md.
Final Response
Lead with results. Name remaining work's pending step and one proposed action; never call incomplete work done.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.