@cubis/foundry 0.3.10

package/Ai Agent Workflow/powers/drift-flutter/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: "drift-flutter"
+description: "Use when implementing Flutter local persistence with Drift: schema design, DAOs, migrations, transactions, and repository integration"
+---
+
+# Drift Flutter
+
+## When to Use
+
+- Adding or refactoring local data persistence in Flutter
+- Migrating from Isar/SQLite wrappers to Drift
+- Creating typed SQL queries, DAOs, and migrations
+- Designing offline-first repository read/write behavior
+
+## Core Workflow
+
+1. Define schema (tables, indexes, constraints)
+2. Add/adjust DAOs for read/write/query use-cases
+3. Implement migrations with backward-compatible strategy
+4. Wire repositories to DAOs (UI must not call DAOs directly)
+5. Validate with migration and DAO tests
+
+## Design Rules
+
+- Keep Drift in data layer only.
+- Keep one app database entrypoint and expose DAOs.
+- Use transactions for multi-table consistency.
+- Add indexes for frequent filters/joins.
+- Prefer soft-delete/status flags when history matters.
+- Keep session/auth flags out of Drift if simple key-value is enough.
+
+## Migration Rules
+
+- Every schema version bump requires explicit migration steps.
+- Never drop user data silently.
+- Backfill new required columns safely (defaults or staged migration).
+- Test migration from at least previous production schema.
+
+## Repository Integration
+
+- Read flow: local-first, optional remote refresh, then persist.
+- Write flow: persist local state deterministically and reconcile sync policy.
+- Keep mapper logic in repository/data mapping classes.
+
+## Load References When Needed
+
+- `steering/migrations.md` for migration strategy and checklist
+- `steering/queries-and-daos.md` for DAO/query patterns

package/Ai Agent Workflow/powers/drift-flutter/steering/migrations.md

@@ -0,0 +1,21 @@
+# Drift migration checklist
+
+## Before migration
+
+- Identify current schema version.
+- List table/column/index changes.
+- Decide data backfill/default strategy.
+
+## Safe migration pattern
+
+1. Increment schema version.
+2. Apply additive changes first (new nullable/defaulted columns, new tables).
+3. Backfill data where needed.
+4. Add stricter constraints only after data is valid.
+5. Rebuild dependent indexes/views if changed.
+
+## Verification
+
+- Migration test from N-1 to N.
+- Data integrity checks for key tables.
+- Query regression checks for critical screens.

package/Ai Agent Workflow/powers/drift-flutter/steering/queries-and-daos.md

@@ -0,0 +1,20 @@
+# Drift DAO/query patterns
+
+## DAO guidelines
+
+- Group by aggregate/root feature, not by screen.
+- Keep return types explicit (table row, projection model, or stream).
+- Prefer typed expressions over raw SQL unless query complexity requires raw SQL.
+
+## Query patterns
+
+- Use stream queries for live lists needing immediate updates.
+- Use one-shot futures for actions/details where live updates are unnecessary.
+- Add indexes for columns used in WHERE + ORDER BY.
+
+## Transactions
+
+Use `transaction(() async { ... })` for operations that must commit together:
+- receipt + receipt lines,
+- stock movement + inventory quantity update,
+- shift close summary + cash variance record.

package/Ai Agent Workflow/powers/error-ux-observability/POWER.md

