@cubis/foundry 0.3.71 → 0.3.73

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

@@ -1,21 +1,166 @@
 ---
 name: testing-patterns
-description: "Compatibility alias skill. Deprecated: use test-master."
+description: Design test strategies with unit, integration, and e2e testing. Apply TDD, mocking, fixtures, coverage analysis, and test architecture best practices.
+license: Apache-2.0
 metadata:
-  deprecated: true
-  replaced_by: test-master
-  removal_target: v0.6.0
+  author: cubis-foundry
+  version: "3.0"
+compatibility: Claude Code, Codex, GitHub Copilot, Gemini CLI
 ---
 
 # Testing Patterns
 
-## Compatibility Alias
+## Purpose
 
-This skill is deprecated and kept for backward compatibility.
+Guide test strategy, structure, and implementation across all testing levels. Covers unit, integration, and e2e testing patterns, TDD methodology, mocking strategies, and test architecture.
 
-Use `test-master` as the canonical skill.
+## When to Use
 
-## Migration
+- Writing tests for new features or bug fixes
+- Designing a test strategy for a new project or module
+- Debugging flaky or slow tests
+- Reviewing test quality and coverage gaps
+- Setting up test infrastructure (runners, fixtures, mocks)
+- Deciding what level of testing is appropriate
 
