@cubis/foundry 0.3.66 → 0.3.68

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/database-design/references/schema-migration-checklist.md

@@ -0,0 +1,26 @@
+# Schema And Migration Checklist
+
+Load this when schema work needs a stricter implementation checklist.
+
+## Model shape
+
+- Define entities, ownership, lifecycle, and access patterns first.
+- Choose relational vs document structure deliberately.
+- Treat indexes as part of the model, not a cleanup pass.
+
+## Keys and pagination
+
+- Choose stable keys that fit access paths and operational constraints.
+- Design pagination from real sort and filter patterns.
+- Re-check uniqueness, foreign keys, and validation rules explicitly.
+
+## Migration posture
+
+- Plan rollout, backfill, and rollback before implementation.
+- Stage destructive or high-risk changes instead of shipping them all at once.
+- Keep blast radius visible for large tables or hot write paths.
+
+## Coupling
+
+- Avoid persistence models that leak too directly into public contracts.
+- Keep ORM convenience from driving the whole schema.

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/database-optimizer/SKILL.md

@@ -1,81 +1,66 @@
 ---
-name: "database-optimizer"
-description: "Use for system-level database performance triage across engines: bottleneck analysis, indexing strategy, config tuning, partitioning, and lock contention."
+name: database-optimizer
+description: "Use for database performance triage across engines: query-plan analysis, indexing changes, wait and contention diagnosis, config tuning, and safe before/after validation."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "3.0"
+compatibility: Claude Code, Codex, GitHub Copilot
 ---
 
-
 # Database Optimizer
 
-## Overview
-
-Senior database optimizer with expertise in performance tuning, query optimization, and scalability across multiple database systems.
-
-## Role Definition
+## Purpose
 
-You are a senior database performance engineer with 10+ years of experience optimizing high-traffic databases. You specialize in PostgreSQL and MySQL optimization, execution plan analysis, strategic indexing, and achieving sub-100ms query performance at scale.
+Use for database performance triage across engines: query-plan analysis, indexing changes, wait and contention diagnosis, config tuning, and safe before/after validation.
 
-## When to Use This Skill
+## When to Use
 
-- Analyzing slow queries and execution plans
-- Designing optimal index strategies
-- Tuning database configuration parameters
-- Optimizing schema design and partitioning
-- Reducing lock contention and deadlocks
-- Improving cache hit rates and memory usage
+- Investigating slow queries, bad plans, lock contention, or throughput collapse.
+- Choosing targeted indexing or query-shape fixes.
+- Deciding whether the bottleneck is query logic, schema, config, or concurrency.
+- Validating performance changes with before/after evidence.
 
-## Core Workflow
+## Instructions
 
-1. **Analyze Performance** - Review slow queries, execution plans, system metrics
-2. **Identify Bottlenecks** - Find inefficient queries, missing indexes, config issues
-3. **Design Solutions** - Create index strategies, query rewrites, schema improvements
-4. **Implement Changes** - Apply optimizations incrementally with monitoring
-5. **Validate Results** - Measure improvements, ensure stability, document changes
+1. Establish the real symptom with timings, plans, waits, or metrics.
+2. Identify whether the bottleneck is query shape, indexing, contention, config, or workload pattern.
+3. Choose the smallest safe optimization with explicit tradeoffs.
+4. Apply one high-signal change at a time when isolating a root cause.
+5. Re-measure and report whether the change actually improved the bottleneck.
 
-## Available Steering Files
+### Baseline standards
 
-Load detailed guidance on-demand:
+- Explain before optimizing.
+- Measure before and after every proposed change.
+- Account for write amplification and operational cost of indexes.
+- Include rollback and monitoring in the optimization plan.
+- Prefer correctness and predictable operations over benchmark vanity.
 
-| Topic                 | Reference                         | Load When                               |
-| --------------------- | --------------------------------- | --------------------------------------- |
-| Query Optimization    | `references/query-optimization.md`  | Analyzing slow queries, execution plans |
-| Index Strategies      | `references/index-strategies.md`    | Designing indexes, covering indexes     |
-| PostgreSQL Tuning     | `references/postgresql-tuning.md`   | PostgreSQL-specific optimizations       |
-| MySQL Tuning          | `references/mysql-tuning.md`        | MySQL-specific optimizations            |
-| Monitoring & Analysis | `references/monitoring-analysis.md` | Performance metrics, diagnostics        |
+### Constraints
 
