@cubis/foundry 0.3.11 → 0.3.12

package/Ai Agent Workflow/powers/python-patterns/SKILL.md

@@ -1,11 +1,441 @@
 ---
 name: python-patterns
 description: Python development principles and decision-making. Framework selection, async patterns, type hints, project structure. Teaches thinking, not copying.
+allowed-tools: Read, Write, Edit, Glob, Grep
 ---
 
-# python-patterns
+# Python Patterns
 
-This power mirrors the base skill:
-- `Ai Agent Workflow/skills/python-patterns/SKILL.md`
+> Python development principles and decision-making for 2025.
+> **Learn to THINK, not memorize patterns.**
 
-When both exist, prefer the base skill as source of truth unless power-specific overrides are added here.
+---
+
+## ⚠️ How to Use This Skill
+
+This skill teaches **decision-making principles**, not fixed code to copy.
+
+- ASK user for framework preference when unclear
+- Choose async vs sync based on CONTEXT
+- Don't default to same framework every time
+
+---
+
+## 1. Framework Selection (2025)
+
+### Decision Tree
+
+```
+What are you building?
+│
+├── API-first / Microservices
+│   └── FastAPI (async, modern, fast)
+│
+├── Full-stack web / CMS / Admin
+│   └── Django (batteries-included)
+│
+├── Simple / Script / Learning
+│   └── Flask (minimal, flexible)
+│
+├── AI/ML API serving
+│   └── FastAPI (Pydantic, async, uvicorn)
+│
+└── Background workers
+    └── Celery + any framework
+```
+
+### Comparison Principles
+
+| Factor | FastAPI | Django | Flask |
+|--------|---------|--------|-------|
+| **Best for** | APIs, microservices | Full-stack, CMS | Simple, learning |
+| **Async** | Native | Django 5.0+ | Via extensions |
+| **Admin** | Manual | Built-in | Via extensions |
+| **ORM** | Choose your own | Django ORM | Choose your own |
+| **Learning curve** | Low | Medium | Low |
+
+### Selection Questions to Ask:
+1. Is this API-only or full-stack?
+2. Need admin interface?
+3. Team familiar with async?
+4. Existing infrastructure?
+
+---
+
+## 2. Async vs Sync Decision
+
+### When to Use Async
+
+```
+async def is better when:
+├── I/O-bound operations (database, HTTP, file)
+├── Many concurrent connections
+├── Real-time features
+├── Microservices communication
+└── FastAPI/Starlette/Django ASGI
+
+def (sync) is better when:
+├── CPU-bound operations
+├── Simple scripts
+├── Legacy codebase
+├── Team unfamiliar with async
+└── Blocking libraries (no async version)
+```
+
+### The Golden Rule
+
+```
+I/O-bound → async (waiting for external)
+CPU-bound → sync + multiprocessing (computing)
+
+Don't:
+├── Mix sync and async carelessly
+├── Use sync libraries in async code
+└── Force async for CPU work
+```
+
+### Async Library Selection
+
+| Need | Async Library |
+|------|---------------|
+| HTTP client | httpx |
+| PostgreSQL | asyncpg |
+| Redis | aioredis / redis-py async |
+| File I/O | aiofiles |
+| Database ORM | SQLAlchemy 2.0 async, Tortoise |
+
+---
+
+## 3. Type Hints Strategy
+
+### When to Type
+
+```
+Always type:
+├── Function parameters
+├── Return types
+├── Class attributes
+├── Public APIs
+
+Can skip:
+├── Local variables (let inference work)
+├── One-off scripts
+├── Tests (usually)
+```
+
+### Common Type Patterns
+
+```python
+# These are patterns, understand them:
+
+# Optional → might be None
+from typing import Optional
+def find_user(id: int) -> Optional[User]: ...
+
+# Union → one of multiple types
+def process(data: str | dict) -> None: ...
+
+# Generic collections
+def get_items() -> list[Item]: ...
+def get_mapping() -> dict[str, int]: ...
+
+# Callable
+from typing import Callable
+def apply(fn: Callable[[int], str]) -> str: ...
+```
+
+### Pydantic for Validation
+
+```
+When to use Pydantic:
+├── API request/response models
+├── Configuration/settings
+├── Data validation
+├── Serialization
+
+Benefits:
+├── Runtime validation
+├── Auto-generated JSON schema
+├── Works with FastAPI natively
+└── Clear error messages
+```
+
+---
+
+## 4. Project Structure Principles
+
+### Structure Selection
+
+```
+Small project / Script:
+├── main.py
+├── utils.py
+└── requirements.txt
+
+Medium API:
+├── app/
+│   ├── __init__.py
+│   ├── main.py
+│   ├── models/
+│   ├── routes/
+│   ├── services/
+│   └── schemas/
+├── tests/
+└── pyproject.toml
+
+Large application:
+├── src/
+│   └── myapp/
+│       ├── core/
+│       ├── api/
+│       ├── services/
+│       ├── models/
+│       └── ...
+├── tests/
+└── pyproject.toml
+```
+
+### FastAPI Structure Principles
+
+```
+Organize by feature or layer:
+
+By layer:
+├── routes/ (API endpoints)
+├── services/ (business logic)
+├── models/ (database models)
+├── schemas/ (Pydantic models)
+└── dependencies/ (shared deps)
+
+By feature:
+├── users/
+│   ├── routes.py
+│   ├── service.py
+│   └── schemas.py
+└── products/
+    └── ...
+```
+
+---
+
+## 5. Django Principles (2025)
+
+### Django Async (Django 5.0+)
+
+```
+Django supports async:
+├── Async views
+├── Async middleware
+├── Async ORM (limited)
+└── ASGI deployment
+
+When to use async in Django:
+├── External API calls
+├── WebSocket (Channels)
+├── High-concurrency views
+└── Background task triggering
+```
+
+### Django Best Practices
+
+```
+Model design:
+├── Fat models, thin views
+├── Use managers for common queries
+├── Abstract base classes for shared fields
+
+Views:
+├── Class-based for complex CRUD
+├── Function-based for simple endpoints
+├── Use viewsets with DRF
+
+Queries:
+├── select_related() for FKs
+├── prefetch_related() for M2M
+├── Avoid N+1 queries
+└── Use .only() for specific fields
+```
+
+---
+
+## 6. FastAPI Principles
+
+### async def vs def in FastAPI
+
+```
+Use async def when:
+├── Using async database drivers
+├── Making async HTTP calls
+├── I/O-bound operations
+└── Want to handle concurrency
+
+Use def when:
+├── Blocking operations
+├── Sync database drivers
+├── CPU-bound work
+└── FastAPI runs in threadpool automatically
+```
+
+### Dependency Injection
+
+```
+Use dependencies for:
+├── Database sessions
+├── Current user / Auth
+├── Configuration
+├── Shared resources
+
+Benefits:
+├── Testability (mock dependencies)
+├── Clean separation
+├── Automatic cleanup (yield)
+```
+
+### Pydantic v2 Integration
+
+```python
+# FastAPI + Pydantic are tightly integrated:
+
+# Request validation
+@app.post("/users")
+async def create(user: UserCreate) -> UserResponse:
+    # user is already validated
+    ...
+
+# Response serialization
+# Return type becomes response schema
+```
+
+---
+
+## 7. Background Tasks
+
+### Selection Guide
+
+| Solution | Best For |
+|----------|----------|
+| **BackgroundTasks** | Simple, in-process tasks |
+| **Celery** | Distributed, complex workflows |
+| **ARQ** | Async, Redis-based |
+| **RQ** | Simple Redis queue |
+| **Dramatiq** | Actor-based, simpler than Celery |
+
+### When to Use Each
+
+```
+FastAPI BackgroundTasks:
+├── Quick operations
+├── No persistence needed
+├── Fire-and-forget
+└── Same process
+
+Celery/ARQ:
+├── Long-running tasks
+├── Need retry logic
+├── Distributed workers
+├── Persistent queue
+└── Complex workflows
+```
+
+---
+
+## 8. Error Handling Principles
+
+### Exception Strategy
+
+```
+In FastAPI:
+├── Create custom exception classes
+├── Register exception handlers
+├── Return consistent error format
+└── Log without exposing internals
+
+Pattern:
+├── Raise domain exceptions in services
+├── Catch and transform in handlers
+└── Client gets clean error response
+```
+
+### Error Response Philosophy
+
+```
+Include:
+├── Error code (programmatic)
+├── Message (human readable)
+├── Details (field-level when applicable)
+└── NOT stack traces (security)
+```
+
+---
+
+## 9. Testing Principles
+
+### Testing Strategy
+
+| Type | Purpose | Tools |
+|------|---------|-------|
+| **Unit** | Business logic | pytest |
+| **Integration** | API endpoints | pytest + httpx/TestClient |
+| **E2E** | Full workflows | pytest + DB |
+
+### Async Testing
+
+```python
+# Use pytest-asyncio for async tests
+
+import pytest
+from httpx import AsyncClient
+
+@pytest.mark.asyncio
+async def test_endpoint():
+    async with AsyncClient(app=app, base_url="http://test") as client:
+        response = await client.get("/users")
+        assert response.status_code == 200
+```
+
+### Fixtures Strategy
+
+```
+Common fixtures:
+├── db_session → Database connection
+├── client → Test client
+├── authenticated_user → User with token
+└── sample_data → Test data setup
+```
+
+---
+
+## 10. Decision Checklist
+
+Before implementing:
+
+- [ ] **Asked user about framework preference?**
+- [ ] **Chosen framework for THIS context?** (not just default)
+- [ ] **Decided async vs sync?**
+- [ ] **Planned type hint strategy?**
+- [ ] **Defined project structure?**
+- [ ] **Planned error handling?**
+- [ ] **Considered background tasks?**
+
+---
+
+## 11. Anti-Patterns to Avoid
+
+### ❌ DON'T:
+- Default to Django for simple APIs (FastAPI may be better)
+- Use sync libraries in async code
+- Skip type hints for public APIs
+- Put business logic in routes/views
+- Ignore N+1 queries
+- Mix async and sync carelessly
+
+### ✅ DO:
+- Choose framework based on context
+- Ask about async requirements
+- Use Pydantic for validation
+- Separate concerns (routes → services → repos)
+- Test critical paths
+
+---
+
+> **Remember**: Python patterns are about decision-making for YOUR specific context. Don't copy code—think about what serves your application best.

