kotlin-project-architecture-review
starsforks
How to install kotlin-project-architecture-review?
mmiani/kotlin-kmp-claude-agent-skills/kotlin-project-architecture-review
$npx -y skills add mmiani/kotlin-kmp-claude-agent-skills --skill kotlin-project-architecture-reviewUse 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.
SKILL.md
| 1 | # Kotlin Multiplatform Architecture Review |
| 2 | |
| 3 | Use this skill to review architecture decisions, feature plans, pull requests, migrations, and refactors in a Kotlin Multiplatform project. |
| 4 | |
| 5 | 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. |
| 6 | |
| 7 | 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`. |
| 8 | |
| 9 | 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. |
| 10 | |
| 11 | --- |
| 12 | |
| 13 | ## Primary review goals |
| 14 | |
| 15 | The review should validate whether the proposal: |
| 16 | |
| 17 | - preserves a clear single source of truth for important data |
| 18 | - follows unidirectional data flow |
| 19 | - uses a proper UI state production pipeline |
| 20 | - keeps Android components as platform entry points rather than business-logic containers |
| 21 | - places business logic in the right layer |
| 22 | - uses the domain layer only when it adds real value |
| 23 | - keeps repositories and data sources responsible for data ownership concerns |
| 24 | - uses source sets correctly in KMP |
| 25 | - preserves modular boundaries and avoids accidental coupling |
| 26 | - keeps platform-specific behavior at the edges |
| 27 | - remains testable and understandable as the codebase grows |
| 28 | - is resilient to partial backend data, evolving schemas, and phased rollouts |
| 29 | - does not introduce architectural security or privacy weaknesses |
| 30 | - preserves diagnosability for important flows |
| 31 | - does not over-couple features, modules, or targets in ways that will slow future evolution |
| 32 | |
| 33 | Do not optimize for theoretical purity alone. |
| 34 | |
| 35 | Optimize for: |
| 36 | - maintainability |
| 37 | - correctness |
| 38 | - consistency |
| 39 | - architectural clarity |
| 40 | - safe evolution |
| 41 | - production resilience |
| 42 | |
| 43 | --- |
| 44 | |
| 45 | ## Official architecture defaults to review against |
| 46 | |
| 47 | Unless the project has a strong, deliberate reason not to, prefer these defaults: |
| 48 | |
| 49 | - Single source of truth for each important data type |
| 50 | - Unidirectional data flow |
| 51 | - UI driven from data models |
| 52 | - State holders for UI complexity |
| 53 | - ViewModels or equivalent state holders such as presenters, reducers, or state machines exposing UI state and receiving user actions |
| 54 | - Coroutines and Flow for async work and observable state |
| 55 | - Clear separation of UI, domain, data, and platform integration |
| 56 | - Domain layer only when business logic is complex or reused |
| 57 | - Repositories as the main boundary for exposing and coordinating app data |
| 58 | - Android components treated as lifecycle-bound entry points, not as general-purpose business-logic containers |
| 59 | - Platform-specific behavior isolated at the edges |
| 60 | - Transport, persistence, and external SDK details hidden behind stable boundaries |
| 61 | - Defensive handling of partial data, unknown values, and rollout skew |
| 62 | - Observability designed into high-risk flows |
| 63 | - Minimal, explicit trust boundaries for auth/session/admin or privileged behavior |
| 64 | |
| 65 | --- |
| 66 | |
| 67 | ## What this skill should review |
| 68 | |
| 69 | Use this skill for: |
| 70 | - feature architecture proposals |
| 71 | - source-set and shared-vs-platform placement decisions |
| 72 | - module extraction or consolidation decisions |
| 73 | - state-holder strategy decisions |
| 74 | - navigation architecture changes |
| 75 | - deep link / intent / manifest surface changes |
| 76 | - SSOT ownership decisions |
| 77 | - repository/domain boundary design |
| 78 | - Android entry-point ownership and delegation |
| 79 | - cross-feature coordination and modularization |
| 80 | - persistence/source-of-truth architecture |
| 81 | - architecture-level security/privacy and rollout concerns |
| 82 | - PRs that introduce structural changes rather than only local implementation changes |
| 83 | |
| 84 | 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. |
| 85 | |
| 86 | --- |
| 87 | |
| 88 | ## Review dimensions |
| 89 | |
| 90 | ### 1. Single source of truth |
| 91 | |
| 92 | Check whether every important piece of data has one clear owner. |
| 93 | |
| 94 | Questions: |
| 95 | - What is the source of truth for this data? |
| 96 | - Is there more than one writable owner? |
| 97 | - Is UI holding durable app truth that should live lower? |
| 98 | - Is repository ownership explicit? |
| 99 | - In offline-first or cache-backed flows, is local persistence treated as source of truth when appropriate? |
| 100 | - Is there a coherent ownership strategy across app memory, persistence, network, and UI? |
People who liked this also viewed
6 picksType
- requesting-code-reviewUse when completing tasks, implementing major features, or before merging to verify work meets requirementsSkillsJul 2026
- code-reviewSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026
- receiving-code-reviewUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performativeSkillsJul 2026
- baoyu-format-markdownFormats plain text or markdown files with frontmatter, titles, summaries, headings, bold, lists, and code blocks. Use when user asks to "format markdown", "beautify article", "add formatting", or imprSkillsJul 2026
- code-review-excellenceMaster effective code review practices to provide constructive feedback, catch bugs early, and foster knowledge sharing while maintaining team morale. Use when reviewing pull requests, establishing reSkillsJul 2026
- code-review-and-qualityConducts multi-axis code review. Use before merging any change. Use when reviewing code written by yourself, another agent, or a human. Use when you need to assess code quality across multiple dimensiSkillsJul 2026
