@cubis/foundry 0.3.10

package/Ai Agent Workflow/powers/react-expert/steering/testing-react.md

@@ -0,0 +1,174 @@
+# Testing React
+
+## Basic Component Test
+
+```tsx
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+test('renders greeting', () => {
+  render(<Greeting name="World" />);
+  expect(screen.getByText('Hello, World!')).toBeInTheDocument();
+});
+
+test('increments counter on click', async () => {
+  const user = userEvent.setup();
+  render(<Counter />);
+
+  await user.click(screen.getByRole('button', { name: /increment/i }));
+
+  expect(screen.getByText('1')).toBeInTheDocument();
+});
+```
+
+## Query Priority
+
+```tsx
+// Preferred: Accessible queries (how users find elements)
+screen.getByRole('button', { name: /submit/i });
+screen.getByLabelText('Email');
+screen.getByPlaceholderText('Search...');
+screen.getByText('Welcome');
+
+// Fallback: Test IDs (when no accessible name)
+screen.getByTestId('custom-element');
+
+// Async queries (wait for element)
+await screen.findByText('Loading complete');
+```
+
+## Testing Forms
+
+```tsx
+test('submits form with user data', async () => {
+  const handleSubmit = vi.fn();
+  const user = userEvent.setup();
+
+  render(<ContactForm onSubmit={handleSubmit} />);
+
+  await user.type(screen.getByLabelText('Name'), 'John Doe');
+  await user.type(screen.getByLabelText('Email'), 'john@example.com');
+  await user.selectOptions(screen.getByLabelText('Topic'), 'support');
+  await user.click(screen.getByRole('button', { name: /submit/i }));
+
+  expect(handleSubmit).toHaveBeenCalledWith({
+    name: 'John Doe',
+    email: 'john@example.com',
+    topic: 'support',
+  });
+});
+```
+
+## Testing with Providers
+
+```tsx
+function renderWithProviders(
+  ui: React.ReactElement,
+  { initialState = {}, ...options } = {}
+) {
+  function Wrapper({ children }: { children: React.ReactNode }) {
+    return (
+      <QueryClientProvider client={queryClient}>
+        <ThemeProvider>
+          {children}
+        </ThemeProvider>
+      </QueryClientProvider>
+    );
+  }
+
+  return render(ui, { wrapper: Wrapper, ...options });
+}
+
+test('displays user data', async () => {
+  renderWithProviders(<UserProfile userId="123" />);
+
+  await screen.findByText('John Doe');
+});
+```
+
+## Mocking API Calls
+
+```tsx
+import { http, HttpResponse } from 'msw';
+import { setupServer } from 'msw/node';
+
+const server = setupServer(
+  http.get('/api/users/:id', ({ params }) => {
+    return HttpResponse.json({ id: params.id, name: 'John' });
+  })
+);
+
+beforeAll(() => server.listen());
+afterEach(() => server.resetHandlers());
+afterAll(() => server.close());
+
+test('fetches and displays user', async () => {
+  render(<UserProfile userId="123" />);
+
+  await screen.findByText('John');
+});
+
+test('handles error', async () => {
+  server.use(
+    http.get('/api/users/:id', () => {
+      return new HttpResponse(null, { status: 500 });
+    })
+  );
+
+  render(<UserProfile userId="123" />);
+
+  await screen.findByText('Error loading user');
+});
+```
+
+## Testing Hooks
+
+```tsx
+import { renderHook, act } from '@testing-library/react';
+
+test('useCounter increments', () => {
+  const { result } = renderHook(() => useCounter());
+
+  act(() => {
+    result.current.increment();
+  });
+
+  expect(result.current.count).toBe(1);
+});
+
+test('useDebounce delays value', async () => {
+  vi.useFakeTimers();
+
+  const { result, rerender } = renderHook(
+    ({ value }) => useDebounce(value, 500),
+    { initialProps: { value: 'initial' } }
+  );
+
+  rerender({ value: 'updated' });
+  expect(result.current).toBe('initial');
+
+  await act(async () => {
+    vi.advanceTimersByTime(500);
+  });
+
+  expect(result.current).toBe('updated');
+  vi.useRealTimers();
+});
+```
+
+## Quick Reference
+
+| Query | Use When |
+|-------|----------|
+| `getByRole` | Buttons, links, headings |
+| `getByLabelText` | Form inputs |
+| `getByText` | Non-interactive text |
+| `findByX` | Async/loading content |
+| `queryByX` | Assert NOT present |
+
+| Pattern | Use Case |
+|---------|----------|
+| `userEvent.setup()` | User interactions |
+| `renderHook()` | Testing custom hooks |
+| `msw` | Mocking API calls |
+| Custom render | Wrap with providers |

