@cubis/foundry 0.3.67 → 0.3.69

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/flutter-go-router/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: flutter-go-router
+description: "Use when adding or refactoring typed GoRouter navigation, guards, shell routes, deep links, or notification-driven routing in Flutter. Do not use for state management or feature business logic."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "1.0"
+compatibility: Claude Code, Codex, GitHub Copilot
+---
+
+# Flutter GoRouter
+
+## Purpose
+
+Guide typed Flutter navigation architecture with safe redirects, deep-link
+handling, and predictable shell-route behavior.
+
+## When to Use
+
+- Adding a route or nested route
+- Introducing auth or init guards
+- Adding a bottom-nav shell
+- Handling deep links or FCM notification taps
+- Fixing redirect loops or back-stack issues
+
+## Instructions
+
+1. Define the route map and parameter shape first.
+2. Choose the right route type for the navigation behavior.
+3. Use typed route classes instead of raw string paths in widgets.
+4. Keep `redirect` and `onEnter` pure, fast, and loop-safe.
+5. Validate deep-link inputs before building pages.
+6. Preserve branch stacks intentionally when using shell navigation.
+7. Add tests for guards, deep links, and shell-route behavior where the flow is non-trivial.
+
+## Output Format
+
+Produce navigation guidance or code that:
+
+- uses typed routes intentionally,
+- explains guard and deep-link decisions,
+- identifies shell-route versus standard-route boundaries,
+- includes edge cases for invalid params or redirect loops.
+
+## References
+
+Load only what the current step needs.
+
+| File | Load when |
+| --- | --- |
+| `references/typed-routes.md` | Defining route files, params, query handling, or typed route usage patterns. |
+| `references/guards-and-deeplinks.md` | Adding auth guards, splash/init gates, notification routing, or shell-route preservation. |
+
+## Scripts
+
+No helper scripts are required for this skill right now.
+
+## Examples
+
+- "Add a typed detail route and deep-link handling for products."
+- "Set up a stateful shell route for Flutter bottom navigation."

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/flutter-go-router/references/guards-and-deeplinks.md

@@ -0,0 +1,20 @@
+# Guards and Deep Links
+
+## Guard Rules
+
+- Redirect functions stay pure and deterministic.
+- Check the current matched location before redirecting to avoid loops.
+- Preserve user intent with a `from` query when redirecting to auth.
+- Keep init/auth guards separate when they represent different state machines.
+
+## Deep-Link Rules
+
+- Validate required IDs and query params before building the page.
+- Route invalid or incomplete links to a safe fallback or error screen.
+- Keep notification payload parsing outside widgets when possible.
+
+## Shell Navigation
+
+- Use stateful shell navigation when each tab needs its own stack.
+- Give each branch its own navigator key.
+- Test back navigation and tab switching explicitly.

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/flutter-go-router/references/typed-routes.md

@@ -0,0 +1,27 @@
+# Typed Routes
+
+## Route File Layout
+
+Prefer a dedicated routing area such as:
+
+- `lib/core/routing/app_router.dart`
+- `lib/core/routing/routes/<feature>_route.dart`
+
+## Route Type Choice
+
+- `GoRouteData` for normal screen routes
+- `ShellRouteData` for shared wrappers with one navigator
+- stateful shell route for persistent tabs with independent stacks
+
+## Parameter Rules
+
+- Required path params for canonical resource identity
+- Optional query params for filters, search, and non-identity state
+- Use `extra` sparingly and avoid relying on it for deep-linkable flows
+
+## Widget Usage
+
+- `ProductListRoute().go(context)`
+- `ProductDetailRoute(id: id).push(context)`
+
+Do not call `context.go('/products')` from widgets when typed routes exist.

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/flutter-offline-sync/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: flutter-offline-sync
+description: "Use when implementing or auditing offline-first sync in Flutter with a local database, outbox queue, retry policy, conflict handling, and dead-letter behavior. Do not use for simple online-only CRUD."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "1.0"
+compatibility: Claude Code, Codex, GitHub Copilot
+---
+
+# Flutter Offline Sync
+
+## Purpose
+
+Guide local-first write flows that reconcile with the server later through an
+outbox queue, retry policy, and explicit conflict handling.
+
+## When to Use
+
+- Adding offline-first writes to a feature
+- Designing or auditing outbox behavior
+- Handling retry, dead-letter, or conflict states
+- Wiring connectivity-driven background draining
+
+## Instructions
+
+1. Identify the feature and write operations that need offline behavior.
+2. Choose a conflict strategy per feature.
+3. Ensure the outbox infrastructure exists once per project.
+4. Persist locally first, then enqueue sync work.
+5. Never block UI completion on network success.
+6. Surface sync status and dead-letter behavior clearly in the UI.
+7. Keep retry policy bounded and explicit.
+
+## Output Format
+
+Produce offline-sync guidance or code that:
+
+- shows the local-write then outbox-enqueue contract,
+- names the retry, dead-letter, and conflict decisions,
+- separates one-time infrastructure from per-feature integration,
+- includes sync-status UI expectations when relevant.
+
+## References
+
+Load only what the current step needs.
+
+| File | Load when |
+| --- | --- |
+| `references/outbox-full.md` | Setting up the outbox table or service, connectivity listeners, feature handlers, retry logic, or dead-letter UI. |
+
+## Scripts
+
+No helper scripts are required for this skill right now.
+
+## Examples
+
+- "Add offline-first create and update support to this Flutter repository."
+- "Review this outbox flow for retry and dead-letter mistakes."

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/flutter-offline-sync/references/outbox-full.md