-1. Replace direct references to `testing-patterns` with `test-master`.
-2. Apply the full workflow from `test-master` for new work.
+## Instructions
+
+### Step 1 — Choose the Right Test Level
+
+| Level       | Tests                        | Speed    | Confidence                   | When to Use                                        |
+| ----------- | ---------------------------- | -------- | ---------------------------- | -------------------------------------------------- |
+| Unit        | Individual functions/classes | ms       | Logic correctness            | Pure logic, calculations, transformers             |
+| Integration | Module boundaries            | 100ms–1s | Components work together     | API routes, database queries, service interactions |
+| E2E         | Full user flows              | 5–30s    | System works as user expects | Critical paths (signup, checkout, deploy)          |
+
+**Testing Trophy** (preferred distribution):
+
+- Many integration tests (highest ROI)
+- Some unit tests (fast logic verification)
+- Few e2e tests (critical paths only)
+- Static analysis as the foundation (TypeScript, linting)
+
+### Step 2 — Write Effective Tests
+
+**Structure every test as Arrange → Act → Assert**:
+
+```typescript
+test("calculates total with tax", () => {
+  // Arrange
+  const items = [{ price: 100 }, { price: 200 }];
+  const taxRate = 0.1;
+
+  // Act
+  const total = calculateTotal(items, taxRate);
+
+  // Assert
+  expect(total).toBe(330);
+});
+```
+
+**Naming**: Use natural language that describes the behavior:
+
+- DO: `"returns empty array when no items match filter"`
+- DON'T: `"test filter"` or `"test1"`
+
+**One assertion per behavior** (not per test):
+
+- One test can have multiple `expect()` calls if they verify the same behavior
+- Split separate behaviors into separate tests
+
+### Step 3 — Mock Strategically
+
+**Mock at boundaries, not everywhere**:
+
+- Mock: external APIs, databases, file system, time, randomness
+- Don't mock: your own code, simple utilities, data transformations
+
+**Mock patterns**:
+
+```typescript
+// Dependency injection (preferred)
+function createUserService(db: Database) {
+  return { getUser: (id) => db.query("SELECT...", [id]) };
+}
+
+// Module mocking (when DI not available)
+vi.mock("./database", () => ({
+  query: vi.fn().mockResolvedValue([{ id: 1, name: "Alice" }]),
+}));
+```
+
+**Avoid**:
+
+- Mocking implementation details (private methods, internal state)
+- Over-mocking (if you mock everything, you're testing nothing)
+- Snapshot tests for behavior (only for serialized output like HTML)
+
+### Step 4 — Handle Test Data
+
+**Factories over fixtures**:
+
+```typescript
+function createUser(overrides = {}) {
+  return {
+    id: crypto.randomUUID(),
+    name: "Test User",
+    email: "test@example.com",
+    role: "user",
+    ...overrides,
+  };
+}
+
+// Usage
+const admin = createUser({ role: "admin" });
+```
+
+**Test isolation**:
+
+- Each test creates its own data (no shared mutable state)
+- Clean up after integration tests (database, files)
+- Use transactions for database tests (rollback after each test)
+
+### Step 5 — Fix Common Test Problems
+
+**Flaky tests**:
+
+- Remove timing dependencies (`setTimeout`, `sleep`)
+- Use deterministic data (no `Math.random()` without seeding)
+- Await all async operations properly
+- Isolate external dependencies (mock network, use test databases)
+
+**Slow tests**:
+
+- Run in parallel when tests are isolated
+- Use in-memory databases for integration tests
+- Minimize e2e tests — push logic down to unit/integration
+- Profile and fix the slowest 10% first
+
+**Brittle tests**:
+
+- Test behavior, not implementation
+- Use accessible queries in UI tests (role, label — not CSS selectors)
+- Avoid testing framework internals
+
+## Output Format
+
+```
+## Test Strategy
+[approach and reasoning for test level choices]
+
+## Tests
+[test code organized by describe blocks]
+
+## Coverage Notes
+[what's tested, what's intentionally not tested, and why]
+```
+
+## Examples
+
+**User**: "Write tests for this user registration function"
+
+**Response approach**: Unit tests for validation logic (email format, password strength). Integration test for the full registration flow (validate → hash password → insert DB → send email). Mock the email service and database. Test edge cases (duplicate email, weak password, missing fields).
+
+**User**: "Our test suite takes 20 minutes, help us speed it up"
+
+**Response approach**: Profile the slowest tests. Look for unnecessary e2e tests that could be integration. Check for missing parallelization. Identify shared state causing serial execution. Suggest in-memory database for integration tests.

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

@@ -1,63 +1,72 @@
 ````markdown
 ---
 inclusion: manual
-name: "typescript-pro"
-description: "Use for TypeScript architecture and implementation with TS 5.9+ production baselines and TS 6/7 transition readiness."
+name: typescript-pro
+description: "Use for TypeScript architecture and implementation with TS 5.9+ production baselines and TS 6/7 transition readiness. Use when designing type-safe APIs, refactoring to strict TypeScript, reducing type regressions in monorepos, or preparing for TS 6/7 behavior shifts."
 license: MIT
 metadata:
-  version: "2.0.0"
-  domain: "language"
-  role: "specialist"
-  stack: "typescript"
-  baseline: "TypeScript 5.9 stable"
-  transition: "TypeScript 6 compatibility prep"
+  author: cubis-foundry
+  version: "3.0"
+compatibility: Claude Code, Codex, GitHub Copilot
 ---
 
 # TypeScript Pro
 
-## When to use
+## Purpose
+
+Language-layer specialist for TypeScript architecture, type design, and production implementation. Provides the type-system foundation before loading framework skills like `nextjs-developer` or `nestjs-expert`. Covers strict compiler configuration, domain modeling with discriminated unions, generic patterns, module structure, and tooling selection for TS 5.9+ codebases with awareness of TS 6/7 transitions.
+
+## When to Use
 
 - Designing type-safe APIs and shared contracts.
 - Refactoring codebases to strict TypeScript.
 - Reducing type regressions in monorepos.
 - Preparing for upcoming TS 6/7 behavior shifts.
+- Acting as the language-layer foundation before loading framework skills.
 
-## Core workflow
+## Instructions
 
-1. Confirm runtime and module target (Node, browser, edge).
-2. Lock strict compiler baseline before feature work.
-3. Model domain types first, then implement behavior.
-4. Keep runtime validation where untrusted input enters.
-5. Run type checks and targeted tests before finishing.
+1. Confirm runtime and module target (Node, browser, edge) because compiler settings and polyfill requirements differ.
+2. Lock strict compiler baseline (`strict: true`) before feature work because weak defaults hide implicit `any`.
+3. Model domain types first with discriminated unions and `satisfies`/`as const`, then implement behavior — type design is the primary design feedback loop.
+4. Use `unknown` over `any` at boundaries because `any` silently defeats type checking.
+5. Narrow with type guards (`x is T`) instead of `as` assertions because guards provide runtime safety while assertions only silence the compiler.
+6. Encode state machines with discriminated unions and exhaustive `switch`/`assertNever` checks because unhandled variants become compile errors.
+7. Use schema validation (Zod/Valibot) for external input because runtime validation must match declared types at system boundaries.
+8. Keep public API types stable and explicit — do not rely on inferred return types for exported functions.
+9. Use project references (`composite: true` + `references`) for large repos because they enable incremental builds and cross-package type awareness.
+10. Keep barrel exports (`index.ts`) thin — re-export only the public API because deep barrels cause circular dependency pain and slow IDE resolution.
+11. Use `import type` for type-only imports because it prevents runtime import of type-only modules and improves tree-shaking.
+12. Use constrained generics to express input/output relationships — do not exceed 3 type parameters without splitting the abstraction.
+13. Prefer mapped types and template literal types for systematic type transformations — extract complex conditional types into named types for readability.
+14. Run `tsc --noEmit` in CI separately from bundling because type errors should fail CI even when the bundler succeeds.
+15. Use Biome or ESLint + `typescript-eslint` for linting; `tsup` for library builds; Vitest for tests with native TS support.
+16. Do not use library-facing `any` — it poisons downstream callers.
+17. Do not use broad `as` casts to silence errors — treat type errors as design feedback, not noise.
+18. Do not mix runtime and type-only imports carelessly — use `import type` consistently.
 
-## Baseline standards
+## Output Format
 
-- Use `strict: true` and avoid opt-outs unless documented.
-- Prefer `unknown` over `any` at boundaries.
-- Use `satisfies` and `as const` for safer inference.
-- Keep public API types stable and explicit.
-- Use project references for large repos.
+Provide type definitions, implementation code, and compiler configuration as fenced TypeScript code blocks. Include `tsconfig.json` excerpts when configuration changes are part of the solution. Explain type-level design decisions inline with brief comments.
 
-## Implementation guidance
+## References
 
-- Encode state with discriminated unions.
-- Narrow with type guards instead of assertions.
-- Keep utility types readable; avoid type-level obfuscation.
-- Use schema validation (zod/valibot/etc.) for external input.
-- Treat type errors as design feedback, not noise.
+| File                           | Load when                                                                    |
+| ------------------------------ | ---------------------------------------------------------------------------- |
+| `references/configuration.md`  | `tsconfig`, strictness, module targets, or project references need detail.   |
+| `references/advanced-types.md` | Generics, conditional types, mapped types, or template literals are central. |
+| `references/type-guards.md`    | Narrowing and runtime-safe type refinement need detail.                      |
+| `references/utility-types.md`  | Utility-type composition or shared helper types are in scope.                |
+| `references/patterns.md`       | Type-safe architecture patterns or public API design needs detail.           |
 
-## Avoid
+## Scripts
 
-- Library-facing `any`.
-- Broad `as` casts to silence errors.
-- Hidden implicit `any` from weak tsconfig defaults.
-- Mixing runtime and type-only imports carelessly.
+No helper scripts are required for this skill right now. Keep execution in `SKILL.md` and `references/` unless repeated automation becomes necessary.
 
-## Reference files
+## Examples
 
-- `references/configuration.md`
-- `references/advanced-types.md`
-- `references/type-guards.md`
-- `references/utility-types.md`
-- `references/patterns.md`
+- "Refactor this module to use strict TypeScript with discriminated unions for state"
+- "Design a type-safe event system with template literal types"
+- "Set up tsconfig project references for our monorepo"
+- "Replace these `any` casts with proper type narrowing"
 ````

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

@@ -1,60 +1,69 @@
 ---
-name: "typescript-pro"
-description: "Use for TypeScript architecture and implementation with TS 5.9+ production baselines and TS 6/7 transition readiness."
+name: typescript-pro
+description: "Use for TypeScript architecture and implementation with TS 5.9+ production baselines and TS 6/7 transition readiness. Use when designing type-safe APIs, refactoring to strict TypeScript, reducing type regressions in monorepos, or preparing for TS 6/7 behavior shifts."
 license: MIT
 metadata:
-  version: "2.0.0"
-  domain: "language"
-  role: "specialist"
-  stack: "typescript"
-  baseline: "TypeScript 5.9 stable"
-  transition: "TypeScript 6 compatibility prep"
+  author: cubis-foundry
+  version: "3.0"
+compatibility: Claude Code, Codex, GitHub Copilot
 ---
 
 # TypeScript Pro
 
-## When to use
+## Purpose
+
+Language-layer specialist for TypeScript architecture, type design, and production implementation. Provides the type-system foundation before loading framework skills like `nextjs-developer` or `nestjs-expert`. Covers strict compiler configuration, domain modeling with discriminated unions, generic patterns, module structure, and tooling selection for TS 5.9+ codebases with awareness of TS 6/7 transitions.
+
+## When to Use
 
 - Designing type-safe APIs and shared contracts.
 - Refactoring codebases to strict TypeScript.
 - Reducing type regressions in monorepos.
 - Preparing for upcoming TS 6/7 behavior shifts.
+- Acting as the language-layer foundation before loading framework skills.
 
-## Core workflow
+## Instructions
 
-1. Confirm runtime and module target (Node, browser, edge).
-2. Lock strict compiler baseline before feature work.
-3. Model domain types first, then implement behavior.
-4. Keep runtime validation where untrusted input enters.
-5. Run type checks and targeted tests before finishing.
+1. Confirm runtime and module target (Node, browser, edge) because compiler settings and polyfill requirements differ.
+2. Lock strict compiler baseline (`strict: true`) before feature work because weak defaults hide implicit `any`.
+3. Model domain types first with discriminated unions and `satisfies`/`as const`, then implement behavior — type design is the primary design feedback loop.
+4. Use `unknown` over `any` at boundaries because `any` silently defeats type checking.
+5. Narrow with type guards (`x is T`) instead of `as` assertions because guards provide runtime safety while assertions only silence the compiler.
+6. Encode state machines with discriminated unions and exhaustive `switch`/`assertNever` checks because unhandled variants become compile errors.
+7. Use schema validation (Zod/Valibot) for external input because runtime validation must match declared types at system boundaries.
+8. Keep public API types stable and explicit — do not rely on inferred return types for exported functions.
+9. Use project references (`composite: true` + `references`) for large repos because they enable incremental builds and cross-package type awareness.
+10. Keep barrel exports (`index.ts`) thin — re-export only the public API because deep barrels cause circular dependency pain and slow IDE resolution.
+11. Use `import type` for type-only imports because it prevents runtime import of type-only modules and improves tree-shaking.
+12. Use constrained generics to express input/output relationships — do not exceed 3 type parameters without splitting the abstraction.
+13. Prefer mapped types and template literal types for systematic type transformations — extract complex conditional types into named types for readability.
+14. Run `tsc --noEmit` in CI separately from bundling because type errors should fail CI even when the bundler succeeds.
+15. Use Biome or ESLint + `typescript-eslint` for linting; `tsup` for library builds; Vitest for tests with native TS support.
+16. Do not use library-facing `any` — it poisons downstream callers.
+17. Do not use broad `as` casts to silence errors — treat type errors as design feedback, not noise.
+18. Do not mix runtime and type-only imports carelessly — use `import type` consistently.
 
-## Baseline standards
+## Output Format
 
-- Use `strict: true` and avoid opt-outs unless documented.
-- Prefer `unknown` over `any` at boundaries.
-- Use `satisfies` and `as const` for safer inference.
-- Keep public API types stable and explicit.
-- Use project references for large repos.
+Provide type definitions, implementation code, and compiler configuration as fenced TypeScript code blocks. Include `tsconfig.json` excerpts when configuration changes are part of the solution. Explain type-level design decisions inline with brief comments.
 
-## Implementation guidance
+## References
 
-- Encode state with discriminated unions.
-- Narrow with type guards instead of assertions.
-- Keep utility types readable; avoid type-level obfuscation.
-- Use schema validation (zod/valibot/etc.) for external input.
-- Treat type errors as design feedback, not noise.
+| File                           | Load when                                                                    |
+| ------------------------------ | ---------------------------------------------------------------------------- |
+| `references/configuration.md`  | `tsconfig`, strictness, module targets, or project references need detail.   |
+| `references/advanced-types.md` | Generics, conditional types, mapped types, or template literals are central. |
+| `references/type-guards.md`    | Narrowing and runtime-safe type refinement need detail.                      |
+| `references/utility-types.md`  | Utility-type composition or shared helper types are in scope.                |
+| `references/patterns.md`       | Type-safe architecture patterns or public API design needs detail.           |
 
-## Avoid
+## Scripts
 
-- Library-facing `any`.
-- Broad `as` casts to silence errors.
-- Hidden implicit `any` from weak tsconfig defaults.
-- Mixing runtime and type-only imports carelessly.
+No helper scripts are required for this skill right now. Keep execution in `SKILL.md` and `references/` unless repeated automation becomes necessary.
 
-## Reference files
+## Examples
 
-- `references/configuration.md`
-- `references/advanced-types.md`
-- `references/type-guards.md`
-- `references/utility-types.md`
-- `references/patterns.md`
+- "Refactor this module to use strict TypeScript with discriminated unions for state"
+- "Design a type-safe event system with template literal types"
+- "Set up tsconfig project references for our monorepo"
+- "Replace these `any` casts with proper type narrowing"

package/workflows/powers/vitess/POWER.md

@@ -0,0 +1,67 @@
+````markdown
+---
+inclusion: manual
+name: vitess
+description: "Use when the task is specifically Vitess or Vitess-backed MySQL platforms: shard-key design, vindexes, resharding, query-routing constraints, Online DDL, and operational tradeoffs for horizontally scaled MySQL."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "3.0"
+compatibility: Claude Code, Codex, GitHub Copilot
+---
+
+# Vitess
+
+## Purpose
+
+Use when the task is specifically Vitess or Vitess-backed MySQL platforms: shard-key design, vindexes, resharding, query-routing constraints, Online DDL, and operational tradeoffs for horizontally scaled MySQL.
+
+## When to Use
+
+- The engine is Vitess or a Vitess-backed managed MySQL platform.
+- The problem depends on shard keys, vindexes, resharding, query routing, or Online DDL behavior.
+- You need guidance for scaling MySQL horizontally rather than treating it like a single-node database.
+
+## Instructions
+
+1. Confirm whether the task is schema design, query shape, shard-key choice, or operational scaling.
+2. Make entity ownership and routing key choice explicit before optimizing anything else.
+3. Check whether queries respect shard boundaries and Vitess execution constraints.
+4. Plan Online DDL, resharding, and rollback with operational evidence.
+5. Report the coupling, fan-out, and migration risks that remain after the change.
+
+### Baseline standards
+
+- Choose shard keys from access patterns and ownership, not convenience.
+- Minimize cross-shard fan-out and hidden coordination costs.
+- Treat Online DDL and resharding as operational programs, not single commands.
+- Keep query routing constraints visible to application teams.
+
+### Constraints
+
+- Avoid designing as if the database were a single-node MySQL instance.
+- Avoid late shard-key decisions after application coupling hardens.
+- Avoid cross-shard joins or transactions without explicit justification.
+- Avoid treating Vitess complexity as free scale.
+
+## Output Format
+
+Provide implementation guidance, code examples, and configuration as appropriate to the task.
+
+## References
+
+Load on demand. Do not preload all reference files.
+
+| File | Load when |
+| --- | --- |
+| `references/vitess-checklist.md` | You need deeper Vitess guidance for shard keys, vindexes, query routing, resharding, and Online DDL tradeoffs. |
+
+## Scripts
+
+No helper scripts are required for this skill right now. Keep execution in `SKILL.md` and `references/` unless repeated automation becomes necessary.
+
+## Examples
+
+- "Help me with vitess best practices in this project"
+- "Review my vitess implementation for issues"
+````

package/workflows/powers/vitess/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: vitess
+description: "Use when the task is specifically Vitess or Vitess-backed MySQL platforms: shard-key design, vindexes, resharding, query-routing constraints, Online DDL, and operational tradeoffs for horizontally scaled MySQL."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "3.0"
+compatibility: Claude Code, Codex, GitHub Copilot
+---
+
+# Vitess
+
+## Purpose
+
+Use when the task is specifically Vitess or Vitess-backed MySQL platforms: shard-key design, vindexes, resharding, query-routing constraints, Online DDL, and operational tradeoffs for horizontally scaled MySQL.
+
+## When to Use
+
+- The engine is Vitess or a Vitess-backed managed MySQL platform.
+- The problem depends on shard keys, vindexes, resharding, query routing, or Online DDL behavior.
+- You need guidance for scaling MySQL horizontally rather than treating it like a single-node database.
+
+## Instructions
+
+1. Confirm whether the task is schema design, query shape, shard-key choice, or operational scaling.
+2. Make entity ownership and routing key choice explicit before optimizing anything else.
+3. Check whether queries respect shard boundaries and Vitess execution constraints.
+4. Plan Online DDL, resharding, and rollback with operational evidence.
+5. Report the coupling, fan-out, and migration risks that remain after the change.
+
+### Baseline standards
+
+- Choose shard keys from access patterns and ownership, not convenience.
+- Minimize cross-shard fan-out and hidden coordination costs.
+- Treat Online DDL and resharding as operational programs, not single commands.
+- Keep query routing constraints visible to application teams.
+
+### Constraints
+
+- Avoid designing as if the database were a single-node MySQL instance.
+- Avoid late shard-key decisions after application coupling hardens.
+- Avoid cross-shard joins or transactions without explicit justification.
+- Avoid treating Vitess complexity as free scale.
+
+## Output Format
+
+Provide implementation guidance, code examples, and configuration as appropriate to the task.
+
+## References
+
+Load on demand. Do not preload all reference files.
+
+| File | Load when |
+| --- | --- |
+| `references/vitess-checklist.md` | You need deeper Vitess guidance for shard keys, vindexes, query routing, resharding, and Online DDL tradeoffs. |
+
+## Scripts
+
+No helper scripts are required for this skill right now. Keep execution in `SKILL.md` and `references/` unless repeated automation becomes necessary.
+
+## Examples
+
+- "Help me with vitess best practices in this project"
+- "Review my vitess implementation for issues"

package/workflows/powers/vitess/references/vitess-checklist.md

@@ -0,0 +1,19 @@
+# Vitess Checklist
+
+Load this when sharded MySQL behavior is the real problem.
+
+## Routing and ownership
+
+- Choose shard keys from access patterns and ownership boundaries.
+- Keep cross-shard fan-out visible and minimized.
+- Treat vindexes as application-shaping decisions, not low-level detail.
+
+## Query behavior
+
+- Check whether queries respect shard routing constraints.
+- Avoid assuming single-node MySQL semantics when the topology is distributed.
+
+## Operations
+
+- Make Online DDL, resharding, and rollback operationally explicit.
+- Keep coupling and migration risk visible to application teams.