@cubis/foundry 0.3.10

package/Ai Agent Workflow/skills/doc.md

@@ -0,0 +1,177 @@
+# Antigravity Skills
+
+> **Guide to creating and using Skills in the Antigravity Kit**
+
+---
+
+## 📋 Overview
+
+While Antigravity's base models (like Gemini) are powerful generalists, they don't know your specific project context or your team's standards. Loading every rule or tool into the agent's context window leads to "tool bloat," higher costs, latency, and confusion.
+
+**Antigravity Skills** solve this through **Progressive Disclosure**. A Skill is a package of specialized knowledge that remains dormant until needed. This information is only loaded into the agent's context when your specific request matches the skill's description.
+
+---
+
+## 📁 Structure and Scope
+
+Skills are folder-based packages. You can define these scopes based on your needs:
+
+| Scope         | Path                              | Description                          |
+| ------------- | --------------------------------- | ------------------------------------ |
+| **Workspace** | `<workspace-root>/.agent/skills/` | Available only in a specific project |
+
+### Skill Directory Structure
+
+```
+my-skill/
+├── SKILL.md      # (Required) Metadata & instructions
+├── scripts/      # (Optional) Python or Bash scripts
+├── references/   # (Optional) Text, documentation, templates
+└── assets/       # (Optional) Images or logos
+```
+
+---
+
+## 🔍 Example 1: Code Review Skill
+
+This is an instruction-only skill; you only need to create the `SKILL.md` file.
+
+### Step 1: Create the directory
+
+```bash
+mkdir -p .agent/skills/code-review
+```
+
+### Step 2: Create SKILL.md
+
+```markdown
+---
+name: code-review
+description: Reviews code changes for bugs, style issues, and best practices. Use when reviewing PRs or checking code quality.
+---
+
+# Code Review Skill
+
+When reviewing code, follow these steps:
+
+## Review checklist
+
+1. **Correctness**: Does the code do what it's supposed to?
+2. **Edge cases**: Are error conditions handled?
+3. **Style**: Does it follow project conventions?
+4. **Performance**: Are there obvious inefficiencies?
+
+## How to provide feedback
+
+- Be specific about what needs to change
+- Explain why, not just what
+- Suggest alternatives when possible
+```
+
+> **Note**: The `SKILL.md` file contains metadata (name, description) at the top, followed by the instructions. The agent will only read the metadata and load the full instructions only when needed.
+
+### Try it out
+
+Create a file `demo_bad_code.py`:
+
+```python
+import time
+
+def get_user_data(users, id):
+    # Find user by ID
+    for u in users:
+        if u['id'] == id:
+            return u
+    return None
+
+def process_payments(items):
+    total = 0
+    for i in items:
+        # Calculate tax
+        tax = i['price'] * 0.1
+        total = total + i['price'] + tax
+        time.sleep(0.1)  # Simulate slow network call
+    return total
+
+def run_batch():
+    users = [{'id': 1, 'name': 'Alice'}, {'id': 2, 'name': 'Bob'}]
+    items = [{'price': 10}, {'price': 20}, {'price': 100}]
+
+    u = get_user_data(users, 3)
+    print("User found: " + u['name'])  # Will crash if None
+
+    print("Total: " + str(process_payments(items)))
+
+if __name__ == "__main__":
+    run_batch()
+```
+
+**Prompt**: `review the @demo_bad_code.py file`
+
+The Agent will automatically identify the `code-review` skill, load the information, and follow the instructions.
+
+---
+
+## 📄 Example 2: License Header Skill
+
+This skill uses a reference file in the `resources/` (or `references/`) directory.
+
+### Step 1: Create the directory
+
+```bash
+mkdir -p .agent/skills/license-header-adder/resources
+```
+
+### Step 2: Create the template file
+
+**`.agent/skills/license-header-adder/resources/HEADER.txt`**:
+
+```
+/*
+ * Copyright (c) 2026 YOUR_COMPANY_NAME LLC.
+ * All rights reserved.
+ * This code is proprietary and confidential.
+ */
+```
+
+### Step 3: Create SKILL.md
+
+**`.agent/skills/license-header-adder/SKILL.md`**:
+
+```markdown
+---
+name: license-header-adder
+description: Adds the standard corporate license header to new source files.
+---
+
+# License Header Adder
+
+This skill ensures that all new source files have the correct copyright header.
+
+## Instructions
+
+1. **Read the Template**: Read the content of `resources/HEADER.txt`.
+2. **Apply to File**: When creating a new file, prepend this exact content.
+3. **Adapt Syntax**:
+   - For C-style languages (Java, TS), keep the `/* */` block.
+   - For Python/Shell, convert to `#` comments.
+```
+
+### Try it out
+
+**Prompt**: `Create a new Python script named data_processor.py that prints 'Hello World'.`
+
+The Agent will read the template, convert the comments to Python style, and automatically add it to the top of the file.
+
+---
+
+## 🎯 Conclusion
+
+By creating Skills, you transform a general AI model into an expert for your project:
+
+- ✅ Systematize best practices
+- ✅ Adhere to code review rules
+- ✅ Automatically add license headers
+- ✅ The Agent automatically knows how to work with your team
+
+Instead of constantly reminding the AI to "remember to add the license" or "fix the commit format," now the Agent will do it automatically!

package/Ai Agent Workflow/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/Ai Agent Workflow/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/Ai Agent Workflow/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/Ai Agent Workflow/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/Ai Agent Workflow/skills/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
+