@cubis/foundry 0.3.31 → 0.3.33

package/workflows/powers/python-patterns/SKILL.md

@@ -1,441 +1,21 @@
 ---
 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
+description: "Compatibility alias skill. Deprecated: use python-pro."
+metadata:
+  deprecated: true
+  replaced_by: python-pro
+  removal_target: v0.6.0
 ---
 
 # Python Patterns
 
-> Python development principles and decision-making for 2025.
-> **Learn to THINK, not memorize patterns.**
+## Compatibility Alias
 
----
-
-## ⚠️ 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
-```
+This skill is deprecated and kept for backward compatibility.
 
-### Django Best Practices
+Use `python-pro` as the canonical skill.
 
-```
-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
-
----
+## Migration
 
-> **Remember**: Python patterns are about decision-making for YOUR specific context. Don't copy code—think about what serves your application best.
+1. Replace direct references to `python-patterns` with `python-pro`.
+2. Apply the full workflow from `python-pro` for new work.

package/workflows/powers/python-pro/POWER.md

@@ -1,87 +1,59 @@
 ````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.
+name: "python-pro"
+description: "Use for production Python with 3.14-era typing, async, packaging, and testing standards."
 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
+  version: "2.0.0"
+  domain: "language"
+  role: "specialist"
+  stack: "python"
+  baseline: "Python 3.14"
 ---
 
 # Python Pro
 
-Senior Python developer with 10+ years experience specializing in type-safe, async-first, production-ready Python 3.11+ code.
+## When to use
 
-## Role Definition
+- Building backend services, automation, or data pipelines in Python.
+- Migrating legacy Python to typed and testable architecture.
+- Implementing async I/O with predictable behavior.
 
-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.
+## Core workflow
 
-## When to Use This Skill
+1. Establish interpreter/runtime constraints.
+2. Define typed interfaces and domain models.
+3. Implement sync/async boundaries explicitly.
+4. Validate with tests, type checks, and linting.
 
-- 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
+## Baseline standards
 
-## Core Workflow
+- Type annotate public functions and critical internal APIs.
+- Use `pyproject.toml`-first packaging and tooling.
+- Use `pytest` for tests and parametrize edge cases.
+- Keep business logic separate from framework glue.
+- Prefer stdlib clarity before adding dependencies.
 
-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
+## Implementation guidance
 
-## Reference Guide
+- Use `dataclass`/Pydantic models for domain boundaries.
+- Use `TaskGroup`-style structured concurrency where possible.
+- Preserve exception context; do not swallow root causes.
+- Keep I/O async and CPU work isolated where needed.
+- Treat free-threaded mode as opt-in until dependencies are validated.
 
-Load detailed guidance based on context:
+## Avoid
 
-| 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 |
+- Untyped public APIs in shared modules.
+- Hidden global state in request paths.
+- Mixed sync/async call graphs without clear adapters.
 
-## Constraints
+## Reference files
 
-### 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
+- `references/type-system.md`
+- `references/async-patterns.md`
+- `references/testing.md`
+- `references/packaging.md`
+- `references/standard-library.md`
 ````

package/workflows/powers/python-pro/SKILL.md

@@ -1,84 +1,56 @@
 ---
-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.
+name: "python-pro"
+description: "Use for production Python with 3.14-era typing, async, packaging, and testing standards."
 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
+  version: "2.0.0"
+  domain: "language"
+  role: "specialist"
+  stack: "python"
+  baseline: "Python 3.14"
 ---
 
 # Python Pro
 
-Senior Python developer with 10+ years experience specializing in type-safe, async-first, production-ready Python 3.11+ code.
+## When to use
 
-## Role Definition
+- Building backend services, automation, or data pipelines in Python.
+- Migrating legacy Python to typed and testable architecture.
+- Implementing async I/O with predictable behavior.
 
-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.
+## Core workflow
 
-## When to Use This Skill
+1. Establish interpreter/runtime constraints.
+2. Define typed interfaces and domain models.
+3. Implement sync/async boundaries explicitly.
+4. Validate with tests, type checks, and linting.
 
-- 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
+## Baseline standards
 
-## Core Workflow
+- Type annotate public functions and critical internal APIs.
+- Use `pyproject.toml`-first packaging and tooling.
+- Use `pytest` for tests and parametrize edge cases.
+- Keep business logic separate from framework glue.
+- Prefer stdlib clarity before adding dependencies.
 
-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
+## Implementation guidance
 
-## Reference Guide
+- Use `dataclass`/Pydantic models for domain boundaries.
+- Use `TaskGroup`-style structured concurrency where possible.
+- Preserve exception context; do not swallow root causes.
+- Keep I/O async and CPU work isolated where needed.
+- Treat free-threaded mode as opt-in until dependencies are validated.
 
-Load detailed guidance based on context:
+## Avoid
 
-| 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 |
+- Untyped public APIs in shared modules.
+- Hidden global state in request paths.
+- Mixed sync/async call graphs without clear adapters.
 
-## Constraints
+## Reference files
 
-### 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
+- `references/type-system.md`
+- `references/async-patterns.md`
+- `references/testing.md`
+- `references/packaging.md`
+- `references/standard-library.md`