-## Constraints
+- Avoid blind config churn.
+- Avoid index additions without real predicate evidence.
+- Avoid query rewrites that ignore semantics or maintenance cost.
+- Avoid treating every slowdown as a single-query problem.
 
-### MUST DO
+## Output Format
 
-- Analyze EXPLAIN plans before optimizing
-- Measure performance before and after changes
-- Create indexes strategically (avoid over-indexing)
-- Test changes in non-production first
-- Document all optimization decisions
-- Monitor impact on write performance
-- Consider replication lag for distributed systems
+Provide implementation guidance, code examples, and configuration as appropriate to the task.
 
-### MUST NOT DO
+## References
 
-- Apply optimizations without measurement
-- Create redundant or unused indexes
-- Skip execution plan analysis
-- Ignore write performance impact
-- Make multiple changes simultaneously
-- Optimize without understanding query patterns
-- Neglect statistics updates (ANALYZE/VACUUM)
+Load on demand. Do not preload all reference files.
 
-## Output Templates
+| File | Load when |
+| --- | --- |
+| `references/query-triage-checklist.md` | You need a deeper performance triage checklist for plans, waits, index tradeoffs, rollback, and before/after evidence. |
 
-When optimizing database performance, provide:
+## Scripts
 
-1. Performance analysis with baseline metrics
-2. Identified bottlenecks and root causes
-3. Optimization strategy with specific changes
-4. Implementation SQL/config changes
-5. Validation queries to measure improvement
-6. Monitoring recommendations
+No helper scripts are required for this skill right now. Keep execution in `SKILL.md` and `references/` unless repeated automation becomes necessary.
 
-## Knowledge Reference
+## Examples
 
-PostgreSQL (pg_stat_statements, EXPLAIN ANALYZE, indexes, VACUUM, partitioning), MySQL (slow query log, EXPLAIN, InnoDB, query cache), query optimization, index design, execution plans, configuration tuning, replication, sharding, caching strategies
+- "Help me with database optimizer best practices in this project"
+- "Review my database optimizer implementation for issues"

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/database-optimizer/references/query-triage-checklist.md

@@ -0,0 +1,26 @@
+# Query Triage Checklist
+
+Load this when database performance work needs a deeper optimization frame.
+
+## Establish the symptom
+
+- Capture timings, plans, waits, lock signals, or saturation evidence first.
+- Confirm whether the bottleneck is query shape, index choice, contention, config, or workload pattern.
+
+## Change selection
+
+- Prefer the smallest safe change with the clearest expected effect.
+- Separate read latency fixes from write amplification or operational tradeoffs.
+- Keep semantics intact while rewriting queries.
+
+## Validation
+
+- Measure before and after every proposed change.
+- Re-check hot paths, secondary queries, and concurrency side effects.
+- Keep rollback and monitoring in the plan.
+
+## Anti-patterns
+
+- No blind config churn.
+- No index additions without predicate evidence.
+- No single-query tunnel vision when workload shape is the real problem.

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/database-skills/SKILL.md

@@ -1,102 +1,68 @@
 ---
 name: database-skills
-description: Unified database skill hub with engine-specific packs for PostgreSQL, MySQL, Vitess, Neki, MongoDB (Mongoose), SQLite, Supabase, and Redis.
-allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+description: "Use as the primary database hub for engine or platform choice, schema-vs-tuning routing, access-layer triage, migration safety framing, and database task triage before deeper engine, platform, or ORM specialists."
+license: MIT
 metadata:
-  version: "2.0.0"
-  domain: data
-  triggers: database, sql, postgres, mysql, vitess, neki, mongodb, mongoose, sqlite, supabase, redis, schema, migration, index, query, performance, pagination, replication, pooling, sharding, cache
+  author: cubis-foundry
+  version: "3.0"
+compatibility: Claude Code, Codex, GitHub Copilot
 ---
 
-# Database Skills Hub
+# Database Skills
 
-Use this as the primary database hub. Keep `database-design`, `database-optimizer`, and `drift-flutter` available for specialized/legacy-compatible flows. Load the target engine's `SKILL.md` from `skills/<engine>/`, then load relevant `references/*` files.
+## Purpose
 
-## Engine selection
+Use as the primary database hub for engine or platform choice, schema-vs-tuning routing, access-layer triage, migration safety framing, and database task triage before deeper engine, platform, or ORM specialists.
 
