agentleFS
whinstudiowhinstudio/skills/compass-kit/CLAUDE.md

skills / compass-kit

CLAUDE.md0 starsChanged 3 days agoMITView on GitHub

This is a Compose Multiplatform app (Android + iOS) generated by Compass from the cmpose template. - androidApp/: Android entry point (Activity, applicationId) - iosApp/: Xcode project that hosts the shared framework - shared/: app shell, navigation graph, di/initKoin.kt (every Koin module is registered here) - core/logging: Kermit logging, in every project (Logger.withTag("Name"); debug builds write every level, release builds warnings and errors) - core/review: in-app review, in every project (ReviewPrompter.recordPositiveEvent() after a moment the user wanted; openStorePage() for "Rate…

The file

We split this CLAUDE.md into the rules it gives an agent

10 rules. About 0 are common, 3 are distinctive, and 7 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 7

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    When server/ exists, the gates include the server: :server:build (its tests and detekt.

    line 35
  2. Very specific:

    Run the gates (after a screen or module, before saying you are done): cmp-gates.

    line 60
  3. Very specific:

    Do not touch the Gradle wrapper, the Kotlin/AGP versions or the build-logic plugin wiring.

    line 71
  4. Very specific:

    Every module with composeResources (fonts, strings, sounds, drawables) needs androidResources.enable = true in its Android block: kotlin { …

    line 72
  5. Distinctive:

    Every name in the code is English: modules, packages, classes, files, string keys — whatever language the request or the UI is in.

    line 77
  6. Very specific:

    Ask for a review only through ReviewPrompter (system dialog).

    line 83
  7. Very specific:

    Keep iosApp/iosApp/PrivacyInfo.xcprivacy in step with the code: a new Kotlin or Swift use of UserDefaults, file dates, disk space or boot …

    line 84
  8. Very specific:

    After DataError.Network, retry on ConnectivityMonitor.reconnections().

    line 85
  9. Distinctive:

    Read the existing code before writing.

    line 91
  10. Distinctive:

    Never push. Commit only when the owner asks.

    line 95

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

Project guide for Claude

This is a Compose Multiplatform app (Android + iOS) generated by Compass from the cmpose template.

Map

  • androidApp/: Android entry point (Activity, applicationId)
  • iosApp/: Xcode project that hosts the shared framework
  • shared/: app shell, navigation graph, di/initKoin.kt (every Koin module is registered here)
  • core/logging: Kermit logging, in every project (Logger.withTag("Name"); debug builds write every level, release builds warnings and errors)
  • core/review: in-app review, in every project (ReviewPrompter.recordPositiveEvent() after a moment the user wanted; openStorePage() for "Rate the app"; ReviewRequestEffect() in MainScreen passes requests on)
  • core/about: app version (AppInfo), PRIVACY_POLICY_URL/TERMS_URL and the licences screen (LicensesDestination(title)), in every project
  • core/update: app updates (AppUpdateEffect() in MainScreen; MIN_VERSION_URL for a forced update)
  • core/image: Coil 3 (AsyncImage; KtAsyncImage with the design system); ImageLoaderSetup() in MainScreen
  • Deep links: <scheme>://<path> (scheme = project name in lower case); a screen gets one with a DeepLinkRoute (@Single(binds = [DeepLinkRoute::class]), pattern = "orders/{id}")
  • ConnectivityMonitor (core/domain, projects with network): isOnline, reconnections()
  • core/insights: Firebase Crashlytics + Analytics behind Insights, only if present (blank with insights, every showcase); a no-op (Insights.isEnabled == false) until the Firebase config files are added. Never send tokens, bodies, headers, emails or names; setUserId takes the backend user id only
  • core/*: shared infrastructure (network, theme, persistence, database (Room), purchases, ads), only if present
  • feature/<name>/{contract,domain,data,presentation}: one folder per feature, four layers
  • feature/monetization/{contract,presentation}: custom paywall (paywall/: Compose screen on PurchasesManager.offer()/purchase()/restore(), FirstLaunchPaywall() in MainScreen) and the ads demo (InterstitialPacer from core/ads for interstitials at natural breaks), only if present (two layers)
  • feature/notes/{contract,presentation}: blank's Room demo, only if present (two layers)
  • server/ (the cmpose backend template's Ktor server, an included build: server/README.md, server/SECURITY-CHECKLIST.md), core/api (the app's client models and routes for the backend API, checked by ApiContractTest), core/auth (Firebase sign-in), feature/account and feature/sharing (spaces, members, invites): the backend, only if server/ exists
  • build-logic/: Gradle convention plugins. Do not change their wiring.
  • design/: the exported design, fonts, icons and sounds Compass prepared (read-only input)

Definition of done

A change is finished only when every gate below passes in the current session. Run them through cmp-gates (all of them, or the ones you need, e.g. cmp-gates tests), not with ./gradlew in this session: it runs the exact commands shown in a separate subagent and returns a short report. ./gradlew build is not used because it links release iOS frameworks and runs out of memory. When server/ exists, the gates include the server: :server:build (its tests and detekt; server/ is an included build that allTests does not cover), run through cmp-gates like the others.

<!-- compass:gates -->

The test gate counts the tests it runs on the iOS simulator, and zero tests is red: write unit tests as you go (see cmp-testing). Host-only tests such as KoinGraphTest do not count.

The app also needs .maestro/walkthrough.yaml (see cmp-maestro); Compass records the demo video from it.

Which skill when

cmp-gates, cmp-testing, cmp-maestro and cmp-detekt run in a subagent that does not see this conversation: pass what they need as the argument (the gates, the class to test, the flow).

  • Any Kotlin change: cmp-code-rules
  • New screen, feature module, repository or data source: cmp-feature
  • UI from files under design/ or a mockup: cmp-design-to-code
  • Maestro flow or testTags: cmp-maestro
  • Writing or fixing unit tests: cmp-testing; only running them: cmp-gates tests
  • detekt findings: cmp-detekt (only when detekt is set up)
  • App data on the server (a migration, a server/.../feature/<name>/ package with its routes and tests, the core/api model, the client repository and screen for it): cmp-backend (only when server/ exists). The server's check, :server:build (its tests and detekt), is a cmp-gates gate when server/ exists.
  • Run the gates (after a screen or module, before saying you are done): cmp-gates; it returns a short report and fixes only mechanical failures
  • A failure cmp-gates left open, or when and how to build: cmp-verify
  • The owner asks for a commit: cmp-commit (follow its steps even if it is not auto-loaded)

Rules that break the app most often

  1. @KoinViewModel is imported from org.koin.android.annotation, never org.koin.core.annotation.
  2. No java.*, android.*, String.format or System.* in commonMain; the iOS compile fails.
  3. DTOs and database entities stay in data; domain and presentation never see them.
  4. No @Suppress, baseline files or disabled rules to make a gate pass.
  5. Do not touch the Gradle wrapper, the Kotlin/AGP versions or the build-logic plugin wiring.
  6. Every module with composeResources (fonts, strings, sounds, drawables) needs androidResources.enable = true in its Android block: kotlin { extensions.configure<KotlinMultiplatformAndroidLibraryExtension> { androidResources.enable = true } } (full example in cmp-feature, references/screen.md). Without it the Android APK ships without those files while every gate stays green.
  7. Every name in the code is English: modules, packages, classes, files, string keys — whatever language the request or the UI is in.
  8. Database (only if core/room exists): add a table to the existing AppDatabase, never a second one: entity, DAO, the entities list and a @Single DAO provider. Commit core/room/schemas/; changing a table means bumping version and adding a migration.
  9. Log with Kermit: private val log = Logger.withTag("Feature"), then log.d { } / log.w(e) { }. Never println (detekt does not catch it here) and never log tokens, bodies or user data.
  10. Ask for a review only through ReviewPrompter (system dialog). No "Do you like the app?" question, no rating screen of your own, no request at launch or mid-task; keep ReviewRequestEffect() in MainScreen.kt.
  11. Keep iosApp/iosApp/PrivacyInfo.xcprivacy in step with the code: a new Kotlin or Swift use of UserDefaults, file dates, disk space or boot time, or new data collection, is declared there.
  12. After DataError.Network, retry on ConnectivityMonitor.reconnections(); keep OfflineBanner and AppUpdateEffect() in MainScreen.kt; no second connectivity or update library.
  13. Images load with Coil only (no Kamel, no second image library); network images need the network module.
  14. Links go through DeepLinkHandler and NavigationManager: no navDeepLink, no second link library; keep handleDeepLink in MainActivity and onOpenURL in iOSApp.swift.

How to work

  • Read the existing code before writing; the project's working code wins over any guide.
  • Change only what the task needs. Do not create README or documentation files unless asked.
  • In a headless run (claude -p) never ask questions: choose the reasonable option and list it under Assumptions in your final message.
  • Never push. Commit only when the owner asks.
  • Code, comments and commit messages are in English; talk to the owner in their language.

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.