package/Ai Agent Workflow/powers/red-team-tactics/POWER.md

@@ -0,0 +1,13 @@
+---
+name: red-team-tactics
+description: Red team tactics principles based on MITRE ATT&CK. Attack phases, detection evasion, reporting.
+---
+
+# red-team-tactics
+
+This is a compatibility power wrapper for the `red-team-tactics` skill.
+
+Primary source:
+- `Ai Agent Workflow/skills/red-team-tactics/SKILL.md`
+
+Use this folder for power-specific extensions when needed.

package/Ai Agent Workflow/powers/red-team-tactics/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: red-team-tactics
+description: Red team tactics principles based on MITRE ATT&CK. Attack phases, detection evasion, reporting.
+---
+
+# red-team-tactics
+
+This power mirrors the base skill:
+- `Ai Agent Workflow/skills/red-team-tactics/SKILL.md`
+
+When both exist, prefer the base skill as source of truth unless power-specific overrides are added here.

package/Ai Agent Workflow/powers/refactor/POWER.md

@@ -0,0 +1,63 @@
+---
+name: "refactor"
+displayName: "Refactor - OneUp HR"
+description: "Migrate legacy code to new architecture while maintaining behavior"
+keywords: ["refactor", "migrate", "clean", "improve", "legacy", "architecture"]
+---
+
+# Refactor - OneUp HR
+
+## Migration Patterns
+
+### State: Legacy → Riverpod
+
+```dart
+// FROM
+class _MyScreenState extends State<MyScreen> {
+  bool _isLoading = false;
+}
+
+// TO
+@riverpod
+class MyNotifier extends _$MyNotifier {
+  @override
+  FutureOr<State> build() => State.initial();
+}
+```
+
+### Models: Class → Freezed
+
+```dart
+// FROM
+class User {
+  final String id;
+  User({required this.id});
+}
+
+// TO
+@freezed
+class User with _$User {
+  const factory User({required String id}) = _User;
+  factory User.fromJson(Map<String, dynamic> json) => _$UserFromJson(json);
+}
+```
+
+### Colors: Hardcoded → Tokens
+
+```dart
+// FROM
+Color(0xFF123456)
+Colors.white
+
+// TO
+context.colors.primary
+OneColor.white
+```
+
+## Checklist
+
+- [ ] Replace hardcoded values with design tokens
+- [ ] Convert to Riverpod providers
+- [ ] Add freezed for models
+- [ ] Remove dead code
+- [ ] Verify behavior unchanged

package/Ai Agent Workflow/powers/refactor/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: "refactor"
+displayName: "Refactor - OneUp HR"
+description: "Migrate legacy code to new architecture while maintaining behavior"
+keywords: ["refactor", "migrate", "clean", "improve", "legacy", "architecture"]
+---
+
+# Refactor - OneUp HR
+
+## Migration Patterns
+
+### State: Legacy → Riverpod
+
+```dart
+// FROM
+class _MyScreenState extends State<MyScreen> {
+  bool _isLoading = false;
+}
+
+// TO
+@riverpod
+class MyNotifier extends _$MyNotifier {
+  @override
+  FutureOr<State> build() => State.initial();
+}
+```
+
+### Models: Class → Freezed
+
+```dart
+// FROM
+class User {
+  final String id;
+  User({required this.id});
+}
+
+// TO
+@freezed
+class User with _$User {
+  const factory User({required String id}) = _User;
+  factory User.fromJson(Map<String, dynamic> json) => _$UserFromJson(json);
+}
+```
+
+### Colors: Hardcoded → Tokens
+
+```dart
+// FROM
+Color(0xFF123456)
+Colors.white
+
+// TO
+context.colors.primary
+OneColor.white
+```
+
+## Checklist
+
+- [ ] Replace hardcoded values with design tokens
+- [ ] Convert to Riverpod providers
+- [ ] Add freezed for models
+- [ ] Remove dead code
+- [ ] Verify behavior unchanged