-| Situation | Engine |
+## When to Use
+
+- Choosing the right database path before implementation dives deep.
+- Routing a task toward schema design, optimization, or engine-specific work.
+- Planning migrations, indexing, query behavior, and operational safety at a high level.
+- Reviewing whether a data problem is really engine choice, schema shape, or query behavior.
+
+## Instructions
+
+1. Clarify workload shape, consistency needs, scale, and operational model.
+2. Decide whether the task is engine choice, schema design, or performance triage.
+3. Choose the narrowest next specialist: `database-design` or `database-optimizer`.
+4. Keep migration risk, rollback, and blast radius visible from the start.
+5. Escalate to the exact engine or platform specialist only when it is known and materially affects the decision: `postgres`, `mysql`, `sqlite`, `mongodb`, `redis`, `supabase`, `firebase`, `vitess`, or `neki`.
+6. Add `drizzle-expert` only when the TypeScript access layer or drizzle-kit workflow is the real decision surface.
+
+### Baseline standards
+
+- Pick storage shape from workload and operations, not preference alone.
+- Treat indexes, migrations, and rollback as first-class design inputs.
+- Separate schema questions from tuning questions.
+- Load engine-specific guidance only when platform behavior or managed-product constraints actually matter.
+- Prefer evidence before recommending a new engine or data model.
+- Keep data safety and operational reversibility explicit.
+
+### Constraints
+
+- Avoid treating every database issue as a query-optimization problem.
+- Avoid recommending engine changes with no workload evidence.
+- Avoid planning destructive schema changes without rollback.
+- Avoid mixing schema design and tuning advice into one vague answer.
+
+## 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 |
 | --- | --- |
-| Relational OLTP, self-hosted or cloud | Postgres |
-| Relational OLTP, MySQL-compatible managed service | MySQL + Vitess (PlanetScale) |
-| Multi-tenant SaaS needing horizontal Postgres scale | Neki |
-| Document model, flexible schema | MongoDB |
-| Mobile / desktop / edge local storage | SQLite |
-| BaaS with built-in auth, storage & realtime | Supabase |
-| Caching, queues, leaderboards, pub/sub | Redis |
-
-## Structure
-
-```
-skills/
-  postgres/
-    SKILL.md
-    references/
-      schema-indexing.md       ← index types, composite, partial, INCLUDE
-      performance-ops.md       ← EXPLAIN, pg_stat_statements, VACUUM, autovacuum
-      migrations.md            ← zero-downtime DDL, expand/contract, tools
-      connection-pooling.md    ← PgBouncer, pool sizing, serverless patterns
-
-  mysql/
-    SKILL.md
-    references/
-      query-indexing.md        ← EXPLAIN, composite indexes, covering, seek pagination
-      locking-ddl.md           ← INSTANT/INPLACE/COPY, MDL, gh-ost, deadlocks
-      replication.md           ← binlog formats, GTID, lag monitoring, read routing
-
-  vitess/
-    SKILL.md
-    references/
-      sharding-routing.md      ← VSchema, vindexes, sequences, scatter queries
-      operational-safety.md    ← Online DDL strategies, migration lifecycle, VReplication
-
-  neki/
-    SKILL.md
-    references/
-      architecture.md          ← sharded Postgres architecture, pre-sharding checklist
-      operations.md            ← migration planning, validation, provisional pre-GA guidance
-
-  mongodb/
-    SKILL.md
-    references/
-      modeling.md              ← embed vs reference, compound indexes, explain(), pagination
-      mongoose-nestjs.md       ← repository pattern, lean reads, transactions, NestJS setup
-      aggregation.md           ← pipeline stages, $group, $lookup, $facet, performance
-
-  sqlite/
-    SKILL.md
-    references/
-      local-first.md           ← WAL mode, migration patterns, sync/conflict strategies
-      performance.md           ← EXPLAIN QUERY PLAN, indexes, batch writes, checkpoint tuning
-
-  supabase/
-    SKILL.md
-    references/
-      rls-auth.md              ← RLS policies, auth.uid(), index predicates, service_role
-      performance-operations.md ← query optimization, connection modes, pooler selection
-
-  redis/
-    SKILL.md
-    references/
-      data-modeling.md         ← data structure selection, key naming, TTL strategy
-      cache-patterns.md        ← pipelining, SCAN, rate limiting, leaderboards, invalidation
-      operations.md            ← memory management, eviction policies, latency diagnostics
-```
-
-## Required flow
-
-1. Read `references/LATEST_VERSIONS.md` before proposing version-specific behavior.
-2. Use engine selection table above to pick the target engine.
-3. Load the target engine `SKILL.md` and relevant `references/*` files — read the ones that match the task (indexing, migrations, replication, etc.).
-4. Provide an optimization or implementation plan that includes:
-   - specific change with rationale,
-   - indexing or schema decisions,
-   - migration safety (online vs offline),
-   - rollback path.
-5. For production-impacting changes, include blast-radius assessment and rollout stages.
-
-## Cross-engine performance checklist
-
-- **Indexing**: add indexes only for real predicates and sort patterns. Drop unused indexes — they penalize writes.
-- **Pagination**: prefer keyset/seek for deep or high-throughput pagination. Reserve offset for shallow interactive pages only.
-- **Measurement**: compare before/after plans with engine-native explain tooling (`EXPLAIN ANALYZE`, `VEXPLAIN`, `explain()`). Validate with realistic cardinality.
-- **Safety**: no destructive data/schema operations without explicit user confirmation. Always include rollback/recovery steps.
+| `references/engine-selection-and-routing.md` | You need a sharper routing aid for engine choice, escalation into schema vs tuning, and when to load exact engine specialists. |
+
+## 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 database skills best practices in this project"
+- "Review my database skills implementation for issues"

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/database-skills/references/engine-selection-and-routing.md

