strvcom · michalurbanek · May 18, 2026 · May 15, 2026 · May 15, 2026 · May 15, 2026
@@ -1,10 +1,15 @@
 @../AGENTS.md
 
-Project-specific reusable AI workflows live in `../ai/skills/`:
-- `../ai/skills/flutter-template-feature-screen/SKILL.md`
-- `../ai/skills/flutter-template-feature-data-flow/SKILL.md`
-- `../ai/skills/flutter-template-upgrade/SKILL.md`
-- `../ai/skills/flutter-template-release-prepare/SKILL.md`
-- `../ai/skills/flutter-template-release-builds/SKILL.md`
-- `../ai/skills/flutter-template-secrets-bootstrap/SKILL.md`
-- `../ai/skills/flutter-template-pr-review/SKILL.md`
+Project-specific reusable AI workflows live in `../ai/skills/` and are surfaced
+to Claude Code two ways:
+- **auto-discovery**: `./skills/<name>` is a symlink with target
+  `../../ai/skills/<name>` (resolved from `.claude/skills/`, this points
+  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`.
+
+See the "Reusable Workflows" section of `AGENTS.md` for the canonical list of
+skills and the four-step convention for adding a new one.
@@ -0,0 +1,8 @@
+---
+description: Run the full build / test / analyze / format verification pass for this Flutter app.
+argument-hint: [optional flags: --full | --skip-gen | --skip-builds | --ios-only | --android-only]
+---
+
+Use the `build-verify` skill to run codegen, analyze, test, native builds, and format. Nothing is committed.
+
+$ARGUMENTS
@@ -0,0 +1,8 @@
+---
+description: Verify, commit, push, and create or update a GitHub PR.
+argument-hint: [type, ticket, title, or base branch]
+---
+
+Use the `create-pr` skill to prepare and open a pull request.
+
+$ARGUMENTS
@@ -0,0 +1,8 @@
+---
+description: Build a full backend-backed feature (DTOs, entities, use cases, state, UI).
+argument-hint: [feature name + API endpoint(s) or data source]
+---
+
+Use the `feature-data-flow` skill to implement a complete data-backed feature.
+
+$ARGUMENTS
@@ -0,0 +1,8 @@
+---
+description: Add a new screen / route / feature folder using the existing pattern.
+argument-hint: [feature name or short description]
+---
+
+Use the `feature-screen` skill to add a new screen or route in `lib/features/`.
+
+$ARGUMENTS
@@ -0,0 +1,8 @@
+---
+description: Execute generated Flutter task files in dependency order without committing.
+argument-hint: [feature name or task folder]
+---
+
+Use the `implement-tasks-sequence` skill to implement generated task files.
+
+$ARGUMENTS
@@ -0,0 +1,8 @@
+---
+description: Implement one generated Flutter task without committing.
+argument-hint: [feature/task file or task number]
+---
+
+Use the `implement` skill to complete one Flutter task.
+
+$ARGUMENTS
@@ -0,0 +1,8 @@
+---
+description: Run Flutter/Dart formatting and analyzer checks for the current worktree.
+argument-hint: [auto|all|--check|--format-only|--analyze-only]
+---
+
+Use the `lint-format` skill to format and analyze Flutter code.
+
+$ARGUMENTS
@@ -0,0 +1,8 @@
+---
+description: Bug-first review of the current branch or diff. Findings first, ordered by severity.
+argument-hint: [optional branch, PR, or scope hints]
+---
+
+Use the `pr-review` skill to review the current branch / diff / PR.
+
+$ARGUMENTS
@@ -0,0 +1,8 @@
+---
+description: Create a Flutter feature Product Requirements Document.
+argument-hint: [feature name or brief]
+---
+
+Use the `prd` skill to create a product requirements document.
+
+$ARGUMENTS
@@ -0,0 +1,8 @@
+---
+description: Customize a fresh template (app identity, platforms, icons, splash, Firebase, secrets).
+argument-hint: [setup phase or specific item]
+---
+
+Use the `project-setup` skill to customize this template for a new app.
+
+$ARGUMENTS
@@ -0,0 +1,8 @@
+---
+description: Post-merge release builds — Android tags and iOS IPA generation + archival.
+argument-hint: [flavor or step: develop|staging|production]
+---
+
+Use the `release-builds` skill for post-merge release builds. Run only after the release PR has been merged.
+
+$ARGUMENTS
@@ -0,0 +1,8 @@
+---
+description: Prepare a release branch + PR (version bump, release notes, branch).
+argument-hint: [target version, e.g. 1.4.0+12]
+---
+
+Use the `release-prepare` skill to prepare the release branch and PR. Do not create tags or build artifacts in this phase.
+
+$ARGUMENTS
@@ -0,0 +1,8 @@
+---
+description: Triage and resolve AI or human GitHub PR review comments for the current branch.
+argument-hint: [optional comment scope, reviewer, or fix instructions]
+---
+
+Use the `review-pr-comments` skill to handle PR feedback on the current branch.
+
+$ARGUMENTS
@@ -0,0 +1,8 @@
+---
+description: Work with encrypted secrets, env files, and signing material safely.
+argument-hint: [operation: decrypt | encrypt | clean | inspect]
+---
+
+Use the `secrets-bootstrap` skill. Prefer existing make targets and avoid logging secret values.
+
+$ARGUMENTS
@@ -0,0 +1,8 @@
+---
+description: Run the post-spec Flutter implementation pipeline end to end without committing.
+argument-hint: [feature name or task folder]
+---
+
+Use the `start-job` skill to run tasks, implementation, verification, and PR review for a completed spec.
+
+$ARGUMENTS
@@ -0,0 +1,8 @@
+---
+description: Break a PRD + tech spec into discrete, dependency-ordered implementation tasks.
+argument-hint: [feature name or path to prd.md/techspec.md]
+---
+
+Use the `tasks` skill to generate the task list and individual task files under `.claude/tasks/[feature]/`. Requires a PRD and tech spec.
+
+$ARGUMENTS
@@ -0,0 +1,8 @@
+---
+description: Translate a PRD into an implementation-ready Flutter tech spec.
+argument-hint: [feature name or path to prd.md]
+---
+
+Use the `techspec` skill to author `.claude/tasks/[feature-name]/techspec.md` from the PRD, grounded in this codebase's Riverpod / Freezed / AutoRoute / Dio / Firebase stack.
+
+$ARGUMENTS
@@ -0,0 +1,8 @@
+---
+description: Upgrade Flutter SDK and/or package dependencies, keeping everything aligned.
+argument-hint: [target Flutter version or scope]
+---
+
+Use the `upgrade` skill to bump the Flutter SDK and dependencies.
+
+$ARGUMENTS
@@ -0,0 +1,44 @@
+{
+  "permissions": {
+    "deny": [
+      "Read(**/google-services.json)",
+      "Read(**/GoogleService-Info.plist)",
+      "Read(**/local.properties)",
+      "Read(**/keystore.properties)",
+      "Read(**/*.jks)",
+      "Read(**/*.keystore)",
+      "Read(**/*.p12)",
+      "Read(**/*.mobileprovision)",
+      "Read(**/*.provisionprofile)",
+      "Read(**/.env)",
+      "Read(**/.env.*)",
+      "Read(**/*.pem)",
+      "Read(**/*.key)",
+      "Read(**/*.cer)",
+      "Read(**/*.p8)",
+      "Read(**/secrets.json)",
+      "Read(**/secrets.yaml)",
+      "Read(**/secrets.properties)",
+      "Read(**/service-account*.json)",
+      "Read(**/.netrc)",
+      "Read(**/.npmrc)",
+      "Read(**/.gitmodules)",
+      "Read(**/.gradle/**)",
+      "Read(**/.idea/**)",
+      "Read(**/.git/**)",
+      "Read(**/.kotlin/**)",
+      "Read(**/.run/**)",
+      "Read(**/build/**)",
+      "Read(**/.dart_tool/**)",
+      "Read(**/.fvm/**)",
+      "Read(**/Pods/**)",
+      "Read(**/DerivedData/**)",
+      "Read(**/xcuserdata/**)",
+      "Read(**/*.xcuserstate)",
+      "Read(**/Flutter/Generated.xcconfig)",
+      "Read(**/Flutter/flutter_export_environment.sh)",
+      "Read(**/coverage/**)",
+      "Read(**/.DS_Store)"
+    ]
+  }
+}
@@ -0,0 +1 @@
+../../ai/skills/build-verify
@@ -0,0 +1 @@
+../../ai/skills/create-pr
@@ -0,0 +1 @@
+../../ai/skills/feature-data-flow
@@ -0,0 +1 @@
+../../ai/skills/feature-screen
@@ -0,0 +1 @@
+../../ai/skills/implement
@@ -0,0 +1 @@
+../../ai/skills/implement-tasks-sequence
@@ -0,0 +1 @@
+../../ai/skills/lint-format
@@ -0,0 +1 @@
+../../ai/skills/pr-review
@@ -0,0 +1 @@
+../../ai/skills/prd
@@ -0,0 +1 @@
+../../ai/skills/project-setup
@@ -0,0 +1 @@
+../../ai/skills/release-builds
@@ -0,0 +1 @@
+../../ai/skills/release-prepare
@@ -0,0 +1 @@
+../../ai/skills/review-pr-comments
@@ -0,0 +1 @@
+../../ai/skills/secrets-bootstrap
@@ -0,0 +1 @@
+../../ai/skills/start-job
@@ -0,0 +1 @@
+../../ai/skills/tasks
@@ -0,0 +1 @@
+../../ai/skills/techspec
@@ -0,0 +1 @@
+../../ai/skills/upgrade
@@ -0,0 +1 @@
+../../ai/templates/prd.md
@@ -0,0 +1 @@
+../../ai/templates/task-list.md
@@ -0,0 +1 @@
+../../ai/templates/task.md
@@ -0,0 +1 @@
+../../ai/templates/techspec.md
@@ -43,12 +43,49 @@ Use this file as the entrypoint for automated work in this repository.
 - If you learn a stable, repo-specific convention while working, update `docs/PROJECT_OVERVIEW.md` or `docs/PROJECT_GUIDELINES.md` instead of adding duplicate instructions elsewhere.
 
 ## Reusable Workflows
-- Shared AI workflow guides live under `ai/skills/`.
-- Use them for repeatable procedures such as:
-  - creating a new feature screen
-  - building a full data-backed feature
-  - upgrading Flutter and dependencies
-  - preparing a release branch and PR
-  - running post-merge release builds
-  - working with encrypted secrets and signing material
-  - reviewing pull requests and diffs
+Repeatable procedures live as skills under `ai/skills/<name>/SKILL.md`. Each
+skill has YAML frontmatter (`name:`, `description:`) so it can be auto-discovered
+by AI tools that support skills.
+
+Existing skills:
+- `project-setup` — customize a new app from this template (identity, platforms, icons, splash, Firebase/secrets, validation)
+- `feature-screen` — add a new route / screen using the existing feature pattern
+- `feature-data-flow` — build a full backend-backed feature (DTOs, entities, use cases, state, UI)
+- `upgrade` — upgrade Flutter SDK and package dependencies
+- `release-prepare` — version bump, release notes, release branch, release PR
+- `release-builds` — post-merge Android tags and iOS IPA generation + archival
+- `secrets-bootstrap` — safe handling of encrypted secrets and signing material
+- `pr-review` — bug-first review of branches / diffs / PRs
+- `review-pr-comments` — triage and resolve AI or human GitHub PR feedback
+- `create-pr` — verify, commit, push, and create or update a GitHub PR
+- `lint-format` — run Flutter/Dart formatting and analyzer checks
+- `build-verify` — full build/test/analyze/format pass (codegen + analyze + test, then iOS + Android builds in parallel, then `dart format`); auto-scopes to the diff and leaves the working tree dirty for review
+- `start-job` — run the post-spec implementation pipeline (`tasks` → `implement-tasks-sequence` → `build-verify` → `pr-review`)
+- `prd` — create a Flutter feature Product Requirements Document under `.claude/tasks/<feature>/prd.md`
+- `tasks` — break a PRD + tech spec into discrete, dependency-ordered Flutter implementation tasks under `.claude/tasks/<feature>/` using `ai/templates/task.md` and `ai/templates/task-list.md`
+- `implement` — implement one generated Flutter task using the repo architecture and verification rules
+- `implement-tasks-sequence` — execute generated task files in dependency order before final verification
+- `techspec` — translate a PRD into an implementation-ready Flutter tech spec at `.claude/tasks/<feature>/techspec.md`, grounded in the Riverpod / Freezed / AutoRoute / Dio / Firebase stack
+
+### How AI tools find these skills
+- **Codex** reads this `AGENTS.md` and the referenced `ai/skills/<name>/SKILL.md`
+  files. When delegating, mention the workflow by name, e.g. *"use the
+  feature-data-flow workflow"*.
+- **Claude Code** auto-discovers skills through `.claude/skills/<name>` symlinks
+  that point at `ai/skills/<name>/`. Each skill is also exposed as a slash
+  command at `.claude/commands/<name>.md`, so `/feature-screen`, `/pr-review`,
+  `/release-prepare`, etc. work as explicit invocations.
+
+### Creating a new skill
+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.
+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>`
+4. **Add a slash command.** Create `.claude/commands/<name>.md` using one of the
+   existing commands as a template — a short frontmatter (`description`,
+   `argument-hint`) and a one-line body that invokes the skill, followed by
+   `$ARGUMENTS`.