| name | flutter-app |
| description | Bootstrap a new Flutter mobile app with clean architecture, Riverpod, FVM-pinned SDK, current packages, and no deprecated APIs. Use when the user wants to start, scaffold, or set up a new Flutter app, a cross-platform mobile app, an Android or iOS app in Dart, or asks to "create a new flutter app". Handles BYOK LLM apps, backend-backed apps, Play Store release setup, and clean-architecture feature structure. |
flutter-app
Bootstrap a new Flutter app the way this owner builds them: FVM-pinned SDK, clean
architecture (feature-first), Riverpod for state, an Either/Failure error model,
current stable packages, and the house git and CI workflow with release-please
and Play Store delivery.
First read the shared rules (they override anything you remember):
../shared/house-rules.md, ../shared/no-ai-attribution.md,
../shared/git-and-ci.md, ../shared/docs-and-context.md,
../shared/hardening.md, and (for public repos) ../shared/open-source-docs.md.
Step 0. Get the brief, then ask the variant questions (hard stop)
This is a hard stop. Do not run any scaffolding command until the user has
answered.
First, get the project brief: one paragraph on what the app does, its main
features, target users, and any hard constraints. If the user has not given one,
ask for it. The brief drives naming, the feature list, and the data model.
Then ask the variant questions. If a choice has multiple options, ask; do not
assume. Ask in one batch, then proceed.
- Repo visibility: private, open-source, or private-plus-open-source.
- Backend: BYOK (each user supplies their own LLM key, no backend), a custom
backend (Dio + JWT auth), or none yet. See
references/architecture.md.
- State codegen: Riverpod with codegen (
@riverpod + build_runner) or plain
Riverpod with hand-written providers. Default: codegen.
- Local data: Drift, Isar, shared_preferences only, or none yet.
- Auth: Google Sign-In, none, or backend-driven.
- Release target: Play Store (default), App Store, or both.
If the user already answered some, do not re-ask.
Step 1. Pin the SDK with FVM and verify versions
- Use FVM so the SDK is pinned per project:
fvm use stable (or a specific
stable). Every command runs through fvm flutter ....
- Run
fvm flutter --version and record the real Flutter and Dart versions in
the project docs.
- Run
scripts/check-latest.sh for current stable package versions from pub.dev.
Pin those, not versions from memory (../shared/house-rules.md rule 2).
- Pull current docs for Flutter, Riverpod, and any codegen packages via Context7
before writing code (
../shared/docs-and-context.md). Riverpod's provider
syntax and codegen naming change between majors; confirm before writing.
Step 2. Scaffold with the official CLI
fvm flutter create --org com.<owner>.<app> --platforms=android,ios <name>
Then add dependencies from references/stack.md and lay out the folders from
references/architecture.md.
Step 3. Apply architecture and conventions
- Clean-architecture layers, feature structure, Either/Failure model, DI, and the
non-negotiable conventions (use cases, datasource interface plus impl, custom
widgets, extensions, central utils, constants for everything, zero hardcoding):
references/architecture.md.
- Riverpod and Flutter do's and don'ts, and code smells to avoid:
references/best-practices.md.
- Dependency set and pinning notes (some packages must be pinned to avoid
analyzer conflicts):
references/stack.md.
- Production hardening (obfuscated release builds, no baked-in secrets, no debug
symbols in git):
../shared/hardening.md.
Step 4. Git, CI, release, docs, security
- Git branch model, conventional commits, auto-merge, release-please:
../shared/git-and-ci.md.
- CI (analyze + test), signing, and Play Store delivery:
references/quality-gates.md.
- Gitignore signing keys, keystore,
google-services.json, and .env*. Store
them as CI secrets. Provide .env.example.
- Add
docs/ (git-workflow, architecture, release-process) and a README. For a
public repo, ship the full open-source docs set per
../shared/open-source-docs.md and run the open-source hard gate in
../shared/no-ai-attribution.md before the first push.
Step 5. Verify before declaring done
Run the gates in references/quality-gates.md: fvm flutter analyze must be
zero issues, fvm flutter test green, and the app must build and run. Report
real results.
