maxsim-flutter

AI-powered Flutter app scaffolding with Clean Architecture, Riverpod state management, go_router navigation, and autonomous development via Claude Code Agent Teams.

Features

• Scaffold a complete Flutter app with Clean Architecture from a single command
• Interactive prompts or fully non-interactive mode with --yes and --config
• Nine opt-in feature modules (auth, API client, database, theming, i18n, push notifications, analytics, CI/CD, deep linking)
• Generates a .claude/ directory with CLAUDE.md, agent definitions, and skills so Claude Code can continue development autonomously
• add command to bolt modules onto an existing project after initial creation
• migrate command that analyses an existing Flutter project and generates a migration plan with prd.json stories
• maxsim.config.yaml written to the project root for reproducible re-runs
• Dry-run mode to preview all generated files before committing

Requirements

• Node.js >= 18
• Flutter SDK (optional at scaffold time; required to build and run the generated app)

Installation

Install globally:

npm install -g maxsim-flutter

Or run without installing:

npx maxsim-flutter <command>

Quick Start

# Interactive: answer prompts for name, org, modules, and platforms
maxsim-flutter create

# Non-interactive: create an app called "my_app" with auth and API modules
maxsim-flutter create my_app --org com.example --modules auth,api --yes

# After creation, enter the project directory and run the app
cd my_app
flutter pub get
flutter run

Commands

maxsim-flutter create [app-name]

Creates a new Flutter project with Clean Architecture, Riverpod, and go_router.

If app-name is omitted and --yes is not set, an interactive prompt is shown.

Flags

| Flag | Description | |------|-------------| | --org <id> | Organisation identifier, e.g. com.example (default: com.example) | | --modules <list> | Comma-separated list of modules to enable, e.g. auth,api,theme | | --platforms <list> | Comma-separated target platforms: android,ios,web,macos,windows,linux (default: android,ios) | | --auth-provider <provider> | Auth provider when auth module is included: firebase, supabase, or custom | | --config <file> | Path to a maxsim.config.yaml preset file — skips all prompts | | --yes | Accept all defaults without prompting | | --dry-run | Preview generated files without writing anything to disk | | --no-claude | Skip generating the .claude/ directory and CLAUDE.md |

Examples

# Interactive
maxsim-flutter create

# Minimal non-interactive
maxsim-flutter create shop_app --org com.acme --yes

# Full feature set, non-interactive
maxsim-flutter create shop_app \
  --org com.acme \
  --modules auth,api,database,theme,i18n \
  --platforms android,ios,web \
  --auth-provider firebase \
  --yes

# Load a saved configuration file
maxsim-flutter create --config ./my-preset.yaml

# Preview without writing
maxsim-flutter create my_app --yes --dry-run

maxsim-flutter add [module]

Adds a feature module to an existing maxsim-flutter project. The command searches for maxsim.config.yaml in the current directory and up to five parent directories.

If module is omitted, an interactive selection prompt is shown listing only modules not yet enabled in the project.

Flags

| Flag | Description | |------|-------------| | --project-dir <path> | Path to the project directory (default: current directory) | | --dry-run | Preview files that would be generated without writing |

Examples

# Interactive: pick from available modules
maxsim-flutter add

# Add a specific module
maxsim-flutter add push

# Add to a project in another directory
maxsim-flutter add analytics --project-dir ~/projects/my_app

# Preview what the database module would generate
maxsim-flutter add database --dry-run

Available module identifiers: auth, api, theme, database, i18n, push, analytics, cicd, deep-linking

maxsim-flutter plan [app-name]

Bootstrap an AI-guided planning workspace before creating your Flutter app. The plan command collects your project name and a short description, then generates three artifacts:

| Artifact | Path | Purpose | |----------|------|---------| | Planning skill | .claude/skills/plan-app.md | 9-step Claude Code skill that guides you from vision to PRD | | Brief template | docs/project-brief-template.md | Structured template for problem statement, user journeys, non-goals | | Partial config | maxsim.config.yaml | Pre-filled with project name and description |