@@ -0,0 +1,158 @@
+---
+name: "error-ux-observability"
+displayName: "Error UX & Observability"
+description: "Map backend failures to user-friendly messages, implement proper logging levels, and ensure observable error handling"
+keywords:
+  [
+    "error handling",
+    "error messages",
+    "logging",
+    "observability",
+    "user feedback",
+    "failure mapping",
+    "error ux",
+  ]
+---
+
+# Error UX & Observability
+
+## Overview
+
+This power helps you translate technical errors into user-friendly messages, implement proper logging for debugging, and ensure errors are observable in production.
+
+## When to Use
+
+- Implementing error handling in repositories/use cases
+- Mapping API errors to UI messages
+- Adding logging to track issues
+- Reviewing error handling code
+- Debugging production issues
+
+## Quick Reference
+
+### Failure to UI Message Mapping
+
+```dart
+// ✅ Map technical errors to user-friendly messages
+String getErrorMessage(Failure failure) {
+  return failure.when(
+    network: () => 'No internet connection. Please check your network.',
+    server: (code, message) {
+      if (code == 401) return 'Session expired. Please login again.';
+      if (code == 403) return 'You don\'t have permission for this action.';
+      if (code == 404) return 'Resource not found.';
+      if (code >= 500) return 'Server error. Please try again later.';
+      return message ?? 'Something went wrong.';
+    },
+    validation: (errors) => errors.values.first,
+    unauthorized: () => 'Please login to continue.',
+    notFound: () => 'Item not found.',
+    unknown: (error) => 'An unexpected error occurred.',
+  );
+}
+```
+
+### Logging Levels
+
+```dart
+// ✅ Use appropriate log levels
+logger.debug('Cache hit for attendance data'); // Development only
+logger.info('User logged in: userId=${user.id}'); // Important events
+logger.warning('API rate limit approaching'); // Potential issues
+logger.error('Failed to sync attendance', error: e, stackTrace: st); // Errors
+logger.fatal('Database corruption detected'); // Critical failures
+```
+
+### Error Context
+
+```dart
+// ✅ Include context in errors
+try {
+  await repository.submitLeave(leaveRequest);
+} catch (e, st) {
+  logger.error(
+    'Failed to submit leave request',
+    error: e,
+    stackTrace: st,
+    context: {
+      'userId': user.id,
+      'leaveType': leaveRequest.type,
+      'startDate': leaveRequest.startDate,
+    },
+  );
+  rethrow;
+}
+```
+
+## Error Handling Patterns
+
+### Repository Layer
+
+```dart
+@override
+Future<Result<Attendance>> submitAttendance(AttendanceRequest request) async {
+  try {
+    final response = await _remoteDataSource.submit(request);
+    return Result.success(response);
+  } on DioException catch (e) {
+    logger.error('Submit attendance failed', error: e);
+    return Result.failure(_mapDioError(e));
+  } catch (e, st) {
+    logger.error('Unexpected error', error: e, stackTrace: st);
+    return Result.failure(Failure.unknown(e.toString()));
+  }
+}
+```
+
+### Controller Layer
+
+```dart
+Future<void> submit() async {
+  final prev = state;
+  state = const AsyncLoading();
+  
+  final result = await ref.read(featureRepositoryProvider).submit(request);
+  
+  result.when(
+    success: (data) => ref.invalidateSelf(),
+    failure: (failure) {
+      logger.warning('Submit failed', context: {'failure': failure});
+      state = prev;
+      throw Exception(failure.message);
+    },
+  );
+}
+```
+
+### UI Layer
+
+```dart
+ref.listen(controllerProvider, (prev, next) {
+  next.whenOrNull(
+    error: (error, _) {
+      final message = error is Failure 
+        ? getErrorMessage(error)
+        : 'An unexpected error occurred';
+      OneSnackbar.error(context, message);
+    },
+  );
+});
+```
+
+## Logging Best Practices
+
+1. **Never log sensitive data** (passwords, tokens, PII)
+2. **Include context** (userId, action, timestamp)
+3. **Use structured logging** (key-value pairs)
+4. **Log at appropriate levels** (debug/info/warning/error/fatal)
+5. **Include stack traces for errors**
+
+## Steering Files
+
+- `failure_to_ui.md` - Complete failure-to-message mapping guide
+- `logging_levels.md` - When to use each log level
+
+## Templates
+
+- `failure_message_mapper` - Failure to UI message mapper template
+

