FuseFlow v4

AI-native Flutter automation. 20-line config → store-published app.

FuseFlow v4 is a generator-first framework that turns a single YAML file into a production-grade Flutter project with full TDD, CI/CD, monitoring, and zero boilerplate decisions.

Quick start

# Install
npm install -g fuseflow

# Scaffold a config
cd my-project
fuseflow init

# Edit fuseflow.yaml (takes ~2 minutes)
# Then:
fuseflow setup

# Done. Run the same four workflows in your IDE:
# Claude Code: /plan /build /refresh /launch
# Cursor: /feature-spec /feature-build /framework-refresh /release-launch
# (Cursor’s built-in /plan is Plan mode — use /feature-spec for FuseFlow specs.)

AI-driven bootstrap (any assistant)

When you want your model to choose a minimal set of project files and write tailored rules/skills—usable from a cloud chat or any IDE—use fuseflow bootstrap after editing fuseflow.yaml:

fuseflow bootstrap                       # FUSEFLOW_BOOTSTRAP.md + fuseflow-context.json
fuseflow bootstrap --stdout              # same, and print the prompt (copy/paste)
fuseflow bootstrap --emit-deterministic  # hybrid: + analyzer, hooks, MCP, project.config.yaml

| Path | Role | |------|------| | FUSEFLOW_BOOTSTRAP.md | Two-phase instructions (manifest first, then apply); model-agnostic | | fuseflow-context.json | Validated stack facts: packages, MCP list, test points, skill hints |

For a full batteries-included scaffold (widgets, commands, pubspec, CI, …), keep using fuseflow setup below.

What you get

After fuseflow setup, your project has a minimal core scaffold (Claude Code + Cursor):

| File | What it does | |---|---| | AGENTS.md + CLAUDE.md | ≤50-line AI instruction file; CLAUDE.md is a symlink | | analysis_options.yaml | very_good_analysis + 9 custom_lint rules, stack-specific | | pubspec.yaml | Only the packages your stack needs | | .mcp.json + .cursor/mcp.json | Same MCP config (Dart/Flutter, Figma, Firebase, Maestro, …) | | lib/core/widgets/ | 6 base widgets (AppButton, AppErrorState, ShimmerList…) | | .claude/hooks/ | 5 scripts: secret-guard, command-safety, post-edit-analyze, format, coverage | | .cursor/hooks.json + .cursor/hooks/ | Cursor hooks: shell safety, format + dart analyze after Dart edits | | codemagic.yaml / .github/workflows/ | Full 3-branch CI/CD pipeline | | l10n.yaml + lib/l10n/app_en.arb | l10n scaffold with ICU plural support | | project.config.yaml | Source of truth for /refresh / /framework-refresh | | .claude/commands/ | plan.md, build.md, refresh.md, launch.md | | .cursor/commands/ | feature-spec.md, feature-build.md, framework-refresh.md, release-launch.md | | .claude/skills/ | Domain skills (Cursor also auto-loads this path) | | lib/ core scaffold | main.dart, router, theme |

Everything else is generated on-demand when you run /build <feature> (Claude) or /feature-build <feature> (Cursor).

The 4 commands

/plan <feature>

Spec-driven planning phase. Creates docs/plans/<feature>.md with user stories, architecture, test points, analytics, l10n requirements. Human confirmation gate: code generation is blocked until you type confirm.

/build <feature>

The core loop. Runs 9 automated steps:

1. Load skill from reference-map
2. Generate RED tests (failing)
3. Implement feature (GREEN)
4. Self-healing test loop
5. Coverage gate (100% default)
6. Golden test generation
7. Analytics event injection
8. 5 parallel review subagents
9. Commit + PR

/refresh

3-way merge framework upgrades. Replaces unchanged files silently. Prompts for files you've modified.

/launch [ramp N | pause | hotfix]

Full release pipeline:

• Pre-flight: tests + security + app-size + E2E
• Version bump + changelog
• Signed builds → stores
• Phased rollout: 5% → 25% → 100%
• Shorebird OTA for Dart-only hotfixes

fuseflow.yaml reference

project: kart                     # app name
bundle_id: com.yourco.kart        # iOS bundle ID / Android package
mode: new                         # new | continue | fix

# Stack (suggested presets — any AI-generated string is accepted and passed through)
architecture: clean               # e.g. clean | mvvm | Layered | hexagonal
state: riverpod                   # e.g. riverpod | bloc | riverpod + hooks
backend: firebase                 # e.g. firebase | supabase | rest | graphql | none
auth: firebase                    # e.g. firebase | supabase | jwt | oauth | none

# Design
design_source: figma              # figma | none | freeform (Figma MCP if "figma" appears)
figma_url: https://figma.com/file/XXX/MyApp

# CI/CD
ci: codemagic                     # codemagic → codemagic.yaml; github_actions / other → .github/workflows/ci.yaml; none | bitrise → no workflow file
flavors: [dev, staging, prod]

# Platforms
platforms: [ios, android]

