@cubis/foundry 0.3.82 → 0.3.84

package/workflows/skills/performance-testing/references/profiling.md

@@ -1,233 +0,0 @@
-# Profiling
-
-## Why Profile Before Optimizing
-
-Profiling identifies where a program actually spends its time and resources. Without profiling, developers rely on intuition, which is wrong more often than right. The 90/10 rule applies: 90% of execution time is spent in 10% of the code. Profiling finds that 10%.
-
-## Profiling Types
-
-### CPU Profiling
-
-Measures which functions consume the most CPU time.
-
-**When to use:** Application response time is high but I/O metrics (disk, network) show no saturation. CPU utilization is elevated.
-
-#### Node.js CPU Profiling
-
-```bash
-# Built-in V8 profiler
-node --prof app.js
-node --prof-process isolate-*.log > profile.txt
-
-# Chrome DevTools profiler
-node --inspect app.js
-# Open chrome://inspect, go to Performance tab, click Record
-
-# Clinic.js (flamegraph)
-npx clinic flame -- node app.js
-```
-
-#### Python CPU Profiling
-
-```python
-# cProfile (standard library)
-import cProfile
-
-cProfile.run('main()', 'output.prof')
-
-# Read the profile
-import pstats
-stats = pstats.Stats('output.prof')
-stats.sort_stats('cumulative')
-stats.print_stats(20)  # Top 20 functions
-
-# py-spy (sampling profiler, no code changes needed)
-# pip install py-spy
-# py-spy top --pid <PID>
-# py-spy record -o profile.svg --pid <PID>
-```
-
-#### Go CPU Profiling
-
-```go
-import "runtime/pprof"
-
-f, _ := os.Create("cpu.prof")
-pprof.StartCPUProfile(f)
-defer pprof.StopCPUProfile()
-
-// Or with net/http/pprof for running servers:
-import _ "net/http/pprof"
-// Access at http://localhost:6060/debug/pprof/
-```
-
-```bash
-go tool pprof http://localhost:6060/debug/pprof/profile?seconds=30
-# (pprof) top 20
-# (pprof) web  # Opens flamegraph in browser
-```
-
-### Memory Profiling
-
-Measures memory allocation patterns and identifies leaks.
-
-**When to use:** Memory usage grows over time (leak), garbage collection pauses are long, or out-of-memory errors occur.
-
-#### Node.js Memory Profiling
-
-```bash
-# Heap snapshot
-node --inspect app.js
-# Chrome DevTools -> Memory tab -> Take heap snapshot
-
-# Track allocations over time
-node --inspect app.js
-# Chrome DevTools -> Memory tab -> Allocation instrumentation on timeline
-
-# Clinic.js heap profiler
-npx clinic heapprofile -- node app.js
-```
-
-#### Python Memory Profiling
-
-```python
-# memory_profiler (line-by-line memory usage)
-from memory_profiler import profile
-
-@profile
-def process_data():
-    data = [i ** 2 for i in range(1_000_000)]
-    filtered = [x for x in data if x % 2 == 0]
-    return sum(filtered)
-
-# tracemalloc (standard library)
-import tracemalloc
-
-tracemalloc.start()
-# ... run code ...
-snapshot = tracemalloc.take_snapshot()
-stats = snapshot.statistics('lineno')
-for stat in stats[:10]:
-    print(stat)
-```
-
-### I/O Profiling
-
-Measures time spent waiting for disk, network, or database operations.
-
-**When to use:** CPU utilization is low but response times are high. The application is I/O bound.
-
-```bash
-# Linux: strace for system call analysis
-strace -c -p <PID>  # Summary of syscall time
-strace -e trace=network -p <PID>  # Network calls only
-
-# Node.js: Clinic.js Doctor (identifies I/O bottlenecks)
-npx clinic doctor -- node app.js
-```
-
-## Flame Graphs
-
-Flame graphs are the most effective visualization for CPU profiles. Each bar represents a function. Width indicates time spent. The y-axis shows the call stack.
-
-### Reading a Flame Graph
-
-```
-|--------- main() ---------|
-|---- processRequest() ----|
-|-- parseJSON() --|-- queryDB() --|
-                  |-- serialize() -|
-```
-
-- **Wide bars** at the top: these functions (and their children) consume the most time.
-- **Wide bars** at the bottom (leaf functions): these functions themselves are slow.
-- **Narrow bars**: fast functions, not worth optimizing.
-
-### Generating Flame Graphs
-
-```bash
-# Node.js
-npx clinic flame -- node app.js
-# Opens interactive flamegraph in browser
-
-# Python
-py-spy record -o profile.svg --pid <PID>
-# Opens as SVG in browser
-
-# Go
-go tool pprof -http=:8080 cpu.prof
-# Navigate to Flame Graph view
-
-# Linux (any language)
-perf record -g -p <PID> -- sleep 30
-perf script | stackcollapse-perf.pl | flamegraph.pl > profile.svg
-```
-
-## Profiling Workflow
-
-### Step 1: Establish the Question
-
-What specific performance problem are you investigating?
-
-- "Why does the /api/search endpoint take 2 seconds?"
-- "Why does memory grow by 100MB per hour?"
-- "Why does CPU spike to 100% during batch processing?"
-
-### Step 2: Choose the Right Profiler
-
-| Symptom | Profiler Type | Tool |
-|---------|--------------|------|
-| High CPU usage | CPU profiler | clinic flame, py-spy, pprof |
-| Growing memory | Memory profiler | Chrome DevTools, tracemalloc, pprof |
-| Slow despite low CPU | I/O profiler | clinic doctor, strace |
-| Long GC pauses | GC profiler | --trace-gc (Node), gc module (Python) |
-
-### Step 3: Profile Under Realistic Load
-
-Profile with production-like traffic, data volumes, and concurrency. Profiling an idle system reveals nothing useful.
-
-```bash
-# Start the application
-node app.js &
-
-# In another terminal, generate load
-k6 run load-test.js
-
-# In a third terminal, capture the profile
-npx clinic flame --autocannon [ /api/endpoint -c 50 -d 30 ]
-```
-
-### Step 4: Identify the Hotspot
-
-Look for functions that:
-- Appear in the widest flame graph bars.
-- Show up in the top 10 by cumulative time.
-- Are called unexpectedly many times.
-- Allocate unexpectedly large amounts of memory.
-
-### Step 5: Optimize and Verify
-
-Make one change, re-profile, and compare. Verify the hotspot is resolved and no new one appeared.
-
-## Continuous Profiling
-
-For production systems, use always-on profilers with minimal overhead:
-
-| Tool | Language | Overhead |
-|------|----------|----------|
-| Pyroscope | Multi-language | ~2% CPU |
-| Datadog Continuous Profiler | Multi-language | ~1-2% CPU |
-| Google Cloud Profiler | Go, Java, Python, Node | ~1% CPU |
-| Parca | Multi-language (eBPF) | < 1% CPU |
-
-Continuous profiling captures production behavior that cannot be reproduced in test environments. It enables comparing profiles across deployments to detect regressions.
-
-## Common Profiling Mistakes
-
-| Mistake | Impact | Fix |
-|---------|--------|-----|
-| Profiling in development only | Development behavior differs from production | Profile under production-like load |
-| Profiling without load | Idle profiles show startup code, not hot paths | Generate realistic concurrent traffic |
-| Optimizing before profiling | Wasting time on non-bottleneck code | Always profile first, then optimize |
-| Ignoring allocation patterns | Memory pressure causes GC pauses that appear as CPU | Profile both CPU and memory |
-| One-time profiling only | Performance characteristics change with new code | Profile regularly, especially after major changes |