@@ -0,0 +1,44 @@
+# Outbox Full
+
+## One-Time Infrastructure
+
+- Outbox table persisted in Drift
+- Outbox service responsible for dequeue, dispatch, retry, and dead-letter transitions
+- Connectivity service that triggers draining when the device comes back online
+- Optional app-init seeding for empty local stores
+
+## Repository Write Contract
+
+1. Generate an operation ID.
+2. Persist the local change.
+3. Enqueue the serialized operation.
+4. Trigger a non-blocking drain when online.
+5. Return the local result immediately.
+
+## Feature Handler Contract
+
+Each queued feature operation needs a handler that:
+
+- decodes the payload,
+- calls the correct API operation,
+- marks success or updates retry/dead-letter state,
+- applies conflict policy when the server rejects the write semantically.
+
+## Sync Status Contract
+
+Offline-capable records should expose a sync field such as:
+
+- `pendingSync`
+- `synced`
+- `failed`
+- `dead`
+- `conflict`
+
+## Conflict Strategies
+
+- `clientWins`
+- `serverWins`
+- `lastWriteWins`
+- `manualResolve`
+
+Pick one per feature. Safety-critical data should not default to silent overwrite.

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/flutter-repository/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: flutter-repository
+description: "Use when building or refactoring a Flutter feature data layer: Drift tables and DAOs, DTOs, mappers, Retrofit APIs, and repository orchestration. Do not use when the task needs a full feature scaffold across presentation and routing."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "1.0"
+compatibility: Claude Code, Codex, GitHub Copilot
+---
+
+# Flutter Repository
+
+## Purpose
+
+Generate or review one Flutter feature's data layer while keeping persistence,
+transport, mapping, and orchestration properly separated.
+
+## When to Use
+
+- Adding a new repository
+- Adding local tables or DAOs
+- Adding DTOs and network API interfaces
+- Wiring local-first read/write behavior
+- Updating sync logic in an existing repository
+
+## Instructions
+
+1. Define the local table and DAO contract first.
+2. Define DTOs and the remote API interface separately.
+3. Keep mapping logic outside large repository methods where possible.
+4. Let repositories own local and remote coordination.
+5. Keep DAOs persistence-focused and DTOs transport-focused.
+6. If offline sync exists, persist locally and enqueue sync work instead of blocking on the network.
+7. Add tests for local-first reads, writes, and sync behavior.
+
+## Output Format
+
+Produce repository-layer guidance or code that:
+
+- separates table, DAO, DTO, mapper, API, and repository responsibilities,
+- explains any offline-sync behavior,
+- identifies test points for read, write, and sync flows,
+- avoids collapsing the whole data layer into a single file.
+
+## References
+
+Load only what the current step needs.
+
+| File | Load when |
+| --- | --- |
+| `references/drift-patterns.md` | Designing local tables, DAO helpers, sync-status fields, or Drift-side read and write helpers. |
+| `references/retrofit-patterns.md` | Designing DTOs, Retrofit interfaces, mapper boundaries, or repository orchestration. |
+
+## Scripts
+
+No helper scripts are required for this skill right now.
+
+## Examples
+
+- "Create the Flutter repository layer for a new offline-capable entity."
+- "Refactor this feature repository so DAO, DTO, and mapping logic are separated."

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/flutter-repository/references/drift-patterns.md