package/Ai Agent Workflow/powers/error-ux-observability/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: "error-ux-observability"
+displayName: "Error UX & Observability"
+description: "Map backend failures to user-friendly messages, implement proper logging levels, and ensure observable error handling"
+keywords:
+  [
+    "error handling",
+    "error messages",
+    "logging",
+    "observability",
+    "user feedback",
+    "failure mapping",
+    "error ux",
+  ]
+---
+
+# Error UX & Observability
+
+## Overview
+
+This power helps you translate technical errors into user-friendly messages, implement proper logging for debugging, and ensure errors are observable in production.
+
+## When to Use
+
+- Implementing error handling in repositories/use cases
+- Mapping API errors to UI messages
+- Adding logging to track issues
+- Reviewing error handling code
+- Debugging production issues
+
+## Quick Reference
+
+### Failure to UI Message Mapping
+
+```dart
+// ✅ Map technical errors to user-friendly messages
+String getErrorMessage(Failure failure) {
+  return failure.when(
+    network: () => 'No internet connection. Please check your network.',
+    server: (code, message) {
+      if (code == 401) return 'Session expired. Please login again.';
+      if (code == 403) return 'You don\'t have permission for this action.';
+      if (code == 404) return 'Resource not found.';
+      if (code >= 500) return 'Server error. Please try again later.';
+      return message ?? 'Something went wrong.';
+    },
+    validation: (errors) => errors.values.first,
+    unauthorized: () => 'Please login to continue.',
+    notFound: () => 'Item not found.',
+    unknown: (error) => 'An unexpected error occurred.',
+  );
+}
+```
+
+### Logging Levels
+
+```dart
+// ✅ Use appropriate log levels
+logger.debug('Cache hit for attendance data'); // Development only
+logger.info('User logged in: userId=${user.id}'); // Important events
+logger.warning('API rate limit approaching'); // Potential issues
+logger.error('Failed to sync attendance', error: e, stackTrace: st); // Errors
+logger.fatal('Database corruption detected'); // Critical failures
+```
+
+### Error Context
+
+```dart
+// ✅ Include context in errors
+try {
+  await repository.submitLeave(leaveRequest);
+} catch (e, st) {
+  logger.error(
+    'Failed to submit leave request',
+    error: e,
+    stackTrace: st,
+    context: {
+      'userId': user.id,
+      'leaveType': leaveRequest.type,
+      'startDate': leaveRequest.startDate,
+    },
+  );
+  rethrow;
+}
+```
+
+## Error Handling Patterns
+
+### Repository Layer
+
+```dart
+@override
+Future<Result<Attendance>> submitAttendance(AttendanceRequest request) async {
+  try {
+    final response = await _remoteDataSource.submit(request);
+    return Result.success(response);
+  } on DioException catch (e) {
+    logger.error('Submit attendance failed', error: e);
+    return Result.failure(_mapDioError(e));
+  } catch (e, st) {
+    logger.error('Unexpected error', error: e, stackTrace: st);
+    return Result.failure(Failure.unknown(e.toString()));
+  }
+}
+```
+
+### Controller Layer
+
+```dart
+Future<void> submit() async {
+  final prev = state;
+  state = const AsyncLoading();
+  
+  final result = await ref.read(featureRepositoryProvider).submit(request);
+  
+  result.when(
+    success: (data) => ref.invalidateSelf(),
+    failure: (failure) {
+      logger.warning('Submit failed', context: {'failure': failure});
+      state = prev;
+      throw Exception(failure.message);
+    },
+  );
+}
+```
+
+### UI Layer
+
+```dart
+ref.listen(controllerProvider, (prev, next) {
+  next.whenOrNull(
+    error: (error, _) {
+      final message = error is Failure 
+        ? getErrorMessage(error)
+        : 'An unexpected error occurred';
+      OneSnackbar.error(context, message);
+    },
+  );
+});
+```
+
+## Logging Best Practices
+
+1. **Never log sensitive data** (passwords, tokens, PII)
+2. **Include context** (userId, action, timestamp)
+3. **Use structured logging** (key-value pairs)
+4. **Log at appropriate levels** (debug/info/warning/error/fatal)
+5. **Include stack traces for errors**
+
+## Steering Files
+
+- `failure_to_ui.md` - Complete failure-to-message mapping guide
+- `logging_levels.md` - When to use each log level
+
+## Templates
+
+- `failure_message_mapper` - Failure to UI message mapper template
+

package/Ai Agent Workflow/powers/error-ux-observability/steering/failure_to_ui.md

@@ -0,0 +1,12 @@
+# Failure -> UI mapping (OneUp HR)
+
+## Rules
+- Do not show raw exceptions to users.
+- Always provide an action when possible.
+
+## Mapping table (example)
+- network -> "You're offline. Please check your internet." (Retry)
+- auth -> "Session expired. Please sign in again." (Go to login)
+- validation -> show field errors (Fix inputs)
+- server -> "Something went wrong on our side." (Retry)
+- cache -> "Saved data is unavailable." (Retry/Refresh)

package/Ai Agent Workflow/powers/error-ux-observability/steering/logging_levels.md

