@cubis/foundry 0.3.32 → 0.3.33

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/nodejs-best-practices/SKILL.md

@@ -1,333 +1,49 @@
 ---
-name: nodejs-best-practices
-description: Node.js development principles and decision-making. Framework selection, async patterns, security, and architecture. Teaches thinking, not copying.
-allowed-tools: Read, Write, Edit, Glob, Grep
+name: "nodejs-best-practices"
+description: "Decision framework for modern Node.js backend architecture, operations, and security using current LTS-era practices."
+license: MIT
+metadata:
+  version: "2.0.0"
+  domain: "backend"
+  role: "decision-guide"
+  stack: "nodejs"
+  baseline: "Node 22/24 LTS era"
 ---
 
 # Node.js Best Practices
 
-> Principles and decision-making for Node.js development in 2025.
-> **Learn to THINK, not memorize code patterns.**
+## Purpose
 
----
-
-## ⚠️ How to Use This Skill
-
-This skill teaches **decision-making principles**, not fixed code to copy.
-
-- ASK user for preferences when unclear
-- Choose framework/pattern based on CONTEXT
-- Don't default to same solution every time
-
----
-
-## 1. Framework Selection (2025)
-
-### Decision Tree
-
-```
-What are you building?
-│
-├── Edge/Serverless (Cloudflare, Vercel)
-│   └── Hono (zero-dependency, ultra-fast cold starts)
-│
-├── High Performance API
-│   └── Fastify (2-3x faster than Express)
-│
-├── Enterprise/Team familiarity
-│   └── NestJS (structured, DI, decorators)
-│
-├── Legacy/Stable/Maximum ecosystem
-│   └── Express (mature, most middleware)
-│
-└── Full-stack with frontend
-    └── Next.js API Routes or tRPC
-```
-
-### Comparison Principles
-
-| Factor | Hono | Fastify | Express |
-|--------|------|---------|---------|
-| **Best for** | Edge, serverless | Performance | Legacy, learning |
-| **Cold start** | Fastest | Fast | Moderate |
-| **Ecosystem** | Growing | Good | Largest |
-| **TypeScript** | Native | Excellent | Good |
-| **Learning curve** | Low | Medium | Low |
-
-### Selection Questions to Ask:
-1. What's the deployment target?
-2. Is cold start time critical?
-3. Does team have existing experience?
-4. Is there legacy code to maintain?
-
----
-
-## 2. Runtime Considerations (2025)
-
-### Native TypeScript
-
-```
-Node.js 22+: --experimental-strip-types
-├── Run .ts files directly
-├── No build step needed for simple projects
-└── Consider for: scripts, simple APIs
-```
-
-### Module System Decision
-
-```
-ESM (import/export)
-├── Modern standard
-├── Better tree-shaking
-├── Async module loading
-└── Use for: new projects
-
-CommonJS (require)
-├── Legacy compatibility
-├── More npm packages support
-└── Use for: existing codebases, some edge cases
-```
+Use this skill to choose the right Node backend patterns for the actual constraints of the task, not by habit.
 
-### Runtime Selection
+## Decision flow
 
