@cubis/foundry 0.3.70 → 0.3.72

package/workflows/powers/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/powers/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/powers/flutter-riverpod/POWER.md

@@ -0,0 +1,70 @@
+````markdown
+---
+inclusion: manual
+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/powers/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/powers/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/powers/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/powers/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/powers/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/powers/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/powers/flutter-state-machine/POWER.md

@@ -0,0 +1,62 @@
+````markdown
+---
+inclusion: manual
+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/powers/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/powers/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/powers/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/powers/flutter-testing/POWER.md

@@ -0,0 +1,64 @@
+````markdown
+---
+inclusion: manual
+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/powers/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/powers/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

package/workflows/powers/flutter-testing/references/test-layers.md

@@ -0,0 +1,33 @@
+# Test Layers
+
+## Repository Tests
+
+Cover:
+
+- local writes,
+- remote sync import,
+- outbox enqueue behavior when applicable,
+- stream/read correctness.
+
+## Service Tests
+
+Cover:
+
+- business-rule success paths,
+- each meaningful failure path,
+- edge cases around validation and policy.
+
+## Notifier or Provider Tests
+
+Cover:
+
+- initial state,
+- success,
+- empty,
+- error,
+- mutation-triggered refresh or invalidation.
+
+## Widget and Golden Tests
+
+- Widget tests verify state-specific rendering and interaction.
+- Golden tests verify stable shared or high-value UI surfaces.