@architecture-rules.md @rules/project-structure.md @rules/routing-and-navigation.md @rules/data-state-and-boundaries.md @rules/native-platform-and-security.md @references/official/flutter-dart-2026-11-04.md @rules/testing-and-validation.md
Flutter ArchitectureCreate and enforce scalable Flutter + Dart architecture for Android and iOS while separating official framework behavior from Hypercore conventions.
<output_language>
Default user-facing deliverables, reports, plans, handoff notes, and validation notes to Korean. Preserve code identifiers, commands, paths, schema keys, package names, API names, and source excerpts in their required language.
</output_language>
- Bootstrap or refactor Flutter applications around the official MVVM layering, one router configuration, strict analyzer settings, and explicit feature boundaries.
- Keep views thin, screen state in the paired view model, and the data layer behind a one-way dependency direction that survives growth.
- Protect secrets, permissions, signing, native configuration, storage, and Android/iOS divergence with explicit gates instead of inherited assumptions.
- Validate architecture against the installed Flutter and Dart toolchain and project evidence before applying current official guidance, without imposing a state library.
<routing_rule>
Use this skill for architecture setup, implementation, review, or remediation in Flutter apps whose primary targets are Android and iOS, with web and desktop included only when the project declares them.
Do not use it for bare Dart command-line tools or servers, standalone package or plugin development, React Native or Expo apps, web-only projects that are not Flutter, a single visual change with no architecture impact, deployment-only work, or documentation-only summaries. For brownfield apps, preserve working project conventions unless the user requests migration or a safety/correctness issue requires change.
</routing_rule>
<instruction_contract>
| Field | Contract |
|---|---|
| Intent | Produce a scalable, testable Flutter architecture whose view, view-model, data, native, and platform boundaries remain understandable as the app grows. |
| Trigger | Flutter/Dart work involving app setup, folder structure, routing and deep links, state/data flow, native configuration, platform divergence, testing, or architecture review. |
| Scope | Touched Dart source, route table, feature/shared modules, pubspec.yaml, analyzer configuration, tests, and architecture validation notes. Regenerating native directories, replacing dependencies, signing, and store actions require explicit scope. |
| Authority | User and project instructions outrank this skill. The installed toolchain and project configuration control project behavior. Official Flutter, Dart, and package documentation control API facts; Hypercore conventions are recommendations unless the project adopts them. |
| Evidence | Inspect pubspec.yaml, analysis_options.yaml, lib/ entry points, the router configuration, ios/ and android/, existing tests, the lockfile or pub workspace, and flutter --version first. Use the dated official reference when version drift decides the change. |
| Tools | Use capability-based inspect/read/search/edit/execute. Validate commands and paths. Gate network installs, credentials, signing, store publication, project-wide generators, and build hooks that download or execute binaries. |
| Loop | Use a bounded verify-repair loop: run the relevant checks, repair only observed failures, and stop after two repair passes. Keep changes only when the format check, analyzer, tests, and safety gates relevant to the change pass. |
| Output | A project-local architecture implementation or review, plus a concise Korean report of decisions, changed files, checks, source/version caveats, and residual risks. |
| Verification | Run project-defined commands plus format checking, flutter analyze, flutter test, per-platform integration runs, and artifact builds relevant to the touched surfaces; inspect resolved native configuration and route behavior when changed. |
| Stop condition | Finish when the toolchain, declared targets, router, and state ownership are identified, applicable critical gates pass, changes are verified, and residual risk is recorded; block on missing authority, unsafe native effects, unresolved version or package incompatibility, or unavailable required verification. |
</instruction_contract>
<activation_examples>
Positive:
- "Set up the Android/iOS app architecture with Flutter and Dart. Split screens by feature and also establish routing and state ownership boundaries."
- "Refactor this Flutter app so go_router setup stays in one place and features stop importing each other's internals."
- "Review the Android productFlavors and iOS per-scheme permission settings of our Flutter app from an architecture perspective."
- "Set up deep links in this Flutter app with go_router and a bottom-tab shell, and tell me what breaks on Android and iOS."
Negative:
- "Our React Native app uses Expo Router with file routes under app/. Rework the navigation and native config so it scales."
- "Design the package structure for a Dart command-line tool that talks to a REST API. No Flutter, no mobile targets."
- "From the Flutter widget package we use, copy just one card widget and create a variant widget that only changes the text. The app structure doesn't matter."
- "This is a screen to be built with Flutter, but just draw a mockup of the login screen like the Figma design. Code later."
Boundary:
- "Prepare the Flutter app for release on the Play Store and App Store. Just check whether the signing configuration and target SDK meet the requirements." Review the build and release configuration and stop before creating signing material or uploading.
- "Change just one line of the button text on the Flutter login screen to 'Continue'." Apply only a quick boundary check; do not force architecture churn.
</activation_examples>
<trigger_conditions>
Activate when the request names a Flutter app, a pubspec.yaml that depends on flutter, the lib/ structure, a router such as go_router, deep links, flavors, native configuration under ios/ or android/, platform-specific code, or the layout of app data and state, and the work is setup, implementation, review, or remediation.
Activate also when a shipped or growing Flutter project needs its structure, routing, imports, platform seams, or validation order changed, including review requests that end in a change set.
The project test runs before the request test. When local files show a Dart project without a Flutter app dependency and the user did not ask to create a Flutter app, do not route here. The remaining exclusions are in <routing_rule>.
</trigger_conditions>
<skill_architecture>
| Part | Role | Load condition |
|---|---|---|
SKILL.md |
Trigger, contract, workflow, gates, validation | Always |
architecture-rules.md |
Rule classes, authority order, blocking gates, default tree | Before classifying a finding |
rules/project-structure.md |
Scale profiles, ownership, imports, migration order, workspace layout | When changing folders, imports, or module ownership |
rules/routing-and-navigation.md |
Navigation model, single router, guards, deep links, back handling | When changing routes or links |
rules/data-state-and-boundaries.md |
State ownership, repositories, DTOs, persistence, dependency injection | When changing data flow or state |
rules/native-platform-and-security.md |
Native directories, flavors, permissions, secrets, trust, interop | When touching native config or platform code |
rules/testing-and-validation.md |
Check order, testing floors, required scenarios, completion record | Before claiming completion |
references/official/flutter-dart-2026-11-04.md |
Dated official version, API, and platform facts | When a current toolchain or API claim decides the change |
</skill_architecture>
<loop_policy>
One bounded loop per change set: run the checks, read the failures, repair only what failed, and re-run. One round is one repair and its re-run, and the loop ends after two rounds. A change stays only when the critical format, analyzer, test, native-config, and safety gates pass; otherwise the loop ends with the failing check named and nothing claimed as verified. There is no loop that keeps restructuring until the tree feels right and no self-scoring loop. Evidence is the recorded command output, the built artifact, and the resolved configuration, not a restatement of the plan.
</loop_policy>
<language_and_translation_default>
Deliver user-facing text in Korean by default: the report, decisions, caveats, and residual risks. Keep code identifiers, commands, paths, package and API names, and quoted source lines in their original form. This package is maintained as English/Korean pairs (X.md ↔ X.ko.md); read one language version per run and update both when a rule changes.
</language_and_translation_default>
<reference_routing>
- Before classifying any finding or enforcing a rule, read
architecture-rules.md. - When changing folders, imports, module ownership, scale profile, or migration order, read
rules/project-structure.md. - When changing the navigation model, the route table, guards, redirects, deep links, or back handling, read
rules/routing-and-navigation.md. - When changing state ownership, repositories, DTOs, serialization, persistence, or dependency wiring, read
rules/data-state-and-boundaries.md. - When touching flavors, permissions, secrets, storage, HTTP trust, native interop, build configuration, or release requirements, read
rules/native-platform-and-security.md. - Before claiming completion, read
rules/testing-and-validation.md. - When the installed toolchain, a package version, or an official API behavior decides the change, read
references/official/flutter-dart-2026-11-04.mdand compare itslast_verified_atwithflutter --versionand theenvironmentblock.
</reference_routing>
<support_file_read_order>
Read one language version per run, in this order. Paths are relative to this skill directory.
- Read
architecture-rules.mdfor rule classes, the authority order, and blocking gates. - Read the rule files for the topics the change touches, choosing them with
<reference_routing>. - Read
references/official/flutter-dart-2026-11-04.mdonly when current toolchain behavior or an API lifecycle decides the change. - Read
rules/testing-and-validation.mdbefore implementation completion.
</support_file_read_order>
| Phase | Task | Output |
|---|---|---|
| 0 | Confirm the project facts from local files: Flutter and Dart versions from flutter --version and the pubspec.yaml environment block, which platform folders exist (android/, ios/, optional web/, macos/, linux/, windows/), flavors and entry points, the state library in use, the router, Swift Package Manager versus CocoaPods, pub workspace or single package layout, material_ui adoption, project commands, and whether the request needs installs, signing, or store effects |
Scope decision |
| 1 | Inventory features, route table, shared modules, state and data flow, native configuration, tests, and dependency direction | Architecture map |
| 2 | Classify findings as Official, Safety, or Hypercore convention | Prioritized plan |
| 3 | Define target boundaries and the smallest vertical slice; preserve user work | Change set |
| 4 | Implement safe reversible changes and update affected callsites, tests, and configuration | Integrated architecture |
| 5 | Run focused then project-level checks and inspect resolved behavior on each declared platform | Verification evidence |
| 6 | Report decisions, versions and sources, results, and residual risks in Korean | Handoff |
- Choose the smallest structure profile that preserves clear ownership: the official hybrid tree for a small app, feature-first folders for a growing app, pub workspace packages when two apps, an independent release, a separate owner, or a rule that must fail the build requires them.
- Keep views thin: screen state lives in the paired view model, a repository is the single source of truth for its data type, and a service exists once per external source and holds no state.
- Keep one router configuration, thin route builders that parse parameters into domain types, and no named-route or mixed-router setup in new code.
- Keep dependencies pointing View to ViewModel to an optional use-case to Repository to Service, with no repository depending on another repository and no view importing the data layer.
- Keep widget-local, view-model, repository, persisted, and form state separated by owner and lifecycle, and keep the state library the project already runs instead of swapping it during unrelated work.
- Treat
--dart-define,--dart-define-from-file,appFlavor, assets, and every compiled constant as public values that ship inside the app. - Make platform divergence explicit behind a capability or adapter, and decide platform behavior with
defaultTargetPlatformandkIsWebin shared code. - Keep
ios/andandroid/as owned, reviewed source, and match every runtime permission to its declaration and user-facing purpose text. - Use the installed toolchain and each package's declared
flutter:andsdk:constraints rather than guessing versions.
- Inventing project commands, packages, native capabilities, API contracts, or environment variables.
- A universal folder template applied without inspecting project scale and existing conventions.
- Forcing a state library, replacing it mid-task, or running two state mechanisms inside one screen.
- Views importing repositories, services, DTOs, or persistence adapters; repositories depending on each other; broad barrel files that create cycles.
- Secrets in source, assets,
--dart-definevalues,appFlavor, logs, analytics, crash reports,shared_preferences, or unencrypted files. - Running dependency install or upgrade,
flutter createover an existing project, signing, store upload, or publish without explicit authorization. - Claiming Android or iOS support from a host unit test, a widget test, or a web run alone.
- Treating a router redirect as authorization, or using deep-link, push, route
extra, persisted, or API input without validation at the boundary. - Unbounded restructuring without a verified incremental slice.
- Flutter and Dart versions, declared platform targets, router, state library, and native dependency manager are identified.
- At least 3 positive, 2 negative, and 1 boundary trigger examples remain present.
- Route builders are thin, one router configuration exists, and no feature imports routing internals.
- Dependency direction and feature/shared ownership are explicit; cycles and unsafe barrels are absent.
- Runtime input, configuration, persistence, permissions, and secure storage follow the boundary and safety rules.
- Android and iOS changes are checked independently where behavior or configuration differs.
- Relevant format check,
flutter analyze, unit and widget tests, per-platform runs, and artifact builds ran or are explicitly reported as unavailable. - English/Korean skill files retain equivalent trigger, authority, workflow, safety, and completion semantics.
- Current official claims cite the dated reference; the baseline is Flutter 3.47.9 / Dart 3.13.7 per
references/official/flutter-dart-2026-11-04.md, and source dates are not in the future. - Completion records
Claim -> Risk -> Evidence -> Verification -> Result -> Caveatand decides ship, iterate, caveated ship, or block.