@@ -0,0 +1,21 @@
+# Drift Patterns
+
+## Local Table Checklist
+
+- stable primary key,
+- timestamps when the domain needs ordering or sync,
+- `syncStatus` and `operationId` when offline sync exists,
+- indexes for common filters or joins.
+
+## DAO Checklist
+
+- `watchAll()` or other reactive streams for UI-facing reads
+- detail reads such as `getById`
+- insert, update, upsert, and delete helpers
+- targeted status updates such as `markSynced` or `markDead` when needed
+
+## Performance Rules
+
+- Prefer `count()` queries over loading whole rows to test emptiness at scale.
+- Use batch writes for bulk sync.
+- Use transactions for multi-table writes.

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/flutter-repository/references/retrofit-patterns.md

@@ -0,0 +1,20 @@
+# Retrofit Patterns
+
+## DTO Rules
+
+- DTOs mirror the wire contract.
+- Use explicit JSON keys when backend naming differs.
+- Keep DTOs separate from domain models.
+
+## API Interface Rules
+
+- Keep the interface thin and transport-oriented.
+- Return typed DTOs, not raw maps, when the shape is known.
+- Keep auth, base URL, and interceptors outside the generated interface.
+
+## Repository Rules
+
+- Reads return local data first.
+- Remote refresh populates local storage.
+- Writes persist locally, enqueue sync work, and return early.
+- Mappers convert DTOs to companions/domain types instead of building them inline everywhere.

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/flutter-riverpod/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: flutter-riverpod
+description: "Use when creating, refactoring, or auditing Riverpod 3 providers and notifiers in Flutter with code generation and correct lifecycle boundaries. Do not use for widget-local ephemeral state that should stay inside the UI."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "1.0"
+compatibility: Claude Code, Codex, GitHub Copilot
+---
+
+# Flutter Riverpod
+
+## Purpose
+
+Guide production Riverpod usage in Flutter with code generation, correct
+lifecycle boundaries, explicit side-effect handling, and testable provider
+design.
+
+## When to Use
+
+- Adding a provider or notifier
+- Refactoring provider lifecycles
+- Fixing rebuild storms or dependency loops
+- Designing async loading and mutation flows
+- Writing or reviewing Riverpod tests
+
+## Instructions
+
+1. Confirm the current package set before making version-sensitive changes. When the task touches `pubspec.yaml` or migration guidance, verify Riverpod package versions against the official docs and the project's Flutter SDK constraints instead of assuming an old example is current.
+2. Choose the narrowest provider type that matches the problem.
+3. Default to generated providers for app code.
+4. Keep business logic in repositories and services behind injected providers.
+5. Use `ref.watch` for build-time dependency tracking, `ref.read` for callbacks and mutation methods, and `ref.listen` for UI side effects.
+6. Default to auto-dispose and opt into `keepAlive` only when the state clearly needs it.
+7. Guard post-`await` writes with `ref.mounted` when disposal is possible.
+8. Prefer targeted invalidation and rebuilds over broad refresh behavior.
+9. Treat experimental Riverpod features as optional and follow project conventions if they are already in use.
+10. Test provider behavior directly with overrides and `ProviderContainer` or scoped widget tests.
+
+## Output Format
+
+Produce Riverpod guidance or code that:
+
+- uses provider types intentionally,
+- keeps side effects out of build paths,
+- exposes clear override points for repositories and services,
+- includes verification guidance where behavior is non-trivial.
+
+## References
+
+Load only what the current step needs.
+
+| File | Load when |
+| --- | --- |
+| `references/version-matrix.md` | You need package-selection guidance or need to verify Riverpod versions against current docs and Flutter SDK constraints. |
+| `references/provider-selection.md` | You need to choose provider types, keep-alive policy, family inputs, or side-effect boundaries. |
+| `references/async-lifecycle.md` | You are designing async flows, refresh or retry behavior, stream-backed state, invalidation, or disposal boundaries. |
+| `references/testing.md` | You need `ProviderContainer`, widget test, or provider override patterns. |
+
+## Scripts
+
+No helper scripts are required for this skill right now.
+
+## Examples
+
+- "Refactor this feature from manual providers to generated `AsyncNotifier` providers."
+- "Choose the right Riverpod provider types for auth, paging, and per-item state."

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/flutter-riverpod/references/async-and-mutations.md

