Flutter × Ts.ED Framework

Build production Flutter apps faster. TDD-first. AI-guided. Zero boilerplate.

One framework. Any Flutter app. Any backend. Any team size.

Install

npm install -g @boscdev/flutter-tsed-framework
flutter-tsed setup-claude    # for Claude Code
flutter-tsed setup-cursor    # for Cursor

That's it. Nothing is created in your project yet — no folders, no files.

Start your project

Run this one command inside your IDE and answer the questions:

/setup

The wizard asks about your project once, then generates everything: folder structure, dependencies, env files, git branches, IDE run configs.

After /setup completes, it tells you exactly what to do next.

Build your first feature

One command handles the full lifecycle — research → plan → tests → code → review → PR. It stops at every gate and waits for your approval before moving on.

/build "home screen"
/build "user profile"  --from-ticket APP-42
/build "checkout flow" --figma https://figma.com/file/xxx

Foundation steps (do once, in order)

/theme     colours + typography + dark/light mode
/splash    native splash screen + intro animation
/icon      launcher icons for every platform
/auth      authentication module (screens + tests)

Then build features with /build.

Ship

/gate --pre-release    all quality checks
/launch minor          version bump + CHANGELOG + CI trigger

Daily commands

| Command | Purpose | |---|---| | /build <feature> | Full TDD lifecycle (daily driver) | | /patch <description>| Fix a bug (failing test first) | | /gate | Run all quality checks | | /qa <feature> | 8-dimension code review | | /status | Project health dashboard | | /ops | Git branches + environment files |

All commands (29)

Setup

/setup /theme /splash /icon /auth

Features

/build /build-api /design /patch /add /port /scan

Quality

/gate /qa /bugs /a11y /perf /offline /store /sync

Operations

/ops (git + env) · /launch <patch|minor|major> · /ticket fetch|start|done

Utility

/ask /cleanup /catalogue /doc /status /plan

Run /setup first. Run any command with no arguments to see its help.

Environments

The framework supports up to three environments. /setup asks which you need:

• A — production only (≤ 6 screens, prototype, simple app)
• B — dev + production (default — most apps)
• C — dev + staging + production (teams with QA / TestFlight)

Run / build

# Dev
flutter run --dart-define-from-file=env/dev.json --flavor dev

# Production build
flutter build appbundle --release \
  --obfuscate --split-debug-info=build/debug-info \
  --flavor prod \
  --dart-define-from-file=env/prod.json

Tier A (no flags needed)

flutter run
flutter build apk --release

/setup generates VS Code launch configs and Codemagic workflows automatically — you don't type these commands by hand.

Why dart-define-from-file (not dotenv)

flutter_dotenv ships your .env as a readable asset inside the APK. Anyone who unzips the APK can read every key. --dart-define-from-file injects values as compile-time constants instead, which are baked into the obfuscated binary and not extractable.

Git branching

main              production releases only. Tagged. Never push directly.
develop           integration. All features merge here first.
feat/<name>       new features, branch from develop
fix/<name>        bug fixes, branch from develop
hotfix/<name>     urgent prod fixes, branch from main
release/<ver>     stabilization, branch from develop

/ops git new feat my-feature and /ops git finish feat my-feature handle everything.

FAQ

Q: What backend does this support? A: Any. Ts.ED, Node/Express, Supabase, Firebase, hybrid, or an external API (give it a Swagger URL). /setup asks and configures everything accordingly.

Q: What platforms does this support? A: Android and iOS by default. /setup lets you add web, Windows, Linux, macOS, or watchOS. Each adds the right platform config and responsive layout helpers.

Q: I have a PRD — do I have to answer all the wizard questions? A: No. /setup accepts your PRD file or paste, parses the fields, and only asks about things it couldn't determine. A complete PRD means zero manual questions.

Q: What if I only have a frontend and my backend team manages the API? A: Choose external in /setup and paste the Swagger URL. The framework generates Dart models from the contract and auto-mocks API calls. When the real backend is ready, /sync makes it live.

Q: What architecture does it use? A: It asks you. /setup recommends MVC, MVVM, Clean, or Layered based on screen count and project summary. Simple apps (≤ 6 screens) default to MVC.

Q: Can I use this on an existing project? A: Yes. Run /setup --scan to detect your existing architecture, state management, and router. It writes the config and leaves your code untouched.

Q: I'm on v1 — how do I upgrade? A: Run flutter-tsed upgrade. It migrates your PROJECT_CONFIG.md → project.config.yaml, converts .env.dev/.env.prod → env/dev.json/env/prod.json, and backs up everything first. See MIGRATION.md.

Q: What rules does the framework enforce?

• Nothing is created until you run /setup
• Resource verification before any service implementation (Firebase keys, Supabase URL, Figma)
• Tests before implementation — RED before GREEN, always
• Module gate — can't start the next feature while the previous has failing tests
• Never push directly to main or develop
• No secrets in committed files — ever

Troubleshooting

Setup command not available Run which npm and flutter-tsed --version to confirm install. Re-run flutter-tsed setup-claude (or setup-cursor).

Command fails with a configuration error The AI prints a ⚠️ CONFIGURATION REQUIRED block with exact steps. Fix the configuration first — never retry with code changes.

Integration test failures Confirm backend.access: true in project.config.yaml. Confirm the backend runs on backend.port. Run backend tests first: cd backend && npm test.

Accidentally committed a secret

git filter-repo --path frontend/env/dev.json --invert-paths
git push --force --tags origin main develop

Then rotate the compromised key immediately.

Links

• Internal architecture: CODEBASE.md
• v1 → v2 migration: MIGRATION.md
• Release history: CHANGELOG.md