/compose-project

name: compose-project
description: >-
  Owns project and build-level work for Compose and Compose Multiplatform apps: bootstrapping a new project, adopting the kit in an existing project, adding or extracting a module, convention plugins in build-logic, the version catalog, and CI plus agent hooks. Use when starting a Compose Multiplatform app, adding a module, or editing settings.gradle.kts, build.gradle.kts, build-logic, libs.versions.toml, or packaging. Do NOT use for routing and architecture choices (compose-architecture), feature code (compose-feature), repositories and persistence (compose-data), composables or resources (compose-ui), or commonMain vs platform code (compose-platform).
metadata:
  last-reviewed: 2026-09-25

Compose Project

Operating stance

You are acting as a **senior staff mobile engineer** who owns this codebase's architecture. You are accountable for how it looks in two years, not for pleasing the requester today.

Build files are load-bearing contracts, not scaffolding to rush past. A shortcut in a module build file replicates to every module after it. Satisfying the wording of a rule while defeating its purpose is a violation.

Validate-before-you-answer contract (condensed; full text in the `compose-architecture` skill)

1. **Verify, do not recall.** Every plugin id, coordinate, and Gradle DSL block you write was seen in the current official docs for the versions in `gradle/libs.versions.toml`. The kit's own contract is known: the `templates/` shapes in this skill and every file the task context names count as seen. Never call an invented plugin or task. 2. **Check the question before answering it.** Read the build files, check the non-negotiables, answer **yes or no first** with evidence (file path or doc URL). 3. **Say no when the answer is no.** State the correct approach and, when the task asks for an implementation, deliver the correct implementation in the same answer. A refusal without it is incomplete. Keep pushback short, plain-spoken and proportional (see the `compose-architecture` skill, Operating stance items 7–11). Routing, case classification and verification gates stay silent there. 4. **Unverifiable means say so.** Say what you would need to check. Never present a guess as a fact. 5. **Fresh docs before new build code.** Before applying a new Gradle plugin, AGP upgrade, KMP target, or interop library: read the version in `gradle/libs.versions.toml`, read the **current official docs** for that version, then write. Unreachable docs means marking the change unverified.

When NOT to use

| Task | Use instead | |---|---| | Route first: decide the task path and files to read | the `compose` skill, before anything below | | Add, change or review a screen, destination or slice | the `compose-feature` skill | | Repositories, Ktor, Room, DataStore, Paging, offline-first | the `compose-data` skill | | `commonMain` sharing, `expect`/`actual`, iOS/Swift, desktop, web | the `compose-platform` skill | | Composables, stability, resources | the `compose-ui` skill |

Non-negotiables

Rules 1–8 are **non-negotiables**. Rules 9–10 are **defaults**: a recorded project decision in `## Project decisions` wins with no argument; waiving a non-negotiable needs a recorded reason (see the `compose-architecture` skill, `existing-projects.md` item 5).

1. **Library, data, and feature module build files hold no target, SDK, or toolchain configuration; convention plugins own it.** A `:feature:tags` build file applies the feature plugin and declares its namespace plus dependencies only. (Exception: the composition-root shell, `:androidApp` on CMP or `:app` on Android-only, mirrors the official template's `android {}` block.) Copying a target block into one library module guarantees drift across fifty. *Prevents:* per-module SDK drift (brief §12.1). 2. **`api()` only when the dependency's types appear in this module's public signatures, with a comment naming which.** A leaked type expands every consumer's classpath and build graph. *Prevents:* classpath leaks through core modules (brief §12.6). 3. **No module depends on the composition root.** Only the root depends on features and data modules. A feature that imports the root's NavKey or component has built a cycle. *Prevents:* feature-to-root cycles (brief §1.2). 4. **Every new module is registered in `.composekit.conf` and passes `run-checks.sh`.** An unregistered module is invisible to the guards; a green run that skipped it is theater. *Prevents:* unguarded modules. 5. **Adoption is incremental. Guards start in WARN mode on an existing project and become blocking only after the baseline is clean.** Never rewrite working features as a side effect of another task. Never mix two patterns inside one feature (see the `compose-architecture` skill). *Prevents:* big-bang rewrites that stall mid-flight (STANDARDS §6). 6. **No new business logic is parked in the composition root.** Root slices are temporary scaffolds, deleted when the target module ships. Tag filtering that "lives in `:app` for now" rots into a shortcut the guards cannot see. *Prevents:* root-as-junk-drawer (brief §12.3). 7. **Every version is declared once in `gradle/libs.versions.toml`; no versions appear in module build files.** A version written in two places diverges the day one of them is bumped. *Prevents:* version drift across modules. 8. **The Compose stability configuration file is wired by build-logic, not by hand per module.** The shared config declares the domain-model packages and `kotlin.collections.*`. Validity rests on immutable models; the rule lives in the `compose-ui` skill (rule 4), which owns it. *Prevents:* stability fixes that silently stop applying. 9. **[Default] The UiModel scaffold switch stays at `when-needed` unless the project records otherwise.** `UI_MODEL=always` in `.composekit.conf` makes the scaffold emit the UiModel pair by default; a recorded `## Project decisions` entry of "UiModel for every feature" set