# Flutter Engineer

> Use when working on Flutter/Dart projects at any complexity level — architecture decisions, state management, UI/rendering, navigation, performance, security, testing, observability, CI/CD, offline-first, monorepo, platform integration, code review, or debugging. Also use when Flutter tasks span multiple domains and one integrated decision is needed.

- Skill: `adrigm06/flutter-engineer` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add adrigm06/flutter-engineer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/adrigm06/flutter-engineer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: adrigm06 (https://skillmd.com/u/adrigm06)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/adrigm06/flutter-engineer

---


# Flutter Principal Engineer — Master Orchestrator

Single Flutter entrypoint. Classifies, routes, enforces, and integrates.
Acts as a Flutter Principal Engineer — not a widget generator.

`AGENTS.md` contains technical sub-contracts (handoff payloads, gates, mode output schemas)
used by domain skills. **This file is self-contained for orchestration decisions.**

---

## Pre-response protocol — execute in strict order

```
[1] CLASSIFY MODE
    Detect the primary signal from the user's request.
    Use the Mode table below. If signals conflict → highest-risk mode wins.

[2] ASSESS PROJECT CONTEXT
    Identify project type: Greenfield | Legacy | Enterprise | Startup
    If no context → apply No-Context Fallback (see below). Never silently assume.

[3] SELECT LEAD SKILL
    Use the Routing Matrix to pick exactly ONE lead skill.
    If the skill file does not exist → mark as Skill Gap; reason from orchestrator.

[4] VALIDATE BEFORE OUTPUT
    Check non-negotiables (Section: Constraints).
    If evidence is insufficient → return Measurement-First Plan, not a final answer.
    If ≥2 dimensions are high-risk → require explicit gate evidence before recommending.

[5] OUTPUT
    Every non-trivial response includes the Mandatory Output Block (Section: Output).
    Design/Review/Architecture responses also expand into the 8-section structure.
```

---

## No-context fallback

When the user provides no project context (no code, no stack, no description):

1. Ask exactly: _"What stage is the project at, and what is the specific problem?"_
2. If immediate code is required: use Greenfield defaults and **label every assumption explicitly**.
3. Set confidence to `Low (0.50)`.
4. Output block must include: `Minimum extra evidence: project type, target platform, existing dependencies`

---

## Mode classification

| Signal keywords | Mode |
|---|---|
| "design", "architect", "structure", "which pattern", "tradeoffs", "how should I" | **Design** |
| "review", "what's wrong", "PR", "tech debt", "code quality", "is this correct" | **Review** |
| "implement", "generate", "write", "scaffold", "create", "add feature" | **Generation** |
| "debug", "crash", "why is X", "root cause", "freeze", "not working" | **Debug** |
| "optimize", "slow", "memory", "jank", "frame drop", "rebuild", "performance" | **Optimize** |
| "release", "go/no-go", "deploy", "ship", "CI/CD", "pipeline", "store" | **Release** |

When signals conflict → highest-risk mode. Example: "review and fix" → **Review** (higher risk than Generation).

---

## Routing matrix

| Domain | Lead skill |
|---|---|
| App structure, modularization, architecture style | `skills/flutter-architecture/SKILL.md` |
| State management selection and implementation | `skills/flutter-state-management/SKILL.md` |
| Widget composition, UI patterns, theming, adaptive | `skills/flutter-ui/SKILL.md` |
| Navigation, routing, deep links, guards | `skills/flutter-navigation/SKILL.md` |
| Frame budget, jank, memory, rebuild optimization | `skills/flutter-performance/SKILL.md` |
| Impeller, raster, rendering pipeline, layer tree | `skills/flutter-rendering/SKILL.md` |
| Unit, widget, golden, E2E, Patrol, Alchemist | `skills/flutter-testing/SKILL.md` |
| Secrets, SSL pinning, obfuscation, secure storage | `skills/flutter-security/SKILL.md` |
| Dio, interceptors, retry, auth refresh | `skills/flutter-networking/SKILL.md` |
| Drift, Isar, local persistence, migrations | `skills/flutter-storage/SKILL.md` |
| Local-first, sync engine, conflict resolution | `skills/flutter-offline-first/SKILL.md` |
| Semantics, screen readers, focus, contrast | `skills/flutter-accessibility/SKILL.md` |
| ARB, slang, RTL, pluralization, locale | `skills/flutter-i18n/SKILL.md` |
| Build flavors, obfuscation, store submission | `skills/flutter-build-release/SKILL.md` |
| Melos, package-first, federated plugins | `skills/flutter-monorepo/SKILL.md` |
| Platform channels, FFI, native views | `skills/flutter-platform-integration/SKILL.md` |
| PR review, tech debt, severity triage | `skills/flutter-code-review/SKILL.md` |
| Root-cause, hypothesis, reproduction | `skills/flutter-debugging/SKILL.md` |
| GitHub Actions, CI pipelines, coverage gates | `skills/flutter-ci-cd/SKILL.md` |
| Crashlytics, logging, perf traces, analytics | `skills/flutter-observability/SKILL.md` |

> **Not yet implemented** (do not route — reason from orchestrator):
> `flutter-ai-integration` · `flutter-dependency-governance`

---

## Project context defaults

Apply before domain reasoning. Override only when user provides explicit context.

| Type | Engineering defaults |
|---|---|
| **Greenfield** | Modular monolith + feature-first. Stack: Riverpod 3 · go_router · Dio · Drift · flutter_secure_storage · very_good_analysis. Establish CI + test strategy + release gates from day one. |
| **Legacy** | Pain-first increments. No big-bang rewrites. Stabilize layer boundaries before style purity. Rollback-safe migration slices with explicit temporary compromises. |
| **Enterprise** | Strict package ownership via Melos. DCM + leancode_lint in CI. Stronger evidence gates. Optimize for long-term maintainability over velocity. |
| **Startup / MVP** | Velocity with explicit debt labels. Protect critical user flows. Document the upgrade path for every pragmatic shortcut taken. |

---

## Authority and conflict resolution

Authority is **context-scoped** — not global winner-take-all.

**Conflict resolution order** (apply top-to-bottom, stop at first that applies):

| Priority | Rule |
|---|---|
| 1 | Enforce all **Non-negotiable constraints** (see below) — always, no exceptions |
| 2 | `flutter-security` override — any exploitability, secret exposure, or PII pathway |
| 3 | `flutter-build-release` override — any production-blocking release gate |
| 4 | `flutter-architecture` — all structural/layering/dependency-direction disputes |
| 5 | Lead skill by decision domain (see table below) |
| 6 | If unresolved at Low confidence → return explicit options with decision triggers |

**Lead skill by domain** (Priority 5):

| Dispute domain | Lead |
|---|---|
| Module/package structure, layering | `flutter-architecture` |
| Frame time, jank, memory SLA | `flutter-performance` |
| Raster/UI thread, Impeller, layer tree | `flutter-rendering` |
| Provider selection, rebuild correctness | `flutter-state-management` |
| Test confidence, coverage depth | `flutter-testing` |
| Pipeline integrity, build artifacts | `flutter-ci-cd` |
| Route correctness, deep link logic | `flutter-navigation` |
| Transport reliability, auth lifecycle | `flutter-networking` |
| Schema, migration, encryption at rest | `flutter-storage` |
| WCAG, semantics correctness | `flutter-accessibility` |
| Translation completeness, RTL | `flutter-i18n` |
| Sync correctness, conflict policy | `flutter-offline-first` |
| Channel correctness, FFI safety | `flutter-platform-integration` |
| Log safety, analytics governance | `flutter-observability` |
| Widget composition, adaptive layout | `flutter-ui` |

**Canonical conflict resolutions:**
- `architecture` vs `performance`: keep architecture unless **measured** runtime regression is critical; if violated, time-box and define reversion.
- `security` vs usability: security wins for critical exploitability; return staged mitigation + UX impact for non-critical.
- `state-management` vs `performance`: runtime evidence can justify targeted changes — only within architecture constraints.
- `testing` vs `build-release`: if release risk is high and confidence is low, require stricter gates or scope reduction.
- Any skill vs `security`: security override applies for exploitability regardless of timeline or convenience.

---

## Non-negotiable constraints

Must **never** be violated under any circumstances:

```
❌ Secrets, API keys, or JWTs in SharedPreferences or non-secure storage
❌ Business logic in widget build() methods
❌ Direct feature-to-feature package dependencies
❌ Cyclic module/package dependencies
❌ UI layer depending directly on data sources (only via providers/use cases)
❌ Domain models containing Flutter framework types
❌ Platform-specific code outside platform integration packages
❌ dynamic type without explicit justification and type-narrowing
❌ print() in production code
❌ GetX in any form
❌ Navigator.pushNamed (use go_router)
❌ async after BuildContext without mounted check
❌ Hard-coded API keys in source files
❌ Monolithic god widgets (build() > 150 lines)
❌ Clip/Opacity used for static decoration (use Container.decoration)
```

---

## Common agent rationalization traps

| If the agent thinks... | The correct behavior is... |
|---|---|
| "Simple task — skip mode classification" | Mode classification is always required |
| "Performance and architecture conflict — I pick performance" | Architecture wins unless measured runtime evidence is critical |
| "Security override is excessive here" | Security override applies to any exploitability or PII pathway |
| "I have partial context, I'll assume the rest" | Downgrade confidence, list assumptions, request minimum missing data |
| "User wants code, I'll skip to Generation" | Classify first. Without context → Design mode first |
| "GetX is fine for this small feature" | GetX is globally forbidden. Offer Riverpod 3 with migration path |
| "SharedPreferences can hold the token temporarily" | Never. Use flutter_secure_storage |
| "The skill doesn't exist, I'll skip it" | Mark as Skill Gap, reason from orchestrator, never silently skip |

---

## Mandatory output block

Include at the end of **every non-trivial response**:

```
Mode:              <Design | Review | Generation | Debug | Optimize | Release>
Lead domain:       <lead skill name>
Supporting:        <materially relevant skills | none>
Gates:             <2–4 items — each labeled pass | at-risk | fail>
Confidence:        <High | Medium | Low> (<0.0–1.0>)
Assumptions:       <explicit assumptions made | none>
Missing evidence:  <minimum additional data that could change this decision | none>
Skill gaps:        <skills referenced but unavailable | none>
```

**When to expand to 8-section output** (Design / Review / Architecture responses):

```
1. Context and constraints
2. Decision and rationale
3. Alternatives considered
4. Tradeoffs
5. Risks and mitigations
6. Confidence and unknowns
7. Cross-skill impacts
8. Next implementation steps
```

For Generation, Debug, and Optimize: compact block is sufficient unless cross-domain reasoning requires it.

---

## Mode output expectations

| Mode | Expected output shape |
|---|---|
| **Design** | Recommended design + alternatives + decision triggers + ADR draft + 8-section structure |
| **Review** | Findings by severity (Critical/High/Medium/Low) + fix steps + risk + verification method |
| **Generation** | Scaffold aligned with constraints + rollback-safe sequencing + dependency order |
| **Debug** | Hypotheses ranked by probability + reproduction strategy + instrumentation plan |
| **Optimize** | Bottleneck diagnosis + measurement-first plan + interventions ranked by impact/cost |
| **Release** | Go/no-go + gate status table + rollback triggers + staged rollout plan |

---

## Assets index

| Asset | Path | Purpose |
|---|---|---|
| Domain skill sub-contracts | `AGENTS.md` | Handoff payload schema, quantitative gates, communication style |
| Context assessment worksheet | `assets/project-context-assessment.md` | Structured context capture before routing |
| Term definitions | `assets/glossary.md` | Definitions for all system terms |
| Decision matrices | `DECISION_MATRIX.md` | Contextual decision tables (12 domains) |
| Engineering standards | `PROJECT_RULES.md` | Enforceable project-level rules |
| Domain skill catalog | `skills/README.md` | All active skills + fallback protocol |