@cubis/foundry 0.3.67 → 0.3.69

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/error-ux-observability/SKILL.md

@@ -1,149 +1,169 @@
 ---
-name: "error-ux-observability"
-description: "Map backend failures to user-friendly messages, implement proper logging levels, and ensure observable error handling"
+name: error-ux-observability
+description: Design error experiences, structured logging, distributed tracing, alerting strategies, and user-facing error handling for production systems.
+license: Apache-2.0
+metadata:
+  author: cubis-foundry
+  version: "3.0"
+compatibility: Claude Code, Codex, GitHub Copilot, Gemini CLI
 ---
 # Error UX & Observability
 
-## Overview
+## Purpose
 
-This power helps you translate technical errors into user-friendly messages, implement proper logging for debugging, and ensure errors are observable in production.
+Bridge user-facing error handling and backend observability. Design error experiences that help users recover, while ensuring engineers have the telemetry to diagnose and fix issues quickly.
 
 ## 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.',
-  );
-}
-```
+- Designing error messages, states, and recovery flows for users
+- Implementing structured logging and error tracking
+- Setting up distributed tracing across services
+- Building alerting strategies that reduce noise
+- Creating error boundaries and fallback UI
+- Debugging production issues with telemetry data
 
-### Logging Levels
+## Instructions
 
-```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
-```
+### Step 1 — Design User-Facing Errors
 
-### 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;
-}
+Every error the user sees must answer three questions:
+
+1. **What happened?** (plain language, no stack traces)
+2. **Is it their fault or ours?** (affects tone)
+3. **What can they do next?** (always give an action)
+
+**Error message structure**:
+
+```
+[Title]: Brief description of what went wrong
+[Body]: What happened and why
+[Action]: Clear next step (retry, change input, contact support)
 ```
 
-## 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()));
+**Good vs Bad error messages**:
+| Bad | Good |
+|-----|------|
+| "Error 500" | "Something went wrong on our end. We're looking into it." |
+| "Invalid input" | "Email address must include @ and a domain (e.g., name@example.com)" |
+| "Network error" | "Couldn't reach the server. Check your connection and try again." |
+| "Null reference exception" | "We couldn't load your profile. Try refreshing the page." |
+
+**Error states in UI**:
+
+- **Inline**: validation errors next to the field that caused them
+- **Toast/snackbar**: transient non-critical errors (auto-dismiss in 5-8s)
+- **Banner**: persistent issues affecting the whole page
+- **Full page**: catastrophic failures with recovery path
+- **Empty state**: data couldn't load — show illustration + retry button
+
+### Step 2 — Implement Error Boundaries
+
+**Frontend**:
+
+- Catch errors at route/feature boundaries, not globally
+- Show fallback UI that lets the user continue elsewhere
+- Log the error with context (component tree, user action, state)
+- Auto-report to error tracking service
+
+**Backend**:
+
+- Return structured error responses:
+
+```json
+{
+  "error": {
+    "code": "PAYMENT_DECLINED",
+    "message": "Your card was declined. Please try a different payment method.",
+    "details": { "reason": "insufficient_funds" },
+    "requestId": "req_abc123"
   }
 }
 ```
 
-### 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);
-    },
-  );
-}
-```
+- Map internal errors to user-safe messages (never expose stack traces, SQL, or internal paths)
+- Include request ID for correlation
+- Use appropriate HTTP status codes (don't 200 everything)
+
+### Step 3 — Structured Logging
+
+**Every log entry should include**:
+
+- Timestamp (ISO 8601, UTC)
+- Level (debug, info, warn, error)
+- Message (human-readable)
+- Request ID / correlation ID
+- Service name and version
+- User ID (if authenticated)
+- Relevant context (input parameters, affected resource)
+
+**Log levels**:
+| Level | When | Example |
+|-------|------|---------|
+| error | Something failed that shouldn't have | Database connection lost |
+| warn | Something unusual but handled | Rate limit approaching |
+| info | Normal business events | User signed up, order placed |
+| debug | Development troubleshooting | Query parameters, cache hit/miss |
+
+**Rules**:
+
+- Never log secrets, passwords, tokens, or PII
+- Use structured format (JSON) for machine parsing
+- Include enough context to diagnose without reproducing
+- Log at the boundary (entry/exit of service calls)
+
+### Step 4 — Distributed Tracing
+
+**Trace propagation**:
+
+- Every request gets a trace ID at the edge
+- Pass trace ID through all service calls (HTTP headers, message metadata)
+- Each service creates spans for its operations
+- Spans include: operation name, duration, status, attributes
+
+**What to trace**:
+
+- HTTP requests (method, path, status, latency)
+- Database queries (operation, table, duration)
+- External API calls (service, endpoint, latency)
+- Queue operations (publish, consume, processing time)
+- Cache operations (hit/miss, key pattern, latency)
+
+### Step 5 — Alerting Strategy
+
+**Alert on symptoms, not causes**:
+
+- DO alert: "Error rate > 1% for 5 minutes"
+- DON'T alert: "CPU > 80%" (that's a dashboard metric, not an alert)
+
+**Reduce noise**:
+
+- Alert on SLO burn rate, not individual errors
+- Group related alerts (one page, not 50)
+- Required for every alert: runbook link, severity, escalation path
+- Review alert fatigue monthly — suppress alerts that never led to action
+
+## Output Format
 