package/Ai Agent Workflow/powers/riverpod-3/POWER.md

@@ -0,0 +1,143 @@
+---
+name: "riverpod-3"
+displayName: "Riverpod 3 Expert"
+description: "Riverpod 3 best practices for codegen, UI interaction boundaries, caching, paging, lifecycle, and testing"
+keywords:
+  [
+    "riverpod",
+    "riverpod 3",
+    "flutter",
+    "state management",
+    "asyncnotifier",
+    "codegen",
+    "keepalive",
+    "testing",
+  ]
+---
+
+# Riverpod 3 Expert
+
+## Overview
+
+Use this skill for production-grade Riverpod 3 usage in Flutter apps.
+Focus: correct provider lifecycles, predictable UI interaction, rebuild control, side effects, and testability.
+
+## When to Use
+
+- Creating or refactoring providers/notifiers
+- Solving rebuild storms or dependency loops
+- Designing refresh/paging/cache behavior
+- Defining provider lifecycles (`autoDispose` vs `keepAlive`)
+- Writing Riverpod unit/widget tests
+
+## Quick Reference
+
+### AsyncNotifier Pattern
+
+```dart
+@riverpod
+class OrdersController extends _$OrdersController {
+  @override
+  FutureOr<OrdersState> build() async {
+    final repo = ref.watch(ordersRepositoryProvider);
+    final items = await repo.fetchOrders();
+    return OrdersState(items: items);
+  }
+
+  Future<void> refresh() async {
+    ref.invalidateSelf();
+    await future;
+  }
+
+  Future<void> createOrder(CreateOrderInput input) async {
+    final repo = ref.read(ordersRepositoryProvider);
+    state = const AsyncLoading();
+    state = await AsyncValue.guard(() async {
+      await repo.createOrder(input);
+      if (!ref.mounted) return const OrdersState(items: []);
+      final items = await repo.fetchOrders();
+      return OrdersState(items: items);
+    });
+  }
+}
+```
+
+### watch/read/listen/listenManual
+
+```dart
+// Build/render: watch
+final state = ref.watch(ordersControllerProvider);
+
+// User callbacks: read
+onPressed: () => ref.read(ordersControllerProvider.notifier).refresh();
+
+// UI side effects in build-capable context
+ref.listen(ordersControllerProvider, (prev, next) {
+  next.whenOrNull(error: (e, st) => showErrorSnackBar(context, e));
+});
+
+// Lifecycle side effects (initState/dispose flows)
+late final remove = ref.listenManual(authStateProvider, (prev, next) {
+  if (next.isLoggedOut) context.go('/login');
+});
+```
+
+### keepAlive Rule
+
+```dart
+// Use only for app-wide long-lived state
+@Riverpod(keepAlive: true)
+SessionState sessionState(Ref ref) => const SessionState.unknown();
+```
+
+Default to auto-dispose for route/screen-scoped and family providers.
+
+## Core Rules (Do/Don't)
+
+1. Do use `ref.watch` only in widget/provider build paths.
+2. Do use `ref.read` for callbacks and imperative actions.
+3. Do use `ref.listen`/`ref.listenManual` for side effects (navigation/snackbar/dialog).
+4. Don't trigger side effects from render branches (`watch + if + navigate`).
+5. Don't call notifier mutation methods from widget `build`.
+6. Don't mutate collections in-place; always emit new immutable values.
+7. Do keep provider parameters stable and immutable (correct `==/hashCode`).
+8. Do keep business state in providers and ephemeral UI state in widgets.
+
+## KeepAlive Decision Matrix
+
+Use `keepAlive: true` only when all are true:
+- state should survive route changes,
+- recomputation is expensive,
+- cardinality is low (not unbounded families).
+
+Avoid keepAlive for:
+- search/filter family providers,
+- row/detail item families,
+- short-lived forms.
+
+## Loop Avoidance Checklist
+
+- No notifier writes inside provider `build()` unless conditional and bounded.
+- No unconditional `invalidateSelf()` in `build()`.
+- No provider cycles (A watches B and B watches A).
+- No `ref.watch` in callbacks.
+- Audit repeated rebuilds with narrowed `select` usage.
+
+## Steering Files
+
+- `loop-avoidance.md` - Loop diagnostics and safe patterns
+- `minimal-rebuild.md` - `select`, widget splitting, item-level providers
+- `provider-layout.md` - Generic provider organization and boundaries
+- `refresh-cache-paging.md` - Refresh/paging/cache recipes
+- `testing.md` - ProviderContainer and widget test patterns
+
+## Examples
+
+- `attendance_paging.md` - Complete paging example
+- `profile_edit.md` - Form workflow example
+
+## Templates
+
+- `cache_policy.dart` - TTL helper for repository cache policy
+- `paged_controller.dart` - Cursor/page-based infinite list controller
+- `riverpod_controller_test` - Provider/controller test template

