CooperativeAICoding
AGENTS.md2 starsChanged 14 days agoMITView on GitHub
A framework that gives Product, Developers, QA and AI one shared way of working: plain-English briefs, specs the AI translates rather than authors, a plan a person approves before code is written, and debt the AI has to declare. It is Markdown, JSON and prompts — there is no application in this repository. The desktop app built with it, Swarm, lives in its own repository with its own guardrails. Changes to the app happen there, not here. - A procedure…
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 repository24 other files it gives its agents.
- buildSkill
- debtSkill
- draftSkill
- emit-guardrailsSkill
- new-itemSkill
- pipelineSkill
- productSkill
- qaSkill
- translateSkill
- verifySkill
- create-pipelineSkill
- draft-briefSkill
- emit-guardrailsSkill
- translate-briefSkill
- buildSkill
- debtSkill
- draftSkill
- emit-guardrailsSkill
- new-itemSkill
- pipelineSkill
- productSkill
- qaSkill
- translateSkill
- verifySkill
The file
We split this AGENTS.md into the rules it gives an agent
3 rules. About 0 are common, 1 is distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 33
A check must be able to fail: Every check in tools/ has tests for the faults it exists to catch.
- Very specific: line 54
If you touched site/, build it: cd site && npm ci && node build.mjs.
- Distinctive: line 59
Treat existing content as in use — projects have copied it.
≈ “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
<!-- Hand-written for working on the framework itself. The framework has no
Project brief of its own yet, so there is nothing to generate this from;
when it has one, `/emit-guardrails` can replace this file. -->CooperativeAICoding — how work is done here
A framework that gives Product, Developers, QA and AI one shared way of working: plain-English briefs, specs the AI translates rather than authors, a plan a person approves before code is written, and debt the AI has to declare. It is Markdown, JSON and prompts — there is no application in this repository.
The desktop app built with it, Swarm, lives in its own repository with its own guardrails. Changes to the app happen there, not here.
Where things live
| Folder | What it is |
template/ | The blank copy init hands to a project: the brief, the forms in _forms/, and the procedures in ai-only/procedures/ |
example/ | A worked Clothing project to read before writing your own |
.claude/ | The slash commands and skills — thin pointers to the procedures, never copies of them |
.cursor/, .agents/, .gemini/, .opencode/, .github/prompts/, .kiro/ | The same commands for other agents, generated from .claude/commands/ by tools/agent-commands.mjs. Change a command there, then run it. |
tools/ | The checks (every *-lint.mjs, run together by check.mjs) and their tests |
bin/ | The coperativeai CLI: init copies the template into a project, update brings it up to date |
site/ | The GitHub Pages site, built from README.md, HOW-TO-USE.md and INSTALL.md |
House rules
- A procedure exists once. It lives in
template/ai-only/procedures/, and every command or skill that runs it points there.tools/commands.test.mjsfails when a pointer starts carrying behaviour of its own. - A check must be able to fail. Every check in
tools/has tests for the faults it exists to catch. A check that passes while reading nothing is worse than no check. - DRY — if something repeats three times, move it into one shared place.
- Keep it simple — enough to finish the job, and no more.
- Anything a project receives is a promise. A change to
template/orbin/reaches every project that runsinitafterwards, so it is reviewed as such.
Testing
From the repository root, these must pass:
npm test # the checks' own tests, and every command points at something real
npm run check # npm test, then every check over this repositoryPublishing runs tools/known-versions.mjs first (prepublishOnly), so
coperativeai update can recognise every version a project might hold.
If you touched site/, build it: cd site && npm ci && node build.mjs.
The working agreement
- Build the smallest thing that answers the request. No unrequested extras.
- Treat existing content as in use — projects have copied it.
- Never invent scope. Anything not asked for is an open question, not a decision you get to make.
- When you cannot understand something, stop and say so. A guess that becomes a rule in the template is the failure this framework exists to prevent.
- A person reviews and approves a plan before files are changed.
When you finish, write this down
Append to ROUND-RECORD.md, one heading each:
What I did
What I could not do (and what you would need to tell me)
Debt I left behind (one paragraph each, so each can become its own work item)
Debt that is not written down is debt that gets paid by surprise.
What this file cannot give you
In Claude Code, .claude/settings.json runs tools/hooks/guard.mjs on every
write: no AI-written sign-off or QA verdict, no secret values, specs checked as
written. That applies to work on this repository too.
The rest are rules, not machinery. Plan approval, model and effort per work item, what a run cost and a bounded place for agents to run live in the Swarm app and its commands. With any other agent you get the guardrails and the procedures; enforcing the rest is on you.
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.