@@ -0,0 +1,19 @@
+# Async and Mutations
+
+## Async Rules
+
+- Use `ref.watch` inside build methods.
+- In mutation methods, use `ref.read` for dependencies.
+- Guard post-`await` state updates with `ref.mounted` when disposal is possible.
+- Prefer invalidate-and-rebuild over bespoke refresh state machines unless the UX needs something custom.
+
+## Stream Rules
+
+- Prefer streams for local reactive data such as Drift watches.
+- Map raw repository output into a UI-friendly state shape at the provider boundary.
+
+## Mutation Rules
+
+- Keep mutation methods thin.
+- Do not trigger UI side effects directly from the provider unless the project has a dedicated side-effect channel.
+- If the project already uses experimental Riverpod mutation helpers, follow existing conventions instead of mixing styles.

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/flutter-riverpod/references/async-lifecycle.md

@@ -0,0 +1,19 @@
+# Async Lifecycle
+
+## Async Rules
+
+- Use `ref.watch` inside build methods.
+- In mutation methods, use `ref.read` for dependencies.
+- Guard post-`await` state updates with `ref.mounted` when disposal is possible.
+- Prefer invalidate-and-rebuild over bespoke refresh state machines unless the UX needs something custom.
+
+## Stream Rules
+
+- Prefer streams for local reactive data such as Drift watches.
+- Map raw repository output into a UI-friendly state shape at the provider boundary.
+
+## Mutation Rules
+
+- Keep mutation methods thin.
+- Do not trigger UI side effects directly from the provider unless the project has a dedicated side-effect channel.
+- If the project already uses experimental Riverpod mutation helpers, follow existing conventions instead of mixing styles.

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/flutter-riverpod/references/provider-selection.md

@@ -0,0 +1,20 @@
+# Provider Selection
+
+## Decision Guide
+
+- pure derived value -> function provider
+- mutable synchronous UI/domain state -> `Notifier`
+- async load with mutations -> `AsyncNotifier`
+- reactive database or socket stream -> stream-backed provider or notifier
+
+## Lifecycle Rules
+
+- auto-dispose by default for screen or parameter-scoped state
+- `keepAlive: true` only for low-cardinality, app-wide, expensive state
+- avoid unbounded keep-alive families
+
+## Boundary Rules
+
+- providers stay top-level,
+- widgets do not own business state transitions,
+- repositories and services remain injectable dependencies.

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/flutter-riverpod/references/testing.md

@@ -0,0 +1,21 @@
+# Riverpod Testing
+
+## Test What Matters
+
+- initial state,
+- success transition,
+- empty transition,
+- error transition,
+- mutation side effects or invalidation behavior.
+
+## Test Tools
+
+- `ProviderContainer` for provider-level tests
+- widget tests for UI reactions to provider state
+- repository/service fakes or mocks through overrides
+
+## Rules
+
+- dispose the container,
+- override dependencies explicitly,
+- assert transitions instead of only final values when behavior matters.

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/flutter-riverpod/references/version-matrix.md

@@ -0,0 +1,24 @@
+# Version Matrix
+
+Do not treat this file as a hardcoded source of truth for package numbers.
+
+## When Version Guidance Is Needed
+
+Before recommending or editing Riverpod package versions:
+
+1. Inspect the project's current Flutter and Dart SDK constraints.
+2. Check the official Riverpod packages and migration notes.
+3. Prefer a version set that is internally compatible with the project's SDK and existing generator tooling.
+
+## Packages to Check Together
+
+- `flutter_riverpod`
+- `riverpod_annotation`
+- `riverpod_generator`
+- `riverpod_lint`
+- `build_runner`
+
+## Output Rule
+
+When the task is version-sensitive, state the versions you verified and why
+they fit the project instead of copying a stale example blindly.

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/flutter-state-machine/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: flutter-state-machine
+description: "Use when implementing or auditing the shared Flutter screen-state contract: loading, data, empty, error, and dead-letter rendering plus consistent error mapping. Do not use for generic Riverpod work when the project does not use this AppState pattern."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "1.0"
+compatibility: Claude Code, Codex, GitHub Copilot
+---
+
+# Flutter State Machine
+
+## Purpose
+
+Guide a consistent Flutter screen-state contract so loading, data, empty,
+error, and dead-letter behavior are handled predictably across features.
+
+## When to Use
+
+- Adding app-state infrastructure
+- Refactoring a screen away from ad hoc async branching
+- Auditing notifier state transitions
+- Standardizing error and dead-letter rendering
+
+## Instructions
+
+1. Identify whether the screen is list, detail, or mutation-heavy.
+2. Map repository or service output into the shared app-state contract.
+3. Keep notifier transition logic small and explicit.
+4. Keep AppError typed and request-ID aware.
+5. Render through a shared state widget or equivalent adapter where possible.
+6. Ensure every failure path carries enough context for support and debugging.
+
+## Output Format
+
+Produce app-state guidance or code that:
+
+- names the expected state cases,
+- shows where notifier mapping stops and widget rendering starts,
+- keeps error and dead-letter behavior distinct,
+- includes the shared rendering expectations for state-specific UI.
+
+## References
+
+Load only what the current step needs.
+
+| File | Load when |
+| --- | --- |
+| `references/app-state-contract.md` | Defining `AppState`, `AppError`, and notifier mapping rules. |
+| `references/ui-rendering.md` | Building or reviewing the shared widget that renders each state consistently. |
+
+## Scripts
+
+No helper scripts are required for this skill right now.
+
+## Examples
+
+- "Standardize this Flutter screen on the shared AppState contract."
+- "Review these notifier transitions for missing error or dead-letter cases."

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/flutter-state-machine/references/app-state-contract.md

