agentleFS
whinstudiowhinstudio/skills/cmp-feature/SKILL.md

cmp-feature

Skill0 starsChanged 3 days agoMITView on GitHub

Use when adding a new screen, feature module or data source to this Compose Multiplatform app — creating or filling feature/<name> with contract, domain, data and presentation layers, a new ViewModel with Route and Content, a repository backed by Ktor, Room or DataStore, a navigation destination, or the Koin wiring for any of these.

The file

We split this skill into the rules it gives an agent

11 rules. About 0 are common, 2 are distinctive, and 9 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 9

    Very specific

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

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

    Look in settings.gradle.kts first.

    line 16
  2. Distinctive:

    When Compass started this run, its prompt names the module to use.

    line 24
  3. Very specific:

    Every module's @Module @ComponentScan classes are registered in appModules() in initKoin.kt (older projects: in the buildList inside …

    line 70
  4. Very specific:

    Not every layer needs code.

    line 76
  5. Very specific:

    Before deleting GuideScreen.kt, keep what the stores require, which it used to reach:

    line 101
  6. Very specific:

    Only when core/network exists.

    line 149
  7. Very specific:

    Only when the app needs local storage.

    line 161
  8. Distinctive:

    Before the first release, schema version 1 may change freely.

    line 168
  9. Very specific:

    No DTO or entity appears in domain or presentation.

    line 191
  10. Very specific:

    Write the files with Write and Edit.

    line 197
  11. Very specific:

    Do not ask which layers to create.

    line 199

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill 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
SKILL.md

Adding a screen or a feature

This project uses one Gradle module per layer: feature/<name>/{contract,domain,data,presentation}. The code rules for what goes inside the files are in cmp-code-rules.

1. Decide where it goes

  • Something with its own data and its own destination is a feature module. A screen that only shows another view of an existing feature's data goes into that feature's presentation.
  • Look in settings.gradle.kts first. The generator may already have created the module. From the template release with the blank guide screen on, every planned feature is a complete module: contract/Screens.kt (<Name>Destination), presentation with <Name>Screen (Route + Screen), <Name>UiState, <Name>Actions, <Name>ViewModel, <Name>Provider and <Name>Entry, and an empty @Module in data and domain — all three registered in appModules(). Projects generated before that have starter files only in the first planned feature and empty shells (four build.gradle.kts, no sources) for the rest. Fill an existing module; do not create a parallel one.
  • When Compass started this run, its prompt names the module to use. Follow it.