package/Ai Agent Workflow/powers/riverpod-3/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: "riverpod-3"
+displayName: "Riverpod 3 Expert"
+description: "Riverpod 3 best practices for codegen, UI interaction boundaries, caching, paging, lifecycle, and testing"
+keywords:
+  [
+    "riverpod",
+    "riverpod 3",
+    "flutter",
+    "state management",
+    "asyncnotifier",
+    "codegen",
+    "keepalive",
+    "testing",
+  ]
+---
+
+# Riverpod 3 Expert
+
+## Overview
+
+Use this skill for production-grade Riverpod 3 usage in Flutter apps.
+Focus: correct provider lifecycles, predictable UI interaction, rebuild control, side effects, and testability.
+
+## When to Use
+
+- Creating or refactoring providers/notifiers
+- Solving rebuild storms or dependency loops
+- Designing refresh/paging/cache behavior
+- Defining provider lifecycles (`autoDispose` vs `keepAlive`)
+- Writing Riverpod unit/widget tests
+
+## Quick Reference
+
+### AsyncNotifier Pattern
+
+```dart
+@riverpod
+class OrdersController extends _$OrdersController {
+  @override
+  FutureOr<OrdersState> build() async {
+    final repo = ref.watch(ordersRepositoryProvider);
+    final items = await repo.fetchOrders();
+    return OrdersState(items: items);
+  }
+
+  Future<void> refresh() async {
+    ref.invalidateSelf();
+    await future;
+  }
+
+  Future<void> createOrder(CreateOrderInput input) async {
+    final repo = ref.read(ordersRepositoryProvider);
+    state = const AsyncLoading();
+    state = await AsyncValue.guard(() async {
+      await repo.createOrder(input);
+      if (!ref.mounted) return const OrdersState(items: []);
+      final items = await repo.fetchOrders();
+      return OrdersState(items: items);
+    });
+  }
+}
+```
+
+### watch/read/listen/listenManual
+
+```dart
+// Build/render: watch
+final state = ref.watch(ordersControllerProvider);
+
+// User callbacks: read
+onPressed: () => ref.read(ordersControllerProvider.notifier).refresh();
+
+// UI side effects in build-capable context
+ref.listen(ordersControllerProvider, (prev, next) {
+  next.whenOrNull(error: (e, st) => showErrorSnackBar(context, e));
+});
+
+// Lifecycle side effects (initState/dispose flows)
+late final remove = ref.listenManual(authStateProvider, (prev, next) {
+  if (next.isLoggedOut) context.go('/login');
+});
+```
+
+### keepAlive Rule
+
+```dart
+// Use only for app-wide long-lived state
+@Riverpod(keepAlive: true)
+SessionState sessionState(Ref ref) => const SessionState.unknown();
+```
+
+Default to auto-dispose for route/screen-scoped and family providers.
+
+## Core Rules (Do/Don't)
+
+1. Do use `ref.watch` only in widget/provider build paths.
+2. Do use `ref.read` for callbacks and imperative actions.
+3. Do use `ref.listen`/`ref.listenManual` for side effects (navigation/snackbar/dialog).
+4. Don't trigger side effects from render branches (`watch + if + navigate`).
+5. Don't call notifier mutation methods from widget `build`.
+6. Don't mutate collections in-place; always emit new immutable values.
+7. Do keep provider parameters stable and immutable (correct `==/hashCode`).
+8. Do keep business state in providers and ephemeral UI state in widgets.
+
+## KeepAlive Decision Matrix
+
+Use `keepAlive: true` only when all are true:
+- state should survive route changes,
+- recomputation is expensive,
+- cardinality is low (not unbounded families).
+
+Avoid keepAlive for:
+- search/filter family providers,
+- row/detail item families,
+- short-lived forms.
+
+## Loop Avoidance Checklist
+
+- No notifier writes inside provider `build()` unless conditional and bounded.
+- No unconditional `invalidateSelf()` in `build()`.
+- No provider cycles (A watches B and B watches A).
+- No `ref.watch` in callbacks.
+- Audit repeated rebuilds with narrowed `select` usage.
+
+## Steering Files
+
+- `loop-avoidance.md` - Loop diagnostics and safe patterns
+- `minimal-rebuild.md` - `select`, widget splitting, item-level providers
+- `provider-layout.md` - Generic provider organization and boundaries
+- `refresh-cache-paging.md` - Refresh/paging/cache recipes
+- `testing.md` - ProviderContainer and widget test patterns
+
+## Examples
+
+- `attendance_paging.md` - Complete paging example
+- `profile_edit.md` - Form workflow example
+
+## Templates
+
+- `cache_policy.dart` - TTL helper for repository cache policy
+- `paged_controller.dart` - Cursor/page-based infinite list controller
+- `riverpod_controller_test` - Provider/controller test template