-### 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);
-    },
-  );
-});
 ```
+## Error Handling Design
+[user-facing error strategy]
 
-## Logging Best Practices
+## Observability Implementation
+[logging, tracing, and metrics setup]
 
-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**
+## Alerting Rules
+[what triggers alerts and who responds]
+
+## Runbook
+[diagnosis and resolution steps for common errors]
+```
 
-## References
+## Examples
 
-Load detailed guidance only when needed.
+**User**: "Design error handling for our checkout flow"
 
-| File | Load when |
-| --- | --- |
-| `references/failure_to_ui.md` | Mapping backend/domain failures into user-facing messages and screen states |
-| `references/logging_levels.md` | Deciding which log level and structure to use for an event or failure |
+**Response approach**: Map all failure modes (payment declined, inventory gone, session expired, network error). Design user-facing messages for each. Implement retry logic for transient errors. Add structured logging at every decision point. Set up alerts on checkout error rate.
 
-## Templates
+**User**: "We can't figure out why requests are slow in production"
 
-- `failure_message_mapper` - Failure to UI message mapper template
+**Response approach**: Add distributed tracing to identify the slow span. Structured logging at service boundaries. Dashboard for p50/p95/p99 latency. Alert on latency SLO burn rate. Runbook for common latency causes.

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/error-ux-observability/evals/evals.json

@@ -0,0 +1,23 @@
+{
+  "evals": [
+    {
+      "prompt": "Design error handling for a checkout flow that can fail at payment, inventory, or shipping steps",
+      "assertions": [
+        "designs user-facing error messages for each failure mode",
+        "error messages answer what happened, whose fault, and what to do next",
+        "implements structured logging with correlation IDs",
+        "recommends retry logic for transient errors",
+        "includes error boundary or fallback UI pattern"
+      ]
+    },
+    {
+      "prompt": "We can't figure out why API requests are intermittently slow — no clear pattern",
+      "assertions": [
+        "recommends distributed tracing to identify slow spans",
+        "suggests structured logging at service boundaries",
+        "recommends latency percentile dashboards (p50, p95, p99)",
+        "addresses alerting on latency SLO burn rate"
+      ]
+    }
+  ]
+}

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/fastapi-expert/SKILL.md

@@ -1,83 +1,69 @@
 ---
 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.
+description: "Use when building FastAPI services with async Python, Pydantic v2, lifespan-managed resources, dependency-based auth, background task boundaries, and OpenAPI-safe request handling."
 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
+  author: cubis-foundry
+  version: "3.0"
+compatibility: Claude Code, Codex, GitHub Copilot
 ---
 # FastAPI Expert
 
-Senior FastAPI specialist with deep expertise in async Python, Pydantic V2, and production-grade API development.
+## Purpose
 
-## Role Definition
+Use when building FastAPI services with async Python, Pydantic v2, lifespan-managed resources, dependency-based auth, background task boundaries, and OpenAPI-safe request handling.
 
-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
 
-## When to Use This Skill
+- Building or refactoring FastAPI REST or internal service APIs.
+- Defining Pydantic v2 models and request/response validation boundaries.
+- Designing dependency-based auth, async database access, lifespan-managed resources, and OpenAPI-safe endpoints.
+- Reviewing FastAPI code for async correctness, background task safety, and operational behavior.
 
-- 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
+## Instructions
 
-## Core Workflow
+1. Model request, response, and error boundaries first with Pydantic v2.
+2. Decide lifespan-managed resources, dependency graph shape, and auth boundaries before adding routes.
+3. Keep async I/O explicit and do not mix sync database access into request paths.
+4. Keep routers thin, keep background work bounded, and move business rules into services or domain code.
+5. Verify OpenAPI output, auth behavior, startup or shutdown behavior, and failure paths before finishing.
 
-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
+### Baseline standards
 
-## Reference Guide
+- Use explicit type hints and Pydantic v2 patterns.
+- Keep request validation and response shaping at the boundary.
+- Use lifespan hooks for startup and teardown resources instead of ad hoc globals.
+- Prefer async database and network paths consistently.
+- Use dependency injection for shared auth/config logic.
+- Keep background tasks lightweight unless a durable queue owns the work.
+- Treat generated OpenAPI as a contract to keep clean.
 