@@ -0,0 +1,30 @@
+# Engine Selection And Routing
+
+Load this when a database task needs routing before implementation depth.
+
+## First decision
+
+- Is the real task engine choice, schema design, or performance triage?
+- Do not jump to tuning when the workload or model is still unclear.
+
+## Engine escalation
+
+- `postgres`: relational depth, extensions, advanced indexing, managed Postgres behavior.
+- `mysql`: InnoDB behavior, Online DDL, replication-aware rollout.
+- `sqlite`: embedded, local-first, WAL, and constrained write concurrency.
+- `mongodb`: document boundaries, aggregation, shard-key decisions.
+- `redis`: cache, TTL, queue, rate-limit, in-memory coordination.
+- `supabase`: managed Postgres plus RLS, auth, storage, and platform policy.
+- `firebase`: Firestore or Realtime Database plus rules, auth, functions, storage, and emulator workflow.
+- `vitess`: sharded MySQL routing, vindexes, and Online DDL at scale.
+- `neki`: sharded Postgres assumptions and distributed Postgres constraints.
+
+## Access Layer Specialist
+
+- `drizzle-expert`: load when schema-as-code, drizzle-kit migrations, relations, or TypeScript database access ergonomics are primary. Pair it with the exact engine or platform skill instead of using it as a database hub.
+
+## Companion skill routing
+
+- `database-design` when entities, keys, relationships, migrations, and indexes are the main problem.
+- `database-optimizer` when the problem is plans, waits, contention, or throughput.
+- Add one language or framework skill only when query code or ORM integration is the active layer.

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/debugging-strategies/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: debugging-strategies
+description: "Use when isolating bugs, regressions, flaky tests, or cross-layer failures with an evidence-first reproduce, narrow, verify workflow."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "1.0"
+compatibility: Claude Code, Codex, GitHub Copilot
+---
+
+# Debugging Strategies
+
+## Purpose
+
+Use when isolating bugs, regressions, flaky tests, or cross-layer failures with an evidence-first reproduce, narrow, verify workflow.
+
+## When to Use
+
+- Reproducing and isolating a bug, regression, intermittent failure, or flaky test.
+- Narrowing a problem that crosses frontend, backend, database, or deployment boundaries.
+- Designing the smallest safe fix and the right regression proof.
+- Turning vague failure reports into a concrete root-cause investigation plan.
+
+## Instructions
+
+1. Lock down reproduction steps and expected-versus-actual behavior before changing code.
+2. Narrow the fault domain with logs, traces, feature flags, bisecting, or minimal reproductions.
+3. Instrument only enough to prove the hypothesis.
+4. Fix the smallest confirmed cause, not the loudest symptom.
+5. Leave behind regression proof and a short explanation of why the bug existed.
+
+### Baseline standards
+
+- Prefer evidence over intuition and one-variable changes over bundle fixes.
+- Separate symptom, trigger, root cause, and prevention.
+- Use the strongest artifact available: trace, stack, query plan, diff, or deterministic reproduction.
+- Check adjacent surfaces for the same class of bug after the first fix lands.
+- Remove temporary debugging code once the regression proof exists.
+
+### Constraints
+
+- Avoid making multiple speculative changes before you can reproduce the issue.
+- Avoid treating flaky behavior as random when a hidden dependency probably exists.
+- Avoid patching over production bugs with retries or timeouts before understanding the failure.
+- Avoid closing the bug without a clear verification path.
+
+## 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/reproduce-isolate-verify-checklist.md` | You need a deeper checklist for reproduction, narrowing the fault domain, instrumenting safely, regression-proofing, or handling flaky and cross-layer failures. |
+
+## 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 debugging strategies best practices in this project"
+- "Review my debugging strategies implementation for issues"

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/debugging-strategies/references/reproduce-isolate-verify-checklist.md

