Read the request carefully — identify exact user-facing behavior, implied edge cases, and ambiguities. Ask if ambiguity blocks architecture; document as assumption if minor.
Run discovery (first feature in session) — invoke flutter-app-discovery skill if codebase not yet inspected.
Identify affected files across data / domain / presentation / routing / tests. See @references/feature-layer-template.md for folder structure.
Find patterns to reuse — existing providers, repositories, widgets (AppButton, ErrorView, EmptyStateView), error handling, API client setup. Import; never recreate.
Write feature spec — use templates/feature_spec.md if present. Cover: summary, user stories, scope in/out, screens, state/async behavior, edge cases, assumptions, open questions.
Produce implementation plan — list every file to create (by layer and path) and every file to modify. Assess risk: low / medium / high.
Get user approval on the plan before writing any code. If user says "yes / go / do it", proceed without repeating the plan.
Implement data → domain → presentation in that order. Do not start presentation before domain contracts are defined.
Implement all UI states for every screen: loading, success, empty, error, offline.
Write tests alongside implementation: unit tests for use cases and repositories, widget tests for pages. See @references/feature-layer-template.md for patterns.
Validate: dart format . → flutter analyze --no-fatal-infos → flutter test. Fix all errors before marking done.
Write summary to docs/features/<feature-name>.md: files created/modified, tests written, validation results, next steps.
Flag any file approaching 300 lines — propose splitting before continuing.

Feature Specification Fields

Field	Description
Goal	One sentence: what problem this solves
User story	"As a [user] I want to [action] so that [outcome]"
Entry point	Screen or action that triggers this feature
Screens affected	Names of pages and widgets created or modified
State requirements	Async operations, loading/error/empty states needed
Data requirements	API endpoints, Firestore collections, local storage keys
Error states	Every failure scenario and how it's handled
Offline behavior	Cached fallback or explicit offline state
Analytics events	Event names to fire on key user actions
Accessibility notes	Semantic labels, tap targets, screen reader behavior
Test cases	Minimum unit tests and widget tests required

Architecture Rules

NEVER introduce a new state management library without explicit user approval.
NEVER add a package without explaining why and checking for existing alternatives.
NEVER hardcode secrets, API keys, or tokens in any Dart file.
NEVER skip tests for business logic — use cases and repositories must have unit tests.
NEVER put business logic in widgets. Use controllers, providers, or cubits.
ALWAYS preserve existing architecture. If the project uses Riverpod, do not add Bloc.
ALWAYS implement all five UI states for every screen.
ALWAYS get plan approval (step 7) before writing implementation code.
After 2 failed fix attempts: re-read the full file top-to-bottom, state the wrong assumption, propose a different approach.
Renaming: search all references — imports, string literals, dynamic imports, test mocks, re-exports.

Required UI States

Every screen must handle:

Loading — skeleton loader or LoadingIndicator (for data fetch)
Success — render actual data
Empty — EmptyStateView with a primary action
Error — ErrorView with retry callback; never silent failure
Offline — OfflineBanner when the app has offline behavior

Every async button must: show loading state (disable + spinner), handle success (navigate / snackbar), handle failure (inline error or snackbar).

Output Artifacts

docs/features/<feature-name>.md — feature spec + implementation summary
lib/features/<feature>/data/ — DTOs, datasources, repository impl
lib/features/<feature>/domain/ — entities, repository interface, use cases
lib/features/<feature>/presentation/ — controller/cubit, page, widgets
test/features/<feature>/ — unit + widget tests

Cross-references

Agents: flutter-implementation-engineer, flutter-test-engineer, state-management-specialist
See @references/feature-layer-template.md for folder structure and Dart patterns
See @references/state-management-snippets.md for Riverpod/Bloc examples
See @references/dart-error-mapping.md for error hierarchy and DioException mapping

flutter-feature-dev

Flutter Feature Development

Workflow