agentleFS
kvdm-co-pilotkvdm-co-pilot/create-cmp/template/CLAUDE.md

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

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
  1. Very specific:

    Never delete, weaken, or @Ignore a failing test to reach green.

    line 105
  2. Very specific:

    Commit it with your change.

    line 135
  3. Very specific:

    Run desktopTest after every change — it carries the architecture gates that keep this codebase coherent.

    line 211

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md
<!-- >>> 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.mjs for 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:desktopTest for 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 --fast run writes qa/evidence/latest-fast.json instead, so the watcher can keep running); commit the receipt with your change. The Stop hook (qa/receipt-check.mjs, run through qa/hooks/fail-closed.sh so 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. domain imports nothing app-internal; presentation never imports data. Koin wires implementations in di/.
  • 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's HomeScreen.kt shows the pattern. ScreenColumn(screenTag = "<feature>") tags the root, and ARCH-04 accepts that wiring as tag provenance — a literal testTag is only needed for content the registry does not already tag (per-row ids, for example). Every screen is a *Screen composable with a tested ViewModel.
  • Errors are typed, never thrown across layers. Repositories return AppResult (Failure carries a DomainError kind). The data layer's suspendRunCatching is the only catch point and always rethrows CancellationException. ViewModels contain no try/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's exemplarFeature key 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 in domain
    • impl in data (+ test) → DI entry → navigation route.

Testing

  • Unit (composeApp/src/commonTest, run via ./gradlew :composeApp:desktopTest): kotlin-test + coroutines-test + Turbine. Hand-written fakes in testing/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 enforcing specs/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 @Ignore a 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 walk skill, .claude/skills/walk/SKILL.md.
  • Approvals — .claude/rules/approvals.md (loads with qa/approvals.json, specs/, theme, components, screens).
  • Comments — .claude/rules/comments.md (loads with qa/comments.json).
<!-- >>> cmp:feature inspector -->
  • UI feedback loop (building any screen) — the ui-loop skill, .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

CommandWhat
node qa/verify.mjsThe verify lane (profile local) — the done checkpoint, run once
node qa/verify.mjs --fastInner 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.mjsResident 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:desktopTestUnit tests only (fast inner loop)
node qa/setup-hooks.mjsEnable the pre-push receipt gate (one-time, after git init)
./gradlew :composeApp:assembleDebugAndroid debug build
./gradlew :composeApp:assembleReleaseAndroid 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:connectedDebugAndroidTestInstrumented behavior tests on the attached device (the lane's androidChecks step)
node qa/framework-check.mjsGATE-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 smokeThe 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 nightlyScheduled 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 releaseShip-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 --determinismTimezone 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.mjsHow 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

CommandWhat
./gradlew :composeApp:desktopTestUnit + conformance + golden-tree tests (JVM, seconds)
./gradlew :composeApp:assembleDebugAndroid debug build
./gradlew :composeApp:installDebugInstall 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 -->

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.