-| Runtime | Best For |
-|---------|----------|
-| **Node.js** | General purpose, largest ecosystem |
-| **Bun** | Performance, built-in bundler |
-| **Deno** | Security-first, built-in TypeScript |
-
----
-
-## 3. Architecture Principles
-
-### Layered Structure Concept
-
-```
-Request Flow:
-│
-├── Controller/Route Layer
-│   ├── Handles HTTP specifics
-│   ├── Input validation at boundary
-│   └── Calls service layer
-│
-├── Service Layer
-│   ├── Business logic
-│   ├── Framework-agnostic
-│   └── Calls repository layer
-│
-└── Repository Layer
-    ├── Data access only
-    ├── Database queries
-    └── ORM interactions
-```
-
-### Why This Matters:
-- **Testability**: Mock layers independently
-- **Flexibility**: Swap database without touching business logic
-- **Clarity**: Each layer has single responsibility
-
-### When to Simplify:
-- Small scripts → Single file OK
-- Prototypes → Less structure acceptable
-- Always ask: "Will this grow?"
-
----
-
-## 4. Error Handling Principles
-
-### Centralized Error Handling
-
-```
-Pattern:
-├── Create custom error classes
-├── Throw from any layer
-├── Catch at top level (middleware)
-└── Format consistent response
-```
-
-### Error Response Philosophy
-
-```
-Client gets:
-├── Appropriate HTTP status
-├── Error code for programmatic handling
-├── User-friendly message
-└── NO internal details (security!)
-
-Logs get:
-├── Full stack trace
-├── Request context
-├── User ID (if applicable)
-└── Timestamp
-```
-
-### Status Code Selection
-
-| Situation | Status | When |
-|-----------|--------|------|
-| Bad input | 400 | Client sent invalid data |
-| No auth | 401 | Missing or invalid credentials |
-| No permission | 403 | Valid auth, but not allowed |
-| Not found | 404 | Resource doesn't exist |
-| Conflict | 409 | Duplicate or state conflict |
-| Validation | 422 | Schema valid but business rules fail |
-| Server error | 500 | Our fault, log everything |
-
----
+1. Clarify deployment target (container, serverless, edge).
+2. Select framework/runtime shape based on latency and team constraints.
+3. Define API, validation, auth, and observability boundaries.
+4. Implement smallest safe slice, then harden.
 
-## 5. Async Patterns Principles
+## Core guidance
 
-### When to Use Each
+- Prefer typed boundaries (TypeScript + schema validation).
+- Keep transport concerns out of business logic.
+- Standardize error envelopes and correlation IDs.
+- Enforce timeout, retry, and circuit-breaker strategy for downstream calls.
+- Use graceful shutdown and health/readiness probes.
 
-| Pattern | Use When |
-|---------|----------|
-| `async/await` | Sequential async operations |
-| `Promise.all` | Parallel independent operations |
-| `Promise.allSettled` | Parallel where some can fail |
-| `Promise.race` | Timeout or first response wins |
+## Security and reliability
 
-### Event Loop Awareness
+- Validate all request input before business logic.
+- Use least-privilege credentials and secret rotation.
+- Avoid blocking the event loop in request paths.
+- Add rate limits and abuse controls on external endpoints.
 
-```
-I/O-bound (async helps):
-├── Database queries
-├── HTTP requests
-├── File system
-└── Network operations
+## Performance
 
-CPU-bound (async doesn't help):
-├── Crypto operations
-├── Image processing
-├── Complex calculations
-└── → Use worker threads or offload
-```
+- Measure before optimizing.
+- Profile CPU and heap in realistic workloads.
+- Use streaming/backpressure for large I/O paths.
 
