chore: tighten AI workflow skills and align project docs

.claude/CLAUDE.md

@@ -7,9 +7,12 @@ to Claude Code two ways:
   at `<repo>/ai/skills/<name>`), so Claude reads the SKILL.md frontmatter
   and triggers them based on context.
 - **slash commands**: `./commands/<name>.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.

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/<name>/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/<name> .claude/skills/<name>`

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)
 

ai/skills/create-pr/SKILL.md

@@ -104,7 +104,7 @@ Use this format when sections apply:
 - <one short bullet per non-user-facing maintenance change>
 
 ## Screenshot
-TODO
+<TODO: paste screenshot or remove the section>
 ```
 
 For small PRs, skip section headers and write 1-3 concise bullets plus `## Screenshot` when appropriate.

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

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

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

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.

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

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/<version>, 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

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

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).

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)

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

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`]

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]

ai/templates/techspec.md

@@ -12,21 +12,23 @@
 
 - Feature module under `lib/features/<feature>/` — 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)]
 
 ## Implementation Design
 
 ### 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<ExampleEntity> fetch(String id);
-  Stream<List<ExampleEntity>> watchAll();
+// Use case — IO orchestration lives under lib/common/usecase/
+@riverpod
+Future<ExampleEntity> fetchExampleUseCase(Ref ref, String id) async {
+  final dio = ref.read(dioProvider);
+  final response = await dio.get<Map<String, dynamic>>('/examples/$id');
+  return ExampleResponseDTO.fromJson(response.data!).toEntity();
 }
 ```
 
@@ -35,7 +37,10 @@ abstract class ExampleRepository {
 @riverpod
 class ExampleController extends _$ExampleController {
   @override
-  Future<ExampleState> build() async => ref.read(exampleRepositoryProvider).load();
+  Future<ExampleState> build() async {
+    final example = await ref.read(fetchExampleUseCaseProvider('id').future);
+    return ExampleState(example: example);
+  }
 
   Future<void> 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.]