meet-miyani/compose-skill/compose-project

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

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" sets it. A chat preference applies to the current task, and the agent offers to record it.
10. [Default] Guards run in CI on every change through the `run-checks.sh` registry, never around it. The CI job calls the registry; agent hooks call the registry before finishing a Compose change. The exact job shape follows the project's forge; what never changes is registry-first ordering.

Version gates: read gradle/libs.versions.toml before writing. If AGP is below 9, stop and report instead of applying the AGP 9 shape. If Kotlin is below 2.3.20, stop and report instead of applying the Koin compiler plugin. If Kotlin is above the highest version the installed SKIE supports, stop and report instead of adding SKIE.

Workflow

• [ ] Create one todo per step below and do them in order.
• [ ] State which of the four workflows this task is: bootstrap, adopt-existing, add-module, or CI/hooks. Follow only that checklist; the checklists link instead of repeating each other.

Bootstrap a new project

• [ ] Pick the target shape from the decision table (CMP app vs Android-only).
• [ ] Lay out the kit skeleton from templates/project/: root settings, root build file, gradle.properties, gradle/libs.versions.toml, build-logic/, :core:mvi and :core:error from the compose-architecture templates, :core:designsystem, :feature:notes, the composition root (:composeApp plus :androidApp on CMP, :app on Android-only). A :data:<domain> module joins only when a second feature needs the same data (see bootstrap.md).
• [ ] Install the guards with install-guards.sh; register every module in .composekit.conf and document every key where setup is explained (see bootstrap.md). UI_MODEL stays when-needed unless the project records always.
• [ ] Create the project's ## Project decisions section in AGENTS.md/CLAUDE.md (see bootstrap.md); add the one-line kit-activation pointer from enforcement.md.
• [ ] Build the first feature with the compose-feature scaffold, never by hand-copying an old screen.
• [ ] Run the Verification gates below.

Adopt the kit in an existing project

• [ ] Run scripts/audit-project.sh and produce the gap report from adopt-existing.md. Classify the project as existing-project case 1, 2, or 3 (defined in the compose-architecture skill).
• [ ] Say no to a full rewrite inside the change at hand when the project is coherent (case 2). Propose migration as a separate task.
• [ ] Plan incrementally: guards first in WARN mode, then convention plugins, then the base contract for new features only.
• [ ] Create ## Project decisions for every deviation the project keeps, with the reason stated once.
• [ ] Run the Verification gates below.

Add or extract a module

• [ ] Apply the owning convention plugin; the module file holds the plugin alias plus namespace plus dependencies, nothing else.
• [ ] Declare dependencies through type-safe project accessors; use api() only per rule 2.
• [ ] Register the module in .composekit.conf and run run-checks.sh.
• [ ] Register the new module's Koin module in the composition root. Prevents: a compiled module with unresolved runtime bindings.
• [ ] When extracting from the composition root, delete the root slice in the same change.

Wire CI and agent hooks

• [ ] The CI job calls scripts/composekit/run-checks.sh (the registry), never individual checks. New checks join as one registry line.
• [ ] Agent hooks (Claude Code / OpenCode / Cursor) run the registry before finishing a Compose change. Print the snippets with install-guards.sh; never write them into the user's config without consent.
• [ ] Activate the kit: the one-line pointer plus the optional SessionStart hook from enforcement.md.

Decision tables

Target shape

AGP plugin shape (read the AGP version first)

Adopt incrementally (existing-project case → plan; cases live in the compose-architecture skill)

Red flags

Verification