---
name: mobile-modern-clean-architecture
description: Modern clean architecture workflow for Android (Kotlin, Compose/XML, coroutines) and Flutter (Dart, widget/state architecture). Use when designing new features, refactoring legacy modules, auditing code quality, or upgrading architecture and async patterns with low-risk, incremental changes.
---

# Mobile Modern Clean Architecture

## Overview
Audit and improve Android/Flutter projects using modern architecture boundaries, coroutine/async safety, and compact maintainable code patterns. Default to stability-first behavior and skip risky modernization when evidence is insufficient.

## Safety Mode (Default)
- Default mode is `SAFE`.
- In `SAFE` mode, do only low-risk, incremental changes with clear rollback.
- If stability confidence is below threshold, output `NO-CHANGE` and provide a safer next step instead of patching.
- Use `safe-refactor-guard` rules as mandatory constraints unless user explicitly requests broader refactor.

## Workflow

1. Snapshot current state
- Run `scripts/mobile_modern_snapshot.sh <repo_root>`.
- Identify platform stacks, dependency/toolchain markers, and large-risk files.

2. Apply architecture lane
- Android lane: UI -> state holder (ViewModel) -> use case/domain -> repository -> data source.
- Flutter lane: presentation -> application/state -> domain -> data/infrastructure.
- Keep boundaries explicit; avoid mixing UI, business rules, and transport models.

3. Enforce modern async rules
- Kotlin coroutines: structured concurrency, dispatcher injection, cancellation-safe flows, immutable state exposure.
- Flutter async: isolate heavy work from UI thread, explicit error/loading handling, repository boundaries for IO.

4. Run stability gate before patching
- Required confidence checks:
  - behavior impact is understood,
  - verification command exists,
  - rollback path is obvious,
  - touched files are minimal and local.
- If any check fails, do not patch; return `NO-CHANGE`.

5. Plan incremental modernization
- Prefer thin slices over big rewrites.
- Tackle highest-risk hotspots first (very large files, unstable async paths, boundary violations).
- Keep each patch reviewable and reversible.

6. Verify and report
- Map each proposed change to verification (unit tests, state/flow checks, UI smoke checks).
- Return prioritized roadmap with effort and risk.

## Android Rules
- Use immutable UI state models (`StateFlow`/single source of truth).
- Keep ViewModels orchestration-focused, not data-transport heavy.
- Keep DTO/network models out of UI/domain APIs.
- Avoid `GlobalScope`; prefer lifecycle/owner scopes.

## Flutter Rules
- Keep widgets focused on presentation; business logic in controllers/blocs/notifiers/use-cases.
- Prefer feature-first module grouping for scale.
- Keep async side effects behind repository/services.
- Split oversized widget files into cohesive components.

## Output Format
Use this structure:

```markdown
# Modernization Report

## Safety Decision
- GO-SAFE | NO-CHANGE
- Confidence:
- Reason:

## Current State
- Android findings:
- Flutter findings:

## Top Risks
1. ...

## Priority Plan
1. [Now] ...
2. [Next] ...
3. [Later] ...

## Minimal Patch Scope
- Files:
- Boundary preserved:

## Verification
- Commands:
- Expected signals:
```

## Guardrails
- No architecture rewrite unless requested.
- No module/file moves or renames in safe mode.
- No dependency upgrades in safe mode unless user explicitly asks and compatibility evidence is shown.
- No public API contract changes in safe mode.
- No unverified async refactors.
- Keep changes compact and evidence-backed.
- Max patch scope in safe mode: one feature/module at a time.

## Resources
- `scripts/mobile_modern_snapshot.sh`
- `references/android-modern-checklist.md`
- `references/flutter-modern-checklist.md`
- `references/stability-gate.md`