@@ -0,0 +1,8 @@
+# Logging levels
+
+- Debug builds: detailed logs allowed but still redact secrets
+- Release builds: only essential logs + correlation ids
+- Never log: tokens, passwords, OTPs, precise location unless required and approved
+
+Prefer structured logs:
+- method, path, status, duration, requestId

package/Ai Agent Workflow/powers/error-ux-observability/templates/failure_message_mapper.md

@@ -0,0 +1,16 @@
+```
+// templates/failure_message_mapper.tmpl
+//
+// Map Failure to safe user message.
+
+String userMessageFromFailure(Failure f) {
+  return f.when(
+    server: (m) => m ?? 'Something went wrong. Please try again.',
+    network: (m) => m ?? 'No internet connection. Please check and retry.',
+    cache: (m) => m ?? 'Saved data is unavailable. Please refresh.',
+    auth: (m) => m ?? 'Session expired. Please sign in again.',
+    validation: (m) => m ?? 'Please check your input and try again.',
+    unknown: (m) => m ?? 'Unexpected error. Please try again.',
+  );
+}
+```

package/Ai Agent Workflow/powers/fastapi-expert/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: fastapi-expert
+description: Use when building high-performance async Python APIs with FastAPI and Pydantic V2. Invoke for async SQLAlchemy, JWT authentication, WebSockets, OpenAPI documentation.
+license: MIT
+metadata:
+  author: https://github.com/Jeffallan
+  version: "1.0.0"
+  domain: backend
+  triggers: FastAPI, Pydantic, async Python, Python API, REST API Python, SQLAlchemy async, JWT authentication, OpenAPI, Swagger Python
+  role: specialist
+  scope: implementation
+  output-format: code
+  related-skills: fullstack-guardian, django-expert, test-master
+---
+
+# FastAPI Expert
+
+Senior FastAPI specialist with deep expertise in async Python, Pydantic V2, and production-grade API development.
+
+## Role Definition
+
+You are a senior Python engineer with 10+ years of API development experience. You specialize in FastAPI with Pydantic V2, async SQLAlchemy, and modern Python 3.11+ patterns. You build scalable, type-safe APIs with automatic documentation.
+
+## When to Use This Skill
+
+- Building REST APIs with FastAPI
+- Implementing Pydantic V2 validation schemas
+- Setting up async database operations
+- Implementing JWT authentication/authorization
+- Creating WebSocket endpoints
+- Optimizing API performance
+
+## Core Workflow
+
+1. **Analyze requirements** - Identify endpoints, data models, auth needs
+2. **Design schemas** - Create Pydantic V2 models for validation
+3. **Implement** - Write async endpoints with proper dependency injection
+4. **Secure** - Add authentication, authorization, rate limiting
+5. **Test** - Write async tests with pytest and httpx
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| Pydantic V2 | `steering/pydantic-v2.md` | Creating schemas, validation, model_config |
+| SQLAlchemy | `steering/async-sqlalchemy.md` | Async database, models, CRUD operations |
+| Endpoints | `steering/endpoints-routing.md` | APIRouter, dependencies, routing |
+| Authentication | `steering/authentication.md` | JWT, OAuth2, get_current_user |
+| Testing | `steering/testing-async.md` | pytest-asyncio, httpx, fixtures |
+| Django Migration | `steering/migration-from-django.md` | Migrating from Django/DRF to FastAPI |
+
+## Constraints
+
+### MUST DO
+- Use type hints everywhere (FastAPI requires them)
+- Use Pydantic V2 syntax (`field_validator`, `model_validator`, `model_config`)
+- Use `Annotated` pattern for dependency injection
+- Use async/await for all I/O operations
+- Use `X | None` instead of `Optional[X]`
+- Return proper HTTP status codes
+- Document endpoints (auto-generated OpenAPI)
+
+### MUST NOT DO
+- Use synchronous database operations
+- Skip Pydantic validation
+- Store passwords in plain text
+- Expose sensitive data in responses
+- Use Pydantic V1 syntax (`@validator`, `class Config`)
+- Mix sync and async code improperly
+- Hardcode configuration values
+
+## Output Templates
+
+When implementing FastAPI features, provide:
+1. Schema file (Pydantic models)
+2. Endpoint file (router with endpoints)
+3. CRUD operations if database involved
+4. Brief explanation of key decisions
+
+## Knowledge Reference
+
+FastAPI, Pydantic V2, async SQLAlchemy, Alembic migrations, JWT/OAuth2, pytest-asyncio, httpx, BackgroundTasks, WebSockets, dependency injection, OpenAPI/Swagger