2. Inspect before writing

  • The four build.gradle.kts files of the existing feature: which convention plugin each applies (libs.plugins.feature.<layer>.plugin) and which project dependencies it declares.
  • The package root, read from contract/Screens.kt.
  • The Koin module class(es) under */di/ and their lines in shared/.../di/initKoin.kt.
  • shared/.../MainScreen.kt: the start destination and how navigation providers are collected.
  • Which core/* modules exist (logging, network, database, presentation, designsystem, multilang); the sections below apply only to what is there.

3. Skeleton

Full tree, build files and the checklist for a brand-new module: references/layout.md.

feature/<name>/contract/      Screens.kt: destinations (@Serializable, NavigationCommand.Destination)
feature/<name>/domain/        model/, repository/<Name>Repository.kt, usecase/ (@Factory), di/<Name>DomainModule.kt
feature/<name>/data/          repository/<Name>RepositoryImpl.kt (@Single(binds = ...)), model/ (DTOs), mapper/, di/<Name>DataModule.kt
feature/<name>/presentation/  ui/<Name>Screen.kt (Route + Content), ui/<Name>ViewModel.kt, ui/<Name>UiState.kt,
                              ui/<Name>Actions.kt, ui/<Name>TestTags.kt, di/<Name>PresentationModule.kt,
                              navigation/<Name>Provider.kt, navigation/<Name>Entry.kt

On a blank app, <Name>Entry (a FeatureEntry) puts a button for the module on GuideScreen, which opens the module's destination. GuideScreen is a developer placeholder the app opens on until you replace it (section 4), not a screen of the app. Projects generated before the blank guide screen release have no <Name>Entry and no FeatureEntry.

From the deep link template release on, every generated module also has presentation/navigation/<Name>DeepLink.kt: a DeepLinkRoute (core/navigation) with @Single(binds = [DeepLinkRoute::class]), @Named("<Name>DeepLink") and pattern = "<name>", so <scheme>://<name> (scheme = project name in lower case) opens the module's destination. To link to a screen with an argument, set pattern = "<name>/{id}" and return the destination from fun destination(arguments: Map<String, String>): NavigationCommand.Destination? (arguments["id"]); return null for a missing or invalid value, and the link only opens the app. Validate the argument (a link is user input). Do not use navDeepLink; links go through DeepLinkHandler and NavigationManager.

  • Packages follow the generated files: <rootPackage>.feature.<name>.<layer> (projects generated before the blank guide screen release: <rootPackage>.<name>.<layer>) plus the sub-package (...feature.<name>.presentation.ui), all lowercase. Copy the root from Screens.kt; do not invent one.
  • A new module is added to settings.gradle.kts (include(":feature:<name>:<layer>")) and to the commonMain dependencies of shared/build.gradle.kts (implementation(projects.feature.<name>.<layer>)).
  • Every module's @Module @ComponentScan classes are registered in appModules() in initKoin.kt (older projects: in the buildList inside initKoin). New projects already have presentation, data and domain registered; in older ones add the data and domain modules when those layers get classes.
  • Dependencies point inward: presentation → domain, presentation → contract, data → domain. Another feature is reached only through its contract.
  • Not every layer needs code. A screen with no data of its own leaves domain and data empty; leave a generated empty module as it is, and do not create one you do not need.

4. Navigation

This template navigates through Koin-registered graph providers and a NavigationManager, not through callbacks or a passed-down NavController.

  • Destinations live in contract/Screens.kt: @Serializable data object XDestination or @Serializable data class XDestination(val id: String), both implementing NavigationCommand.Destination. Arguments are simple values such as ids, never whole objects.
  • The feature's presentation/navigation/<Name>Provider.kt implements NavGraphProvider and registers composable<XDestination> { XRoute() } for each destination. MainScreen collects every provider from Koin, so a new destination needs no edit in shared. Only the start destination is set in MainScreen.kt.
  • A blank app generated from the blank guide screen release on starts at GuideDestination, the developer placeholder. When you build the app, point the start destination in shared/.../MainScreen.kt at the app's first destination (shared already depends on every feature's contract): the start value, which with the backend is the argument of rememberSessionStart(GuideDestination, …) (the sign-in gate returns there after sign-in). Then delete GuideScreen.kt and, in MainScreen.kt, the composable<GuideDestination> { ... } block, the entries and uriHandler lines and the imports they leave unused. Do not delete the ReviewRequestEffect() line in MainScreen.kt; it passes in-app review requests on. The About dialog on GuideScreen goes with it; core/about stays (its licences screen and the legal URLs are still used). The <Name>Entry classes may stay or go.
  • Before deleting GuideScreen.kt, keep what the stores require, which it used to reach:
    • With the backend (feature/account exists): a way from the app's own screens (a settings or profile entry) to AccountSettingsDestination. It holds account deletion and the privacy and terms links; App Store and Google Play reject an app with accounts but no in-app deletion. Reference AccountSettingsDestination directly; the FeatureEntry list GuideScreen showed does not count.
    • With insights (core/insights exists): keep InsightsConsentDialog in MainScreen.kt and put InsightsConsentSettings (the analytics and crash report switches) in the app's own settings screen; GuideScreen's About dialog held them.
    • Without the backend: show the privacy and terms links (AppInfo.legalLinks from core/about) on the app's own settings or about screen; GuideScreen's About dialog held them, and the App Store requires an in-app privacy policy link.
    • Fill PRIVACY_POLICY_URL and TERMS_URL in core/about/.../LegalUrls.kt; while they are empty the links stay hidden.
  • The ViewModel navigates with the injected NavigationManager: NavigationCommand.NavigateTo(XDestination(id)), NavigateUp, PopBackStackTo(...).
  • The ViewModel reads its arguments from SavedStateHandle by name: private val id: String = checkNotNull(savedStateHandle[XDestination::id.name]) { "id missing" }. toRoute<XDestination>() works in the app but fails the JVM host test (Bundle not mocked); it stays for custom NavType arguments. Details: references/screen.md.
  • To open another feature's screen, the presentation module depends on that feature's contract (implementation(projects.feature.<other>.contract)).

5. Presentation

Code shapes, imports and test tags: references/screen.md.

  • The generated ui/<Name>Screen.kt is a placeholder screen (a Route and a private <Name>Screen with a Back button). Replace its content with the real Route and Content, and make the provider call the Route.
  • The Route (internal) takes the ViewModel from koinViewModel() and collects state. The Content (private) is stateless and draws loading, empty, error and content.
  • The screen root and every interactive element get a Modifier.testTag(...) from constants in <Name>TestTags; cmp-maestro builds the walkthrough on these tags.
  • A module that gets src/commonMain/composeResources/ (strings, drawables, fonts) must also enable Android resources in its build file (references/screen.md, "Resources"). Without it both gates stay green, but the files are left out of the APK and the app fails on Android.
  • Previews: none in commonMain (see references/screen.md for the Android-only option).

6. Data

Details: references/data.md. The repository interface lives in domain, the implementation in data. Reads are Flow<T> or suspend functions; failures come back typed. Mappers are extension functions (fun XDto.toDomain(): X) that do not change their input. No silent fallbacks.

7. Network

Only when core/network exists. Details: references/network.md.

  • Reuse the HttpClient from core/network's NetworkModule; never build a second client. The platform engines stay as the template set them.
  • DTOs are @Serializable; the client already ignores unknown keys.
  • The base URL is set in core/network's ApiConfig.kt (debug and release; older projects: NetworkModule).
  • Network failures become typed errors in data.
  • An API that needs a key is never written into source. If no key-free public API fits, use fake data and say so in your summary.

8. Persistence

Only when the app needs local storage. Details: references/persistence.md.

  • DataStore already exists in core/database when the project was generated with it; reuse the single instance from Koin.
  • Room is not in the template. Add it to core/database the way references/persistence.md describes; the Room compiler generates the database constructor's actuals.
  • DAOs read with Flow and write with suspend. Entities do not leave core/database and data.
  • Before the first release, schema version 1 may change freely. After a release every schema change needs a migration; no destructive fallback.

9. Koin

Details and runtime diagnosis: references/koin.md.

  • Annotations and imports: cmp-code-rules, section 6.
  • A class is only resolvable if its Gradle module is on shared's dependency list and its @Module is registered in initKoin.kt.
  • A dependency provided by another Gradle module is marked @Provided (or that module is included), or KSP stops with Unreachable definition.
  • A dependency cycle (A needs B, B needs A) is reported, not hidden.
  • The template turns on Koin's compile-time check in KSP. Keep it on.
  • NoDefinitionFoundException at runtime: go through the order in references/koin.md.

Done when

  • New modules are in settings.gradle.kts and shared/build.gradle.kts, and every new @Module class is in initKoin.kt.
  • Each new destination is registered by a provider and reachable: something navigates to it, or it is the start destination. A GuideScreen button does not count for an app you ship: that app starts at its own first destination, not at GuideDestination (section 4).
  • No DTO or entity appears in domain or presentation.
  • The screen's <Name>TestTags exist and are applied.
  • The Android gate is green (cmp-gates android); the iOS gate runs on the schedule in cmp-verify, section 2.

Headless runs

  • Write the files with Write and Edit. Run the Android gate (cmp-gates android) once the screen or module's files are in place, not after every file and not only at the end (cmp-verify, section 2).
  • Do not ask which layers to create. Choose by need and list the choice under Assumptions in your final message.

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.