@@ -0,0 +1,42 @@
+# Reproduce, Isolate, Verify Checklist
+
+Use this when the bug is real but the shortest path to root cause is still unclear.
+
+## Reproduce
+
+- Capture exact steps, inputs, environment, and expected-versus-actual behavior.
+- Determine whether the bug is:
+  - consistent
+  - data-dependent
+  - environment-specific
+  - time or concurrency sensitive
+- Reduce the problem to the smallest reliable reproduction you can keep.
+
+## Isolate
+
+Move from broad to narrow:
+
+1. which boundary fails first
+2. which recent change could have shifted behavior
+3. which artifact proves the branch is wrong
+
+Useful tools by situation:
+
+- browser trace or devtools for UI failures
+- focused logs or request IDs for service failures
+- query plans for data slowdowns
+- `git bisect` for regressions with unknown starting points
+- targeted tests for turning a manual reproduction into an automated one
+
+## Hypothesis discipline
+
+- Write down one likely cause at a time.
+- Add the smallest instrumentation that can disprove it.
+- Revert or remove exploratory logging once the cause is known.
+
+## Fix and verify
+
+- Fix the confirmed cause, not just the outer symptom.
+- Add or update the smallest regression proof that would have caught it earlier.
+- Recheck adjacent cases with similar state, timing, or data-shape assumptions.
+- Record any residual risk if the full environment could not be reproduced locally.

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/deep-research/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: deep-research
+description: "Use when a task needs multi-round research rather than a quick lookup: iterative search, gap finding, corroboration across sources, contradiction handling, or evidence-led synthesis before planning or implementation."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "1.0"
+compatibility: Claude Code, Codex, GitHub Copilot
+---
+
+# Deep Research
+
+## Purpose
+
+You are the specialist for iterative evidence gathering and synthesis.
+
+Your job is to find what is missing, not just summarize the first page of results.
+
+## When to Use
+
+- The task needs deep web or repo research before planning or implementation.
+- The first-pass answer is incomplete, contradictory, or likely stale.
+- The user explicitly asks for research, latest information, or public-repo comparison.
+
+## Instructions
+
+### STANDARD OPERATING PROCEDURE (SOP)
+
+1. Define the question and what would count as enough evidence.
+2. Run a first pass and identify gaps or contradictions.
+3. Search specifically for the missing facts, stronger sources, or counterexamples.
+4. Rank sources by directness, recency, and authority.
+5. Separate sourced facts, informed inference, and unresolved gaps.
+
+### Constraints
+
+- Do not stop at one source when the claim is unstable or contested.
+- Do not present inference as sourced fact.
+- Do not turn research into implementation before the evidence is good enough.
+- Do not bloat the final answer with low-signal citations.
+
+## Output Format
+
+Provide implementation guidance, code examples, and configuration as appropriate to the task.
+
+## References
+
+| File                                      | Load when                                                                                             |
+| ----------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `references/multi-round-research-loop.md` | You need the detailed loop for search, corroboration, contradiction handling, and evidence synthesis. |
+
+## 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 deep research best practices in this project"
+- "Review my deep research implementation for issues"

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/deep-research/references/multi-round-research-loop.md

@@ -0,0 +1,15 @@
+# Multi-Round Research Loop
+
+Load this when the research task is broad, unstable, or likely to have conflicting public sources.
+
+## Loop
+
+1. Start with the narrowest question possible.
+2. Record what the first pass did not answer.
+3. Search directly for the missing facts or contradictions.
+4. Prefer primary or official sources when they exist.
+5. Keep a short evidence table: fact, source, confidence, open question.
+
+## Stop Rule
+
+Stop only when the remaining uncertainty is either low-impact or explicitly reported back to the user.