Arguments

| Argument | Description | |----------|-------------| | [app-name] | Project name in snake_case (prompted if omitted) |

Flags

| Flag | Description | |------|-------------| | --description <text> | Short description of the app (1-2 sentences; prompted if omitted) |

Examples

# Interactive — prompts for name and description
maxsim-flutter plan

# Non-interactive
maxsim-flutter plan my_team_app --description "A chat app for small teams."

Workflow

# 1. Bootstrap the planning workspace
maxsim-flutter plan my_app

# 2. Navigate to the new directory and open Claude Code
cd my_app
claude

# 3. Run the AI planning skill (guides you through 9 steps)
/plan-app

# 4. After Claude generates maxsim.config.yaml with your chosen modules, scaffold
maxsim-flutter create --config maxsim.config.yaml

The /plan-app skill leads Claude through:

1. Understanding your app's vision and core problem
2. Defining core features and explicit non-goals
3. Technical decisions (auth provider, database, platforms)
4. Context-aware module suggestions (REQUIRED / RECOMMENDED / NICE-TO-HAVE)
5. Confirmation and approval
6. Generating docs/project-brief.md
7. Generating docs/architecture.md with Riverpod provider tree and go_router navigation flow
8. Generating complete maxsim.config.yaml
9. Generating prd.json v2 with stories derived from user journeys

maxsim-flutter migrate [path]

Analyses an existing Flutter project and, optionally, migrates it to maxsim conventions. Detected architecture, state management, routing, and dependencies are reported. On confirmation the command writes maxsim.config.yaml, generates a .claude/ directory, and creates a prd.json file containing story-by-story migration tasks.

Arguments

| Argument | Description | |----------|-------------| | [path] | Path to the Flutter project root (default: current directory) |

Flags

| Flag | Description | |------|-------------| | --analysis-only | Print the analysis report without making any changes | | --yes | Skip the confirmation prompt and apply migration immediately |

Examples

# Analyse the project in the current directory without making changes
maxsim-flutter migrate --analysis-only

# Analyse a project at a specific path
maxsim-flutter migrate ~/projects/legacy_app --analysis-only

# Migrate with confirmation prompt
maxsim-flutter migrate

# Migrate without prompting
maxsim-flutter migrate ~/projects/legacy_app --yes

The migration writes non-destructively: if maxsim.config.yaml, CLAUDE.md, or prd.json already exist they are skipped.

Modules

The core module is always included. All other modules are opt-in.

| Module | ID | Description | Options | |--------|----|-------------|---------| | Core | core | Base Clean Architecture structure with Riverpod state management and go_router navigation | Always included | | Authentication | auth | User authentication with login, register, and session management | Provider: firebase (default), supabase, custom | | API Client | api | HTTP client setup with Dio, interceptors, and typed error handling | Base URL (configurable) | | Theme | theme | Advanced Material 3 theming with seed colors, dark/light mode switching via Riverpod | Seed color, dark mode toggle | | Database | database | Local database persistence | Engine: drift / SQLite (default), hive / NoSQL, isar / NoSQL | | Internationalization | i18n | Multi-language support with ARB files and Flutter localization | Default locale | | Push Notifications | push | Push notification support | Provider: firebase / FCM (default), onesignal | | Analytics | analytics | Analytics event tracking and route observation via Firebase Analytics | — | | CI/CD | cicd | Continuous integration and deployment pipeline configuration | Provider: github (default), gitlab, bitbucket | | Deep Linking | deep-linking | Deep link and universal link handling via app_links with go_router integration | URL scheme, host domain |

Agent Teams Workflow

Every generated project includes a .claude/ directory pre-configured for Claude Code Agent Teams. This enables autonomous AI-assisted feature development after the initial scaffold.

Prerequisites