package/Ai Agent Workflow/powers/python-pro/POWER.md

@@ -0,0 +1,87 @@
+````markdown
+---
+inclusion: manual
+name: python-pro
+description: Use when building Python 3.11+ applications requiring type safety, async programming, or production-grade patterns. Invoke for type hints, pytest, async/await, dataclasses, mypy configuration.
+license: MIT
+metadata:
+  author: https://github.com/Jeffallan
+  version: "1.0.0"
+  domain: language
+  triggers: Python development, type hints, async Python, pytest, mypy, dataclasses, Python best practices, Pythonic code
+  role: specialist
+  scope: implementation
+  output-format: code
+  related-skills: fastapi-expert, devops-engineer
+---
+
+# Python Pro
+
+Senior Python developer with 10+ years experience specializing in type-safe, async-first, production-ready Python 3.11+ code.
+
+## Role Definition
+
+You are a senior Python engineer mastering modern Python 3.11+ and its ecosystem. You write idiomatic, type-safe, performant code across web development, data science, automation, and system programming with focus on production best practices.
+
+## When to Use This Skill
+
+- Writing type-safe Python with complete type coverage
+- Implementing async/await patterns for I/O operations
+- Setting up pytest test suites with fixtures and mocking
+- Creating Pythonic code with comprehensions, generators, context managers
+- Building packages with Poetry and proper project structure
+- Performance optimization and profiling
+
+## Core Workflow
+
+1. **Analyze codebase** - Review structure, dependencies, type coverage, test suite
+2. **Design interfaces** - Define protocols, dataclasses, type aliases
+3. **Implement** - Write Pythonic code with full type hints and error handling
+4. **Test** - Create comprehensive pytest suite with >90% coverage
+5. **Validate** - Run mypy, black, ruff; ensure quality standards met
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| Type System | `references/type-system.md` | Type hints, mypy, generics, Protocol |
+| Async Patterns | `references/async-patterns.md` | async/await, asyncio, task groups |
+| Standard Library | `references/standard-library.md` | pathlib, dataclasses, functools, itertools |
+| Testing | `references/testing.md` | pytest, fixtures, mocking, parametrize |
+| Packaging | `references/packaging.md` | poetry, pip, pyproject.toml, distribution |
+
+## Constraints
+
+### MUST DO
+- Type hints for all function signatures and class attributes
+- PEP 8 compliance with black formatting
+- Comprehensive docstrings (Google style)
+- Test coverage exceeding 90% with pytest
+- Use `X | None` instead of `Optional[X]` (Python 3.10+)
+- Async/await for I/O-bound operations
+- Dataclasses over manual __init__ methods
+- Context managers for resource handling
+
+### MUST NOT DO
+- Skip type annotations on public APIs
+- Use mutable default arguments
+- Mix sync and async code improperly
+- Ignore mypy errors in strict mode
+- Use bare except clauses
+- Hardcode secrets or configuration
+- Use deprecated stdlib modules (use pathlib not os.path)
+
+## Output Templates
+
+When implementing Python features, provide:
+1. Module file with complete type hints
+2. Test file with pytest fixtures
+3. Type checking confirmation (mypy --strict passes)
+4. Brief explanation of Pythonic patterns used
+
+## Knowledge Reference
+
+Python 3.11+, typing module, mypy, pytest, black, ruff, dataclasses, async/await, asyncio, pathlib, functools, itertools, Poetry, Pydantic, contextlib, collections.abc, Protocol
+````

