@cubis/foundry 0.3.10

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/windsurf/skills/openapi-docs/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: "openapi-docs"
+description: "Use when writing or updating OpenAPI specifications, defining request/response schemas, or configuring Stoplight Elements (Swagger-style) documentation UI."
+---
+
+
+# OpenAPI Docs & Stoplight UI
+
+## Overview
+
+API documentation specialist who produces clean, consistent OpenAPI 3.1 specs and a polished Stoplight Elements UI across frameworks (FastAPI, NestJS, Express, Hono, etc.).
+
+## Role Definition
+
+You are a technical writer and API designer. You standardize request/response schemas, ensure authentication is documented accurately, and keep UI docs consistent with runtime behavior across different stacks.
+
+## When to Use This Skill
+
+- Creating new API endpoints with OpenAPI documentation (FastAPI, NestJS, Express, Hono, raw OpenAPI files)
+- Updating request/response schemas or error contracts
+- Adding or fixing authentication/headers in docs
+- Setting up or refining Stoplight Elements UI
+- Defining CRUD endpoints (create, update, delete)
+
+## Core Workflow
+
+1. **Inventory** - Identify endpoints, auth headers, and response types
+2. **Schemas** - Define reusable schemas and examples
+3. **Operations** - Document create/update/delete with standard responses
+4. **Errors** - Add consistent error responses for all routes
+5. **UI** - Wire Stoplight Elements to the OpenAPI spec
+
+## Available Steering Files
+
+| Topic             | Reference                         | Load When                          |
+| ----------------- | --------------------------------- | ---------------------------------- |
+| OpenAPI Checklist | references/openapi-checklist.md     | Before writing or updating specs   |
+| CRUD Templates    | references/crud-templates.md        | Adding create/update/delete routes |
+| Stoplight UI      | references/stoplight-ui.md          | Configuring or styling docs UI     |
+| FastAPI           | references/framework-fastapi.md     | FastAPI-specific documentation     |
+| NestJS            | references/framework-nestjs.md      | NestJS Swagger integration         |
+| Express           | references/framework-express.md     | Express spec-first or code-first   |
+| Raw OpenAPI       | references/framework-raw-openapi.md | Spec-first workflows               |
+
+## Constraints
+
+### MUST DO
+
+- Ensure headers in docs match actual middleware requirements
+- Reuse schemas via the framework’s component registration mechanism (e.g., FastAPI models, NestJS decorators, Zod/OpenAPI registries)
+- Include examples for request bodies and error payloads
+- Document 4xx and 5xx error responses
+- Keep descriptions concise and user-focused
+
+### MUST NOT DO
+
+- Invent undocumented headers or parameters
+- Drift away from runtime validation rules
+- Document endpoints that don’t exist
+- Use inconsistent casing for headers
+
+## Output Template
+
+1. Summary of changes
+2. Updated schemas and examples
+3. Updated endpoints (create/update/delete)
+4. Stoplight UI status and URL
+5. Verification notes

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/windsurf/skills/openapi-docs/references/crud-templates.md

@@ -0,0 +1,43 @@
+# CRUD Templates (Create / Update / Delete)
+
+## Create (POST)
+
+- `summary`: Create <resource>
+- `request.body`:
+  - `application/json` schema with required fields
+  - example payload
+- Responses:
+  - `201` with created resource schema
+  - `400` validation error
+  - `401` missing auth
+  - `403` forbidden
+  - `500` server error
+
+## Update (PUT/PATCH)
+
+- `summary`: Update <resource>
+- `request.params`: `{ id }`
+- `request.body`: optional fields for update
+- Responses:
+  - `200` with updated resource schema
+  - `400` validation error
+  - `401` missing auth
+  - `403` forbidden
+  - `404` not found
+  - `500` server error
+
+## Delete (DELETE)
+
+- `summary`: Delete <resource>
+- `request.params`: `{ id }`
+- Responses:
+  - `204` no content (or `200` with confirmation schema)
+  - `401` missing auth
+  - `403` forbidden
+  - `404` not found
+  - `500` server error
+
+## Notes
+
+- Ensure `request.headers` includes all required auth headers
+- Use shared `ErrorResponse` schema for errors

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/windsurf/skills/openapi-docs/references/framework-express.md