• Claude Code installed and authenticated
• Enable the experimental agent teams feature:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Step-by-step guide

1. Scaffold the project

maxsim-flutter create task_manager --org com.example --modules auth,api --yes
cd task_manager

2. Review the generated prd.json

The scaffold generates a prd.json containing phase-by-phase user stories for the enabled modules. Review and adjust stories to match your product requirements before starting the agent team.

3. Start a Claude Code session in the project

claude

4. Instruct Claude Code to form a team

Create an agent team from prd.json. Spawn an architect, two builders,
a tester, and a reviewer. Implement the PRD stories phase by phase.

Claude Code reads the .claude/agents/ directory, creates a shared task list from prd.json, and coordinates the agents:

• Architect plans the implementation approach for each story
• Builders implement code following the Clean Architecture layers
• Tester writes unit and widget tests for new code
• Reviewer performs code review and enforces quality gates

5. Monitor progress

Agents communicate via the Claude Code task system. Use /tasks in your session to see the current state. Each story commit follows the format:

feat: [Story-ID] - Story Title

6. Quality gates

Each story must pass the following before being marked complete:

flutter analyze        # zero errors
flutter test           # all tests pass
dart format --set-exit-if-changed .

7. Continue development after initial scaffold

To add a new module and have the agent team implement it:

maxsim-flutter add push

The command regenerates CLAUDE.md with updated context. Tell Claude Code:

Implement the push notifications module stories from prd.json.

Configuration Reference

Every project includes a maxsim.config.yaml at its root. You can edit this file and re-run scaffold commands.

version: "1"

project:
  name: my_app                  # Flutter package name (snake_case)
  orgId: com.example            # Reverse-DNS organisation ID
  description: "My Flutter app" # Optional description
  minSdkVersion: "21"           # Optional minimum Android SDK version

platforms:
  - android
  - ios
  # also supported: web, macos, windows, linux

modules:
  auth:
    enabled: true
    provider: firebase          # firebase | supabase | custom

  api:
    enabled: true
    baseUrl: https://api.example.com
    timeout: 30000              # Optional request timeout in milliseconds

  database:
    enabled: true
    engine: drift               # drift | hive | isar

  theme:
    enabled: true
    seedColor: "#6750A4"        # Optional Material 3 seed color (hex)
    useMaterial3: true
    darkMode: true

  i18n:
    enabled: true
    defaultLocale: en
    supportedLocales:
      - en
      - es

  push:
    enabled: true
    provider: firebase          # firebase | onesignal

  analytics:
    enabled: true

  cicd:
    enabled: true
    provider: github            # github | gitlab | bitbucket
    targets:
      - android
      - ios

  deep-linking:
    enabled: true
    scheme: myapp               # Custom URL scheme, e.g. myapp://
    host: example.com           # Universal link host

claude:
  enabled: true                 # Generate .claude/ directory (default: true)
  generateAgents: false         # Generate agent definition files
  generateSkills: false         # Generate skill files
  generateHooks: false          # Generate hook files
  agentTeams: false             # Enable agent teams configuration
  mcpServers: []                # MCP server names to include

ralph:
  enabled: false                # Enable Ralph autonomous loop
  maxIterations: 25             # Maximum Ralph iterations

scaffold:
  overwriteExisting: ask        # ask | always | never
  runDartFormat: true           # Run dart format after scaffolding
  runPubGet: true               # Run flutter pub get after scaffolding
  runBuildRunner: false         # Run build_runner after scaffolding
  dryRun: false                 # Preview only, do not write files

Contributing

We welcome contributions! See CONTRIBUTING.md for:

• Development setup and build instructions
• How to add a new module (step-by-step walkthrough)
• Template guidelines and conventions
• TDD workflow and quality gates
• Pull request process

For a deep dive into how the subsystems fit together, see docs/architecture.md.

Changelog

See CHANGELOG.md for release history.

License

MIT. See LICENSE for details.