package/Ai Agent Workflow/powers/fastapi-expert/steering/async-sqlalchemy.md

@@ -0,0 +1,146 @@
+# Async SQLAlchemy
+
+## Engine & Session Setup
+
+```python
+from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession, async_sessionmaker
+from sqlalchemy.orm import DeclarativeBase
+
+engine = create_async_engine(
+    settings.DATABASE_URL,
+    echo=settings.DEBUG,
+    pool_pre_ping=True,
+)
+
+async_session = async_sessionmaker(
+    engine,
+    class_=AsyncSession,
+    expire_on_commit=False,
+)
+
+class Base(DeclarativeBase):
+    pass
+```
+
+## Model Definition
+
+```python
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+from sqlalchemy import String, ForeignKey, DateTime, func
+from datetime import datetime
+
+class User(Base):
+    __tablename__ = "users"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    email: Mapped[str] = mapped_column(String(255), unique=True, index=True)
+    username: Mapped[str] = mapped_column(String(50), unique=True)
+    hashed_password: Mapped[str] = mapped_column(String(255))
+    is_active: Mapped[bool] = mapped_column(default=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime, server_default=func.now())
+
+    # Relationships
+    posts: Mapped[list["Post"]] = relationship(back_populates="author", lazy="selectin")
+
+class Post(Base):
+    __tablename__ = "posts"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    title: Mapped[str] = mapped_column(String(200))
+    content: Mapped[str]
+    author_id: Mapped[int] = mapped_column(ForeignKey("users.id"))
+
+    author: Mapped["User"] = relationship(back_populates="posts")
+```
+
+## Database Dependency
+
+```python
+from typing import AsyncGenerator
+from fastapi import Depends
+
+async def get_db() -> AsyncGenerator[AsyncSession, None]:
+    async with async_session() as session:
+        try:
+            yield session
+            await session.commit()
+        except Exception:
+            await session.rollback()
+            raise
+
+# Type alias for injection
+DB = Annotated[AsyncSession, Depends(get_db)]
+```
+
+## CRUD Operations
+
+```python
+from sqlalchemy import select, update, delete
+from sqlalchemy.orm import selectinload
+
+async def get_user(db: AsyncSession, user_id: int) -> User | None:
+    result = await db.execute(select(User).where(User.id == user_id))
+    return result.scalar_one_or_none()
+
+async def get_user_with_posts(db: AsyncSession, user_id: int) -> User | None:
+    result = await db.execute(
+        select(User)
+        .options(selectinload(User.posts))
+        .where(User.id == user_id)
+    )
+    return result.scalar_one_or_none()
+
+async def get_users(db: AsyncSession, skip: int = 0, limit: int = 100) -> list[User]:
+    result = await db.execute(select(User).offset(skip).limit(limit))
+    return list(result.scalars().all())
+
+async def create_user(db: AsyncSession, user_in: UserCreate) -> User:
+    user = User(**user_in.model_dump())
+    db.add(user)
+    await db.flush()
+    await db.refresh(user)
+    return user
+
+async def update_user(db: AsyncSession, user_id: int, user_in: UserUpdate) -> User:
+    await db.execute(
+        update(User)
+        .where(User.id == user_id)
+        .values(**user_in.model_dump(exclude_unset=True))
+    )
+    return await get_user(db, user_id)
+
+async def delete_user(db: AsyncSession, user_id: int) -> bool:
+    result = await db.execute(delete(User).where(User.id == user_id))
+    return result.rowcount > 0
+```
+
+## Lifespan Handler
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Startup
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+    yield
+    # Shutdown
+    await engine.dispose()
+
+app = FastAPI(lifespan=lifespan)
+```
+
+## Quick Reference
+
+| Operation | Method |
+|-----------|--------|
+| Select one | `result.scalar_one_or_none()` |
+| Select many | `result.scalars().all()` |
+| Eager load | `.options(selectinload(...))` |
+| Create | `db.add(obj)` + `await db.flush()` |
+| Update | `update(Model).where(...).values(...)` |
+| Delete | `delete(Model).where(...)` |
+| Commit | `await db.commit()` |
+| Rollback | `await db.rollback()` |