package/workflows/skills/php-best-practices/SKILL.md

@@ -1,85 +0,0 @@
----
-name: php-best-practices
-description: "Use when writing, reviewing, or refactoring modern PHP, including readonly classes, enums, property hooks, Composer package design, strict types, and security hardening."
-license: MIT
-metadata:
-  author: cubis-foundry
-  version: "3.0"
-compatibility: Claude Code, Codex, GitHub Copilot
----
-
-# PHP Best Practices
-
-## Purpose
-
-Production-grade guidance for PHP 8.4+ application engineering. Covers strict typing with property hooks and asymmetric visibility, Fiber-based concurrency for non-blocking I/O, enum-driven domain modeling, readonly classes for immutable data transfer, Composer package design with autoloading and security auditing, and defense-in-depth security practices.
-
-## When to Use
-
-- Building new PHP services, APIs, or packages targeting PHP 8.4+.
-- Designing typed service layers with readonly classes, enums, and property hooks.
-- Implementing non-blocking I/O with Fibers or async runtimes (ReactPHP, Revolt, AMPHP).
-- Creating Composer packages with proper autoloading, versioning, and CI.
-- Hardening PHP applications against injection, CSRF, deserialization, and session attacks.
-- Reviewing PHP code for type safety, architectural issues, or security vulnerabilities.
-
-## Instructions
-
-1. **Add `declare(strict_types=1)` to every PHP file without exception** because without it PHP silently coerces types at call boundaries, turning type declarations into documentation rather than enforcement. Automate this with PHP CS Fixer's `declare_strict_types` rule.
-
-2. **Use typed properties, parameters, return types, and union/intersection types on all public APIs** because PHP 8.4's type system is rich enough to express precise contracts. Use `string|int` for unions, `Countable&Iterator` for intersections, `never` for functions that always throw or exit, and `null` only when null is a meaningful domain value.
-
-3. **Use enums for all fixed value sets instead of string/int constants** because enums are type-safe, auto-complete friendly, and exhaustively matchable in `match` expressions. Use backed enums (`enum Status: string`) when values must serialize to storage or APIs. Implement interfaces on enums when they need to satisfy polymorphic contracts.
-
-4. **Use readonly classes and readonly properties for immutable DTOs and value objects** because readonly enforcement prevents accidental mutation after construction, making objects safe to pass across service boundaries without defensive copying. Use constructor promotion (`public readonly string $name`) for concise declaration.
-
-5. **Adopt property hooks (PHP 8.4) for computed and validated properties** because hooks replace magic `__get`/`__set` with type-safe, per-property get/set logic that the engine optimizes. Use `set` hooks for validation at assignment time and `get` hooks for lazy computation, eliminating boilerplate getter/setter methods.
-
-6. **Use asymmetric visibility (PHP 8.4) to expose read-only public interfaces** because `public private(set)` lets external code read a property while restricting writes to the owning class, replacing the common pattern of a private property with a public getter method.
-
-7. **Understand Fibers for non-blocking I/O coordination** because Fibers provide cooperative multitasking within a single thread — they suspend and resume execution at explicit points without callback nesting. Use Fibers through established libraries (Revolt event loop, AMPHP, ReactPHP) rather than raw `Fiber::suspend()`/`Fiber::resume()` because the libraries handle scheduling, error propagation, and resource cleanup.
-
-8. **Separate controllers, services, and repositories into distinct layers** because mixing request handling with business logic and persistence creates untestable monoliths. Controllers validate input and return responses. Services contain business rules. Repositories abstract storage. Use constructor injection for all dependencies.
-
-9. **Use interfaces at module boundaries and concrete classes internally** because interface-based contracts enable testing with mocks, swapping implementations (e.g., switching cache backends), and enforcing the dependency inversion principle. Keep interfaces focused — one responsibility per interface.
-
-10. **Handle errors with specific exception hierarchies and result objects** because catching `\Exception` or `\Throwable` broadly swallows unexpected failures. Define domain-specific exception classes (`OrderNotFoundException`, `InsufficientFundsException`). Use result objects or union return types for expected failure paths like validation, which are control flow rather than exceptional conditions.
-
-11. **Write tests with PHPUnit or Pest using data providers and mocked dependencies** because parameterized tests via data providers cover edge cases without code duplication. Mock external dependencies (HTTP clients, databases) with Mockery or PHPUnit mocks. Run tests in CI with coverage reporting and target meaningful coverage of business logic paths.
-
-12. **Run PHPStan or Psalm at level 8+ in CI and treat failures as build-breaking** because static analysis catches type errors, dead code, and impossible conditions that tests miss. Use `@phpstan-type` and `@phpstan-param` for complex generic shapes that PHP's native type system cannot yet express.
-
-13. **Design Composer packages with PSR-4 autoloading and semantic versioning** because PSR-4 eliminates manual `require`/`include` calls and semantic versioning lets consumers pin compatible ranges safely. Commit `composer.lock` in applications (reproducible builds) but not in libraries (flexibility for consumers). Run `composer audit` in CI to catch known vulnerabilities.
-
-14. **Harden against injection by using prepared statements and parameterized queries exclusively** because SQL injection remains the most common PHP vulnerability. Never concatenate user input into queries. Use PDO with `PDO::ATTR_EMULATE_PREPARES => false` for real server-side preparation. Validate and sanitize all input at the boundary layer.
-
-15. **Protect sessions and authentication with secure defaults** because PHP's default session configuration is insufficient for production. Set `session.cookie_httponly`, `session.cookie_secure`, `session.cookie_samesite`, and regenerate session IDs on privilege changes. Use `password_hash()`/`password_verify()` with `PASSWORD_ARGON2ID` for credential storage.
-
-16. **Use OPcache with preloading in production** because OPcache eliminates repeated parsing and compilation, and preloading keeps frequently used classes in shared memory across requests. Profile with Xdebug (development) or Blackfire (production profiling) before optimizing — measure, do not guess.
-
-17. **Avoid `mixed` type, `@` error suppression, and global mutable state** because `mixed` defeats static analysis, `@` hides errors that should be handled explicitly, and global state creates hidden coupling that makes testing impossible. Use proper union types, explicit error handling, and dependency injection instead.
-
-18. **Use `match` expressions over `switch` for value-returning conditionals** because `match` uses strict comparison (no type coercion), requires exhaustive handling, returns values directly, and does not fall through — eliminating an entire category of bugs common with `switch`.
-
-## Output Format
-
-Produces PHP 8.4+ code with strict types, readonly classes, enums, property hooks, and explicit interface contracts. Includes Composer configuration, PHPStan setup, and test examples where relevant.
-
-## References
-
-| File | Load when |
-| --- | --- |
-| `references/modern-php.md` | You need property hooks, asymmetric visibility, enums, match expressions, named arguments, or first-class callable syntax. |
-| `references/type-system.md` | You need union/intersection types, readonly classes, DNF types, PHPStan generics, or strict typing migration guidance. |
-| `references/testing.md` | You need PHPUnit/Pest setup, data providers, mocking strategies, code coverage, or CI test pipeline patterns. |
-| `references/composer-packaging.md` | You need PSR-4 autoloading, semantic versioning, package publishing, dependency auditing, or lock file strategies. |
-| `references/security.md` | You need injection prevention, session hardening, CSRF protection, deserialization safety, or input validation patterns. |
-
-## Scripts
-
-No helper scripts are required for this skill right now. Keep execution in `SKILL.md` and `references/` unless repeated automation becomes necessary.
-
-## Examples
-
-- "Design a typed service with readonly value objects, enums, and property hooks for an e-commerce domain."
-- "Create a Composer package with PSR-4 autoloading, PHPStan level 9, and CI-ready test configuration."