-### Avoiding Event Loop Blocking
-
-- Never use sync methods in production (fs.readFileSync, etc.)
-- Offload CPU-intensive work
-- Use streaming for large data
-
----
-
-## 6. Validation Principles
-
-### Validate at Boundaries
-
-```
-Where to validate:
-├── API entry point (request body/params)
-├── Before database operations
-├── External data (API responses, file uploads)
-└── Environment variables (startup)
-```
-
-### Validation Library Selection
-
-| Library | Best For |
-|---------|----------|
-| **Zod** | TypeScript first, inference |
-| **Valibot** | Smaller bundle (tree-shakeable) |
-| **ArkType** | Performance critical |
-| **Yup** | Existing React Form usage |
-
-### Validation Philosophy
-
-- Fail fast: Validate early
-- Be specific: Clear error messages
-- Don't trust: Even "internal" data
-
----
-
-## 7. Security Principles
-
-### Security Checklist (Not Code)
-
-- [ ] **Input validation**: All inputs validated
-- [ ] **Parameterized queries**: No string concatenation for SQL
-- [ ] **Password hashing**: bcrypt or argon2
-- [ ] **JWT verification**: Always verify signature and expiry
-- [ ] **Rate limiting**: Protect from abuse
-- [ ] **Security headers**: Helmet.js or equivalent
-- [ ] **HTTPS**: Everywhere in production
-- [ ] **CORS**: Properly configured
-- [ ] **Secrets**: Environment variables only
-- [ ] **Dependencies**: Regularly audited
-
-### Security Mindset
-
-```
-Trust nothing:
-├── Query params → validate
-├── Request body → validate
-├── Headers → verify
-├── Cookies → validate
-├── File uploads → scan
-└── External APIs → validate response
-```
-
----
-
-## 8. Testing Principles
-
-### Test Strategy Selection
-
-| Type | Purpose | Tools |
-|------|---------|-------|
-| **Unit** | Business logic | node:test, Vitest |
-| **Integration** | API endpoints | Supertest |
-| **E2E** | Full flows | Playwright |
-
-### What to Test (Priorities)
-
-1. **Critical paths**: Auth, payments, core business
-2. **Edge cases**: Empty inputs, boundaries
-3. **Error handling**: What happens when things fail?
-4. **Not worth testing**: Framework code, trivial getters
-
-### Built-in Test Runner (Node.js 22+)
-
-```
-node --test src/**/*.test.ts
-├── No external dependency
-├── Good coverage reporting
-└── Watch mode available
-```
-
----
-
-## 10. Anti-Patterns to Avoid
-
-### ❌ DON'T:
-- Use Express for new edge projects (use Hono)
-- Use sync methods in production code
-- Put business logic in controllers
-- Skip input validation
-- Hardcode secrets
-- Trust external data without validation
-- Block event loop with CPU work
-
-### ✅ DO:
-- Choose framework based on context
-- Ask user for preferences when unclear
-- Use layered architecture for growing projects
-- Validate all inputs
-- Use environment variables for secrets
-- Profile before optimizing
-
----
-
-## 11. Decision Checklist
-
-Before implementing:
-
-- [ ] **Asked user about stack preference?**
-- [ ] **Chosen framework for THIS context?** (not just default)
-- [ ] **Considered deployment target?**
-- [ ] **Planned error handling strategy?**
-- [ ] **Identified validation points?**
-- [ ] **Considered security requirements?**
-
----
+## Output expectation
 
-> **Remember**: Node.js best practices are about decision-making, not memorizing patterns. Every project deserves fresh consideration based on its requirements.
+Return concrete architecture choices with tradeoffs, then implementation steps and verification criteria.

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/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`

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/react-best-practices/SKILL.md

@@ -1,136 +1,53 @@
 ---
-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."
+name: "react-best-practices"
+description: "Performance-focused React/Next.js review checklist. Use for audits and optimization passes, not as primary implementation skill."
 license: MIT
 metadata:
   author: vercel
-  version: "1.0.0"
+  version: "2.0.0"
+  domain: "frontend"
+  role: "review-checklist"
 ---
 
-# Vercel React Best Practices
+# 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.
+## Purpose
 
-## When to Apply
+Use this skill to run structured optimization reviews on React/Next.js code. Pair it with implementation skills (`react-expert`, `nextjs-developer`) when code changes are required.
 
-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
+## Review order
 
-## Rule Categories by Priority
+1. Async waterfalls and request parallelization.
+2. Bundle and hydration footprint.
+3. Server rendering and serialization overhead.
+4. Client data-fetching and rerender churn.
+5. JS/runtime hot paths.
 
-| 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-` |
+## High-impact checks
 
-## Quick Reference
+- Parallelize independent async work.
+- Eliminate unnecessary client components.
+- Remove heavy modules from critical path.
+- Avoid unstable props that trigger deep rerenders.
+- Keep server-to-client payloads minimal.
 
-### 1. Eliminating Waterfalls (CRITICAL)
+## Output format
 
-- `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
+Return prioritized findings with:
 
-### 2. Bundle Size Optimization (CRITICAL)
+1. Issue and impact.
+2. Minimal safe change.
+3. Verification method (profile metric or test).
 
-- `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
+## Rule catalog
 
-### 3. Server-Side Performance (HIGH)
+Detailed rules are under `rules/` and grouped by prefix:
 
-- `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`
+- `async-*`
+- `bundle-*`
+- `server-*`
+- `client-*`
+- `rerender-*`
+- `rendering-*`
+- `js-*`
+- `advanced-*`