From 34bc70ea3098c7eb92dbd649cd630124f5866051 Mon Sep 17 00:00:00 2001 From: Michal Urbanek Date: Tue, 19 May 2026 09:49:08 +0200 Subject: [PATCH] chore: Update AI flows --- .claude/CLAUDE.md | 9 ++++++--- AGENTS.md | 13 +++++++++++-- README.md | 6 +++--- ai/skills/create-pr/SKILL.md | 2 +- ai/skills/feature-data-flow/SKILL.md | 2 ++ ai/skills/feature-screen/SKILL.md | 2 ++ ai/skills/pr-review/SKILL.md | 2 ++ ai/skills/project-setup/SKILL.md | 8 +++++--- ai/skills/release-builds/SKILL.md | 2 ++ ai/skills/release-prepare/SKILL.md | 2 ++ ai/skills/secrets-bootstrap/SKILL.md | 2 ++ ai/skills/tasks/SKILL.md | 4 ++-- ai/skills/techspec/SKILL.md | 5 +++-- ai/skills/upgrade/SKILL.md | 2 ++ ai/templates/task-list.md | 2 +- ai/templates/task.md | 6 +++--- ai/templates/techspec.md | 25 +++++++++++++++---------- 17 files changed, 64 insertions(+), 30 deletions(-) diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index a0ed72c..cda855e 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -7,9 +7,12 @@ to Claude Code two ways: at `/ai/skills/`), so Claude reads the SKILL.md frontmatter and triggers them based on context. - **slash commands**: `./commands/.md` exposes each skill as an explicit - command — `/project-setup`, `/feature-screen`, `/feature-data-flow`, - `/upgrade`, `/release-prepare`, `/release-builds`, `/secrets-bootstrap`, - `/pr-review`. + command. Current commands mirror the skills listed in `AGENTS.md`, including + `/project-setup`, `/feature-screen`, `/feature-data-flow`, `/prd`, + `/techspec`, `/tasks`, `/implement`, `/implement-tasks-sequence`, + `/start-job`, `/build-verify`, `/lint-format`, `/create-pr`, + `/review-pr-comments`, `/upgrade`, `/release-prepare`, `/release-builds`, + `/secrets-bootstrap`, and `/pr-review`. See the "Reusable Workflows" section of `AGENTS.md` for the canonical list of skills and the four-step convention for adding a new one. diff --git a/AGENTS.md b/AGENTS.md index 0f8cf8f..9f5cd7b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -80,8 +80,17 @@ Existing skills: When adding a new repeatable workflow, complete all four steps so both Codex and Claude can use it: 1. **Author the skill.** Create `ai/skills//SKILL.md` with YAML frontmatter - (`name:` matching the folder, `description:` explaining when to use it) and - the workflow body. + and the workflow body. Required fields: + - `name:` matching the folder + - `description:` explaining when to use the skill + - `allowed-tools:` listing the tools the skill needs (for example + `Bash, Read, Grep, Glob, Edit, Write`; add `Agent` for skills that delegate + to subagents, `Skill` for orchestrators that invoke other skills) + - `model:` selecting the model — use `claude-sonnet-4-6` for most + implementation, verification, and review workflows, and `claude-opus-4-7` + for spec-writing skills like `prd` and `techspec` + - `user-invocable: true` only on top-level entry-point skills such as + `start-job` and `create-pr` 2. **Mention it for Codex.** Add the skill to the "Existing skills" list above. 3. **Expose it to Claude Code (auto-discovery).** Add a symlink: `ln -s ../../ai/skills/ .claude/skills/` diff --git a/README.md b/README.md index a34c9cb..f6980f5 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,7 @@ - [Web](#web) - [Versioning](#versioning) -- [Implementation details](#implementation-details) +- [Implementation Details](#implementation-details) - [Architecture](#architecture) - [Push Notifications](#push-notifications) - [GIT](#git) @@ -35,7 +35,7 @@ - [Google on iOS](#google-on-ios) - [Testing](#testing) - - [Widgets Tests](#widget-tests) + - [Widget tests](#widget-tests) - [Integration Tests](#integration-tests) - [Tooling](#tooling) @@ -53,7 +53,7 @@ - [Security](#security) - [freeRASP](#freerasp) -- [TODOs](#todos) +- [Todos](#todos) - [Authors](#authors) diff --git a/ai/skills/create-pr/SKILL.md b/ai/skills/create-pr/SKILL.md index 19c3f7c..88c0619 100644 --- a/ai/skills/create-pr/SKILL.md +++ b/ai/skills/create-pr/SKILL.md @@ -104,7 +104,7 @@ Use this format when sections apply: - ## Screenshot -TODO + ``` For small PRs, skip section headers and write 1-3 concise bullets plus `## Screenshot` when appropriate. diff --git a/ai/skills/feature-data-flow/SKILL.md b/ai/skills/feature-data-flow/SKILL.md index 6826e0b..2c29e1d 100644 --- a/ai/skills/feature-data-flow/SKILL.md +++ b/ai/skills/feature-data-flow/SKILL.md @@ -1,6 +1,8 @@ --- name: feature-data-flow description: Build a full feature in this Flutter repository that includes backend or storage data flow: read API schema, create DTOs, map DTOs to entities, add Riverpod use cases, connect feature state, and render UI data. Use when a task goes beyond a screen and needs real data integration. +allowed-tools: Bash, Read, Grep, Glob, Edit, Write +model: claude-sonnet-4-6 --- # Flutter Template Feature Data Flow diff --git a/ai/skills/feature-screen/SKILL.md b/ai/skills/feature-screen/SKILL.md index 335a42f..10f9240 100644 --- a/ai/skills/feature-screen/SKILL.md +++ b/ai/skills/feature-screen/SKILL.md @@ -1,6 +1,8 @@ --- name: feature-screen description: Create a new Flutter screen in this repository using the existing feature structure, AutoRoute setup, Riverpod state pattern, and code generation workflow. Use when adding a new page, route, stateful screen, or feature folder in this template. +allowed-tools: Bash, Read, Grep, Glob, Edit, Write +model: claude-sonnet-4-6 --- # Flutter Template Feature Screen diff --git a/ai/skills/pr-review/SKILL.md b/ai/skills/pr-review/SKILL.md index 7020939..fb0e47b 100644 --- a/ai/skills/pr-review/SKILL.md +++ b/ai/skills/pr-review/SKILL.md @@ -1,6 +1,8 @@ --- name: pr-review description: Review pull requests, branch diffs, and uncommitted changes in this Flutter repository with a bug-finding mindset. Use when asked to review changes, review a PR, audit a diff, check standards, check compliance, or look for regressions, missing tests, release risks, or architecture mismatches. +allowed-tools: Agent, Bash, Read, Grep, Glob, Edit +model: claude-sonnet-4-6 --- # Flutter Template PR Review diff --git a/ai/skills/project-setup/SKILL.md b/ai/skills/project-setup/SKILL.md index e26ba28..5074030 100644 --- a/ai/skills/project-setup/SKILL.md +++ b/ai/skills/project-setup/SKILL.md @@ -1,6 +1,8 @@ --- name: project-setup description: Customize a new project created from this Flutter template, including app identity, package name, platform cleanup, icons, splash screen, Firebase/secrets decisions, setup tool execution, code generation, and validation. +allowed-tools: Bash, Read, Grep, Glob, Edit, Write +model: claude-sonnet-4-6 --- # Flutter Template Project Setup @@ -68,7 +70,7 @@ Use this when setting up a new clone, preparing AI workflows, or debugging skill - `ai/skills/release-builds/scripts/archive_ios_ipa.sh` should print usage and exit non-zero when no flavor is supplied. ## Platform Cleanup Workflow -Use this workflow to automate step 4 from the README First steps checklist. +Use this workflow to automate README First steps > Automated steps item 1. 1. Determine the final supported platforms from the user request. Supported platform names are Android, iOS, web, Windows, Linux, snap, and macOS. If the request does not clearly say which platforms to keep or remove, ask before deleting platform folders. 2. Remove unsupported platform folders and files: @@ -99,7 +101,7 @@ Use this workflow to automate step 4 from the README First steps checklist. 9. Run `fvm flutter analyze`. Run relevant tests when platform cleanup touches shared runtime logic. ## Firebase Workflow -Use this workflow to automate step 9 from the README First steps checklist. +Use this workflow to automate README First steps > Automated steps item 5. 1. Determine whether Firebase should be kept or removed. If the request is unclear, ask because Firebase affects authentication, analytics, crash reporting, push notifications, remote config, web hosting, release distribution, and secrets. 2. If Firebase is kept: @@ -124,7 +126,7 @@ Use this workflow to automate step 9 from the README First steps checklist. - `firebase`, `Firebase`, `GoogleService`, `google-services`, `flutterfire`, `Crashlytics`, `RemoteConfig`, `FirebaseMessaging`, `FirebaseAuth`, `.firebaserc`, and `firebase.json`. - Treat encrypted secret files under `extras/secrets/` as secrets-owned unless the user explicitly asked to rotate or remove encrypted Firebase secrets. 5. Validate with `make gen` when generated providers or routes changed, then run `fvm flutter analyze` and relevant tests. -6. Mark README First steps item 9 as `[x]` only after Firebase has been configured for the intended platforms or removed completely. +6. Mark README First steps > Automated steps item 5 as `[x]` only after Firebase has been configured for the intended platforms or removed completely. ## Dependency Checks - Run `fvm dart pub outdated` inside `project_setup/` when touching the setup tool. diff --git a/ai/skills/release-builds/SKILL.md b/ai/skills/release-builds/SKILL.md index 4781ec8..0ab187e 100644 --- a/ai/skills/release-builds/SKILL.md +++ b/ai/skills/release-builds/SKILL.md @@ -1,6 +1,8 @@ --- name: release-builds description: Run post-merge release build steps for this repository, including Android tag-driven releases and sequential iOS IPA generation with archival for Transporter upload and Crashlytics deobfuscation. Use after the release PR has been merged. +allowed-tools: Bash, Read, Grep, Glob +model: claude-sonnet-4-6 --- # Flutter Template Release Builds diff --git a/ai/skills/release-prepare/SKILL.md b/ai/skills/release-prepare/SKILL.md index 3a29b71..4e2f1be 100644 --- a/ai/skills/release-prepare/SKILL.md +++ b/ai/skills/release-prepare/SKILL.md @@ -1,6 +1,8 @@ --- name: release-prepare description: Prepare a release in this repository by bumping the app version, updating release notes, creating a release branch named release/, and preparing the PR for merge before any release builds or tags are created. +allowed-tools: Bash, Read, Grep, Glob, Edit, Write +model: claude-sonnet-4-6 --- # Flutter Template Release Prepare diff --git a/ai/skills/secrets-bootstrap/SKILL.md b/ai/skills/secrets-bootstrap/SKILL.md index 937bef5..f290768 100644 --- a/ai/skills/secrets-bootstrap/SKILL.md +++ b/ai/skills/secrets-bootstrap/SKILL.md @@ -1,6 +1,8 @@ --- name: secrets-bootstrap description: Safely work with encrypted secrets, environment files, and signing material in this repository. Use when a task requires loading, decrypting, validating, or explaining the repo's secrets and signing setup. +allowed-tools: Bash, Read, Grep, Glob +model: claude-sonnet-4-6 --- # Flutter Template Secrets Bootstrap diff --git a/ai/skills/tasks/SKILL.md b/ai/skills/tasks/SKILL.md index a208d87..1512bcb 100644 --- a/ai/skills/tasks/SKILL.md +++ b/ai/skills/tasks/SKILL.md @@ -45,8 +45,8 @@ Order tasks following this Flutter-stack progression (mirrors the `ai/templates/ phases): 1. **Foundation (data layer)** — DTOs in `lib/common/data/dto/` (`@freezed` with - generated `fromJson` factories), domain entities in `lib/common/data/entity/`, repositories, and - use cases. Run `make gen` after annotation changes. + generated `fromJson` factories), domain entities in `lib/common/data/entity/`, and + Riverpod use cases/providers. Run `make gen` after annotation changes. 2. **Core implementation (state + UI)** — `@riverpod` notifiers, `*_state.dart` / `*_event.dart` (feature-scoped freezed types), and the page split: `*_page.dart` (thin `@RoutePage` widget) + `*_page_content.dart` (heavier UI). diff --git a/ai/skills/techspec/SKILL.md b/ai/skills/techspec/SKILL.md index 6b5c212..2dc484c 100644 --- a/ai/skills/techspec/SKILL.md +++ b/ai/skills/techspec/SKILL.md @@ -47,7 +47,8 @@ Explore the codebase to ground the spec in reality: - Check `lib/common/` for reusable widgets, extensions, theming, formatters before introducing new primitives. - Inspect existing DTOs (`lib/common/data/dto/`), entities (`lib/common/data/entity/`), - repositories, and use cases for naming / mapping conventions. + use cases, and providers for naming / mapping conventions. Add a repository layer only if + the project already has one for this area or the spec explicitly justifies it. - Check `lib/app/setup/setup_app.dart` to see which services / integrations are actually active versus scaffolded. - Read `AGENTS.md`, `docs/PROJECT_OVERVIEW.md`, and `docs/PROJECT_GUIDELINES.md` for the @@ -78,7 +79,7 @@ Read the template at `ai/templates/techspec.md` (also reachable at - Follow the project's architecture rules from `AGENTS.md`, `docs/PROJECT_OVERVIEW.md`, and `docs/PROJECT_GUIDELINES.md` - Include a clear build order in Development Sequencing — typically: - 1. Data layer (DTOs, entities, repository, use cases) — `make gen` after annotations + 1. Data layer (DTOs, entities, use cases/providers) — `make gen` after annotations 2. State layer (`@riverpod` notifier, `*_state.dart`, `*_event.dart`) 3. UI layer (`*_page.dart` + `*_page_content.dart`) 4. Integration / navigation (`@RoutePage` wiring, Firebase services, analytics, permissions) diff --git a/ai/skills/upgrade/SKILL.md b/ai/skills/upgrade/SKILL.md index b9fa14d..c8ade6e 100644 --- a/ai/skills/upgrade/SKILL.md +++ b/ai/skills/upgrade/SKILL.md @@ -1,6 +1,8 @@ --- name: upgrade description: Upgrade Flutter and package dependencies in this repository while keeping .fvmrc, pubspec.yaml, code generation, CI, and tests aligned. Use when bumping Flutter, Dart constraints, direct dependencies, or generator toolchains. +allowed-tools: Bash, Read, Grep, Glob, Edit, Write +model: claude-sonnet-4-6 --- # Flutter Template Upgrade diff --git a/ai/templates/task-list.md b/ai/templates/task-list.md index e653a64..054a4be 100644 --- a/ai/templates/task-list.md +++ b/ai/templates/task-list.md @@ -5,7 +5,7 @@ ## Task List ### Phase 1: Foundation (data layer) -- [ ] 1.0 [Task title — DTOs, entities, repository, use cases; run `make gen` after annotation changes] +- [ ] 1.0 [Task title — DTOs, entities, use cases/providers; run `make gen` after annotation changes] ### Phase 2: Core Implementation (state + UI) - [ ] 2.0 [Task title — `@riverpod` notifier, `*_state.dart`, `*_event.dart`, `*_page.dart`, `*_page_content.dart`] diff --git a/ai/templates/task.md b/ai/templates/task.md index f4eaee7..d59482c 100644 --- a/ai/templates/task.md +++ b/ai/templates/task.md @@ -6,7 +6,7 @@ [Business value, user problem being solved] ## How does it connect to everything else? -[Where does data flow from/to? Which existing features, providers, repositories, or services does this touch?] +[Where does data flow from/to? Which existing features, providers, use cases, or services does this touch?] ## What does success look like? [Concrete outcome - what should the user be able to do when this is done?] @@ -27,11 +27,11 @@ ## Dependencies ### Requires (inputs) -- [APIs (`dio` endpoints), providers, repositories, or use cases this consumes] +- [APIs (`dio` endpoints), providers, use cases, or services this consumes] - [Required Firebase services or platform permissions] ### Provides (outputs) -- [New providers, repositories, routes, or use cases this exposes to the rest of the app] +- [New providers, routes, or use cases this exposes to the rest of the app] ### Third-party integrations - [External APIs, SDKs, Firebase modules, or platform channels needed] diff --git a/ai/templates/techspec.md b/ai/templates/techspec.md index c8e8e76..97d720e 100644 --- a/ai/templates/techspec.md +++ b/ai/templates/techspec.md @@ -12,7 +12,7 @@ - Feature module under `lib/features//` — pages, content widgets, state notifier, events - Shared widgets/extensions reused from `lib/common/` -- Data layer: DTOs in `lib/common/data/dto/`, domain entities in `lib/common/data/entity/`, use cases, repositories +- Data layer: DTOs in `lib/common/data/dto/`, domain entities in `lib/common/data/entity/`, use cases, and providers - Riverpod providers / `@riverpod` notifiers and how state flows into the UI - Navigation entry via `auto_route` (`@RoutePage`, route registration)] @@ -20,13 +20,15 @@ ### Main Interfaces -[Define main contracts (≤20 lines per example). Prefer Dart abstract classes for repositories/use cases and `@riverpod` for state. Examples: +[Define main contracts (≤20 lines per example). Prefer existing Riverpod use-case/provider patterns and `@riverpod` for state. Add repository abstractions only when the project already has them for this area or the spec explicitly justifies them. Examples: ```dart -// Repository contract — implementations live in lib/common/data/ -abstract class ExampleRepository { - Future fetch(String id); - Stream> watchAll(); +// Use case — IO orchestration lives under lib/common/usecase/ +@riverpod +Future fetchExampleUseCase(Ref ref, String id) async { + final dio = ref.read(dioProvider); + final response = await dio.get>('/examples/$id'); + return ExampleResponseDTO.fromJson(response.data!).toEntity(); } ``` @@ -35,7 +37,10 @@ abstract class ExampleRepository { @riverpod class ExampleController extends _$ExampleController { @override - Future build() async => ref.read(exampleRepositoryProvider).load(); + Future build() async { + final example = await ref.read(fetchExampleUseCaseProvider('id').future); + return ExampleState(example: example); + } Future onEvent(ExampleEvent event) async { /* ... */ } } @@ -69,7 +74,7 @@ Run `make gen` after touching `@riverpod`, `@freezed`, `@RoutePage`, or other co [Define implementation sequence: -1. Data layer — DTOs, entity mapping, repository, use cases (run `make gen`) +1. Data layer — DTOs, entity mapping, use cases/providers (run `make gen`) 2. State layer — `@riverpod` notifier, state/event classes, unit tests 3. UI layer — `*_page.dart` (thin) + `*_page_content.dart` (heavy UI) 4. Navigation wiring — `@RoutePage`, route registration, deep link if needed @@ -90,7 +95,7 @@ Run `make gen` after touching `@riverpod`, `@freezed`, `@RoutePage`, or other co [Document important technical decisions: -- Approach choice and justification (e.g., Riverpod `Notifier` vs. `AsyncNotifier`, repository vs. direct use case) +- Approach choice and justification (e.g., Riverpod `Notifier` vs. `AsyncNotifier`, direct use case vs. an explicitly justified repository layer) - Trade-offs considered - Rejected alternatives and why] @@ -115,4 +120,4 @@ Validation before merging: ### Relevant Files -[List relevant files here — pages, content widgets, state/event, DTOs, entities, repositories, providers, route definitions, generated files to regenerate.] +[List relevant files here — pages, content widgets, state/event, DTOs, entities, use cases, providers, route definitions, generated files to regenerate.]