@@ -0,0 +1,19 @@
+# Express OpenAPI Guidance
+
+## Core Patterns
+
+- Maintain a source OpenAPI file (YAML/JSON) or generate via schema tools
+- Validate requests with a middleware (zod, joi, ajv)
+- Ensure validation and docs stay in sync
+
+## Options
+
+- Code-first: Zod/OpenAPI registry or tsoa
+- Spec-first: Handwritten OpenAPI with request validation middleware
+
+## Example Checklist
+
+- Centralize schemas for reuse
+- Add standard error responses across routes
+- Document auth headers explicitly
+- Serve `/openapi.json` and Stoplight UI at `/docs`

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/windsurf/skills/openapi-docs/references/framework-fastapi.md

@@ -0,0 +1,20 @@
+# FastAPI OpenAPI Guidance
+
+## Core Patterns
+
+- Use Pydantic models for request/response schemas
+- Use `response_model` for output typing and docs
+- Use `status_code` on route decorators
+- Use dependency injection for auth headers
+
+## Example Checklist
+
+- Define `BaseModel` for request/response
+- Add examples via `Field(..., example=...)`
+- Document security scheme with `HTTPBearer` or `APIKeyHeader`
+- Add tags on routes for grouping
+
+## Notes
+
+- FastAPI auto-generates OpenAPI 3.1 in recent versions; verify version
+- Use `openapi_url` and `docs_url` to expose spec and UI routes

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/windsurf/skills/openapi-docs/references/framework-nestjs.md

@@ -0,0 +1,20 @@
+# NestJS OpenAPI Guidance
+
+## Core Patterns
+
+- Use `@nestjs/swagger` decorators for schemas and routes
+- Use DTO classes with `@ApiProperty()`
+- Set `@ApiTags()` per controller
+- Use `@ApiBearerAuth()` or `@ApiSecurity()` for API keys
+
+## Example Checklist
+
+- Create DTOs for create/update responses
+- Add `@ApiResponse()` for 200/201/400/401/403/404/500
+- Use `@ApiHeader()` for required headers
+- Generate spec via `SwaggerModule.createDocument()`
+
+## Notes
+
+- Keep DTO validation (class-validator) aligned with docs
+- Export `/openapi.json` and mount UI (Stoplight or Swagger)

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/windsurf/skills/openapi-docs/references/framework-raw-openapi.md

@@ -0,0 +1,14 @@
+# Raw OpenAPI (Spec-First) Guidance
+
+## Core Patterns
+
+- Keep a single `openapi.yaml` or `openapi.json`
+- Reuse components for schemas and security
+- Validate requests using an OpenAPI-aware validator
+
+## Example Checklist
+
+- Define tags and operationIds for all endpoints
+- Use consistent error schema across operations
+- Add examples for request/response bodies
+- Expose spec and Stoplight UI endpoints

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/windsurf/skills/openapi-docs/references/openapi-checklist.md

@@ -0,0 +1,33 @@
+# OpenAPI Checklist (3.1)
+
+## Spec Metadata
+
+- `openapi: 3.1.0`
+- `info`: title, version, description, contact
+- `servers`: local + staging/prod when available
+- `tags`: used by all documented routes
+
+## Security & Headers
+
+- Add `components.securitySchemes` for auth headers
+- Use `security` at global or route level
+- All required headers appear in `request.headers`
+- Header keys are lowercase
+
+## Schemas
+
+- Use the framework’s component registration mechanism (FastAPI Pydantic models, NestJS `@ApiProperty`, Express+zod/openapi registry, etc.)
+- Provide examples for request/response schemas
+- Prefer shared schemas for errors
+
+## Operations
+
+- `summary` and `description` on every operation
+- Responses: `200/201`, plus `400/401/403/404/500` as appropriate
+- `request.body.required: true` if Content-Type is mandatory
+
+## Consistency
+
+- Types and descriptions match actual validation
+- IDs and formats align with persistence (UUID vs ObjectId)
+- No unused tags or components

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/windsurf/skills/openapi-docs/references/stoplight-ui.md

