@cubis/foundry 0.3.64 → 0.3.65

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/documentation-templates/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: documentation-templates
+description: Documentation templates and structure guidelines. README, API docs, code comments, and AI-friendly documentation.
+allowed-tools: Read, Glob, Grep
+---
+
+# Documentation Templates
+
+> Templates and structure guidelines for common documentation types.
+
+---
+
+## 1. README Structure
+
+### Essential Sections (Priority Order)
+
+| Section | Purpose |
+|---------|---------|
+| **Title + One-liner** | What is this? |
+| **Quick Start** | Running in <5 min |
+| **Features** | What can I do? |
+| **Configuration** | How to customize |
+| **API Reference** | Link to detailed docs |
+| **Contributing** | How to help |
+| **License** | Legal |
+
+### README Template
+
+```markdown
+# Project Name
+
+Brief one-line description.
+
+## Quick Start
+
+[Minimum steps to run]
+
+## Features
+
+- Feature 1
+- Feature 2
+
+## Configuration
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| PORT | Server port | 3000 |
+
+## Documentation
+
+- [API Reference](./docs/api.md)
+- [Architecture](./docs/architecture.md)
+
+## License
+
+MIT
+```
+
+---
+
+## 2. API Documentation Structure
+
+### Per-Endpoint Template
+
+```markdown
+## GET /users/:id
+
+Get a user by ID.
+
+**Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | User ID |
+
+**Response:**
+- 200: User object
+- 404: User not found
+
+**Example:**
+[Request and response example]
+```
+
+---
+
+## 3. Code Comment Guidelines
+
+### JSDoc/TSDoc Template
+
+```typescript
+/**
+ * Brief description of what the function does.
+ * 
+ * @param paramName - Description of parameter
+ * @returns Description of return value
+ * @throws ErrorType - When this error occurs
+ * 
+ * @example
+ * const result = functionName(input);
+ */
+```
+
+### When to Comment
+
+| ✅ Comment | ❌ Don't Comment |
+|-----------|-----------------|
+| Why (business logic) | What (obvious) |
+| Complex algorithms | Every line |
+| Non-obvious behavior | Self-explanatory code |
+| API contracts | Implementation details |
+
+---
+
+## 4. Changelog Template (Keep a Changelog)
+
+```markdown
+# Changelog
+
+## [Unreleased]
+### Added
+- New feature
+
+## [1.0.0] - 2025-01-01
+### Added
+- Initial release
+### Changed
+- Updated dependency
+### Fixed
+- Bug fix
+```
+
+---
+
+## 5. Architecture Decision Record (ADR)
+
+```markdown
+# ADR-001: [Title]
+
+## Status
+Accepted / Deprecated / Superseded
+
+## Context
+Why are we making this decision?
+
+## Decision
+What did we decide?
+
+## Consequences
+What are the trade-offs?
+```
+
+---
+
+## 6. AI-Friendly Documentation (2025)
+
+### llms.txt Template
+
+For AI crawlers and agents:
+
+```markdown
+# Project Name
+> One-line objective.
+
+## Core Files
+- [src/index.ts]: Main entry
+- [src/api/]: API routes
+- [docs/]: Documentation
+
+## Key Concepts
+- Concept 1: Brief explanation
+- Concept 2: Brief explanation
+```
+
+### MCP-Ready Documentation
+
+For RAG indexing:
+- Clear H1-H3 hierarchy
+- JSON/YAML examples for data structures
+- Mermaid diagrams for flows
+- Self-contained sections
+
+---
+
+## 7. Structure Principles
+
+| Principle | Why |
+|-----------|-----|
+| **Scannable** | Headers, lists, tables |
+| **Examples first** | Show, don't just tell |
+| **Progressive detail** | Simple → Complex |
+| **Up to date** | Outdated = misleading |
+
+---
+
+> **Remember:** Templates are starting points. Adapt to your project's needs.

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/documentation-templates/docs/api.md

@@ -0,0 +1,16 @@
+# API Reference Template
+
+Use this file as the canonical entry point for API endpoint documentation.
+
+## Endpoint Index
+
+- `GET /resource`
+- `POST /resource`
+- `PATCH /resource/{id}`
+- `DELETE /resource/{id}`
+
+## Conventions
+
+- Include auth requirements per endpoint.
+- Include request/response examples.
+- Include error codes and retry guidance.

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/documentation-templates/docs/architecture.md

@@ -0,0 +1,23 @@
+# Architecture Overview Template
+
+Use this file to describe system boundaries and data flow.
+
+## Components
+
+- API layer
+- Domain/service layer
+- Persistence layer
+- External integrations
+
+## Runtime Flow
+
+1. Request enters API layer
+2. Domain logic validates and processes
+3. Persistence reads/writes state
+4. Response returns with observability metadata
+
+## Non-Functional Notes
+
+- Reliability/SLOs
+- Security model
+- Scaling strategy

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/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
+
+- `references/migrations.md` for migration strategy and checklist
+- `references/queries-and-daos.md` for DAO/query patterns

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/drift-flutter/references/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/workflows/workflows/agent-environment-setup/platforms/claude/skills/drift-flutter/references/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/workflows/workflows/agent-environment-setup/platforms/claude/skills/error-ux-observability/SKILL.md

@@ -0,0 +1,161 @@
+---
+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**
+
+## References
+
+Load detailed guidance only when needed.
+
+| 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 |
+
+## Templates
+
+- `failure_message_mapper` - Failure to UI message mapper template

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/error-ux-observability/references/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/workflows/workflows/agent-environment-setup/platforms/claude/skills/error-ux-observability/references/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/workflows/workflows/agent-environment-setup/platforms/claude/skills/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/workflows/workflows/agent-environment-setup/platforms/claude/skills/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/workflows/workflows/agent-environment-setup/platforms/claude/skills/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/workflows/workflows/agent-environment-setup/platforms/claude/skills/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 | `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 |
+
+## 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