Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Design & UI

kotlin-project-architecture-review

Use when reviewing KMP architecture, feature proposals, PR structure, layer boundaries, state-holder design, Android entry-point discipline, source-set placement, modularization, and long-term maintainability in Kotlin Multiplatform / Compose Multiplatform projects.

mmiani · AI review on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add mmiani/kotlin-kmp-claude-agent-skills --skill kotlin-project-architecture-review

About this skill


name: kotlin-project-architecture-review description: Use when reviewing KMP architecture, feature proposals, PR structure, layer boundaries, state-holder design, Android entry-point discipline, source-set placement, modularization, and long-term maintainability in Kotlin Multiplatform / Compose Multiplatform projects. allowed-tools: Read, Grep, Glob license: Apache-2.0 metadata: author: Mariano Miani version: "4.1.0"

Kotlin Multiplatform Architecture Review

Use this skill to review architecture decisions, feature plans, pull requests, migrations, and refactors in a Kotlin Multiplatform project.

This skill is architecture-review only. It evaluates structural fit, ownership, boundaries, layering, source-set placement, Android entry-point discipline, resilience, security/privacy boundaries, rollout safety, and long-term maintainability.

It does not perform detailed implementation-level code review for Compose recomposition, coroutine misuse, static-analysis details, line-by-line refactoring, or file-level style issues. For that, use kotlin-project-code-review.

This skill is intentionally strict. Its purpose is to protect maintainability, correctness of shared code placement, clean boundaries between layers, realistic ownership of state and data, Android entry-point discipline, safe trust boundaries, diagnosability, rollout resilience, and long-term scalability.


Primary review goals

The review should validate whether the proposal:

  • preserves a clear single source of truth for important data
  • follows unidirectional data flow
  • uses a proper UI state production pipeline
  • keeps Android components as platform entry points rather than business-logic containers
  • places business logic in the right layer
  • uses the domain layer only when it adds real value
  • keeps repositories and data sources responsible for data ownership concerns
  • uses source sets correctly in KMP
  • preserves modular boundaries and avoids accidental coupling
  • keeps platform-specific behavior at the edges
  • remains testable and understandable as the codebase grows
  • is resilient to partial backend data, evolving schemas, and phased rollouts
  • does not introduce architectural security or privacy weaknesses
  • preserves diagnosability for important flows
  • does not over-couple features, modules, or targets in ways that will slow future evolution

Do not optimize for theoretical purity alone.

Optimize for:

  • maintainability
  • correctness
  • consistency
  • architectural clarity
  • safe evolution
  • production resilience

Official architecture defaults to review against

Unless the project has a strong, deliberate reason not to, prefer these defaults:

  • Single source of truth for each important data type
  • Unidirectional data flow
  • UI driven from data models
  • State holders for UI complexity
  • ViewModels or equivalent state holders such as presenters, reducers, or state machines exposing UI state and receiving user actions
  • Coroutines and Flow for async work and observable state
  • Clear separation of UI, domain, data, and platform integration
  • Domain layer only when business logic is complex or reused
  • Repositories as the main boundary for exposing and coordinating app data
  • Android components treated as lifecycle-bound entry points, not as general-purpose business-logic containers
  • Platform-specific behavior isolated at the edges
  • Transport, persistence, and external SDK details hidden behind stable boundaries
  • Defensive handling of partial data, unknown values, and rollout skew
  • Observability designed into high-risk flows
  • Minimal, explicit trust boundaries for auth/session/admin or privileged behavior

What this skill should review

Use this skill for:

  • feature architecture proposals
  • source-set and shared-vs-platform placement decisions
  • module extraction or consolidation decisions
  • state-holder strategy decisions
  • navigation architecture changes
  • deep link / intent / manifest surface changes
  • SSOT ownership decisions
  • repository/domain boundary design
  • Android entry-point ownership and delegation
  • cross-feature coordination and modularization
  • persistence/source-of-truth architecture
  • architecture-level security/privacy and rollout concerns
  • PRs that introduce structural changes rather than only local implementation changes

Use kotlin-project-code-review instead when the main question is whether implemented code is clean, safe, performant, and consistent within an already chosen architecture.


Review dimensions

The 22 review dimensions and their check/flag criteria live in this skill's reference/ folder. Read only the files that match the proposal under review; do not load them all by default.

FileCovers
reference/dimensions-core.md1-10: Single source of truth; Unidirectional data flow; Android component entry-point discipline; UI layer responsibilities; State-holder quality; Domain layer usage; Data layer responsibilities; Failure model; Layering and separation of concerns; Dependency boundaries and lifetime
reference/dimensions-kmp-modularity.md11-15: Source-set correctness in KMP; Shared vs platform-specific boundary quality; Module boundaries and modularization quality; Navigation and Android component interaction; Manifest and exported-surface review
reference/dimensions-resilience.md16-22: Security and privacy architecture; Responsiveness and configuration resilience; Resources and presentation boundaries; Observability and diagnosability; Backward compatibility, migration, and rollout safety; Testability; Architecture consistency with existing project patterns

If a dimension is relevant and you have not read its reference file, read it before judging that dimension. Do not infer a rule you have not read.

Severity framework

High severity

Likely to cause architectur

Read the complete source ↗