@@ -0,0 +1,21 @@
+# Stoplight Elements UI
+
+## Standard Setup (Web Component)
+
+- Include:
+  - `https://unpkg.com/@stoplight/elements/styles.min.css`
+  - `https://unpkg.com/@stoplight/elements/web-components.min.js`
+- Embed:
+  - `<elements-api apiDescriptionUrl="/openapi.json" router="hash" layout="sidebar" />`
+
+## Recommended Options
+
+- `router="hash"` for static hosting
+- `layout="sidebar"` for readable nav
+- `tryItCredentialsPolicy="include"` when auth cookies or credentials are needed
+
+## Verification
+
+- UI loads and shows all tags
+- Try-it panel works for secured endpoints
+- Schemas and examples render correctly

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/windsurf/skills/parallel-agents/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: parallel-agents
+description: Multi-agent orchestration patterns. Use when multiple independent tasks can run with different domain expertise or when comprehensive analysis requires multiple perspectives.
+allowed-tools: Read, Glob, Grep
+---
+
+# Native Parallel Agents
+
+> Orchestration through Antigravity's built-in Agent Tool
+
+## Overview
+
+This skill enables coordinating multiple specialized agents through Antigravity's native agent system. Unlike external scripts, this approach keeps all orchestration within Antigravity's control.
+
+## When to Use Orchestration
+
+✅ **Good for:**
+- Complex tasks requiring multiple expertise domains
+- Code analysis from security, performance, and quality perspectives
+- Comprehensive reviews (architecture + security + testing)
+- Feature implementation needing backend + frontend + database work
+
+❌ **Not for:**
+- Simple, single-domain tasks
+- Quick fixes or small changes
+- Tasks where one agent suffices
+
+---
+
+## Native Agent Invocation
+
+### Single Agent
+```
+Use the security-auditor agent to review authentication
+```
+
+### Sequential Chain
+```
+First, use the explorer-agent to discover project structure.
+Then, use the backend-specialist to review API endpoints.
+Finally, use the test-engineer to identify test gaps.
+```
+
+### With Context Passing
+```
+Use the frontend-specialist to analyze React components.
+Based on those findings, have the test-engineer generate component tests.
+```
+
+### Resume Previous Work
+```
+Resume agent [agentId] and continue with additional requirements.
+```
+
+---
+
+## Orchestration Patterns
+
+### Pattern 1: Comprehensive Analysis
+```
+Agents: explorer-agent → [domain-agents] → synthesis
+
+1. explorer-agent: Map codebase structure
+2. security-auditor: Security posture
+3. backend-specialist: API quality
+4. frontend-specialist: UI/UX patterns
+5. test-engineer: Test coverage
+6. Synthesize all findings
+```
+
+### Pattern 2: Feature Review
+```
+Agents: affected-domain-agents → test-engineer
+
+1. Identify affected domains (backend? frontend? both?)
+2. Invoke relevant domain agents
+3. test-engineer verifies changes
+4. Synthesize recommendations
+```
+
+### Pattern 3: Security Audit
+```
+Agents: security-auditor → penetration-tester → synthesis
+
+1. security-auditor: Configuration and code review
+2. penetration-tester: Active vulnerability testing
+3. Synthesize with prioritized remediation
+```
+
+---
+
+## Available Agents
+
+| Agent | Expertise | Trigger Phrases |
+|-------|-----------|-----------------|
+| `orchestrator` | Coordination | "comprehensive", "multi-perspective" |
+| `security-auditor` | Security | "security", "auth", "vulnerabilities" |
+| `penetration-tester` | Security Testing | "pentest", "red team", "exploit" |
+| `backend-specialist` | Backend | "API", "server", "Node.js", "Express" |
+| `frontend-specialist` | Frontend | "React", "UI", "components", "Next.js" |
+| `test-engineer` | Testing | "tests", "coverage", "TDD" |
+| `devops-engineer` | DevOps | "deploy", "CI/CD", "infrastructure" |
+| `database-architect` | Database | "schema", "Prisma", "migrations" |
+| `mobile-developer` | Mobile | "React Native", "Flutter", "mobile" |
+| `api-designer` | API Design | "REST", "GraphQL", "OpenAPI" |
+| `debugger` | Debugging | "bug", "error", "not working" |
+| `explorer-agent` | Discovery | "explore", "map", "structure" |
+| `documentation-writer` | Documentation | "write docs", "create README", "generate API docs" |
+| `performance-optimizer` | Performance | "slow", "optimize", "profiling" |
+| `project-planner` | Planning | "plan", "roadmap", "milestones" |
+| `seo-specialist` | SEO | "SEO", "meta tags", "search ranking" |
+| `game-developer` | Game Development | "game", "Unity", "Godot", "Phaser" |
+
+---
+
+## Antigravity Built-in Agents
+
+These work alongside custom agents:
+
+| Agent | Model | Purpose |
+|-------|-------|---------|
+| **Explore** | Haiku | Fast read-only codebase search |
+| **Plan** | Sonnet | Research during plan mode |
+| **General-purpose** | Sonnet | Complex multi-step modifications |
+
+Use **Explore** for quick searches, **custom agents** for domain expertise.
+
+---
+
+## Synthesis Protocol
+
+After all agents complete, synthesize:
+
+```markdown
+## Orchestration Synthesis
+
+### Task Summary
+[What was accomplished]
+
+### Agent Contributions
+| Agent | Finding |
+|-------|---------|
+| security-auditor | Found X |
+| backend-specialist | Identified Y |
+
+### Consolidated Recommendations
+1. **Critical**: [Issue from Agent A]
+2. **Important**: [Issue from Agent B]
+3. **Nice-to-have**: [Enhancement from Agent C]
+
+### Action Items
+- [ ] Fix critical security issue
+- [ ] Refactor API endpoint
+- [ ] Add missing tests
+```
+
+---
+
+## Best Practices
+
+1. **Available agents** - 17 specialized agents can be orchestrated
+2. **Logical order** - Discovery → Analysis → Implementation → Testing
+3. **Share context** - Pass relevant findings to subsequent agents
+4. **Single synthesis** - One unified report, not separate outputs
+5. **Verify changes** - Always include test-engineer for code modifications
+
+---
+
+## Key Benefits
+
+- ✅ **Single session** - All agents share context
+- ✅ **AI-controlled** - Claude orchestrates autonomously
+- ✅ **Native integration** - Works with built-in Explore, Plan agents
+- ✅ **Resume support** - Can continue previous agent work
+- ✅ **Context passing** - Findings flow between agents

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/windsurf/skills/performance-profiling/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: performance-profiling
+description: Performance profiling principles. Measurement, analysis, and optimization techniques.
+allowed-tools: Read, Glob, Grep, Bash
+---
+
+# Performance Profiling
+
+> Measure, analyze, optimize - in that order.
+
+## 🔧 Runtime Scripts
+
+**Execute these for automated profiling:**
+
+| Script | Purpose | Usage |
+|--------|---------|-------|
+| `scripts/lighthouse_audit.py` | Lighthouse performance audit | `python scripts/lighthouse_audit.py https://example.com` |
+
+---
+
+## 1. Core Web Vitals
+
+### Targets
+
+| Metric | Good | Poor | Measures |
+|--------|------|------|----------|
+| **LCP** | < 2.5s | > 4.0s | Loading |
+| **INP** | < 200ms | > 500ms | Interactivity |
+| **CLS** | < 0.1 | > 0.25 | Stability |
+
+### When to Measure
+
+| Stage | Tool |
+|-------|------|
+| Development | Local Lighthouse |
+| CI/CD | Lighthouse CI |
+| Production | RUM (Real User Monitoring) |
+
+---
+
+## 2. Profiling Workflow
+
+### The 4-Step Process
+
+```
+1. BASELINE → Measure current state
+2. IDENTIFY → Find the bottleneck
+3. FIX → Make targeted change
+4. VALIDATE → Confirm improvement
+```
+
+### Profiling Tool Selection
+
+| Problem | Tool |
+|---------|------|
+| Page load | Lighthouse |
+| Bundle size | Bundle analyzer |
+| Runtime | DevTools Performance |
+| Memory | DevTools Memory |
+| Network | DevTools Network |
+
+---
+
+## 3. Bundle Analysis
+
+### What to Look For
+
+| Issue | Indicator |
+|-------|-----------|
+| Large dependencies | Top of bundle |
+| Duplicate code | Multiple chunks |
+| Unused code | Low coverage |
+| Missing splits | Single large chunk |
+
+### Optimization Actions
+
+| Finding | Action |
+|---------|--------|
+| Big library | Import specific modules |
+| Duplicate deps | Dedupe, update versions |
+| Route in main | Code split |
+| Unused exports | Tree shake |
+
+---
+
+## 4. Runtime Profiling
+
+### Performance Tab Analysis
+
+| Pattern | Meaning |
+|---------|---------|
+| Long tasks (>50ms) | UI blocking |
+| Many small tasks | Possible batching opportunity |
+| Layout/paint | Rendering bottleneck |
+| Script | JavaScript execution |
+
+### Memory Tab Analysis
+
+| Pattern | Meaning |
+|---------|---------|
+| Growing heap | Possible leak |
+| Large retained | Check references |
+| Detached DOM | Not cleaned up |
+
+---
+
+## 5. Common Bottlenecks
+
+### By Symptom
+
+| Symptom | Likely Cause |
+|---------|--------------|
+| Slow initial load | Large JS, render blocking |
+| Slow interactions | Heavy event handlers |
+| Jank during scroll | Layout thrashing |
+| Growing memory | Leaks, retained refs |
+
+---
+
+## 6. Quick Win Priorities
+
+| Priority | Action | Impact |
+|----------|--------|--------|
+| 1 | Enable compression | High |
+| 2 | Lazy load images | High |
+| 3 | Code split routes | High |
+| 4 | Cache static assets | Medium |
+| 5 | Optimize images | Medium |
+
+---
+
+## 7. Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Guess at problems | Profile first |
+| Micro-optimize | Fix biggest issue |
+| Optimize early | Optimize when needed |
+| Ignore real users | Use RUM data |
+
+---
+
+> **Remember:** The fastest code is code that doesn't run. Remove before optimizing.

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/windsurf/skills/performance-profiling/scripts/lighthouse_audit.py

