agentic-sdlc
AGENTS.md0 starsChanged 37 days agoMITView on GitHub
For agents working in or on this repository. The skills under skills/ are the product; this file is about changing the product. - One plan step at a time. A change says which rule ids it touches. - Commit only when just check exits 0: ruff, the test suite, agentic-sdlc validate, agentic-sdlc check-skills, agentic-sdlc lint-voice, agentic-sdlc coverage --check and claude plugin validate --strict . (TEST-5). - Every commit, push and post waits for its own go-ahead (ASK-1, ASK-2, ASK-3). Stage…
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 32,671 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 repository11 other files it gives its agents.
- cut-ticketsSkill
- decision-recordsSkill
- deep-modulesSkill
- evidenceSkill
- grill-planSkill
- plain-voiceSkill
- plan-projectSkill
- review-changeSkill
- setup-conventionsSkill
- test-firstSkill
- thin-slicesSkill
The file
We split this AGENTS.md into the rules it gives an agent
4 rules. About 0 are common, 0 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
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 9
Commit only when just check exits 0: ruff, the test suite, agentic-sdlc validate, agentic-sdlc check-skills, agentic-sdlc lint-voice, …
- Very specific: line 12
Every commit, push and post waits for its own go-ahead (ASK-1, ASK-2, ASK-3).
- Very specific: line 21
Every rule with hook in its mechanisms carries examples in the registry, which tests/test_operability.py runs through the guard, and a case …
- Very specific: line 30
Every skills/*/SKILL.md cites existing rule ids, lists in metadata.rules exactly the ids its body cites, has name equal to its folder, a …
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 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
agentic-sdlc: rules that bind
For agents working in or on this repository. The skills under skills/ are the product; this
file is about changing the product.
How to work
- One plan step at a time. A change says which rule ids it touches.
- Commit only when
just checkexits 0: ruff, the test suite,agentic-sdlc validate,agentic-sdlc check-skills,agentic-sdlc lint-voice,agentic-sdlc coverage --checkandclaude plugin validate --strict .(TEST-5). - Every commit, push and post waits for its own go-ahead (ASK-1, ASK-2, ASK-3). Stage by path
(STAGE-1). No tool attribution in commit or pull request text (ATTR-1). Never
--no-verify(GUARD-1).
Rules
rules/registry.jsonis the single source of rules. A new rule gets the next id in its prefix, a statement with an RFC 2119 word, a mechanism list, an owner skill andsince. An id is never reused or renumbered; a retired rule is marked deprecated withreplaced_by.- Every rule with
hookin its mechanisms carriesexamplesin the registry, whichtests/test_operability.pyruns through the guard, and a case intests/test_hook.pyortests/test_operability.pywhen it changes the hook contract. - The hook stays standard-library Python that runs on 3.9. No dependency is added to the
runtime path.
tests/run on 3.9 and 3.14 in CI and on the stock macOS interpreter. command.pyparses;guard.pydecides;text.pymatches;hook.pyandcli.pyadapt. A new mechanism goes into those modules, not into the adapters.docs/coverage.mdis generated. Runagentic-sdlc coverageafter a registry change; CI fails when it is stale.- Every
skills/*/SKILL.mdcites existing rule ids, lists inmetadata.rulesexactly the ids its body cites, hasnameequal to its folder, a description under 1024 characters, and a license line; a skill rewritten from another carries aNOTICEwith the source's copyright line.check-skillsenforces the first four. - The repository tree carries no attribution patterns and no key-shaped literals;
check-skillsscans for both. It also refuses any token the maintainer lists inAGENTIC_SDLC_FORBIDDEN(CI) or.agentic-sdlc-forbidden.txt(local, gitignored). - Text in
README.md,docs/andskills/passeslint-voice --fail-on fail. A line that must quote a banned word carriesvoice-lint: skipin an HTML comment. - Actions in workflows are pinned by commit sha with
persist-credentials: false, and every workflow declarespermissions. - A tag-triggered workflow, when one is added, carries
if: github.event.createdso a moved tag cannot run it again.
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.

