Flutter Flavors

Use this skill when the user asks to configure, audit, or switch Flutter flavors, build environments, app IDs, display names, launch configs, or platform-specific app identities.

Core Rule

Flutter flavor/environment and Flutter build mode are separate axes.

• Flavor/environment defines which app identity or deployment profile is built.
• Build mode (debug, profile, release) defines how the Flutter runtime is compiled.
• Do not use profile as a synonym for beta.
• Do not use release as a synonym for prod.
• Validate every app ID against references/identifier-rules.md before editing. That reference owns platform character rules, cross-platform ID differences, slug derivation from display names, and the ban on applying example IDs literally.
• When Flavorizr config and native platform files both exist, treat them as separate sources until reconciled. Before applying canonical or personal changes, identify which one is source of truth and update the other to match; if they conflict, ask before editing.
• Preserve unknown or extra flavors unless the user explicitly asks to remove or rename them. If applying canonical or personal policy, ask whether extra flavors should be updated, mapped, or left untouched.
• If multiple flavor meanings coexist, such as environment flavors (dev, test, beta, prod) plus custom flavors (custom_flavor_a, custom_flavor_b), ask whether to flatten combinations or keep them independent. When kept independent, add VS Code debug launch configs for custom-only flavors unless the user requests profile/release variants.

Scope

Current bundled references cover generic Android/iOS mobile setup:

• Read references/identifier-rules.md before writing any app ID, bundle identifier, or derived slug.
• Read references/mobile-identities.md for canonical team identities and personal Apple Developer/local device testing identities.
• Read references/flutter-flavorizr.md when a project already uses flutter_flavorizr, has flavorizr.yaml, or the user asks to generate/manage Flutter Flavorizr configuration.
• Read references/example-prompts.md only when the user asks for example prompts or usage examples.

For macOS, web, Windows, or Linux, first inspect existing project docs and native platform files. Only apply platform-specific identity changes when the requested target and source of truth are clear. Otherwise, report the likely files and ask for a platform policy.

If the user invokes only $flutter-flavors without a concrete task, ask for the intended action and do not edit files.

Workflow

1. Identify requested target: canonical, personal, switch canonical to personal, switch personal to canonical, audit only, or add a new platform policy.
2. Load only the relevant reference file.
3. Inspect existing Android/iOS/macOS/web/Windows/Linux project files before editing.
4. Preserve unrelated launch configs, schemes, build files, signing settings, and app logic.
5. Stop and report when signing, export, store, CI/CD, provisioning, capabilities, notarization, package identity, or release-path decisions need human confirmation.
6. Verify with the smallest available Flutter/native check that does not require unavailable signing credentials.

For an implementation, correct in-scope flavor/configuration errors found during verification, including pre-existing errors that prevent the requested outcome, and rerun the affected check. Report unrelated defects separately and unavailable SDKs, signing access, or unresolved source-of-truth decisions as pending verification; do not change signing, install tools, or broaden platform scope to make a check pass without authorization. An audit reports discrepancies without applying fixes.

Platform Notes

• Android uses Gradle Kotlin DSL product flavors, lowercase applicationId, and manifest label placeholders.
• iOS and macOS use Xcode schemes/build configurations, bundle identifiers, display names, and signing settings.
• Web usually uses deployment environment/profile settings rather than a native installable flavor.
• Windows/Linux usually use package/app metadata and build-time environment profiles rather than Android-style product flavors.

Output

Report what identity set was applied or audited, which platform files changed, which checks ran, and any human decisions still required.