@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+"""
+Skill: performance-profiling
+Script: lighthouse_audit.py
+Purpose: Run Lighthouse performance audit on a URL
+Usage: python lighthouse_audit.py https://example.com
+Output: JSON with performance scores
+Note: Requires lighthouse CLI (npm install -g lighthouse)
+"""
+import subprocess
+import json
+import sys
+import os
+import tempfile
+
+def run_lighthouse(url: str) -> dict:
+    """Run Lighthouse audit on URL."""
+    try:
+        with tempfile.NamedTemporaryFile(suffix='.json', delete=False) as f:
+            output_path = f.name
+        
+        result = subprocess.run(
+            [
+                "lighthouse",
+                url,
+                "--output=json",
+                f"--output-path={output_path}",
+                "--chrome-flags=--headless",
+                "--only-categories=performance,accessibility,best-practices,seo"
+            ],
+            capture_output=True,
+            text=True,
+            timeout=120
+        )
+        
+        if os.path.exists(output_path):
+            with open(output_path, 'r') as f:
+                report = json.load(f)
+            os.unlink(output_path)
+            
+            categories = report.get("categories", {})
+            return {
+                "url": url,
+                "scores": {
+                    "performance": int(categories.get("performance", {}).get("score", 0) * 100),
+                    "accessibility": int(categories.get("accessibility", {}).get("score", 0) * 100),
+                    "best_practices": int(categories.get("best-practices", {}).get("score", 0) * 100),
+                    "seo": int(categories.get("seo", {}).get("score", 0) * 100)
+                },
+                "summary": get_summary(categories)
+            }
+        else:
+            return {"error": "Lighthouse failed to generate report", "stderr": result.stderr[:500]}
+            
+    except subprocess.TimeoutExpired:
+        return {"error": "Lighthouse audit timed out"}
+    except FileNotFoundError:
+        return {"error": "Lighthouse CLI not found. Install with: npm install -g lighthouse"}
+
+def get_summary(categories: dict) -> str:
+    """Generate summary based on scores."""
+    perf = categories.get("performance", {}).get("score", 0) * 100
+    if perf >= 90:
+        return "[OK] Excellent performance"
+    elif perf >= 50:
+        return "[!] Needs improvement"
+    else:
+        return "[X] Poor performance"
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        print(json.dumps({"error": "Usage: python lighthouse_audit.py <url>"}))
+        sys.exit(1)
+    
+    result = run_lighthouse(sys.argv[1])
+    print(json.dumps(result, indent=2))