create-cmp / template
AGENTS.md0 starsChanged 47 days agoMITView on GitHub
Read CLAUDE.md before making changes. It applies to every coding agent, not only Claude. Every command below runs from the repo root with nothing to install: Gradle is wrapped, the scripts ship inside this project, and npx fetches on demand. The create-cmp Claude Code plugin layers better ergonomics over the same capabilities (skills, the cmp-inspector MCP's structured tools) — an accelerator, never a prerequisite. Famous build failures (kotlin↔KSP mismatch, the KSP2/iOS catch-22, SDK location not found, No space left on…
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 repository17 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- template/CLAUDE.mdCLAUDE.md
- llms.txtllms.txt
- npm-publishSkill
- plugin-refreshSkill
- cmp-auditSkill
- cmp-dev-clientSkill
- cmp-doctorSkill
- cmp-firebase-connectSkill
- cmp-inspectSkill
- cmp-newSkill
- cmp-previewSkill
- cmp-qa-prepSkill
- cmp-testSkill
- cmp-upgradeSkill
- grill-meSkill
The file
We split this AGENTS.md into the rules it gives an agent
2 rules. About 0 are common, 1 is distinctive, and 1 is 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.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 14
Read CLAUDE.md before making changes.
- Very specific: line 18
Every command below runs from the repo root with nothing to install: Gradle is wrapped, the scripts ship inside this project, and npx …
≈ “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
Agent instructions
<!-- >>> cmp:feature harness -->This repository is agent-first, with a verification harness. The working contract — the
definition of done (node qa/verify.mjs must PASS, receipt committed), the architecture
gates, and the device-free UI feedback loop — lives in CLAUDE.md.
<!-- <<< cmp:feature harness --><!-- >>> cmp:feature !harness -->This repository is agent-first. The working guide — the architecture, the commands that build and test it, and the device-free UI feedback loop — lives in CLAUDE.md.
<!-- <<< cmp:feature !harness -->Read CLAUDE.md before making changes. It applies to every coding agent, not only Claude.
Stuck? Symptom → command
Every command below runs from the repo root with nothing to install: Gradle is
wrapped, the scripts ship inside this project, and npx fetches on demand. The
create-cmp Claude Code plugin layers better ergonomics over the same capabilities
(skills, the cmp-inspector MCP's structured tools) — an accelerator, never a
prerequisite.
| Symptom | Run |
<!-- >>> cmp:feature harness -->| "Did my edit break anything?" | node qa/verify.mjs --fast — the inner loop: seconds of JVM-tier signal; never the done-gate |
| Want that answer on every save | node qa/watch.mjs — resident watcher; re-runs the fast tier on save, debounced |
<!-- <<< cmp:feature harness --><!-- >>> cmp:feature !harness -->| "Did my edit break anything?" | ./gradlew :composeApp:desktopTest — unit + conformance + golden-tree tests in seconds, no device |
<!-- <<< cmp:feature !harness --><!-- >>> cmp:feature inspector -->| Can't see the UI (no device attached) | ./gradlew :composeApp:renderScreens && node qa/preview-gallery.mjs — every real screen headless: tree.json for you to assert on, one gallery page for the human |
| Need the RUNNING app's real state | adb forward tcp:9500 tcp:9500, then http://127.0.0.1:9500/inspect/remote — debug builds serve the live semantics tree on loopback |
<!-- <<< cmp:feature inspector --><!-- >>> cmp:feature harness -->| Adding a feature / screen / repository | node qa/scaffold-feature.mjs <Name> — clones the tested exemplar through every layer; never freehand the pattern (skills: add-feature, add-screen, add-repository) |
| A gate failed and looks arbitrary | node qa/refusal-demo.mjs — stages canonical violations so each gate names the clause it protects |
| Where are we / whose turn is it | node qa/walk-status.mjs — every open walk's stage card (Decide·Design·Contract·Build·Prove·Sign-off), whose turn, what arrived unplanned; --statusline is the one-liner |
<!-- <<< cmp:feature harness -->| Build broken, toolchain suspect | npx create-cmp-cli doctor --fix — diagnoses machine AND project (kotlin↔ksp lockstep, catalog drift) and applies the safe heals. It also rewrites the hook commands create-cmp itself shipped before 0.26.3 into their anchored form, so they run from any directory — and never a hook this app wrote, which it reports with the form to paste. That rewrite is the one project heal that asks first, and installing a missing tool asks too; local.properties, ksp.useKSP2 and the walk wiring are written without a prompt. --dry-run previews every heal and writes nothing |
| Dependency versions stale or mismatched | npx create-cmp-cli upgrade --dry-run — diff against the next proven-green set before touching anything |
<!-- >>> cmp:feature harness -->| Ready to claim done | node qa/verify.mjs — the full lane, once, deliberately; commit the receipt it writes |
<!-- <<< cmp:feature harness -->Famous build failures (kotlin↔KSP mismatch, the KSP2/iOS catch-22, SDK location not
found, No space left on device): doctor diagnoses all of them offline; the worked
write-ups live upstream at
https://github.com/kvdm-co-pilot/create-cmp/tree/main/docs/errors.
A secret scanner that flags qa/harness.lock.json (gitleaks' generic-api-key, or any rule for a
64-character hex string) has found sha256 digests, not a credential: each value in the lock's
files map is the digest of one lane file, and its top-level sha256 the digest of them all,
which is how the lane knows its own code was not edited. Allowlist the path, not the values — they
change with every harness upgrade or relock. For gitleaks, that is
paths = ['''qa/harness\.lock\.json'''] under [allowlist] in .gitleaks.toml.
<!-- >>> cmp:feature harness -->The receipts committed under qa/evidence/ carry digests of the same shape; allowlist them the
same way.
<!-- <<< cmp:feature harness --><!-- >>> cmp:feature harness -->One rule before you edit anything: the .mjs files directly under qa/ and qa/lib/
are machine-owned harness code — byte-identical in every create-cmp app and
hash-locked by qa/harness.lock.json. Editing them fails the lane's first step. If the
lane is wrong, the fix is upstream — see "The lane is not yours to edit" in CLAUDE.md.
<!-- <<< cmp:feature harness --><!-- >>> cmp:feature !harness -->This is a minimal scaffold — no verify lane, receipts, specs, or generators are
installed. One idempotent command installs the full harness and its machine-checked
definition of done: npx create-cmp-cli harden.
<!-- <<< cmp:feature !harness -->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.

