create-cmp / template
CLAUDE.md0 starsChanged 47 days agoMITView on GitHub
Generated by create-cmp with a verification harness. Every AI session in this repo works under this contract. Principles — derived, never claimed · prove the instrument before you read it · the layer you changed cannot certify itself · proof costs what the change costs · never wait on nothing · a signature binds content, a decision is closed · one record, read first. The full form with each episode is create-cmp's docs/PRINCIPLES.md (upstream, not shipped); when a rule below…
- Commits and pushes
In this repository17 other files it gives its agents.
- AGENTS.mdAGENTS.md
- template/AGENTS.mdAGENTS.md
- 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 CLAUDE.md into the rules it gives an agent
3 rules. About 0 are common, 0 are distinctive, and 3 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.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 105
Never delete, weaken, or @Ignore a failing test to reach green.
- Very specific: line 135
Commit it with your change.
- Very specific: line 211
Run desktopTest after every change — it carries the architecture gates that keep this codebase coherent.
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.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
<!-- >>> cmp:feature harness -->APP_NAME — AI delivery contract
Generated by create-cmp with a verification harness. Every AI session in this repo works under this contract.
Principles — derived, never claimed · prove the instrument before you read it · the layer you
changed cannot certify itself · proof costs what the change costs · never wait on nothing · a
signature binds content, a decision is closed · one record, read first. The full form with each
episode is create-cmp's docs/PRINCIPLES.md (upstream, not shipped); when a rule below and a
principle disagree, the principle wins and the rule is the bug.
Definition of done
Done means node qa/verify.mjs reports PASS and the receipt it writes
(qa/evidence/latest.json) attests this tree — the hook checks the working tree by hash; commit
it with your change so CI and reviewers hold the same proof. Claiming completion without a PASS receipt is
a failure. SKIPped steps are recorded in the receipt, and a step that SKIPped for an environmental reason (no
device, no bootable AVD) makes the receipt unusable as done-evidence — qa/receipt-check.mjs refuses
it. Never present green-with-gaps as fully verified.
Verify in two tiers — the full lane is a checkpoint, not an inner loop. It builds, tests, and gates the whole tree to produce the receipt, so it is slow by design; running it after every edit wastes the minutes it takes. Iterate on the fast tier, and run the lane once — when you believe the change is done.
- Inner loop — run continuously (seconds): the preview loop (below) for UI;
node qa/watch.mjsfor verification — a resident watcher that re-runs the fast tier (node qa/verify.mjs --fast) on every save and re-prints the step table, so the did-I-break-anything signal is free the way an IDE's errors-on-save are free; and./gradlew :composeApp:desktopTestfor the unit tests your change touches. This is where you catch your own mistakes. - Checkpoint — run once, at done:
node qa/verify.mjs. It writes the receipt (a--fastrun writesqa/evidence/latest-fast.jsoninstead, so the watcher can keep running); commit the receipt with your change. The Stop hook (qa/receipt-check.mjs, run throughqa/hooks/fail-closed.shso a gate that cannot run refuses) then confirms — with a cheap hash check, not another lane run — that a valid receipt attests this tree, and CI re-runs the full lane on push. After a green checkpoint, do not re-run the lane unless you change the tree again.
Humans get the same gate at push time: run node qa/setup-hooks.mjs once (after git init)
to enable the shipped pre-push hook. It blocks a push whose receipt doesn't attest
the tree — the same cheap check, before code leaves the machine (git push --no-verify bypasses
it; CI still enforces it).
Specifications — behavior starts here
New behavior begins as a spec clause in specs/<feature>.spec.md: Given/When/Then with a
stable id (see specs/README.md). Propose the clause, get it confirmed,
then implement. Durable tests cite their clause (// SPEC: HOME-02).
A clause about device behavior must say so. A citation proves a test exists; it cannot
prove that test could ever observe the promise. Add [tier: device] (or [tier: e2e])
after the id when the claim is about OS facts a host JVM cannot see — lifecycle, alarms,
notifications, permissions, real navigation. specCoverage then requires a citation from
androidInstrumentedTest or qa/e2e for device, from qa/e2e alone for e2e, and FAILS without one, rather than accepting a
desktop test that is structurally blind to the claim.
specs/app-base.spec.md states the architecture and shell
invariants the conformance gates enforce.
Architecture
docs/ARCHITECTURE.md is the doc of record. Every normative
sentence in it carries a tier tag: [enforced: CLAUSE-ID], [governed], or [advisory].
Its cmp:generated sections (expect/actual table, layer inventory, ADR index, glossary) are
derived from a tree walk, never hand-maintained — node qa/arch-doc.mjs regenerates them,
and node qa/arch-doc.mjs --check, a verify-lane step, fails the lane when they drift from
the tree. The governed architecture artifact (.claude/rules/approvals.md) hashes the document alongside
specs/app-base.spec.md, so approving it is consent to this document. The summary:
- Layers:
presentation→domain←data.domainimports nothing app-internal;presentationnever importsdata. Koin wires implementations indi/. - Screens compose the registry vocabulary (
presentation/components/*.kt—ScreenColumn,AppHeader,ContentStateContainer,ListItemCard, …). Do not hand-roll a header, loading state, or list row; the exemplar'sHomeScreen.ktshows the pattern.ScreenColumn(screenTag = "<feature>")tags the root, and ARCH-04 accepts that wiring as tag provenance — a literaltestTagis only needed for content the registry does not already tag (per-row ids, for example). Every screen is a*Screencomposable with a tested ViewModel. - Errors are typed, never thrown across layers. Repositories return
AppResult(Failurecarries aDomainErrorkind). The data layer'ssuspendRunCatchingis the only catch point and always rethrowsCancellationException. ViewModels contain notry/catch; they fold results into a sealed UiState, and presentation maps error kinds to user copy. - Design values (colors, spacing, typography, radii) come from the token catalog in
presentation/theme/. No hardcoded literals in screens. - One feature is the exemplar — the full pattern through every layer, tests included.
It ships as
home;qa/approvals.json'sexemplarFeaturekey retargets it to your own first feature once shaped (see.claude/rules/approvals.md). New features mirror the exemplar exactly: Screen → ViewModel (+ test) → UseCase (+ test) → Repository interface indomain- impl in
data(+ test) → DI entry → navigation route.
- impl in
Testing
- Unit (
composeApp/src/commonTest, run via./gradlew :composeApp:desktopTest): kotlin-test + coroutines-test + Turbine. Hand-written fakes intesting/fakes/; no mocking frameworks. Every new ViewModel/UseCase/Repository gets a test in the exemplar's style: Arrange-Act-Assert, behavior-named backtick tests, one behavior per test. - Conformance + screen tests (
composeApp/src/desktopTest): source-scanning architecture gates enforcingspecs/app-base.spec.md's ARCH clauses, Compose UI Tests (spec-cited, testTag selectors), and the golden-tree baseline (qa/golden/). Unintended golden drift means fix your change; intended drift is regenerated explicitly (UPDATE_GOLDEN=1) and declared. - E2E (
qa/e2e/*.yaml): Maestro flows; smoke covers boot + bottom nav. Select by testTag, never by display text. - Never delete, weaken, or
@Ignorea failing test to reach green. Fix the behavior — or, if the test itself is wrong, say so in your summary and justify the change.
Platform behavior tests live in composeApp/src/androidInstrumentedTest — when a
feature touches alarms, notifications, lock-screen intents, audio routing, or app/process
lifecycle (cold start vs warm resume, "once per process start", process death and
restore, ON_STOP/ON_START), its behavior test goes there, because no desktop tier can
see those OS facts. A desktop Compose test has no process lifecycle at all, so a claim
about one is unobservable there by construction — and ProcessControl below is the organ
that puts the device into the state such a claim is about. Declare it on the clause:
- **MOTION-13** [tier: device] — Given a cold start, …. The lane's specCoverage then
FAILS unless a test from a tier that can actually see it cites the clause, instead of
accepting a citation from a tier that cannot. Assertion helpers:
NotificationAsserts, AlarmAsserts, SystemState. Runtime state control — put the
device into the state your claim is about, instead of waiting for it: TimeWarp (clock,
timezone), DozeControl (forced idle), PermissionControl, ProcessControl,
NetworkControl, ConfigControl (dark mode, font scale, per-app locale). They compose —
the exemplar proves an allowWhileIdle alarm delivers from inside forced deep idle by
nesting a clock warp in a Doze bracket. Exemplars: PlatformBehaviorSeamTest,
RuntimeStateSeamTest. Each organ's header states what it does NOT reproduce; read it
before claiming more than it proves. The lane's androidChecks step runs them — the lane provisions its own device: an attached one, or a
headless AVD it boots itself. CMP_DEVICE=none opts out, and that SKIP is environmental, so the receipt is
then not done-evidence. See docs/TESTING.md.
Evidence
node qa/verify.mjs writes qa/evidence/latest.json (schema: qa/evidence/schema.json).
Each PASS receipt names its evidence rung (L0 scaffold / L1 desktop / L2 device /
L3 release), derived from which steps actually ran and passed — never declared, and a
SKIPped step never upgrades it (see docs/TESTING.md §"The evidence ladder").
Commit it with your change; git history is the audit ledger. Binary artifacts under
qa-artifacts/ are hashed into the receipt, never committed. The studio console's Evidence
page reconstructs the full audit trail from the git log of latest.json — every commit is
one verified, attributed state — so committing each receipt is what builds the record.
The lane is not yours to edit
Do not edit qa/*.mjs, qa/lib/**, qa/harness-manifest.json or qa/verified-surface.json — machine-owned
lane code, locked by sha256 in qa/harness.lock.json; an edit fails harnessIntegrity. Yours: qa/approvals.json,
comments.json, golden/, evidence/, e2e/*.yaml, specs/, composeApp/src/. Your own profile, a relock,
a genuine fork, upgrade --harness: .claude/rules/lane.md.
Every change — the triage is visible, then the walk
Genesis (cmp-new; node qa/approve.mjs --status) is over before this file is your contract;
every change after runs the SAME loop — decide → contract → build → prove → sign. Your FIRST
reply to any change request states in one or two plain sentences what you understood, which
lane it takes, and why, before any tool runs; the human can overrule it in a word, and a silent
route is a routing error even when the lane was right.
Grill before the brief (the grill-me plugin skill carries the procedure; the rule holds without the plugin):
settle the load-bearing questions as a numbered list with a recommended answer each, and WAIT — a signed brief
or spec is a CLOSED decision: cite it, never re-ask it. The direct lane is not grilled.
- The walk (every kickoff, every human gate) — the
walkskill,.claude/skills/walk/SKILL.md. - Approvals —
.claude/rules/approvals.md(loads withqa/approvals.json,specs/, theme, components, screens). - Comments —
.claude/rules/comments.md(loads withqa/comments.json).
<!-- >>> cmp:feature inspector -->- UI feedback loop (building any screen) — the
ui-loopskill,.claude/skills/ui-loop/SKILL.md.
<!-- <<< cmp:feature inspector -->Docs
README.md (front page) · docs/ARCHITECTURE.md
(layers + how to add a feature) · docs/TESTING.md (pyramid +
conventions) · CONTRIBUTING.md (workflow, Conventional Commits) ·
docs/adr/ (decision records — significant decisions get one). Keep
CHANGELOG.md current under [Unreleased] as part of your change.
Commands
| Command | What |
node qa/verify.mjs | The verify lane (profile local) — the done checkpoint, run once |
node qa/verify.mjs --fast | Inner loop — NOT the done-gate: skips the device/release tier (releaseBuild, tokenDrift, e2eSmoke, androidChecks, releaseSmoke), reuses unchanged pure-Node step results (CACHED, content-hashed inputs), and scopes unit tests to the working-tree change (broad-impact changes — build files, DI, theme, shared components, qa/ — run the full suite). Its receipt records "mode": "fast", earns no evidence rung, and the Stop hook refuses it — run the full lane once at done |
node qa/watch.mjs | Resident inner loop — never a gate: watches composeApp/src, specs/, qa/ and re-runs node qa/verify.mjs --fast on save (debounced — a save storm is one run; defers while a verify lane or a preview render holds the project). --once for a single pass, --json for line-per-run output. The done-gate stays one deliberate full node qa/verify.mjs run |
./gradlew :composeApp:desktopTest | Unit tests only (fast inner loop) |
node qa/setup-hooks.mjs | Enable the pre-push receipt gate (one-time, after git init) |
./gradlew :composeApp:assembleDebug | Android debug build |
./gradlew :composeApp:assembleRelease | Android release build — R8 + lintVital, the variant the lane's releaseBuild step proves. Produces an unsigned APK; signing needs a keystore, which is yours to create and keep out of the repo. |
./gradlew :composeApp:connectedDebugAndroidTest | Instrumented behavior tests on the attached device (the lane's androidChecks step) |
node qa/framework-check.mjs | GATE-RULES Rule 0: proves the lane returns both ways — PASS on the clean tree, FAIL by name on planted violations — in seconds, restoring every byte. Run it first in a repo whose harness is new or freshly upgraded. |
node qa/verify.mjs --profile smoke | The smallest end-to-end lane: every pure-Node gate, no Gradle, no device — seconds. Proves the framework returns, never the change (its receipt is refused as done-evidence). Run it first in any repo whose harness is new or freshly upgraded |
node qa/verify.mjs --profile nightly | Scheduled stage: everything ci proves with the determinism probe forced on. Proves the harness, never a change — its receipt (stage: "nightly") is refused as done-evidence, exactly like --fast. Schedule it; never wait on it |
node qa/verify.mjs --profile release | Ship-time lane: everything ci proves plus the audit-cadence report (auditCadence — which androidMain subsystems changed since their last recorded cmp-audit; a nudge, never a gate) and the release-APK Maestro smoke (releaseSmoke) |
node qa/verify.mjs --determinism | Timezone determinism probe, alone: runs the JVM test tier twice under UTC-12 and UTC+14 and FAILs naming any test whose outcome differs — the dynamic net behind ARCH-13's static one. Opt-in inside a lane via --profile ci --determinism; never with --fast; writes no receipt on its own |
node qa/record-audit.mjs <subsystem> | Record that a cmp-audit of an androidMain subsystem happened (appends subsystem + HEAD sha + timestamp to qa/audits.jsonl; refuses dirty/unknown targets). --list shows every derived subsystem and its audit status |
node qa/retrospective.mjs | How this project actually uses its harness, from qa/flight-recorder.jsonl (appended by every lane run): fast vs full ratio, verbatim SKIP reasons grouped, whether the device tier is ever reached, longest stretch with no full lane. States only what the journal recorded |
<!-- >>> cmp:feature dev-client -->| ./gradlew :composeApp:hotRunDesktop --auto | Desktop dev-client with hot reload |
<!-- <<< cmp:feature dev-client --><!-- <<< cmp:feature harness --><!-- >>> cmp:feature !harness -->APP_NAME — working guide
Generated by create-cmp as a minimal scaffold: the full app architecture and its tests, without the verification harness.
Build & test
| Command | What |
./gradlew :composeApp:desktopTest | Unit + conformance + golden-tree tests (JVM, seconds) |
./gradlew :composeApp:assembleDebug | Android debug build |
./gradlew :composeApp:installDebug | Install on the attached device/emulator |
Run desktopTest after every change — it carries the architecture gates that keep this
codebase coherent. Never delete or weaken a failing test to reach green.
Architecture
docs/ARCHITECTURE.md is the working guide: presentation →
domain ← data; typed errors (AppResult, no cross-layer throws); design tokens from
presentation/theme/ (no hardcoded values); every screen a *Screen composable with a
tested ViewModel, mirroring the home exemplar through every layer.
<!-- >>> cmp:feature inspector -->UI feedback loop — see what you build, without a device
./gradlew :composeApp:renderScreens renders every screen in
inspector/PreviewRegistry.kt headlessly (real DI, real theme) to
composeApp/build/previews/<id>/{screen.png, tree.json}; node qa/preview-gallery.mjs
builds one self-contained gallery page. Assert on tree.json structure — pixels are for
humans. Register new screens in the PreviewRegistry.
With a debug build running: adb forward tcp:9500 tcp:9500, then
http://127.0.0.1:9500/inspect/remote mirrors the live app with click-to-tap.
<!-- <<< cmp:feature inspector -->What full mode adds
The verification harness: a verify lane (qa/verify.mjs) with evidence receipts,
behavior specs, approval gates, feature generators, and a Stop hook that makes "done"
machine-checked instead of honor-system. One idempotent command installs it all:
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.