package/workflows/skills/php-best-practices/evals/assertions.md

@@ -1,35 +0,0 @@
-# PHP Best Practices — Eval Assertions
-
-## Eval 1: Typed Service Implementation
-
-Tests whether the agent produces correct PHP 8.4 typed architecture with value objects and domain modeling.
-
-### Assertions
-
-1. **strict-types-and-readonly-classes** — Every PHP file begins with `declare(strict_types=1);`. Value objects like `Money`, `Quantity`, and `ProductId` are declared as `readonly class` with constructor property promotion (`public readonly string $currency`). No value object has mutable public properties. Reject classes that allow post-construction mutation of identity or value fields.
-
-2. **enum-driven-domain-modeling** — Product status is a `backed enum` (e.g., `enum ProductStatus: string { case Active = 'active'; ... }`). The enum is used in method signatures, `match` expressions for business rules, and type hints on properties. Reject code using string constants (`const STATUS_ACTIVE = 'active'`), integer flags, or untyped status fields.
-
-3. **property-hooks-usage** — At least one class demonstrates PHP 8.4 property hooks. Examples: a `get` hook on a `Product` class that computes `$formattedPrice` from `$price` and `$currency`, or a `set` hook on `Quantity` that validates the value is non-negative at assignment time. Reject code that uses traditional `getX()`/`setX()` methods where hooks would be cleaner. Accept the syntax `public int $quantity { set => $value >= 0 ? $value : throw new \InvalidArgumentException(...) }`.
-
-4. **interface-based-contracts** — A `ProductRepositoryInterface` (or similar) defines `findById(ProductId $id): ?Product`, `save(Product $product): void`, etc. with full type hints. The `InventoryService` constructor accepts this interface, not a concrete class. Reject services that instantiate their own repositories with `new` or depend on concrete database classes.
-
-5. **specific-exception-hierarchy** — Domain exceptions extend a base class (e.g., `abstract class DomainException extends \RuntimeException`). Specific exceptions like `ProductNotFoundException` include the `ProductId` that failed lookup. `InsufficientStockException` includes requested and available quantities. Reject generic `throw new \Exception('not found')` patterns.
-
----
-
-## Eval 2: Composer Package Design
-
-Tests whether the agent produces a properly structured, CI-ready PHP package with modern tooling.
-
-### Assertions
-
-1. **psr4-autoloading-config** — The `composer.json` includes `"autoload": { "psr-4": { "Vendor\\Validation\\": "src/" } }` and `"autoload-dev": { "psr-4": { "Vendor\\Validation\\Tests\\": "tests/" } }`. Dependencies include `phpunit/phpunit` and `phpstan/phpstan` as `require-dev`. No `require` or `include` statements appear in source files for class loading. Reject packages missing autoload configuration.
-
-2. **typed-rule-interface** — An interface like `ValidationRuleInterface` defines `validate(mixed $value): ValidationResult` with full PHP type declarations. The `ValidationResult` is a typed object (readonly class or record-like structure) containing success/failure state, error details, and the validated value. Custom rules implement this interface. Reject loosely-typed contracts using arrays or untyped returns.
-
-3. **enum-error-codes** — Error identification uses a backed enum (e.g., `enum ErrorCode: string { case Required = 'required'; case MinLength = 'min_length'; ... }`). Validation failures reference enum cases rather than raw strings. This enables consumers to match on error codes programmatically (`match ($error->code) { ... }`). Reject string-based error codes.
-
-4. **phpstan-level-9-config** — A `phpstan.neon.dist` file exists with `level: 9` (or `level: max`) and `paths: [src]`. The configuration may include additional strict rules or PHPStan extensions. The existence of this config at level 9 implies the source code is designed with precise enough types to pass strict analysis. Reject configurations below level 8.
-
-5. **phpunit-test-with-data-providers** — Test classes use `#[DataProvider('validInputProvider')]` (PHP 8 attribute syntax) or `@dataProvider` annotations for parameterized tests. Data providers return arrays of `[input, expectedResult]` tuples covering valid values, invalid values, boundary values, and type edge cases. A `phpunit.xml.dist` file configures test suites and coverage. Reject test files with duplicated test methods that differ only in input data.