-Load detailed guidance based on context:
+### Constraints
 
-| Topic | Reference | Load When |
-|-------|-----------|-----------|
-| Pydantic V2 | `references/pydantic-v2.md` | Creating schemas, validation, model_config |
-| SQLAlchemy | `references/async-sqlalchemy.md` | Async database, models, CRUD operations |
-| Endpoints | `references/endpoints-routing.md` | APIRouter, dependencies, routing |
-| Authentication | `references/authentication.md` | JWT, OAuth2, get_current_user |
-| Testing | `references/testing-async.md` | pytest-asyncio, httpx, fixtures |
-| Django Migration | `references/migration-from-django.md` | Migrating from Django/DRF to FastAPI |
+- Avoid mixing sync and async code casually in request handlers.
+- Avoid leaking ORM models directly as public response contracts.
+- Avoid hiding resource lifecycle in module import side effects.
+- Avoid using in-process background tasks for work that needs durable retries.
+- Avoid hiding auth or validation behavior in ad hoc helpers.
+- Avoid treating FastAPI convenience as a substitute for service boundaries.
 
-## Constraints
+## Output Format
 
-### 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)
+Provide implementation guidance, code examples, and configuration as appropriate to the task.
 
-### 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
+## References
 
-## Output Templates
+Load on demand. Do not preload all reference files.
 
-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
+| File | Load when |
+| --- | --- |
+| `references/pydantic-async-playbook.md` | You need deeper guidance for Pydantic v2 boundaries, async correctness, lifespan resources, dependency-based auth, and OpenAPI-safe FastAPI structure. |
 
-## Knowledge Reference
+## Scripts
 
-FastAPI, Pydantic V2, async SQLAlchemy, Alembic migrations, JWT/OAuth2, pytest-asyncio, httpx, BackgroundTasks, WebSockets, dependency injection, OpenAPI/Swagger
+No helper scripts are required for this skill right now. Keep execution in `SKILL.md` and `references/` unless repeated automation becomes necessary.
+
+## Examples
+
+- "Help me with fastapi expert best practices in this project"
+- "Review my fastapi expert implementation for issues"

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/fastapi-expert/references/pydantic-async-playbook.md

@@ -0,0 +1,35 @@
+# Pydantic And Async Playbook
+
+Load this when FastAPI work needs deeper structure guidance.
+
+## Boundary models
+
+- Model request and response contracts first with Pydantic v2.
+- Keep public response models separate from ORM or persistence models.
+- Make validation and serialization behavior explicit.
+
+## Async correctness
+
+- Keep async I/O consistent through request paths.
+- Do not mix blocking database or network work casually into handlers.
+- Keep background tasks, retries, and timeouts visible.
+
+## Lifespan and background work
+
+- Use lifespan-managed startup and shutdown for shared clients, pools, and caches.
+- Keep per-request state out of global mutable singletons.
+- Use in-process background tasks only for short, non-durable follow-up work.
+- Move durable or slow work into a queue or worker boundary.
+
+## Dependencies and auth
+
+- Use dependencies for shared auth, config, and request-scoped behavior.
+- Make token parsing, session lookup, or scope enforcement explicit in dependencies.
+- Keep dependency trees understandable and testable.
+- Treat generated OpenAPI as a contract that should stay clean.
+
+## Service boundaries
+
+- Keep routers thin.
+- Move business rules into services or domain modules.
+- Re-check failure paths, auth, and OpenAPI output before finishing.

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/firebase/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: firebase
+description: "Use when the task is specifically Firebase: Firestore or Realtime Database choice, security rules, indexes, auth, storage, cloud functions, hosting, emulator workflows, or platform-coupled rollout decisions."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "1.0"
+compatibility: Claude Code, Codex, GitHub Copilot
+---
+# Firebase
+
+## Purpose
+
+You are the platform specialist for Firebase application backends.
+
+Your job is to keep product-surface coupling explicit across Firestore or Realtime Database, security rules, indexes, auth, storage, functions, hosting, and emulator-driven local workflows.
+
+## When to Use
+
+- The task is specifically about Firebase or a Firebase-backed application.
+- Firestore, Realtime Database, security rules, indexes, auth, storage, functions, hosting, or emulator workflow materially changes the answer.
+- The real decision is platform coupling, local emulation, or rules-plus-index behavior.
+
+## Instructions
+
+### STANDARD OPERATING PROCEDURE (SOP)
+
+1. Confirm which Firebase products are actually in use.
+2. Separate platform decisions from generic backend or frontend code changes.
+3. Check rules, indexes, auth, and local emulator posture before changing app behavior.
+4. Keep rollout, local testing, and data-access constraints visible together.
+5. Escalate to framework or language skills only after the Firebase surface is clear.
+
+### Constraints
+
+- Do not treat Firebase as only a database choice.
+- Do not answer Firestore, rules, or auth questions as generic NoSQL advice.
+- Do not recommend platform features without checking local emulator and deployment implications.
+- Do not hide security-rule risk behind client convenience.
+
+## Output Format
+
+Provide implementation guidance, code examples, and configuration as appropriate to the task.
+
+## References
+
+Load on demand. Do not preload all reference files.
+
+| File                                        | Load when                                                                                                                     |
+| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `references/platform-routing.md`            | You need Firebase product routing across Firestore, Realtime Database, Auth, Storage, Functions, Hosting, and Emulator usage. |
+| `references/rules-and-indexes-checklist.md` | You need a sharper checklist for security rules, index requirements, auth coupling, and rollout safety.                       |
+
+## Scripts
+
+No helper scripts are required for this skill right now. Keep execution in `SKILL.md` and `references/` unless repeated automation becomes necessary.
+
+## Examples
+
+- "Help me with firebase best practices in this project"
+- "Review my firebase implementation for issues"

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/firebase/references/platform-routing.md

