platform-agent-harness
AGENTS.md2 starsChanged 6 days agoApache-2.0View on GitHub
This repository is the platform-agent-harness. It is the source of the harness itself — not an infra or platform repo. The file you are reading exists so any CLI agent opened in this directory knows how to behave. The instruction contract you copy into your infra repo lives at templates/AGENTS.template.md. Copy that file to your repo as AGENTS.md, then pick a runtime wiring from adapters/. The end-to-end story is in README.md and the compaction lifecycle is in LIFECYCLE.md. Do not…
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 repository16 other files it gives its agents.
- adopt-evalSkill
- contract-validationSkill
- create-prSkill
- designSkill
- graphifySkill
- helm-upgradeSkill
- ingest-readingSkill
- investigate-alertSkill
- k8s-debugSkill
- parallax-reviewSkill
- shiny-engineerSkill
- stakeholder-commsSkill
- stop-slop-codeSkill
- systematic-debuggingSkill
- upstream-triageSkill
- verify-claimsSkill
The file
We split this AGENTS.md into the rules it gives an agent
7 rules. About 0 are common, 4 are distinctive, and 3 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.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Distinctive: line 13
Keep all content public-safe.
- Very specific: line 14
Before every commit that touches examples, references, or templates, run sanitization/prepublish-checklist.md (trufflehog, gitleaks, the …
- Very specific: line 15
Search agent-knowledge/references/index.md before adding new docs — reuse before duplication.
- Distinctive: line 22
No mutating Kubernetes commands.
- Distinctive: line 23
No pushes to main / master.
- Distinctive: line 24
Never delete or overwrite untracked files without explicit instruction — treat them as user-owned work.
- Very specific: line 25
No real graphify-out/, .beads/, runtime settings, MCP credentials, sessions, or logs in commits.
≈ “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
AGENTS.md — about this repository
This repository is the platform-agent-harness. It is the source of the harness itself — not an infra or platform repo. The file you are reading exists so any CLI agent opened in this directory knows how to behave.
If you are adopting the harness
The instruction contract you copy into your infra repo lives at templates/AGENTS.template.md. Copy that file to your repo as AGENTS.md, then pick a runtime wiring from adapters/. The end-to-end story is in README.md and the compaction lifecycle is in LIFECYCLE.md.
Do not copy this file. It only describes the harness source repo itself.
If you are working inside this repo
- Keep all content public-safe. No real cluster names, account IDs, customer names, internal URLs, or tokens.
- Before every commit that touches examples, references, or templates, run
sanitization/prepublish-checklist.md(trufflehog,gitleaks, the local denylist). - Search
agent-knowledge/references/index.mdbefore adding new docs — reuse before duplication. - Instance knowledge (cluster registries, account IDs, fleet inventories, "metric X does not exist" claims) never belongs in
agent-knowledge/references/— that tier is portable by definition. Here the instance tier ships asagent-knowledge/orgs/README.mdand nothing else. Rule:core/protocols/knowledge-tiers.md. - Runtime-specific assumptions belong only under
adapters/.core/,skills/, anddomain-packs/must stay portable. - Match the tone and structure of the closest existing files when editing.
Safety defaults that apply here too
- No mutating Kubernetes commands.
- No pushes to
main/master. No force-pushes to protected branches. - Never delete or overwrite untracked files without explicit instruction — treat them as user-owned work.
- No real
graphify-out/,.beads/, runtime settings, MCP credentials, sessions, or logs in commits.
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.