package/Ai Agent Workflow/powers/python-pro/SKILL.md

@@ -44,11 +44,11 @@ Load detailed guidance based on context:
 
 | Topic | Reference | Load When |
 |-------|-----------|-----------|
-| Type System | `steering/type-system.md` | Type hints, mypy, generics, Protocol |
-| Async Patterns | `steering/async-patterns.md` | async/await, asyncio, task groups |
-| Standard Library | `steering/standard-library.md` | pathlib, dataclasses, functools, itertools |
-| Testing | `steering/testing.md` | pytest, fixtures, mocking, parametrize |
-| Packaging | `steering/packaging.md` | poetry, pip, pyproject.toml, distribution |
+| Type System | `references/type-system.md` | Type hints, mypy, generics, Protocol |
+| Async Patterns | `references/async-patterns.md` | async/await, asyncio, task groups |
+| Standard Library | `references/standard-library.md` | pathlib, dataclasses, functools, itertools |
+| Testing | `references/testing.md` | pytest, fixtures, mocking, parametrize |
+| Packaging | `references/packaging.md` | poetry, pip, pyproject.toml, distribution |
 
 ## Constraints
 

package/Ai Agent Workflow/powers/react-best-practices/POWER.md

@@ -0,0 +1,139 @@
+````markdown
+---
+inclusion: manual
+name: react-best-practices
+description: "Performance-focused React/Next.js review checklist from Vercel. Use for optimization/refactor passes, not as the primary implementation skill."
+license: MIT
+metadata:
+  author: vercel
+  version: "1.0.0"
+---
+
+# Vercel React Best Practices
+
+Comprehensive performance optimization guide for React and Next.js applications, maintained by Vercel. Contains 57 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.
+
+## When to Apply
+
+Reference these guidelines when:
+- Writing new React components or Next.js pages
+- Implementing data fetching (client or server-side)
+- Reviewing code for performance issues
+- Refactoring existing React/Next.js code
+- Optimizing bundle size or load times
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | Eliminating Waterfalls | CRITICAL | `async-` |
+| 2 | Bundle Size Optimization | CRITICAL | `bundle-` |
+| 3 | Server-Side Performance | HIGH | `server-` |
+| 4 | Client-Side Data Fetching | MEDIUM-HIGH | `client-` |
+| 5 | Re-render Optimization | MEDIUM | `rerender-` |
+| 6 | Rendering Performance | MEDIUM | `rendering-` |
+| 7 | JavaScript Performance | LOW-MEDIUM | `js-` |
+| 8 | Advanced Patterns | LOW | `advanced-` |
+
+## Quick Reference
+
+### 1. Eliminating Waterfalls (CRITICAL)
+
+- `async-defer-await` - Move await into branches where actually used
+- `async-parallel` - Use Promise.all() for independent operations
+- `async-dependencies` - Use better-all for partial dependencies
+- `async-api-routes` - Start promises early, await late in API routes
+- `async-suspense-boundaries` - Use Suspense to stream content
+
+### 2. Bundle Size Optimization (CRITICAL)
+
+- `bundle-barrel-imports` - Import directly, avoid barrel files
+- `bundle-dynamic-imports` - Use next/dynamic for heavy components
+- `bundle-defer-third-party` - Load analytics/logging after hydration
+- `bundle-conditional` - Load modules only when feature is activated
+- `bundle-preload` - Preload on hover/focus for perceived speed
+
+### 3. Server-Side Performance (HIGH)
+
+- `server-auth-actions` - Authenticate server actions like API routes
+- `server-cache-react` - Use React.cache() for per-request deduplication
+- `server-cache-lru` - Use LRU cache for cross-request caching
+- `server-dedup-props` - Avoid duplicate serialization in RSC props
+- `server-serialization` - Minimize data passed to client components
+- `server-parallel-fetching` - Restructure components to parallelize fetches
+- `server-after-nonblocking` - Use after() for non-blocking operations
+
+### 4. Client-Side Data Fetching (MEDIUM-HIGH)
+
+- `client-swr-dedup` - Use SWR for automatic request deduplication
+- `client-event-listeners` - Deduplicate global event listeners
+- `client-passive-event-listeners` - Use passive listeners for scroll
+- `client-localstorage-schema` - Version and minimize localStorage data
+
+### 5. Re-render Optimization (MEDIUM)
+
+- `rerender-defer-reads` - Don't subscribe to state only used in callbacks
+- `rerender-memo` - Extract expensive work into memoized components
+- `rerender-memo-with-default-value` - Hoist default non-primitive props
+- `rerender-dependencies` - Use primitive dependencies in effects
+- `rerender-derived-state` - Subscribe to derived booleans, not raw values
+- `rerender-derived-state-no-effect` - Derive state during render, not effects
+- `rerender-functional-setstate` - Use functional setState for stable callbacks
+- `rerender-lazy-state-init` - Pass function to useState for expensive values
+- `rerender-simple-expression-in-memo` - Avoid memo for simple primitives
+- `rerender-move-effect-to-event` - Put interaction logic in event handlers
+- `rerender-transitions` - Use startTransition for non-urgent updates
+- `rerender-use-ref-transient-values` - Use refs for transient frequent values
+
+### 6. Rendering Performance (MEDIUM)
+
+- `rendering-animate-svg-wrapper` - Animate div wrapper, not SVG element
+- `rendering-content-visibility` - Use content-visibility for long lists
+- `rendering-hoist-jsx` - Extract static JSX outside components
+- `rendering-svg-precision` - Reduce SVG coordinate precision
+- `rendering-hydration-no-flicker` - Use inline script for client-only data
+- `rendering-hydration-suppress-warning` - Suppress expected mismatches
+- `rendering-activity` - Use Activity component for show/hide
+- `rendering-conditional-render` - Use ternary, not && for conditionals
+- `rendering-usetransition-loading` - Prefer useTransition for loading state
+
+### 7. JavaScript Performance (LOW-MEDIUM)
+
+- `js-batch-dom-css` - Group CSS changes via classes or cssText
+- `js-index-maps` - Build Map for repeated lookups
+- `js-cache-property-access` - Cache object properties in loops
+- `js-cache-function-results` - Cache function results in module-level Map
+- `js-cache-storage` - Cache localStorage/sessionStorage reads
+- `js-combine-iterations` - Combine multiple filter/map into one loop
+- `js-length-check-first` - Check array length before expensive comparison
+- `js-early-exit` - Return early from functions
+- `js-hoist-regexp` - Hoist RegExp creation outside loops
+- `js-min-max-loop` - Use loop for min/max instead of sort
+- `js-set-map-lookups` - Use Set/Map for O(1) lookups
+- `js-tosorted-immutable` - Use toSorted() for immutability
+
+### 8. Advanced Patterns (LOW)
+
+- `advanced-event-handler-refs` - Store event handlers in refs
+- `advanced-init-once` - Initialize app once per app load
+- `advanced-use-latest` - useLatest for stable callback refs
+
+## How to Use
+
+Read individual rule files for detailed explanations and code examples:
+
+```
+rules/async-parallel.md
+rules/bundle-barrel-imports.md
+```
+
+Each rule file contains:
+- Brief explanation of why it matters
+- Incorrect code example with explanation
+- Correct code example with explanation
+- Additional context and references
+
+## Full Compiled Document
+
+For the complete guide with all rules expanded: `AGENTS.md`
+````