End-to-end Flutter mobile app development workflow plugin for Claude Code.
FlutterForge guides development teams from idea to release-ready Flutter app using specialized agents, reusable skills, quality hooks, and phased subagent workflows — all inside Claude Code.
Plan like a product team. Design like a mobile UX expert. Code like a senior Flutter engineer. Test like a QA engineer. Debug like a production maintainer. Release like a mobile DevOps engineer.
- Install
- Quick Start
- Commands
- Agents
- Skills
- Hooks
- MCP Integrations
- Configuration
- Templates
- Examples
- Contributing
- Flutter SDK ≥ 3.x — flutter.dev/get-started
- Node.js ≥ 18 — ships with Claude Code; required for hooks
- Claude Code — claude.ai/code or the VS Code / JetBrains extension
Optional (required only for the corresponding MCP integration):
firebase-tools(npm i -g firebase-tools && firebase login) for Firebase MCPGITHUB_PERSONAL_ACCESS_TOKENenv var for GitHub MCPSUPABASE_ACCESS_TOKENenv var for Supabase MCPFIGMA_API_KEYenv var for Figma MCP
git clone https://github.com/Yakoub-ai/flutterforge.git ~/flutterforgeThen in Claude Code, run:
/plugin install --from-dir ~/flutterforge
/plugin marketplace add https://github.com/Yakoub-ai/flutterforge
/plugin install flutterforge
After install, run /flutterforge:flutterforge in Claude Code — you should see the FlutterForge workflow menu.
If hooks do not fire, ensure Node.js is on your PATH: node --version should print v18 or later.
/flutterforge:plan-flutter-app I want to build a social fitness app where friends compete on weekly challenges
This runs a 3-phase workflow:
- Product strategist produces app brief, MVP scope, user stories
- UX designer + Flutter architect work in parallel on screen flows and architecture
- You approve the plan before any code is written
Then scaffold:
/flutterforge:new-flutter-app
/flutterforge:build-flutter-feature Add a leaderboard screen that shows weekly challenge rankings
/flutterforge:audit-flutter-app
Runs 5 agents in parallel: architecture audit, security review, performance check, test coverage review, release readiness check.
All commands are available as /flutterforge:<command> or via the main /flutterforge:flutterforge menu.
| Command | Purpose | Agents Used |
|---|---|---|
/flutterforge:flutterforge |
Workflow menu — pick your mode | (router) |
/flutterforge:plan-flutter-app |
Brainstorm + architecture plan | product-strategist, ux-mobile-designer, flutter-architect |
/flutterforge:new-flutter-app |
Scaffold new Flutter project | flutter-architect, flutter-implementation-engineer, flutter-test-engineer |
/flutterforge:build-flutter-feature |
Implement a feature with tests | flutter-architect, flutter-implementation-engineer, flutter-test-engineer |
/flutterforge:audit-flutter-app |
Full app audit (5 parallel agents) | codebase-auditor, mobile-security-reviewer, mobile-performance-engineer, flutter-test-engineer, release-engineer |
/flutterforge:debug-flutter |
Root-cause debug and fix | flutter-debugger, flutter-test-engineer |
/flutterforge:generate-tests |
Generate unit + widget tests | flutter-test-engineer |
/flutterforge:improve-ux |
UX analysis and UI improvements | ux-mobile-designer, flutter-implementation-engineer |
/flutterforge:prepare-release |
Android + iOS release checklist | release-engineer, mobile-security-reviewer |
/flutterforge:refactor-flutter |
LSP-guided safe refactoring | codebase-auditor, flutter-implementation-engineer |
/flutterforge:flutter-accessibility |
Accessibility audit and WCAG 2.1 AA improvements | ux-mobile-designer |
Agents are dispatched by commands using the Task tool for isolated-context execution. Each agent is scoped to its expertise and avoids context pollution from the main session.
| Agent | Role | Model |
|---|---|---|
product-strategist |
Converts app ideas into product briefs with user stories, MVP scope, metrics | opus |
flutter-architect |
Architecture decisions, folder structure, state management, ADRs | opus |
ux-mobile-designer |
Screen flows, design system, component inventory, accessibility | sonnet |
flutter-implementation-engineer |
Clean Flutter code following project architecture | sonnet |
state-management-specialist |
Riverpod/Bloc/Cubit design, async handling, rebuild optimization | sonnet |
api-integration-engineer |
REST/Firebase/Supabase clients, repositories, DTOs, offline patterns | sonnet |
flutter-test-engineer |
Unit, widget, integration, golden test strategy and generation | sonnet |
flutter-debugger |
Stack trace analysis, root cause, minimal patch, regression tests | sonnet |
mobile-performance-engineer |
Rebuild analysis, list optimization, image caching, profiling guidance | sonnet |
mobile-security-reviewer |
Secrets detection, permissions, auth flows, storage security | sonnet |
release-engineer |
Android/iOS build readiness, store metadata, CI/CD checklist | sonnet |
codebase-auditor |
Architecture drift, anti-patterns, unused deps, refactor prioritization | sonnet |
Skills are invoked by agents (and by Claude directly when trigger phrases match). Each skill documents a complete methodology.
| Skill | Trigger | Output |
|---|---|---|
flutter-app-discovery |
"audit existing Flutter app", "understand this Flutter codebase" | Architecture summary, dependency audit, risks |
flutter-product-brief |
"plan a Flutter app", "write a product brief" | Brief, personas, user stories, MVP scope |
flutter-architecture |
"design Flutter architecture", "choose state management" | ADR, folder structure, dependency list |
flutter-ux-design |
"design Flutter UX", "create screen flow" | Screen map, user flows, component inventory |
flutter-feature-dev |
"build Flutter feature", "implement Flutter screen" | Feature spec, implementation, tests |
flutter-state-management |
"Riverpod", "Bloc", "manage state in Flutter" | State model, provider design, test strategy |
flutter-api-integration |
"integrate API", "connect Firebase", "add Supabase" | API client, repositories, DTOs, mocks |
flutter-testing |
"write Flutter tests", "generate tests" | Test plan, unit tests, widget tests |
flutter-debugging |
"debug Flutter", "fix Flutter error", "stack trace" | Root cause, patch, validation commands |
flutter-performance |
"optimize Flutter", "fix jank", "improve performance" | Performance findings, prioritized fixes |
flutter-accessibility |
"check accessibility", "add semantics", "a11y" | Accessibility findings, semantic improvements |
flutter-security |
"security review", "check secrets", "Flutter security" | Security risks, fixes, permission review |
flutter-release-readiness |
"prepare release", "app store", "publish Flutter app" | Android + iOS checklist, build commands |
flutter-documentation |
"generate docs", "update README", "document Flutter" | README updates, architecture docs, feature docs |
FlutterForge hooks are quality gates that run automatically. All Flutter-specific hooks no-op when pubspec.yaml is not found — they are safe to install globally.
| Hook | Trigger | Action |
|---|---|---|
| Format | After editing any .dart file |
dart format <file> |
| Analyzer | After editing .dart (opt-in) |
flutter analyze — enable with FLUTTERFORGE_AUTO_ANALYZE=1 |
| Pre-commit | Before git commit |
dart format --set-exit-if-changed . + flutter analyze + flutter test |
| Secret detection | Before any file write or commit | Blocks API keys, tokens, .env files — override with FLUTTERFORGE_SKIP_SECRET_CHECK=1 |
| Pubspec sync | After editing pubspec.yaml |
flutter pub get |
To skip pre-commit checks during WIP: FLUTTERFORGE_SKIP_PRECOMMIT=1 git commit -m "WIP".
FlutterForge ships .mcp.json with default MCP server integrations that work without credentials. Credentialed integrations are opt-in and documented in mcp-servers/optional-mcp.json.
| Server | Purpose | Setup |
|---|---|---|
context7 |
Flutter/Dart/pub.dev documentation lookup | npx @upstash/context7-mcp (no auth needed) |
pub-dev |
Package search, scores, versions, Flutter SDK compatibility | Auto-installs Node dependencies into Claude plugin data on first use |
Optional integrations:
| Server | Purpose | Setup |
|---|---|---|
github |
PR and issue workflows | Copy from mcp-servers/optional-mcp.json and set GITHUB_PERSONAL_ACCESS_TOKEN |
supabase |
Supabase schema and auth integration | Copy from mcp-servers/optional-mcp.json and set SUPABASE_ACCESS_TOKEN |
figma |
Design-to-Flutter component mapping | Copy from mcp-servers/optional-mcp.json and set FIGMA_API_KEY |
firebase |
Firebase Auth, Firestore, Storage, Functions | Copy from mcp-servers/optional-mcp.json, install/login to firebase-tools, optionally set FIREBASE_PROJECT |
See mcp-servers/README.md for detailed setup instructions and mcp-servers/ROADMAP.md for planned future MCPs.
FlutterForge reads environment variables for behavior configuration:
| Variable | Default | Effect |
|---|---|---|
FLUTTERFORGE_AUTO_ANALYZE |
0 |
Set to 1 to auto-run flutter analyze after every Dart edit |
FLUTTERFORGE_SKIP_PRECOMMIT |
unset | Set to 1 to skip pre-commit quality gate (WIP escape hatch) |
FLUTTERFORGE_SKIP_SECRET_CHECK |
unset | Set to 1 to skip secret detection (use carefully) |
Maintainer validation before release:
claude plugin validate .
node --check hooks/lib-node/*.cjs
node --check mcp-servers/pub-dev-mcp/server.js
node --check mcp-servers/pub-dev-mcp/lib/pubdev-client.jsCopy templates from templates/ into your Flutter project to bootstrap documentation:
| Template | Use |
|---|---|
app_brief.md |
Product brief for new app planning |
technical_plan.md |
Architecture and implementation plan |
architecture_decision_record.md |
Document architecture decisions |
feature_spec.md |
Feature specification before implementation |
ux_review.md |
UX review checklist |
test_plan.md |
Test strategy documentation |
release_checklist.md |
Android + iOS release checklist |
debug_report.md |
Structured debugging report |
claude_project_memory.md |
CLAUDE.md template for Flutter project AI context |
See examples/ for guided walkthrough recipes showing how to use FlutterForge commands to build real app types:
todo_app.md— Simple CRUD with local storagefirebase_auth_app.md— Authentication with Firebaseecommerce_app.md— Product catalog with cart and paymentsmaps_upload_app.md— Maps, location, and photo upload
Hooks not firing?
- Run
node --versionto confirm Node.js ≥ 18 is on your PATH. - Run the MCP verification script to check all server connections:
bash scripts/verify_mcps.sh # macOS / Linux pwsh scripts/verify_mcps.ps1 # Windows
MCP server not connecting?
- Check the required env vars in the table above.
- See
mcp-servers/README.mdfor per-server troubleshooting.
Secret detection blocking a legitimate value?
- Add a placeholder comment (
# example) on the same line, or setFLUTTERFORGE_SKIP_SECRET_CHECK=1.
Pre-commit hook blocking?
- Bypass for WIP work:
FLUTTERFORGE_SKIP_PRECOMMIT=1 git commit -m "WIP".
See CONTRIBUTING.md for how to add skills, agents, commands, and hook scripts.
MIT — see LICENSE.