@@ -0,0 +1,16 @@
+# Firebase Platform Routing
+
+Load this when the task is Firebase-specific but the exact product surface is still unclear.
+
+## Routing
+
+- Firestore: document modeling, composite indexes, query limits, and rules coupling.
+- Realtime Database: tree shape, fan-out, listener behavior, and simpler realtime synchronization.
+- Auth: sign-in providers, session flow, user identity, and backend policy coupling.
+- Storage: object lifecycle, access rules, uploads, and media-heavy workloads.
+- Cloud Functions: backend triggers, scheduled jobs, and server-side integration points.
+- Hosting and Emulator Suite: local confidence, preview flow, and safe rollout checks.
+
+## Rule
+
+Keep Firebase product boundaries explicit. Do not answer a Firestore problem as if it were only a generic database problem.

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/firebase/references/rules-and-indexes-checklist.md

@@ -0,0 +1,11 @@
+# Firebase Rules And Indexes Checklist
+
+Load this when security rules, index requirements, or rollout safety are the main risk.
+
+## Checklist
+
+- Confirm which Firebase product owns the access rule.
+- Review auth assumptions before changing client reads or writes.
+- Check whether query changes need index updates or new composite indexes.
+- Keep emulator validation in the plan before shipping rule or index changes.
+- Do not widen reads or writes without stating the blast radius.

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/flutter-design-system/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: flutter-design-system
+description: "Use when creating, auditing, or extending shared Flutter theme tokens, ThemeData, and reusable cross-feature UI primitives such as loading, error, empty, dead-letter, and sync-status components. Do not use for one-off screen styling that should remain local."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "1.0"
+compatibility: Claude Code, Codex, GitHub Copilot
+---
+# Flutter Design System
+
+## Purpose
+
+Keep shared Flutter visual decisions centralized in theme tokens and reusable
+UI primitives instead of repeating feature-specific styling.
+
+## When to Use
+
+- Adding or changing colors, spacing, radius, typography, or elevations
+- Wiring or refactoring app-wide `ThemeData`
+- Creating shared widgets used across multiple screens
+- Replacing hard-coded visual values with design-system tokens
+- Auditing feature UI for token compliance
+
+## Instructions
+
+1. Inspect the existing theme contract before adding new tokens.
+2. Reuse an existing token or shared widget when possible.
+3. Add a new token only when the concept is reusable across features.
+4. Keep shared widgets generic and free of feature repositories, notifiers, or routes.
+5. Prefer Material 3 theming through `ThemeData` before per-widget overrides.
+6. Replace hard-coded values in consuming widgets after updating the shared system.
+
+## Output Format
+
+Produce Flutter guidance or code that:
+
+- uses `AppColors`, `AppSpacing`, `AppTypography`, and `AppRadius` consistently,
+- keeps shared widgets generic and token-driven,
+- identifies which changes belong in theme files versus shared widgets,
+- includes audit notes when replacing hard-coded values.
+
+## References
+
+Load only what the current step needs.
+
+| File | Load when |
+| --- | --- |
+| `references/tokens-and-theme.md` | Adding tokens, changing `ThemeData`, or reviewing shared theme file organization. |
+| `references/shared-widgets.md` | Creating or auditing shared widgets such as loading, error, empty, dead-letter, or sync-status components. |
+
+## Scripts
+
+No helper scripts are required for this skill right now.
+
+## Examples
+
+- "Replace hard-coded spacing and colors in this Flutter module with shared tokens."
+- "Set up a reusable `ErrorView` and `LoadingView` for the app shell."