# Testing
e2e: maestro                      # presets: maestro | patrol | both | none; any other value is kept as the E2E primary label
coverage_threshold: 100           # must be one of: 100 | 90 | 85 | 80

# OTA
ota: shorebird                    # e.g. shorebird | none | freeform (Shorebird tooling if name contains "shorebird")

# Screens (drives test-point inference)
screens:
  - name: auth
    type: auth
  - name: products
    type: crud_list
  - name: checkout
    type: payment
  - name: profile
    type: profile

Architecture overview

3-tier system

Tier 1 — Universal logic (ships in npm package, never copied to project)

• CLI, validator, generator engine
• Universal hooks: secret-guard, command-safety, test-coverage-audit
• Universal rules: security, TDD, backend boundary, copyright
• Test-points catalog (TP-xxx + PATTERN-xxx taxonomy)
• Reference map: canonical GitHub repo per (feature × stack)
• All Tier-3 templates

Tier 2 — Universal templates (copied once, user-owned)

• AGENTS.md / CLAUDE.md
• BUG_PATTERNS.md
• .gitignore / .claudeignore

Tier 3 — Project-generated (regenerated by /refresh)

• Stack-specific rules and skills
• All commands
• pubspec.yaml, analysis_options.yaml
• Base widgets
• CI/CD config
• Feature scaffolds

Generated-by headers

Every generated file carries:

# generated-by: [email protected]
# template:     <template-name>
# config-hash:  abc123ef
# regenerate:   fuseflow refresh

/refresh uses these headers for safe 3-way merging.

MCP integration

FuseFlow v4 writes the same MCP definition to .mcp.json (Claude Code and other tools) and .cursor/mcp.json (Cursor) so the full AI toolchain is configured in either IDE:

| MCP server | Purpose | |---|---| | Dart/Flutter MCP | Code analysis, pub.dev, hot reload, test runner | | Figma MCP | Design tokens, components, Code Connect | | Firebase MCP | Auth, Firestore, Remote Config | | Maestro MCP | E2E flow authoring, screenshots | | iOS Simulator MCP | Screenshots, hot restart | | GitHub MCP | Issues, PRs, code search |

Testing pyramid

                E2E (Maestro / Patrol)
               ─────────────────────────
                Nightly + /launch only

           Widget tests (per feature)
          ─────────────────────────────────
           Golden tests (Alchemist)
           Accessibility (meetsGuideline)

     Unit tests (per feature)
    ─────────────────────────────────────────
     Business logic, repos, use cases
     Coverage gate: 100% (with ignore markers)

New in v4

• Golden tests (Alchemist) — platform goldens for dev, Ahem-font CI goldens for stability
• Accessibility matchers — meetsGuideline in every widget test
• l10n completeness tests — all locales, all plural forms
• osv-scanner — pubspec.lock vulnerability scanning in CI

Key improvements over v3

| Area | v3 | v4 | |---|---|---| | Intake | ~9-section markdown, 30–60 min | 20-line YAML, 2 min | | Commands | 9+ project-specific | 4 universal | | AGENTS.md | Generated with all rules | ≤50 lines, human-curated | | MCP | Figma only | 6 servers auto-configured | | E2E | Patrol only | Maestro (default) + Patrol (pluggable) | | Coverage default | 85% | 100% (VGV standard) | | Golden tests | Optional | Default (Alchemist) | | A11y testing | TP-A11y listed | meetsGuideline in every widget test | | Planning | /build directly | /plan gate → /build | | Review | Single PR review | 5 parallel subagents | | OTA | Not wired | Shorebird hotfix flow | | CI default | Either | Codemagic M2/M4 (iOS-heavy) |

Codemagic vs GitHub Actions

Codemagic (default for iOS-heavy teams)

• M2 runners are ~2× faster than stock GitHub macos-15
• Fixed-price unlimited M2 plan: $3,990/yr for >250 builds/month
• Auto code-signing via Magic Actions

GitHub Actions (for teams already on GH)

• Use with self-hosted macOS runners (Blacksmith, Namespace, WarpBuild)
• Stock macos-15 runners can exceed 45-minute timeouts on full Flutter builds
• Set ci: github_actions in fuseflow.yaml

Shorebird OTA constraints

Shorebird patches Dart code only.

❌ Cannot patch:

• Native plugin additions/removals
• AndroidManifest.xml / Info.plist
• Gradle / Xcode project settings
• Flutter engine version

No on-prem/self-host option (Shorebird SaaS only). Healthcare/fintech teams with data-residency requirements: use full store release instead.

Security

• secret-guard.sh: blocks .env commits and common secret patterns
• command-safety.sh: warns on high-impact CLI commands
• osv-scanner: pubspec.lock vulnerability scanning (every PR)
• OWASP Mobile Top 10 skill: loaded automatically for auth/payment screens
• post-edit-analyze.sh: blocking dart analyze after every file edit (exit 2)
• Apple Privacy Manifest: generated at /launch for iOS

License

MIT — see LICENSE

Contributing

See docs/03-ROADMAP.md for planned improvements. Issues and PRs welcome.