package/Ai Agent Workflow/powers/riverpod-3/examples/attendance_paging.md

@@ -0,0 +1,29 @@
+# Example: Attendance list with paging + refresh (realistic)
+
+This example shows how to implement:
+- initial load (today’s attendance)
+- pull-to-refresh
+- infinite scroll “load more” (older records)
+- cached-first UX
+
+## Files
+- `features/attendance/attendance_controller.dart`
+- `features/attendance/attendance_state.dart`
+- `features/attendance/views/attendance_view.dart`
+
+## State (simplified)
+Use `PagedState<AttendanceRecord>` from the template.
+
+## Controller
+Use `PagedItemsController` template but rename:
+- `PagedAttendanceController`
+- `AttendanceRepository.fetchAttendancePage(...)`
+
+## UI
+- The screen watches the controller provider.
+- A `ScrollController` triggers `loadNextPage` when close to bottom.
+- `RefreshIndicator` calls `refresh()`.
+
+Important minimal-rebuild tip:
+- The list widget should be a separate widget that receives `items` as plain values.
+- Only one place watches the provider.

package/Ai Agent Workflow/powers/riverpod-3/examples/profile_edit.md

@@ -0,0 +1,15 @@
+# Example: Profile edit flow (load + edit + save, loop-free)
+
+Goal:
+- Load profile (AsyncNotifier build)
+- Edit in UI without triggering network calls per keystroke
+- Save -> invalidateSelf -> refresh
+
+Pattern:
+- Controller exposes AsyncValue<ProfileState>.
+- Text fields use local `TextEditingController` for draft edits.
+- On Save: call controller.save(draft) (ref.read(notifier))
+- After save success: controller invalidates itself so build reloads canonical data.
+
+This avoids the common anti-pattern:
+- writing draft state directly into provider on each keystroke (causes rebuild storms).