package/workflows/skills/php-best-practices/evals/evals.json

@@ -1,64 +0,0 @@
-[
-  {
-    "id": "php-typed-service-implementation",
-    "prompt": "Design a typed PHP 8.4 service for managing product inventory in an e-commerce system. Use readonly classes for value objects (Money, Quantity, ProductId), enums for product status, property hooks for computed properties, and strict interface contracts. Include proper error handling with specific exception hierarchies and a repository interface for persistence.",
-    "assertions": [
-      {
-        "id": "strict-types-and-readonly-classes",
-        "description": "Every file includes declare(strict_types=1). Value objects (Money, Quantity, ProductId) are readonly classes with typed constructor-promoted properties. No public mutable properties on value objects.",
-        "weight": 1.0
-      },
-      {
-        "id": "enum-driven-domain-modeling",
-        "description": "Product status uses a backed enum (e.g., enum ProductStatus: string) with cases like Active, Discontinued, OutOfStock. The enum is used in type hints, match expressions, and domain logic — not string constants or integer flags.",
-        "weight": 1.0
-      },
-      {
-        "id": "property-hooks-usage",
-        "description": "At least one class uses PHP 8.4 property hooks for computed or validated properties (e.g., a get hook for formatted price or a set hook for quantity validation). This replaces traditional getter/setter boilerplate.",
-        "weight": 1.0
-      },
-      {
-        "id": "interface-based-contracts",
-        "description": "The repository layer is defined as an interface (e.g., ProductRepositoryInterface) with typed method signatures. The service depends on the interface, not the concrete implementation, enabling dependency injection and test doubles.",
-        "weight": 1.0
-      },
-      {
-        "id": "specific-exception-hierarchy",
-        "description": "Error handling uses domain-specific exceptions (e.g., ProductNotFoundException, InsufficientStockException) extending a base domain exception. Exceptions include contextual data (the product ID that wasn't found). No bare Exception catches in business logic.",
-        "weight": 1.0
-      }
-    ]
-  },
-  {
-    "id": "php-composer-package-design",
-    "prompt": "Create a Composer package for a PHP 8.4 validation library. The package should use PSR-4 autoloading, include typed validation rules with enum-based error codes, support custom rule creation through interfaces, and have a complete CI-ready test setup with PHPUnit and PHPStan at level 9. Show composer.json, directory structure, example rules, and test configuration.",
-    "assertions": [
-      {
-        "id": "psr4-autoloading-config",
-        "description": "The composer.json uses PSR-4 autoloading with a proper namespace mapping (e.g., Vendor\\Validation\\ -> src/). Dev dependencies include phpunit/phpunit and phpstan/phpstan. No require/include statements for class loading.",
-        "weight": 1.0
-      },
-      {
-        "id": "typed-rule-interface",
-        "description": "A ValidationRule interface defines the contract with typed parameters and return types (e.g., validate(mixed $value): ValidationResult). Custom rules implement this interface. The interface enables polymorphic composition of rule chains.",
-        "weight": 1.0
-      },
-      {
-        "id": "enum-error-codes",
-        "description": "Validation error codes use a backed enum (e.g., enum ErrorCode: string) rather than string constants. Error results include the enum value, a human-readable message, and the field path. This enables programmatic error handling by consumers.",
-        "weight": 1.0
-      },
-      {
-        "id": "phpstan-level-9-config",
-        "description": "A phpstan.neon or phpstan.neon.dist file configures PHPStan at level 9 (or max) with paths pointing to the src/ directory. The configuration demonstrates that the code is designed to pass strict static analysis.",
-        "weight": 1.0
-      },
-      {
-        "id": "phpunit-test-with-data-providers",
-        "description": "Tests use PHPUnit with data providers for parameterized validation scenarios (valid input, invalid input, edge cases). Tests cover the rule interface contract, built-in rules, and error code correctness. A phpunit.xml.dist file configures the test suite.",
-        "weight": 1.0
-      }
-    ]
-  }
-]