{
  "markdown": "[![CI](https://github.com/tsnAnh/flutter-agentic-starter/actions/workflows/dart.yml/badge.svg)](https://github.com/tsnAnh/flutter-agentic-starter/actions/workflows/dart.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Flutter](https://img.shields.io/badge/Flutter-3.44+-blue.svg)](https://flutter.dev)\n[![Dart](https://img.shields.io/badge/Dart-3.10+-blue.svg)](https://dart.dev)\n[![style: flutter_lints](https://img.shields.io/badge/style-flutter__lints-blue.svg)](https://pub.dev/packages/flutter_lints)\n\n# Flutter Agentic Starter\n\nProduction-ready Flutter starter built for AI-assisted development with Signals\nand Clean Architecture. Its predictable feature structure, project skills,\nsetup wizard, and generated catalog let coding agents start shipping without\nrepeated architecture prompts.\n\n## Why this starter?\n\n| Capability | Included |\n| --- | :---: |\n| AI instruction files and project skills | ✅ |\n| Signals-based Clean Architecture | ✅ |\n| Setup wizard and multi-flavor entry points | ✅ |\n| Firebase, analytics, cache, and offline queue | ✅ |\n| Generated Widgetbook catalog | ✅ |\n\n## Stack\n\n- Signals 7 for reactive presentation and service state\n- GetIt + Injectable for composition\n- GoRouter for navigation\n- Dio + fpdart for typed network results\n- Hive for local cache and offline writes\n- Freezed + json_serializable for immutable wire/domain models\n- Flutter localization, Material 3, Firebase, and PostHog integrations\n\n## Architecture\n\n```mermaid\ngraph TD\n    subgraph Presentation\n        W[Widgets] --> VM[Signals ViewModels]\n    end\n\n    subgraph Domain\n        VM --> U[Use Cases]\n        U --> R[Repository Contracts]\n        R --> M[Domain Models]\n    end\n\n    subgraph Data\n        RI[Repository Implementations] --> A[API / Dio]\n        RI --> C[Cache / Hive]\n    end\n\n    subgraph Core\n        DI[GetIt / Injectable]\n        RO[GoRouter]\n        DS[Theme / Design System]\n    end\n\n    R --> RI\n    DI --> VM\n    DI --> RI\n    W --> RO\n    W --> DS\n```\n\nFeatures use `data/domain/presentation` boundaries:\n\n```text\nScreen -> ViewModel -> Use case -> Repository -> Data source\n   ^          |\n   +-- ReadonlySignal<AsyncState<T>>\n```\n\nView models own private mutable signals and expose read-only signals. Screens\nreceive their view model at the route boundary and rebuild with `SignalWidget`\nor a focused `SignalBuilder`. Services may expose signals for app-wide state,\nsuch as `SessionManager.active`, `ConnectivityService.online`, and\n`OfflineQueueService.pendingCount`.\n\nSee [System architecture](docs/system-architecture.md) and\n[Code standards](docs/code-standards.md).\n\n## Features\n\n| Module | Description | Key packages |\n| --- | --- | --- |\n| **State** | Reactive presentation and service state | Signals |\n| **Network** | HTTP client, authentication, caching, retry, and connectivity interceptors | Dio |\n| **Auth** | Session and in-memory token state | Signals, Dart SDK |\n| **Cache** | Memory and persistent cache policies | Hive, Hive Flutter |\n| **Connectivity** | Network monitoring and offline request replay | Connectivity Plus, Hive |\n| **DI** | Generated dependency injection | GetIt, Injectable |\n| **Router** | Declarative routing and deep links | GoRouter, App Links |\n| **Models** | Immutable wire and domain models | Freezed, json_serializable |\n| **Widgets** | Responsive shared widgets and generated component catalog | ScreenUtil, Widgetbook |\n| **Firebase** | Analytics, Crashlytics, Remote Config, Messaging, and App Check | Firebase |\n| **Analytics** | Composite analytics providers | Firebase Analytics, PostHog |\n| **Permissions** | Runtime permission handling | Permission Handler |\n| **Forms** | Validated reusable form inputs | Formz |\n| **Lifecycle** | App lifecycle and update checks | Flutter SDK |\n| **Logger** | Debug and production logging | Logger |\n| **Localization** | Generated localized strings | Flutter localization, intl |\n\n## Quick Start\n\n```sh\n# 1. Use this template, then clone your repository\ngit clone https://github.com/YOUR_USERNAME/your-app-name.git\ncd your-app-name\n\n# 2. Install dependencies\nflutter pub get\n\n# 3. Configure the template\ndart run project_setup\n\n# 4. Generate code\ndart run build_runner build --delete-conflicting-outputs\n\n# 5. Run the development entry point\nflutter run -t lib/main.dart\n```\n\nAvailable entry points:\n\n- `lib/main.dart`\n- `lib/main_staging.dart`\n- `lib/main_production.dart`\n\n## Widgetbook\n\nGenerate the catalog after adding or changing a use case:\n\n```sh\ndart run build_runner build --delete-conflicting-outputs\n```\n\nRun Widgetbook locally in Chrome:\n\n```sh\nflutter run -t lib/widgetbook/widgetbook.dart -d chrome\n```\n\n## Project Structure\n\n```text\nlib/\n├── app.dart\n├── main.dart\n├── main_staging.dart\n├── main_production.dart\n├── core/\n│   ├── analytics/\n│   ├── assets/\n│   ├── auth/\n│   ├── cache/\n│   ├── connectivity/\n│   ├── design_system/\n│   ├── di/\n│   ├── extensions/\n│   ├── firebase/\n│   ├── lifecycle/\n│   ├── logger/\n│   ├── network/\n│   ├── permissions/\n│   ├── router/\n│   ├── theme/\n│   └── utils/\n├── features/\n│   └── home/\n│       ├── data/\n│       ├── domain/\n│       └── presentation/\n├── shared/\n│   ├── data/\n│   ├── forms/\n│   ├── i18n/\n│   ├── services/\n│   └── widgets/\n└── widgetbook/\n    ├── use_cases/\n    ├── widgetbook.dart\n    └── widgetbook.directories.g.dart\n```\n\n## Create a feature\n\n1. Add the domain model, repository contract, and use case.\n2. Implement the data source and repository.\n3. Add an injectable `*ViewModel` with private `Signal` state.\n4. Pass the view model from GoRouter into the screen.\n5. Add focused view-model and widget tests.\n6. Regenerate Injectable/Freezed/JSON code.\n\nThe Home feature is the reference implementation:\n`lib/features/home/`.\n\n## Customize the template\n\n```sh\ndart run project_setup \\\n  --app-name \"Your App\" \\\n  --dart-package-name your_app \\\n  --app-id com.example.yourapp \\\n  --organization Example \\\n  --yes\n```\n\nThe checked-in template identity is:\n\n- App name: `Flutter Agentic Starter`\n- Dart package: `flutter_agentic_starter`\n- Organization: `Example`\n- Application ID: `dev.example.flutteragenticstarter`\n\n## Verification\n\n```sh\nflutter analyze\nflutter test\nflutter build apk --release -t lib/main_staging.dart\n```\n\n## AI Agent Guide\n\n### What Makes This Agent-Ready\n\nUse `flutter-agentic-starter` only when implementing Flutter application code\nunder `lib/`, Flutter tests, or platform integration required by that code. It\ndoes not apply to documentation, setup tooling, repository automation, or other\nnon-app maintenance.\n\n- **Clean separation** — predictable `data/domain/presentation` boundaries\n- **Signals conventions** — private mutable signals and public read-only state\n- **Generated DI** — add Injectable annotations and regenerate\n- **Preconfigured guidance** — `CLAUDE.md`, `AGENTS.md`, Cursor rules, and project skills\n\n### Available Skills\n\n- `flutter-agentic-starter` — Flutter/Signals/Clean Architecture rules\n- `caveman` — concise technical communication\n- `frontend-design` — polished user-facing Flutter UI\n\n### Supported Tools\n\nWorks with Claude Code, Codex, OpenCode, Cursor, GitHub Copilot, Windsurf, and\nother coding assistants that can read repository instructions.\n\n### Example Prompts\n\n```text\n\"Add a profile feature with a Signals ViewModel, use case, repository, and screen\"\n\"Create an immutable Order model with Freezed and JSON serialization\"\n\"Add a typed /users API flow with Dio and fpdart\"\n\"Add a shared widget and cover its states in Widgetbook\"\n```\n\n## Configuration\n\n### Flavors\n\n| Flavor | Entry point | Use case |\n| --- | --- | --- |\n| Development | `lib/main.dart` | Local development |\n| Staging | `lib/main_staging.dart` | QA and internal testing |\n| Production | `lib/main_production.dart` | Release builds |\n\n### Environment Setup\n\nEach flavor can configure its API, Firebase project, analytics, and feature\nflags through `lib/core/flavor_configurations.dart` and generated DI.\n\n## Showcase\n\nProjects built with this template:\n\n- [bit](https://github.com/tsnAnh/bit) — Flutter reader for Medium articles\n\nBuilt something with this template? Open a pull request to add it here.\n\n## Contributing\n\nContributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## License\n\n[MIT](LICENSE) — tsnAnh\n\nSee the [documentation index](docs/README.md) for detailed guides.\n",
  "bytes": 8387,
  "sha": "3d264f892595d815e7deb54c7d8a3c195c61fc7e9306af6366e934cb115ee7b0",
  "repo_slug": "tsnanh/flutter-agentic-starter",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_tsnanh_flutter_agentic_starter_okf_memor_877a7336/readme"
}