Generate a detailed specification document for building a Flutter mobile application using Flutter 3.x (Dart 3.x), Riverpod 2.x for state management, Hive 2.x for local storage, Dio 5.x for REST API with smart retry, Firebase Messaging + flutter_local_notifications for push/event notifications, go_router 14.x for navigation, freezed 2.x + json_serializable for immutable models, and build_runner for code generation. The spec also covers cached_network_image, flutter_svg, pull_to_refresh, font_...
Scanned 5/27/2026
Install via CLI
Skills Directoryopenskills install rashidee/co2-skills---
name: specgen-flutter-riverpod
model: claude-opus-4-6
effort: high
description: >
Generate a detailed specification document for building a Flutter mobile application
using Flutter 3.x (Dart 3.x), Riverpod 2.x for state management, Hive 2.x for local
storage, Dio 5.x for REST API with smart retry, Firebase Messaging + flutter_local_notifications
for push/event notifications, go_router 14.x for navigation, freezed 2.x + json_serializable
for immutable models, and build_runner for code generation. The spec also covers
cached_network_image, flutter_svg, pull_to_refresh, font_awesome_flutter, material_design_icons_flutter,
intl, url_launcher, and flutter_native_splash. Authentication (Keycloak OAuth2/OIDC PKCE
via flutter_appauth, local JWT, or none) and optional features (WebSocket, i18n via intl)
are configurable based on user input.
Standardized input: application name (mandatory), version (mandatory), module (optional).
Use this skill whenever the user asks to create a spec, specification, blueprint, or
technical design document for a new Flutter mobile application.
Also trigger when the user says things like "spec out a new Flutter app", "design a
Flutter app with Riverpod", "write a technical spec for my new mobile app", "scaffold
spec for a Flutter Riverpod app", or any request for a specification document describing
a Flutter + Riverpod + Dio + Hive application. Even if the user only mentions a subset
of the stack (e.g., "Flutter mobile app" or "Flutter with Firebase notifications"),
this skill likely applies — ask and confirm.
---
# Flutter Mobile Specification Generator
This skill generates a comprehensive specification document (Markdown) that serves as a
blueprint for building a Flutter mobile application. The spec is intended to be followed
by a developer or a coding agent to produce a fully functional project scaffold targeting
both Android and iOS.
The specification does NOT generate code. It produces a detailed, opinionated technical
document describing every layer of the application — from `pubspec.yaml` configuration to
Material Theme, from Riverpod providers to Dio retry interceptors — so that implementation
becomes a mechanical exercise.
## Technology Stack
### Core Stack (Always Included)
These are the fixed versions the spec targets. Do not deviate unless the user explicitly
requests different versions.
| Component | Version |
|----------------------------------|-----------|
| Flutter SDK | 3.24.x |
| Dart SDK | 3.5.x |
| flutter_riverpod | 2.5.x |
| riverpod_annotation | 2.3.x |
| riverpod_generator | 2.4.x |
| hooks_riverpod | 2.5.x |
| flutter_hooks | 0.20.x |
| hive | 2.2.x |
| hive_flutter | 1.1.x |
| dio | 5.7.x |
| dio_smart_retry | 6.0.x |
| pretty_dio_logger | 1.4.x |
| go_router | 14.x |
| freezed_annotation | 2.4.x |
| freezed | 2.5.x |
| json_annotation | 4.9.x |
| json_serializable | 6.8.x |
| build_runner | 2.4.x |
| firebase_core | 3.6.x |
| firebase_messaging | 15.1.x |
| flutter_local_notifications | 17.2.x |
| cached_network_image | 3.4.x |
| flutter_svg | 2.0.x |
| pull_to_refresh | 2.0.x |
| font_awesome_flutter | 10.7.x |
| material_design_icons_flutter | 7.0.x |
| intl | 0.19.x |
| url_launcher | 6.3.x |
| flutter_native_splash | 2.4.x |
| flutter_dotenv | 5.2.x |
| path_provider | 2.1.x |
| flutter_secure_storage | 9.2.x |
### Optional Integration Versions
Include in the version table only when the corresponding integration is selected.
| Component | Version | When Selected |
|--------------------------|-----------|-----------------------------|
| Keycloak | 26.x | Auth = Keycloak |
| flutter_appauth | 8.0.x | Auth = Keycloak or OIDC |
| openid_client | 0.4.x | Auth = Keycloak or OIDC |
| web_socket_channel | 3.0.x | WebSocket = yes |
| flutter_localizations | SDK | i18n = yes |
| share_plus | 10.0.x | Sharing = yes |
| image_picker | 1.1.x | ImagePicker = yes |
| file_picker | 8.1.x | FilePicker = yes |
| permission_handler | 11.3.x | Permissions = yes |
| firebase_analytics | 11.3.x | Analytics = yes |
| firebase_crashlytics | 4.1.x | Crashlytics = yes |
## Core Dependencies (pubspec.yaml)
The spec must include these in the `pubspec.yaml` dependencies section (always):
**Runtime dependencies:**
- `flutter` (sdk: flutter) — Core Flutter framework
- `flutter_riverpod` — Riverpod for Flutter
- `riverpod_annotation` — Annotations for riverpod_generator
- `hooks_riverpod` — Riverpod with flutter_hooks integration
- `flutter_hooks` — React-style hooks for Flutter
- `hive` + `hive_flutter` — Local NoSQL key-value database
- `dio` — HTTP client
- `dio_smart_retry` — Retry interceptor for Dio
- `pretty_dio_logger` — Request/response logging in development
- `go_router` — Declarative routing
- `freezed_annotation` — Annotations for freezed code generation
- `json_annotation` — Annotations for json_serializable
- `firebase_core` — Firebase initialization
- `firebase_messaging` — Push notification (FCM)
- `flutter_local_notifications` — Foreground/scheduled local notifications
- `cached_network_image` — Network image with caching and placeholders
- `flutter_svg` — SVG rendering
- `pull_to_refresh` — Smart pull-to-refresh widget
- `font_awesome_flutter` — Font Awesome icons
- `material_design_icons_flutter` — Material Design Icons (MDI)
- `intl` — Internationalization, date/number formatting
- `url_launcher` — Open URLs, dial, mailto, etc.
- `flutter_dotenv` — Load `.env` configuration files
- `path_provider` — Filesystem paths for Hive init
- `flutter_secure_storage` — Encrypted key-value store (keychain/keystore)
**Development dependencies:**
- `flutter_test` (sdk: flutter) — Widget test framework
- `build_runner` — Code generation runner
- `freezed` — Immutable data class generator
- `json_serializable` — JSON serialization generator
- `riverpod_generator` — Riverpod provider generator
- `hive_generator` — Hive type adapter generator
- `flutter_lints` — Recommended lint rules
- `flutter_native_splash` — Native splash screen generator
- `mocktail` — Mock library for unit tests
### Conditional Dependencies
**If Auth = Keycloak or OIDC:**
- `flutter_appauth` — Native OAuth2/OIDC PKCE flow (uses AppAuth Android/iOS)
- `openid_client` — OIDC discovery and token parsing
**If WebSocket = yes:**
- `web_socket_channel` — Cross-platform WebSocket client
**If i18n = yes:**
- `flutter_localizations` (sdk: flutter)
- `intl` is already in core — used for ARB-based message localization
**If Analytics = yes:**
- `firebase_analytics`
**If Crashlytics = yes:**
- `firebase_crashlytics`
**If ImagePicker = yes:**
- `image_picker`
- `permission_handler` (for camera/photo permissions)
**If FilePicker = yes:**
- `file_picker`
**If Sharing = yes:**
- `share_plus`
## When the Skill Triggers
Generate the spec when the user provides an **application name** and **version** that
corresponds to one of the custom applications defined in `CLAUDE.md`. The skill
reads all required inputs from the project's context files — no interactive Q&A is needed
for the core inputs.
The user invokes this skill by specifying the target application and version, for example:
- `/specgen-flutter-riverpod mobile v1.0.4`
- `/specgen-flutter-riverpod mobile v1.0.4 module:Hero Section`
- `/specgen-flutter-riverpod "Field Worker App" v1.0.4`
The skill then locates the matching context folder and reads all input files automatically.
## Version Gate
Before starting any work, resolve the application folder first (see Input Resolution below), then check `CHANGELOG.md` in the application folder (`<app_folder>/CHANGELOG.md`):
1. If `<app_folder>/CHANGELOG.md` does not exist, skip this check (first-ever execution for this application).
2. If `<app_folder>/CHANGELOG.md` exists, scan all `## vX.Y.Z` headings and determine the **highest version** using semantic versioning comparison.
3. Compare the requested version against the highest version:
- If requested version **>=** highest version: proceed normally.
- If requested version **<** highest version: **STOP immediately**. Print: `"Version {requested} is lower than the current application version {highest} recorded in <app_folder>/CHANGELOG.md. Execution rejected."` Do NOT proceed with any work.
## Input Resolution
This skill uses standardized input resolution. Provide:
| Argument | Required | Example | Description |
|----------|----------|---------|-------------|
| `<application>` | Yes | `mobile` | Application name to locate the context folder |
| `<version>` | Yes | `v1.0.4` | Version to scope processing |
| `module:<name>` | No | `module:Hero Section` | Limit generation to a single module |
### Application Folder Resolution
The application name is matched against root-level application folders:
1. Strip any leading `<number>_` prefix from folder names (e.g., `1_mobile` → `mobile`)
2. Match case-insensitively against the provided application name
3. Accept snake_case, kebab-case, or title-case input (all match the same folder)
4. If no match found, list available applications and stop
### Auto-Resolved Paths
| File | Resolved Path |
|------|---------------|
| PRD.md | `<app_folder>/context/PRD.md` |
| Module Models | `<app_folder>/context/model/` |
| HTML Mockups | `<app_folder>/context/mockup/` |
| Output (specification) | `<app_folder>/context/specification/` |
### Version Filtering
When a version is provided, only include user stories, NFRs, and constraints from versions
<= the provided version. For example, if `v1.0.4` is specified:
- Include items tagged `[v1.0.0]`, `[v1.0.1]`, `[v1.0.2]`, `[v1.0.3]`, `[v1.0.4]`
- Exclude items tagged `[v1.0.5]` or later
- Version comparison uses semantic versioning order
### Module Filtering
When `module:<name>` is provided:
- Only generate the `SPEC.md` for that specific module
- Other existing module spec files remain untouched
- `SPECIFICATION.md` (root) gets a partial update — only that module's entry in the TOC
is added or updated; all other TOC entries are preserved as-is
## Gathering Input
The specification is driven by **six input sources** read from the project's context files.
The skill does NOT ask the user for auth, API backend URL, or optional component choices —
it **determines** these automatically from the context.
### Input 1: Application Name (from CLAUDE.md)
From CLAUDE.md (already loaded in context), locate the target application under the
**Custom Applications** section. Extract:
- **Application name**: The section heading (e.g., "Mobile App", "Field Worker")
- **Application description**: The description paragraph below the heading
- **Dependencies**: The "Depends on" list — primary source for determining backend API
base URL, authentication provider, and optional components
The application name is used to derive:
- **Project slug**: snake_case of the application name (Dart/Flutter package naming;
e.g., `mobile_app`, `field_worker`)
- **App bundle ID / Application ID**: Reverse-DNS format (e.g.,
`com.example.mobile_app`) — Android `applicationId` and iOS `CFBundleIdentifier`
- **App display name**: Title-case of application name (e.g., "Mobile App")
### Input 2: User Stories (from PRD.md)
Read `<app_folder>/context/PRD.md`. This file contains all user stories organized by
module. Extract:
- **System modules**: Modules under `# System Module` heading (e.g., Authentication,
Profile). These become system-level features.
- **Business modules**: Modules under `# Business Module` heading (e.g., Order,
Catalogue). These become business-level features.
- **User stories per module**: Each `### User Story` section contains tagged items.
These define the functional requirements for each feature's repositories, providers,
forms, and screens.
The user stories directly inform:
- Which API calls each feature's repository must expose
- Which screens (Stateful/HookConsumerWidget) and routes are needed
- Which form fields and validation rules apply
- Which Flutter widgets best match the described UI
**Important:** Items with strikethrough (`~~text~~`) are deprecated — do NOT include them
as active requirements. List them in the "Removed / Replaced" subsection of the
traceability table.
- **Version tags per item**: Each `### User Story`, `### Non Functional Requirement`,
and `### Constraint` section contains one or more version blocks formatted as `[v1.0.x]`.
The skill must track the version tag for each item and carry it through to the
generated specification's traceability section.
### Input 3: Non-Functional Requirements (from PRD.md)
Within the same `PRD.md`, each module has a `### Non Functional Requirement` section.
These inform:
- UI layout choices (list vs. grid, card sizes, image dimensions)
- Data fetching strategies (pagination, infinite scroll, refresh)
- Validation rules (character limits, format requirements)
- Performance constraints (lazy widgets, image caching, offline support)
NFRs should be mapped to specific technical decisions in the spec — for example, an NFR
stating "paginated with 20 items per page" confirms which Riverpod pagination pattern
to use, while "must work offline" confirms which Hive box manages the offline cache.
### Input 4: Constraints (from PRD.md)
Within the same `PRD.md`, each module has a `### Constraint` section. These define
hard boundaries that the spec must enforce:
- Status enum values (e.g., "DRAFT, ACTIVE, EXPIRED")
- Business rules (e.g., "category must exist before creating content")
- Access control (e.g., "only WORKER role can access task management")
Constraints are embedded directly into the relevant module blueprint — they inform
freezed model definitions, repository method parameters, and route guard configurations.
### Input 5: Module Model (from model/ folder)
Read `<app_folder>/context/model/MODEL.md` first as the index, then read the
individual module model files in each module subfolder.
**MODEL.md** provides:
- Summary table of all modules with table/collection counts and design decisions
- Links to each module's detailed model files
**Per-module files** (e.g., `model/hero-section/model.md`):
- Complete field definitions with types and constraints
- Relationships and references
- Table/collection names
**Per-module schema** (e.g., `model/hero-section/schemas.json`):
- JSON schemas defining exact field types, required fields, and validation rules
The module model directly maps to:
- Freezed data class definitions (field-for-field, not placeholder)
- Hive type adapters (`@HiveType`/`@HiveField`) for cached entities
- JSON serialization via `json_serializable`
- Dio request/response DTOs
- Riverpod state model
### Input 6: HTML Mockup Screens (from mockup/ folder)
Read `<app_folder>/context/mockup/MOCKUP.html` first as the index page, then read the
HTML files organized by role in subfolders.
**MOCKUP.html** provides:
- Application identity (name, version, short name)
- Design tokens: fonts, colors from Tailwind/CSS config or inline styles
- List of user roles and their screen sets
**Role-specific subfolders** (e.g., `mockup/worker/task/`):
- Individual HTML screens for each page in the application
- Screen layout: which widgets are used (ListView, GridView, Forms, Modals, Cards)
- Navigation structure from drawer/bottom-nav HTML files
- Data display patterns (list pages, detail pages, create/edit forms)
**IMPORTANT — Role folders inform access control, NOT route paths.** The role-specific
folder structure (e.g., `mockup/worker/task/task-list.html`) determines:
1. Which role can access the screen → `redirect` guard with role check
2. Which navigation items appear for each role
It does NOT determine the route path. The route path is always module-based:
- `GoRoute(path: '/task', ...)` — NOT `GoRoute(path: '/worker/task', ...)`
The mockup screens directly map to:
- Flutter screen widgets (one per HTML screen)
- go_router route definitions
- Widget selections (ListView vs DataTable, BottomSheet vs Drawer, Card vs Tile)
- Form field layouts
- Navigation items per role (drawer / bottom navigation bar)
- ThemeData color tokens (extract from mockup CSS/styles)
## PRD.md Extended Sections
Before determining optional components, check PRD.md for the following extended sections:
### Architecture Principle Extraction
If PRD.md contains an `# Architecture Principle` section, extract patterns that affect mobile decisions:
| Pattern to Extract | How It Influences the Specification |
|---|---|
| "Stateless REST API" | Confirms Dio + Riverpod async provider pattern for API calls |
| "Event-driven" / "WebSocket" / "real-time" | Include web_socket_channel and a stream provider for live data |
| "API gateway" | Configure base URL to point to gateway rather than individual services |
| Backend framework mention | Validate API response format assumptions |
| "Offline-first" / "local cache" | Include Hive cache layer for read paths |
If the section is absent, proceed with existing CLAUDE.md-only detection.
### Design System Extraction
If PRD.md contains a `# Design System` section with a file reference:
1. Resolve and read the referenced file
2. Map design tokens to Flutter `ThemeData` configuration: color scheme, text theme,
component themes (ElevatedButtonTheme, AppBarTheme, CardTheme, InputDecorationTheme)
3. Include a complete `ThemeData` configuration in SPECIFICATION.md derived from the
design system tokens
If the section is absent, use a default Material 3 theme (existing behavior).
### High Level Process Flow Extraction
If PRD.md contains a `# High Level Process Flow` section:
1. Process flows with user-visible states inform which status values appear in
filter chips/dropdowns
2. Process flows with real-time updates inform WebSocket subscription patterns
3. Multi-step user flows inform go_router nested route design and Stepper/PageView usage
If the section is absent, derive UI flow from user stories only (existing behavior).
---
## Determining Optional Components
Instead of asking the user, the skill determines optional components by analyzing the
dependencies listed in `CLAUDE.md`, the `# Architecture Principle` section in PRD.md (if present),
and cross-referencing with PRD.md NFRs and constraints.
### Backend API Detection
Examine the "Depends on" list in CLAUDE.md for the target application:
| Dependency Pattern | API Configuration |
|---|---|
| References another application's REST API | `API_BASE_URL` set to that app's base URL |
| References a Spring Boot backend | Include Spring Boot CORS headers note |
| No explicit backend | Include mock API / json-server note for development |
### Authentication Detection
| Dependency / PRD Pattern | Auth Selection |
|---|---|
| References "Single Sign On" or "Keycloak" in CLAUDE.md dependencies | Auth = Keycloak |
| PRD.md has login user stories with email/password | Auth = Local (local JWT from API) |
| PRD.md constraint says "public access, no auth required" | Auth = none |
| PRD.md has only public-facing content | Auth = none |
If Auth = Keycloak, also extract from CLAUDE.md:
- Keycloak version
- Keycloak realm: Default derived from project name
- Keycloak client ID: Default `<project-slug>-mobile`
- Keycloak issuer URI: Default `http://localhost:8180/realms/<realm>`
- Keycloak roles: Infer from mockup role folders (e.g., `worker` → `WORKER`, `admin` → `ADMIN`)
If Auth = Local (API-managed JWT):
- Login/logout handled by Dio calls to the backend
- Access token stored in `flutter_secure_storage` (Keychain / Android Keystore)
- Refresh token also in `flutter_secure_storage`
- Dio interceptor attaches `Authorization: Bearer <token>` header
- Token refresh interceptor handles 401 responses
### Optional Component Detection
| PRD.md Pattern | Component Selection |
|---|---|
| NFRs mention "real-time", "live updates", "push notification" | FirebaseMessaging always-on (core); WebSocket = yes if user-driven streams |
| User stories mention "schedule reminder", "local alarm", "background reminder" | Local notifications always-on (core); add scheduled notification helper |
| NFRs mention "share to social", "share link" | Sharing = yes |
| User stories mention "upload photo", "take photo" | ImagePicker = yes |
| User stories mention "attach file", "upload document" | FilePicker = yes |
| PRD.md mentions multiple languages or localization | i18n = yes |
| NFRs mention "track screen views", "user analytics", "conversion funnel" | Analytics = yes |
| NFRs mention "crash reporting", "production error monitoring" | Crashlytics = yes |
| NFRs mention "camera", "gallery", "storage", "location" | Permissions = yes |
### Summary of Determination
After analyzing all inputs, produce a determination summary before generating the spec.
Present it to the user for confirmation:
```
Optional Component Determination:
- Backend API: http://localhost:<port>/api (from CLAUDE.md Port Allocation table → depends on backend app)
- Authentication: Keycloak PKCE via flutter_appauth (from CLAUDE.md → depends on Single Sign On)
- WebSocket: no
- i18n: yes (from PRD.md → English + Bahasa Malaysia required)
- Analytics: yes (from PRD.md NFR → screen view tracking)
- Crashlytics: yes (from PRD.md NFR → production error monitoring)
- ImagePicker: yes (from PRD.md → upload photo of completed task)
- FilePicker: no
- Sharing: no
- Permissions: yes (camera, photo library)
```
If the user disagrees with any determination, allow them to override before proceeding.
## Required Inputs
After determination, these values are needed. Most are derived automatically:
**Auto-derived from context files:**
- **Application name**: From CLAUDE.md section heading
- **Project slug**: snake_case of application name
- **App display name**: Title-case used in `AppBar` title and launcher label
- **App bundle ID**: Reverse-DNS from project slug
- **Application description**: From CLAUDE.md description
- **Backend API base URL**: From CLAUDE.md dependencies
- **Modules / Features**: From PRD.md module headings + model/MODEL.md
- **Auth type**: Auto-determined (see above)
- **Optional components**: Auto-determined (see above)
- **User roles**: From mockup role folders
- **Design tokens**: ThemeData colors extracted from mockup CSS/inline styles
**Auto-derived from CLAUDE.md (Port Allocation table):**
- **Backend API base URL**: Look up the backend application's port from the `Port Allocation` table in the `Custom Applications` section of `CLAUDE.md`. Construct the base URL as `http://10.0.2.2:<port>/api/v1` for Android emulator development (which proxies `localhost`) and `http://localhost:<port>/api/v1` for iOS simulator. Do NOT hardcode `8080` — the port MUST match the allocated port for the backend application this mobile app depends on.
**Optional (use sensible defaults if not found in context):**
- **Default locale**: Default `en`
- **Page size**: Default `20` (mobile-appropriate, from NFRs or fallback)
- **Min Android SDK**: Default `23` (Android 6.0)
- **Min iOS deployment target**: Default `13.0`
## Generating the Specification
Once inputs are gathered from context files and optional components are determined,
generate the specification as a **multi-file output split by module**. Read the spec
template at `references/spec-template.md` for the exact structure and content of each
section. The template is the authoritative guide — follow it closely.
The specification is split into two categories:
1. **Root `SPECIFICATION.md`** — Table of Contents, shared infrastructure, ThemeData,
routing, auth configuration, Hive/Dio/Firebase init, and application-level sections
that apply across all modules.
2. **Per-module `<module-name>/SPEC.md`** — Each module gets its own folder with a
self-contained specification covering that module's complete blueprint.
This split enables a coding agent to:
- First, scaffold the shared infrastructure from `SPECIFICATION.md`
- Then, implement each module independently by picking up its `<module>/SPEC.md`
**Important:** The generated spec must use **real module data** from the context files,
not generic placeholders. Specifically:
- **Modules** must use the actual module names from PRD.md and MODEL.md
(e.g., `task`, `order`, `catalogue` — not `module1`, `module2`)
- **Freezed models** must match the actual fields defined in the module model files,
not placeholder `fieldOne`/`fieldTwo`
- **Repositories** must expose methods matching the actual user stories (e.g., if a story
says "view list of tasks", the repository needs `fetchTasks()`)
- **Screens** must map to the actual mockup screens (e.g., if
`worker/task/task-list.html` exists, there must be a matching route and screen
widget). The route path is module-based (e.g., `/task`), NOT role-prefixed
(e.g., NOT `/worker/task`).
- **Form fields** must match what the mockup screens display
- **Validation rules** must enforce the constraints from PRD.md (character limits, URL format, etc.)
- **ThemeData** must use the design tokens extracted from the mockup (colors, border-radius, font)
- **Version tags**: Every user story ID, NFR ID, constraint ID, and mockup screen in the
traceability section must include its version tag (e.g., `USA000030 [v1.0.4]`).
**ALL traceability sub-tables (User Stories, NFRs, AND Constraints) MUST include the
`| Version |` column.**
- **Removed / Replaced items**: The traceability section must include a "Removed / Replaced"
subsection listing deprecated items — showing the removed ID, the version that removed it,
the replacement ID (if any), and a brief reason.
### Output Structure
```
<app_folder>/context/specification/
├── SPECIFICATION.md ↠TOC + shared/application-level specs
├── task/
│ └── SPEC.md ↠Module blueprint for Task
├── order/
│ └── SPEC.md ↠Module blueprint for Order
├── catalogue/
│ └── SPEC.md ↠Module blueprint for Catalogue
├── ... ↠One folder per module from PRD.md
```
### What Goes in `SPECIFICATION.md` (Root)
The root file contains the TOC and all shared/application-level sections. These are
sections a coding agent implements **first** before any module work:
#### 1. Project Overview
Project metadata, application description, technology stack summary, user roles, module
index table linking to each module's SPEC.md, target platforms (Android/iOS) and minimum
OS versions.
#### 2. Package Configuration
Complete `pubspec.yaml` with all dependencies (core + selected conditional),
`build_runner` scripts, and asset/font declarations.
#### 3. Application Configuration
`analysis_options.yaml` (lints), `.gitignore`, Flutter `flavors` if multi-environment
needed, native splash and launcher icon configuration, Android `build.gradle` & iOS
`Info.plist` notes (permissions, deep links, FCM background handler).
#### 3a. Application Version Configuration
The application MUST include a version value derived from the version argument provided
during skill invocation. If multiple versions were provided, use the highest one.
In `pubspec.yaml`:
```yaml
version: 1.0.3+1
```
The first part (`1.0.3`) is the human-readable version; the suffix (`+1`) is the build
number. The build number MUST be incremented manually or via CI on each release.
The application MUST expose this version in a **Settings/About** screen or persistent
drawer footer. Use `package_info_plus` (add as dependency if surfacing programmatically):
```dart
final info = await PackageInfo.fromPlatform();
final versionLabel = 'v${info.version}+${info.buildNumber}';
```
#### 3b. `.env` File Generation from ENVIRONMENT.md
Generate `.env.development` and `.env.production` files at the project root for use with
`flutter_dotenv`. The `.env.development` file is populated by reading `ENVIRONMENT.md` from
the project root, mapping credential and platform values to plain environment variable
names (no `VITE_` prefix — Flutter does not use Vite). The `.env.production` file uses
placeholder values for production.
**Process:**
1. Read `ENVIRONMENT.md` from the project root
2. Extract credential values from `ENVIRONMENT.md` (`# Supporting 3rd Party Applications`
for Keycloak host/realm/client, plus `# External Services` such as Firebase config); the
backend API host/port comes from the `# Port Allocation` table in `CLAUDE.md`. Read any
toolchain paths from `DEVTOOL.md`
3. Map each value to the corresponding environment variable name
4. Generate `.env.development` with actual local values
5. Generate `.env.production` with production placeholder values
6. Register both files under `assets:` in `pubspec.yaml`
**Example `.env.development` output (derived from ENVIRONMENT.md):**
```properties
# Backend API
API_BASE_URL=http://10.0.2.2:<port from CLAUDE.md Port Allocation table>/api/v1
API_TIMEOUT_MS=30000
API_RETRY_ATTEMPTS=3
# Authentication (Keycloak)
KEYCLOAK_ISSUER=http://10.0.2.2:8180/realms/urp
KEYCLOAK_CLIENT_ID=urp-mobile
KEYCLOAK_REDIRECT_URI=com.example.mobile_app:/oauth2redirect
```
**Rules:**
- Use plain environment variable names; access via `dotenv.env['API_BASE_URL']`
- Use actual values from ENVIRONMENT.md — never use placeholders or `TODO`
- If ENVIRONMENT.md does not exist or a value is not found, use sensible defaults for local
development (Android emulator uses `10.0.2.2` for host's `localhost`)
- Both `.env.development` and `.env.production` are gitignored, but the **files MUST
still be declared under `assets:`** in `pubspec.yaml` so `flutter_dotenv` can load them
at runtime
- Firebase config (`google-services.json`, `GoogleService-Info.plist`) is checked in
per-flavor but the Firebase project ID/sender ID are read from `.env` if dynamic
#### 4. Directory Structure
The complete source tree under `lib/`. The structure follows feature-based architecture
where each PRD module maps to a `lib/features/<module>/` folder.
Read `references/routing-patterns.md` for the module folder layout.
#### 5. Theme Configuration
Custom Material 3 `ThemeData` built from design tokens extracted from mockup screens.
Includes color scheme (seeded from primary), text theme (Google Fonts or custom font
family), component themes (ElevatedButtonTheme, AppBarTheme, CardTheme, InputDecorationTheme,
FloatingActionButtonTheme), and shape/radius tokens.
Read `references/component-patterns.md` for theme setup patterns.
#### 6. Authentication Configuration *(conditional — include only if Auth != none)*
**If Auth = Keycloak:** PKCE Authorization Code flow using `flutter_appauth`. The native
AppAuth library (Android + iOS) handles the system browser redirect. `AuthRepository`
exposes `signIn()`, `signOut()`, `getAccessToken()`. Tokens stored in
`flutter_secure_storage`. Dio interceptor reads access token. Refresh token used to renew
silently. Deep link callback configured for both platforms.
Read `references/security-patterns.md` for the full auth architecture.
**If Auth = Local (API JWT):** Login screen submits to backend API, JWT stored in
`flutter_secure_storage`, Dio interceptor attaches Authorization header, token refresh
interceptor handles 401 responses, route guard via go_router `redirect` callback
redirects unauthenticated users.
#### 7. Router Configuration
go_router v14 route tree — top-level routes, nested shell routes for bottom navigation,
route guards via `redirect`, deep link configuration for FCM/Keycloak callbacks,
typed route helpers (optional, via `go_router_builder`).
Read `references/routing-patterns.md` for route patterns.
#### 8. API Client Configuration
Dio instance with `baseUrl` from `dotenv.env['API_BASE_URL']`, request/response
interceptors:
- Auth interceptor (Bearer token injection)
- Retry interceptor (`DioSmartRetry` — exponential backoff on 5xx, network errors, retry idempotent methods)
- Logging interceptor (`PrettyDioLogger`, **dev only** — guard with `kDebugMode`)
- Error interceptor (transforms `DioException` → typed `ApiFailure` sealed class)
`connectTimeout`, `receiveTimeout`, `sendTimeout` from `.env`.
#### 9. Local Storage (Hive)
`Hive.initFlutter()` in `main()`, type adapters registered for each cached entity,
typed `Box<T>` providers via Riverpod, helper extension methods for upsert/find/clear,
encryption optional (HiveAesCipher with key from `flutter_secure_storage`).
Read `references/storage-patterns.md` for Hive patterns.
#### 10. Riverpod Setup
`ProviderScope` wrapping `MyApp`, code generation via `riverpod_generator`,
`AsyncNotifier`/`Notifier` providers for state, family providers for parameterized
queries, naming convention: `<entity>RepositoryProvider`, `<entity>ListProvider`,
`<entity>ByIdProvider(id)`.
Read `references/state-patterns.md` for Riverpod patterns.
#### 11. Shared Layouts
`AppShellScreen` (bottom navigation + Scaffold body via `ShellRoute`), `AuthShell`
(login/forgot-password scaffolding), `PublicShell` for unauthenticated content (if any).
Each shell uses Material 3 widgets.
#### 12. Shared Widgets
Reusable widgets used across multiple modules: `AppScaffold` (AppBar + body slot),
`LoadingIndicator`, `EmptyState`, `ErrorState`, `ConfirmDialog`, `StatusChip`,
`SearchBarField`, `FormTextField`, `FormDatePickerField`, `FormDropdownField`,
`ImagePickerField` (if ImagePicker = yes), `PullToRefreshList`, `InfiniteScrollList`,
`CachedSvgIcon`, `AppNetworkImage` (wraps `CachedNetworkImage` with placeholder/error).
#### 13. Navigation Configuration
Bottom navigation items (or drawer items) derived from mockup nav files, organized by
role. Each item has label, icon (Material/MDI/FA), path, and required role.
Navigation is rendered dynamically based on the authenticated user's roles.
#### 14. Form Infrastructure
Reusable form-field widgets wrapping `TextFormField` / `DropdownButtonFormField` /
`DatePicker` with consistent decoration, validators (`Validator` static methods:
`required`, `email`, `min/maxLength`, `url`, `compose`), submit button with loading
state (CircularProgressIndicator inside ElevatedButton).
#### 15. Error Handling Strategy
Top-level `FlutterError.onError` and `PlatformDispatcher.instance.onError` for uncaught
errors (route to Crashlytics if enabled), Dio error interceptor mapping `DioException`
→ `ApiFailure` sealed class, Riverpod `AsyncValue.when(...)` for screen-level
error/loading states, `ErrorState` widget for full-screen errors with retry button,
`ScaffoldMessenger` (SnackBar) for transient errors.
#### 16. Notification System
**Push notifications (FCM):**
- `firebase_messaging` foreground/background/terminated handlers
- Token registration with backend on first launch and refresh
- Notification permission request (iOS + Android 13+)
- Deep link from notification payload to a specific route via go_router
**Local notifications:**
- `flutter_local_notifications` initialized with platform settings (Android channels,
iOS categories)
- Used to display FCM messages received in foreground (FCM does not show banners in
foreground by default on iOS/Android)
- Used for in-app scheduled reminders if PRD requires it
**In-app toasts:**
- `ScaffoldMessenger.of(context).showSnackBar(...)` for non-critical user feedback.
Read `references/notification-patterns.md` for the full notification architecture.
#### 17. Theming & Dark Mode
`MaterialApp.themeMode` toggled via UI control, persisted in Hive `settings` box.
`lightTheme` and `darkTheme` constructed via `ThemeData(colorScheme: ColorScheme.fromSeed(...))`
with brightness override. `ThemeToggle` widget switches mode and writes to Hive.
#### 18. Testing Strategy
Overview: `flutter_test` + `mocktail` for widget/unit tests, `ProviderContainer` for
testing Riverpod providers in isolation, golden tests for critical screens, integration
tests via `integration_test` package. Per-feature test conventions matching the module spec.
#### 19. Build & Distribution
- `flutter build apk --release` / `flutter build appbundle --release` (Android)
- `flutter build ipa --release` (iOS)
- Code signing notes (Android: upload keystore in `~/.gradle/gradle.properties`; iOS:
Apple Developer team + provisioning profile)
- Native splash via `flutter_native_splash` (`dart run flutter_native_splash:create`)
- Launcher icon via `flutter_launcher_icons` (optional)
- ProGuard rules for Firebase + AppAuth (Android release builds)
#### 20. Internationalisation *(conditional — include only if i18n = yes)*
`flutter_localizations` enabled, `intl` for ARB messages, `flutter_gen_l10n` configured
in `pubspec.yaml`, `lib/l10n/app_en.arb` + per-locale ARBs, generated `AppLocalizations`
class, `MaterialApp.localizationsDelegates` and `supportedLocales` wired, locale-switch
provider persisted in Hive.
#### 21. WebSocket Integration *(conditional — include only if WebSocket = yes)*
`web_socket_channel` setup, connection management Riverpod provider with auto-reconnect
+ exponential backoff, typed event handler with sealed-class events, lifecycle hook
in `AppShellScreen` to open/close socket on app foreground/background.
#### 22. Firebase Initialization
Always required (push notifications depend on it). Cover:
- `Firebase.initializeApp(options: DefaultFirebaseOptions.currentPlatform)` in `main()`
before `runApp(...)`
- `google-services.json` (Android) + `GoogleService-Info.plist` (iOS) placement
- `flutterfire configure` CLI workflow (used once during scaffolding)
- Background message handler: top-level `@pragma('vm:entry-point')` function
- Firebase Analytics initialization (if Analytics = yes)
- Firebase Crashlytics setup hook (if Crashlytics = yes)
### What Goes in Each `<module>/SPEC.md` (Per-Module)
For EACH module from PRD.md and MODEL.md, create a folder named after the module
(kebab-case, e.g., `task/`) and generate a `SPEC.md` inside it.
Each module `SPEC.md` is a **self-contained** blueprint that a coding agent can pick up
and implement independently (after the shared infrastructure is in place). It must include:
- **Header** with module name and back-reference to root `SPECIFICATION.md`
- **Traceability**: User story IDs, NFR IDs, constraint IDs, table/collection names,
mockup screen filenames, all with version tags
- **Freezed Models** — `@freezed` data classes matching the module model fields
(field-for-field), including `fromJson`/`toJson` via `json_serializable`
- **Hive Adapters** *(if module is cached offline)* — `@HiveType` adapter with field
numbers matching the freezed model
- **Validation Rules** — Validator static methods or `Form` validator closures derived
from PRD constraints
- **API Repository** — Dio-based API class matching user story data operations
- **Riverpod Providers** — `AsyncNotifierProvider` for list, family provider for detail,
mutation methods on a `Notifier` for CUD operations, cache invalidation pattern via
`ref.invalidate()`
- **Screens** — one per mockup screen, using Material 3 widgets matching the mockup layout
- **Form Widgets** — create/edit forms with `Form` + `GlobalKey<FormState>` + reusable
field widgets
- **Route Definitions** — go_router routes for this module with `redirect` guards
matching the mockup role folder access control
- **Navigation Items** — bottom-nav / drawer entries for each role that can access this module
- **Complete code samples** for every widget — continuous and copy-pasteable
See `references/spec-template.md` for the exact per-module template structure.
## Changelog Append
After all specification files are successfully generated, append an entry to `CHANGELOG.md` in the application folder (`<app_folder>/CHANGELOG.md`):
1. Read `<app_folder>/CHANGELOG.md`. If it does not exist, create it with:
```markdown
# Changelog
- This file tracks all skill executions by version for this application.
- The highest version recorded here is the current application version.
- Skills MUST NOT execute for a version lower than the highest version in this file.
---
```
2. Search for a `## {version}` heading matching the current version.
3. If the section **exists**: append a new row to its table.
4. If the section **does not exist**: insert a new section after the `---` below the context header and before any existing `## vX.Y.Z` section (newest-first ordering), with a new table header and the first row.
5. Row format: `| {YYYY-MM-DD} | {application_name} | specgen-flutter-riverpod | {module or "All"} | Generated Flutter Riverpod mobile technical specification |`
6. **Never modify or delete existing rows.**
## Output Format
The generated specification is a **folder of files**, not a single document:
```
<app_folder>/context/specification/
├── SPECIFICATION.md ↠Root: TOC + shared/application-level specs
├── <module-1>/
│ └── SPEC.md ↠Module blueprint (self-contained)
├── <module-2>/
│ └── SPEC.md
├── <module-N>/
│ └── SPEC.md
```
## Constraints (Non-Negotiable)
These constraints apply to every code sample in the generated spec:
**Null-safe Dart everywhere.** Target Dart 3.5+ with sound null safety. No `dynamic`
unless the API genuinely returns unstructured JSON — prefer `Object?` with explicit
type checks, or strongly typed `Map<String, dynamic>` only at the JSON boundary.
**Feature-based architecture.** Every module maps to `lib/features/<module>/`. Nothing
module-specific leaks into `lib/shared/` or `lib/core/`. Shared widgets must be
genuinely reusable across at least two modules.
**No tokens in plaintext storage.** JWT access and refresh tokens are stored in
`flutter_secure_storage` (Keychain / Android Keystore), never in `SharedPreferences`,
Hive, or in-memory globals that persist beyond the process. Hive is encrypted (`HiveAesCipher`)
when storing user-sensitive cached data — encryption key lives in `flutter_secure_storage`.
**Riverpod for all state.** Do not use `setState` for state that crosses widgets, and
do not use `InheritedWidget` directly — use Riverpod providers. `setState` is only
acceptable for purely local widget UI state (animation controllers, hover, focus).
**Freezed for all data models.** No hand-rolled equality / hashCode / copyWith. Every
data class is `@freezed` with `fromJson`/`toJson` if it crosses the API boundary.
**Generated code via build_runner.** Always include the standard commands in the spec:
- `dart run build_runner build --delete-conflicting-outputs` — one-shot generation
- `dart run build_runner watch --delete-conflicting-outputs` — watch mode for development
**Material 3 only.** `ThemeData(useMaterial3: true)`. Do not mix in Cupertino-only widgets
in cross-platform screens — use `Adaptive*` constructors or platform-aware wrappers if
truly necessary.
**go_router for navigation.** Do not use raw `Navigator.push`/`Navigator.pop`. All
navigation is `context.go(...)`, `context.push(...)`, or `context.pop()` via go_router.
Deep link configuration is centralized in `lib/router/app_router.dart`.
**Consistent file naming (Dart conventions):**
- Widgets / classes: `PascalCase` class names in `snake_case.dart` files (e.g.,
`task_list_screen.dart` defines `class TaskListScreen`)
- Riverpod providers: generated by `riverpod_generator` from `<feature>_providers.dart`
- Repository files: `<feature>_repository.dart` (e.g., `task_repository.dart`)
- Models: `<entity>.dart` for `@freezed` data class, generated `*.freezed.dart` &
`*.g.dart` are committed
- Test files: `<file>_test.dart` co-located in `test/<feature>/` mirroring `lib/features/`
No comments yet. Be the first to comment!