@@ -0,0 +1,23 @@
+# App State Contract
+
+## Expected States
+
+- `loading`
+- `data`
+- `empty`
+- `error`
+- `deadLetter`
+
+## Error Contract
+
+Errors should carry enough context for:
+
+- user-facing messaging,
+- developer debugging,
+- support follow-up through a request or correlation ID.
+
+## Notifier Rules
+
+- Start from a deliberate initial state.
+- Map repository/service failures into typed app errors.
+- Keep mutation methods thin and consistent with the same error contract.

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/flutter-state-machine/references/ui-rendering.md

@@ -0,0 +1,14 @@
+# UI Rendering
+
+## Shared Rendering Rules
+
+- Render app state through one shared abstraction when possible.
+- Use shared design-system widgets for loading, empty, error, and dead-letter states.
+- Keep the data branch focused on actual content, not error plumbing.
+
+## Review Checklist
+
+- error state exposes request ID when available,
+- empty state has helpful next-step messaging,
+- dead-letter state does not masquerade as a retryable transient error,
+- loading state matches the design system.

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/flutter-testing/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: flutter-testing
+description: "Use when adding or refactoring Flutter tests for repositories, services, Riverpod notifiers, widgets, and golden coverage around a feature. Do not use for production feature implementation unless the task is explicitly test-focused."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "1.0"
+compatibility: Claude Code, Codex, GitHub Copilot
+---
+
+# Flutter Testing
+
+## Purpose
+
+Guide layered Flutter verification so repositories, services, notifiers,
+widgets, and high-value UI surfaces are tested at the right level.
+
+## When to Use
+
+- Adding missing test coverage
+- Writing tests for a new feature
+- Verifying offline-sync behavior
+- Testing provider state transitions
+- Adding widget or golden regression coverage
+
+## Instructions
+
+1. Identify which feature layers actually exist before generating tests.
+2. Cover repository behavior with local persistence and sync expectations.
+3. Cover service rules separately when business logic exists.
+4. Cover notifier or provider transitions directly.
+5. Cover widgets for state-specific rendering and interaction.
+6. Add goldens only where visual regression risk is real.
+7. Assert transitions and side effects, not only final snapshots.
+
+## Output Format
+
+Produce test guidance or code that:
+
+- identifies the right layers to test,
+- names the behaviors that must be verified,
+- distinguishes unit, provider, widget, and golden coverage,
+- includes offline-sync expectations when the feature needs them.
+
+## References
+
+Load only what the current step needs.
+
+| File | Load when |
+| --- | --- |
+| `references/test-layers.md` | Choosing which repository, service, notifier, widget, or golden tests to generate. |
+| `references/offline-sync-tests.md` | Verifying outbox, retry, conflict, or dead-letter behavior. |
+
+## Scripts
+
+No helper scripts are required for this skill right now.
+
+## Examples
+
+- "Add repository, notifier, and widget tests for this Flutter feature."
+- "Review the offline-sync tests for retry and dead-letter coverage gaps."

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/flutter-testing/references/offline-sync-tests.md

@@ -0,0 +1,16 @@
+# Offline Sync Tests
+
+## Cover These Behaviors
+
+- write succeeds locally before network success,
+- outbox entry is queued correctly,
+- remote sync upserts data idempotently,
+- retry count changes on failure,
+- dead-letter state appears after retry exhaustion,
+- conflict handling follows the declared feature policy.
+
+## Useful Test Shapes
+
+- in-memory Drift database for repository tests
+- mocked API and connectivity services
+- notifier tests that assert sync-status or dead-letter transitions