Writing Flutter Implementation Plans

Overview

Write comprehensive implementation plans assuming the engineer has zero context for our codebase. Document everything they need: which files to create/modify for each task, complete code, testing approach, how to verify it works. Give them the whole plan as bite-sized tasks following Clean Architecture layer order.

Announce at start: "I'm using the flutter-planning skill to create the implementation plan."

Save plans to: docs/plans/YYYY-MM-DD-<feature-name>-plan.md

Feature-Driven Development Order

CRITICAL: Follow Clean Architecture layer order:

1. Domain Layer (First)
   ├── Entities
   ├── Repository interfaces
   └── UseCases (optional)

2. Data Layer (Second)
   ├── Models (DTOs with fromJson/toJson)
   ├── DataSources (Remote/Local)
   └── Repository implementations

3. Presentation Layer (Third)
   ├── State Management (BLoC/Provider/Riverpod)
   ├── Widgets
   └── Screens

4. Tests (After implementation)
   ├── Priority 1: Repository, DataSource unit tests
   ├── Priority 2: State management unit tests
   ├── Priority 3: Widget tests (optional)
   └── Priority 4: Golden tests (optional, visual regression)

5. Integration & Wiring
   └── DI setup (get_it, injectable, etc.)

Plan Document Header

Every plan MUST start with this header:

# [Feature Name] Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use flutter-craft:flutter-executing to implement this plan task-by-task.

**Goal:** [One sentence describing what this builds]

**Architecture:** Clean Architecture with [BLoC/Provider/Riverpod]

**Dependencies:** [New packages needed]

---

Task Structure

### Task N: [Component Name]

**Layer:** Domain / Data / Presentation / Test

**Files:**
- Create: `lib/features/<feature>/domain/entities/user.dart`
- Modify: `lib/features/<feature>/data/repositories/user_repository_impl.dart`
- Test: `test/features/<feature>/data/repositories/user_repository_test.dart`

**Implementation:**

// Complete code here - no placeholders like "add validation" class User { final String id; final String name; final String email;

const User({ required this.id, required this.name, required this.email, }); }

**Verification:**

flutter analyze lib/features/<feature>/

Expected: No issues found!

**Commit:**

git add lib/features/<feature>/domain/entities/user.dart git commit -m "feat(<feature>): add User entity"

Task Granularity

Each task is one logical unit (2-10 minutes):

Example Plan Structure

# Authentication Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use flutter-craft:flutter-executing

**Goal:** Implement user login/logout with token-based auth

**Architecture:** Clean Architecture with BLoC

**Dependencies:**

flutter pub add dio flutter pub add flutterbloc flutter pub add getit

---

## Domain Layer

### Task 1: User Entity
**Layer:** Domain
**Files:**
- Create: `lib/features/auth/domain/entities/user.dart`
...

### Task 2: AuthRepository Interface
**Layer:** Domain
**Files:**
- Create: `lib/features/auth/domain/repositories/auth_repository.dart`
...

## Data Layer

### Task 3: UserModel
**Layer:** Data
**Files:**
- Create: `lib/features/auth/data/models/user_model.dart`
...

### Task 4: AuthRemoteDataSource
**Layer:** Data
**Files:**
- Create: `lib/features/auth/data/datasources/auth_remote_datasource.dart`
...

### Task 5: AuthRepositoryImpl
**Layer:** Data
**Files:**
- Create: `lib/features/auth/data/repositories/auth_repository_impl.dart`
...

## Presentation Layer

### Task 6: AuthBloc
**Layer:** Presentation
**Files:**
- Create: `lib/features/auth/presentation/bloc/auth_bloc.dart`
- Create: `lib/features/auth/presentation/bloc/auth_event.dart`
- Create: `lib/features/auth/presentation/bloc/auth_state.dart`
...

### Task 7: LoginScreen
**Layer:** Presentation
**Files:**
- Create: `lib/features/auth/presentation/screens/login_screen.dart`
...

## Testing

### Task 8: AuthRepository Unit Tests
**Layer:** Test (Priority 1)
**Files:**
- Create: `test/features/auth/data/repositories/auth_repository_impl_test.dart`
...

### Task 9: AuthBloc Unit Tests
**Layer:** Test (Priority 2)
**Files:**
- Create: `test/features/auth/presentation/bloc/auth_bloc_test.dart`
...

## Integration

### Task 10: DI Setup
**Layer:** Integration
**Files:**
- Modify: `lib/core/di/injection.dart`
...

Remember

• Exact file paths always - Full path from lib/ or test/
• Complete code in plan - No "add validation here"
• Verification commands - flutter analyze, flutter test
• Layer order - Domain → Data → Presentation → Test
• One commit per task - Keep commits atomic
• Conventional commits - feat(), fix(), test(), refactor()

Execution Handoff

After saving the plan, offer execution choice:

"Plan complete and saved to docs/plans/<filename>.md. Two execution options:

1. Subagent-Driven (this session) - Dispatch fresh subagent per task, review between tasks, fast iteration

2. Batch Execution (this session) - Execute 3 tasks at a time with checkpoints

Which approach?"

If Subagent-Driven chosen:

• REQUIRED SUB-SKILL: Use flutter-craft:flutter-subagent-dev
• Fresh subagent per task + 2-stage code review

If Batch Execution chosen:

• REQUIRED SUB-SKILL: Use flutter-craft:flutter-executing
• Execute 3 tasks, verify, checkpoint, continue

REQUIRED SUB-SKILL

After completing the plan, you MUST offer execution options and invoke one of: → flutter-craft:flutter-executing (batch execution) → flutter-craft:flutter-subagent-dev (subagent per task)

This is NOT optional. Plans without execution are incomplete.