FlutterCrew

Spec-driven Flutter delivery with Dashboard Runtime

FlutterCrew adds an observable delivery workflow to your AI assistant. It breaks implementation requests into requirements (REQ-xxx), asks for developer approval before implementation, and records task progress and verification evidence on a local dashboard. Instructions guide the assistant; runtime gates validate recorded state and local checks, not every editor action.

🚀 Why FlutterCrew?

Raw AI assistants generate code inside a black box—deciding architecture unilaterally, silently faking missing backend configs, and triggering expensive late-stage rewrites.

FlutterCrew makes delivery progress and evidence visible:

| 🎰 Raw AI Black Box | 🛡️ The FlutterCrew Way | |---|---| | ❌ Dumps code blindly with zero requirement visibility | 📋 Spec Breakdown: Decomposes prompts into transparent REQ-xxx items with acceptance criteria | | ❌ Unilateral decisions leading to painful rewrites | 👤 Developer Approval Gate: Review & approve the spec before any Dart code is touched | | ❌ Silent mock fallbacks & ignored backend errors | 🚨 Blocker Detection: Automatically halts on missing Firebase/Supabase configs or RLS rules | | ❌ No progress tracking across dozens of files | 📊 Live Dashboard: Real-time browser board tracking tasks from pending to done | | ❌ "Looks good to me" code that fails in production | 🧪 Automated Quality Gates: Enforces dart format, flutter analyze, and unit/widget tests |

💡 Review the scope early to catch missing requirements before implementation. Time and token savings depend on the project; no fixed reduction is guaranteed.

How it works

[1. Intake]          💬 Prompt: "FlutterCrew: Add Firebase Google Sign-In"
      ↓
[2. Spec Breakdown]  📋 Generates REQ-001 (Auth Service) & REQ-002 (Login UI)
      ↓
[3. Dev Approval 👤] 🛑 You review & approve spec BEFORE any code is touched
      ↓
[4. Implementation]  🛠️ Implements Model, Service, Bloc and View cleanly
      ↓
[5. Tests]           🧪 Auto-writes & runs tests mapped to each REQ-xxx
      ↓
[6. Quality Gates]   🛡️ Enforces `dart format` & `flutter analyze --fatal-infos`
      ↓
[7. Done]            🚀 Evidence saved, marked complete on Live Dashboard
      ↓
[8. Feature catalog] 📚 docs/features/<feature>/FEATURE.md updated for devs & agents

Dashboard

Run these commands from the Flutter project:

node .agents/runtime/crew.js dashboard --open

The dashboard summarizes requirements, tasks, workflow stage, verification, and review evidence. In headless environments, start the watcher with node .agents/runtime/crew.js watch.

Requirements

• Node.js 18 or later
• Flutter and Dart SDK for Flutter projects
• A tool-capable AI assistant, such as VS Code Copilot or Antigravity

Install

Create a new project:

npx flutter-crew init

Install workflows in an existing Flutter project:

npx flutter-crew

Run from a local FlutterCrew checkout:

node bin/cli.js /path/to/flutter_project

Inspect available commands and diagnose your environment:

npx flutter-crew --help
npx flutter-crew --version
npx flutter-crew doctor

doctor performs local checks only. It does not deploy, connect to your backend, approve a spec or start a delivery run. A missing SDK or configuration is reported with a next step; a passing diagnosis is not evidence of backend authorization.

Uninstall

Uninstall from the Flutter project:

npx flutter-crew uninstall

Use

For implementation, include FlutterCrew in the request to activate delivery. Advice, review-only and plan-only requests do not start a run, even if they mention the product name. A requirements file is optional.

FlutterCrew: Build a task manager with Firebase Auth and Firestore. Use BLoC, owner-only access, and responsive layouts.

Choose the amount of process appropriate to the task:

| Approach | When to use | Behavior | |---|---|---| | Quick assistance | Questions, review or small direct edits without the keyword | Direct work with relevant checks; no runtime run | | Standard delivery | A bounded implementation request with the keyword | Compact spec and focused implementation/tests, with all delivery gates retained | | Full delivery | Larger, backend or multi-feature implementation with the keyword | Expanded acceptance criteria, vertical slices and review evidence |

These are workflow descriptions, not CLI profile flags. Standard delivery does not bypass approval, traceability, format/analyze/test gates or applicable backend authorization checks. Feature-first BLoC (models/, services/, bloc/, views/) is the default; if the project already uses another state management solution, reuse it, and do not add a mocking library merely to satisfy a template.

For both features and bug fixes, edit production code before writing or updating tests, then execute the relevant tests immediately. Bug fixes still require regression coverage after the fix; there is no test-first exception. Existing tests may be run unchanged during diagnosis.

When blocked, inspect status or the dashboard for the cause and next command:

npx flutter-crew status

Preflight checks infer backend capabilities from source and local configuration: Firebase Auth-only does not require Firestore resources, Firestore requires its rules/indexes/converters, and Storage requires its own rules. Supabase Auth-only does not require application-table migrations; database/RPC/Postgres realtime requires RLS evidence, and Storage requires policies on storage.objects. Unrecognized Supabase usage is checked conservatively as database usage. These are static heuristics, not a Dart/SQL parser or proof of connectivity. Wrappers, generated code or unusual layouts need explicit review; requirement coverage and negative authorization tests remain part of delivery.

IDE support

| Host | Entry point | Delegation | |---|---|---| | VS Code Copilot | Root/project instructions plus .github/agents/ and .github/prompts/ | Native custom agents when the host exposes them | | Claude Code | CLAUDE.md referencing the shared workflow | Shared role guides can be executed sequentially; no claim of native registration | | Gemini / Antigravity | GEMINI.md referencing the shared workflow | Explicit workflow loading when not auto-discovered; sequential fallback | | Cursor | .cursorrules referencing the shared workflow | Host-dependent; sequential fallback | | Other tool-capable assistants | Read AGENTS.md and the shared workflow explicitly | Sequential role passes unless native delegation is available |

.agents/agents/ contains portable role guides, not a universal native-agent registration format. Discovery depends on the host/version and workspace settings. This repository tests customization contracts; it does not simulate each IDE or guarantee that every host loads files automatically.

Frequently Asked Questions

FlutterCrew does not replace your AI assistant—it acts as an engineering fleet orchestrator & quality gatekeeper. While raw AI assistants generate code without boundaries or spec tracking, FlutterCrew enforces structured requirement breakdown (REQ-xxx), waits for your explicit approval before modifying code, detects blocked tasks, runs automated verifications, and gives you a visual dashboard.

No! Interact normally for rapid, ad-hoc coding or quick Q&A. Include FlutterCrew in an implementation request when you want delivery with specs, approval gates and verification evidence. Review, advice and plan-only requests remain read-only with respect to runtime runs even when they mention the keyword.

FlutterCrew natively supports Firebase (Auth, Firestore, Security Rules, Storage) and Supabase (Auth, PostgreSQL Schema, RLS Policies, Realtime, Storage), as well as pure offline or client-only Flutter applications (none).

Documentation

• Delivery workflow
• Spec-driven development
• Project instructions

Development and validation

npm run check
npm test
npm run test:flutter-smoke

License

MIT