@cubis/foundry 0.3.30 → 0.3.32

package/workflows/workflows/agent-environment-setup/platforms/cursor/skills/cli-developer/steering/ux-patterns.md

@@ -0,0 +1,447 @@
+# CLI UX Patterns
+
+## Progress Indicators
+
+### When to Use Each Type
+
+| Type                           | When to Use          | Example                                        |
+| ------------------------------ | -------------------- | ---------------------------------------------- |
+| **Determinate** (progress bar) | Total count is known | Downloading 50 files, processing 200 records   |
+| **Indeterminate** (spinner)    | Duration unknown     | Connecting to server, waiting for API response |
+| **Multi-step** (sequential)    | Ordered pipeline     | Build → Test → Deploy                          |
+
+### Progress Bar Components
+
+```
+  Downloading |████████████░░░░░░░░| 60% | 30/50 files | 2.3 MB/s | ETA: 12s
+               ↑ visual bar          ↑ %    ↑ current/total  ↑ rate    ↑ ETA
+```
+
+| Component     | Include When                                     |
+| ------------- | ------------------------------------------------ |
+| Visual bar    | Always — gives immediate sense of progress       |
+| Percentage    | Always — precise progress indication             |
+| Current/Total | When count is meaningful (files, records, items) |
+| Rate          | For data transfer or long operations             |
+| ETA           | For operations > 10 seconds                      |
+
+### Spinner Styles
+
+Use spinners for operations where you can't predict completion:
+
+```
+⠋ Connecting to server...       # Braille dots (smooth, modern)
+⣾ Building project...           # Braille dots (alternative)
+◐ Running health checks...      # Circle quarters
+⠸ Uploading artifacts...        # Dots
+```
+
+**Rules:**
+
+- Update spinner text as the operation progresses through stages
+- Stop the spinner before printing other output
+- On success: replace with `✓` in green
+- On failure: replace with `✗` in red
+
+---
+
+## Color Usage
+
+### Semantic Colors
+
+| Color        | Meaning                | Symbol | Usage                                     |
+| ------------ | ---------------------- | ------ | ----------------------------------------- |
+| **Red**      | Error, failure, danger | `✗`    | Fatal errors, destructive actions         |
+| **Green**    | Success, completion    | `✓`    | Completed operations, confirmations       |
+| **Yellow**   | Warning, caution       | `⚠`    | Non-fatal issues, deprecation notices     |
+| **Blue**     | Info, neutral          | `ℹ`    | Status updates, informational messages    |
+| **Cyan**     | Highlight, accent      |        | Commands, paths, important values         |
+| **Dim/Gray** | Secondary, hint        |        | Timestamps, hints, less important details |
+| **Bold**     | Emphasis               |        | Key values, headings, important names     |
+
+### When to Disable Color
+
+```javascript
+function shouldUseColor() {
+  // Respect NO_COLOR standard (https://no-color.org/)
+  if (process.env.NO_COLOR !== undefined) return false;
+
+  // Disable in CI environments
+  if (process.env.CI) return false;
+
+  // Disable when not a TTY (piped output)
+  if (!process.stdout.isTTY) return false;
+
+  // Disable if TERM is "dumb"
+  if (process.env.TERM === "dumb") return false;
+
+  return true;
+}
+```
+
+### Accessibility: Symbols + Color, Not Color Alone
+
+```
+# GOOD — meaning conveyed by both symbol and color
+✓ Tests passed                    (green + checkmark)
+✗ Build failed                    (red + X)
+⚠ Deprecated API version          (yellow + warning symbol)
+ℹ Using default configuration     (blue + info symbol)
+
+# BAD — meaning conveyed by color only
+Tests passed                      (green text only)
+Build failed                      (red text only)
+```
+
+**Rule:** Every colored message must also have a symbol or text prefix that conveys the same meaning. Users with color blindness or monochrome terminals must still understand the output.
+
+---
+
+## Help Text Design
+
+### Command Help
+
+```
+USAGE
+  $ mycli <command> [options]
+
+COMMANDS
+  init <name>       Create a new project from a template
+  deploy            Deploy to target environment
+  config            Manage configuration settings
+  plugin            Manage CLI plugins
+
+OPTIONS
+  -v, --verbose     Enable verbose output
+  -q, --quiet       Suppress all output except errors
+  --no-color        Disable colored output
+  --version         Show version number
+  -h, --help        Show this help message
+
+EXAMPLES
+  $ mycli init my-app --template react
+  $ mycli deploy --env production --dry-run
+  $ mycli config set apiKey sk-1234
+```
+
+### Subcommand Help
+
+```
+USAGE
+  $ mycli deploy [options]
+
+DESCRIPTION
+  Deploy the current project to the specified environment.
+  Runs build, upload, and health check steps automatically.
+
+OPTIONS
+  -e, --env <name>        Target environment (required)
+                           Allowed: staging, production
+  --dry-run               Preview changes without deploying
+  --tag <tag>             Deploy a specific version tag
+  --timeout <seconds>     Deployment timeout (default: 300)
+  --skip-health-check     Skip post-deploy health check
+  --rollback-on-failure   Auto-rollback if health check fails
+
+EXAMPLES
+  # Deploy to staging
+  $ mycli deploy --env staging
+
+  # Dry run for production
+  $ mycli deploy --env production --dry-run
+
+  # Deploy specific version with auto-rollback
+  $ mycli deploy --env production --tag v1.2.0 --rollback-on-failure
+```
+
+**Rules:**
+
+- USAGE first, then DESCRIPTION (for subcommands), then OPTIONS, then EXAMPLES
+- Align option descriptions in columns
+- Show default values inline: `(default: 300)`
+- Show allowed values inline: `Allowed: staging, production`
+- Include 2-3 practical examples with comments
+
+---
+
+## Error Messages
+
+### Good Pattern: Context → Problem → Solution
+
+**Example 1: Missing configuration**
+
+```
+✗ Cannot deploy to production
+
+  Configuration file not found at ~/.mycli/config.yaml
+  This file is required for deployment credentials.
+
+  To fix this:
+    $ mycli config init
+    $ mycli config set deploy.token <your-token>
+```
+
+**Example 2: Network failure**
+
+```
+✗ Failed to connect to registry
+
+  Could not reach https://registry.example.com (connection timed out after 30s)
+
+  Possible fixes:
+    • Check your internet connection
+    • Verify the registry URL: mycli config get registry.url
+    • Try again with a longer timeout: --timeout 60
+    • If behind a proxy, set HTTPS_PROXY environment variable
+```
+
+**Example 3: Validation error**
+
+```
+✗ Invalid project name: "My Project"
+
+  Project names must be lowercase alphanumeric with hyphens only.
+  Examples: my-project, api-v2, hello-world
+
+  Try:
+    $ mycli init my-project
+```
+
+### Error Message Guidelines
+
+**DO:**
+
+- Be specific about what failed and where
+- Include the actual value that caused the error
+- Suggest concrete fixes (commands, flags, config changes)
+- Use plain language, not technical jargon
+- Show the relevant file path or URL
+
+**DON'T:**
+
+- Show raw stack traces to end users (use `--verbose` for debug info)
+- Use error codes without explanation (`Error: E4012`)
+- Be vague (`Something went wrong`, `An error occurred`)
+- Use technical jargon (`ECONNREFUSED`, `EPERM`, `segfault`)
+- Blame the user (`You did something wrong`)
+
+---
+
+## Interactive Prompts
+
+### Prompt Types
+
+| Type         | When to Use             | Example                   |
+| ------------ | ----------------------- | ------------------------- |
+| **Text**     | Free-form input         | Project name, description |
+| **Select**   | Single choice from list | Template, environment     |
+| **Checkbox** | Multiple choices        | Features, plugins         |
+| **Confirm**  | Yes/no decision         | Overwrite, deploy, delete |
+| **Password** | Sensitive input         | API keys, tokens          |
+
+### Prompt Guidelines
+
+- **Show keyboard hints:** `↑/↓: navigate • space: toggle • enter: confirm`
+- **Provide defaults:** Pre-fill with sensible values (current directory name, common choices)
+- **Handle Ctrl+C gracefully:** Print "Operation cancelled." and exit with code 130
+- **Never prompt in CI:** Detect non-interactive mode and use defaults or fail with a clear message
+- **Every prompt must have a flag equivalent:** `--name`, `--template`, `--yes` for confirm-all
+
+```
+? Project name: (my-project) █
+  ↑ question      ↑ default    ↑ cursor
+
+? Select a template: (Use arrow keys)
+❯ Default — Minimal starter template
+  React — React with Vite
+  Vue — Vue 3 with Vite
+  Node API — Express REST API
+
+? Select features: (Press <space> to select, <enter> to confirm)
+ ◉ TypeScript
+ ◉ ESLint
+ ◯ Prettier
+ ◯ Testing (Vitest)
+ ◯ Docker
+
+? Initialize git repository? (Y/n) █
+
+? Enter your API key: ********█
+```
+
+---
+
+## Output Formatting
+
+### Tables
+
+**Fancy (default for TTY):**
+
+```
+┌─────────────┬───────────┬─────────┬──────────────────┐
+│ Environment │ Status    │ Version │ Last Deploy      │
+├─────────────┼───────────┼─────────┼──────────────────┤
+│ production  │ ✓ healthy │ v2.1.0  │ 2024-01-15 14:30 │
+│ staging     │ ✓ healthy │ v2.2.0  │ 2024-01-16 09:15 │
+│ development │ ⚠ degraded│ v2.2.0  │ 2024-01-16 11:00 │
+└─────────────┴───────────┴─────────┴──────────────────┘
+```
+
+**Minimal (for piped output or `--plain`):**
+
+```
+ENVIRONMENT  STATUS     VERSION  LAST DEPLOY
+production   healthy    v2.1.0   2024-01-15 14:30
+staging      healthy    v2.2.0   2024-01-16 09:15
+development  degraded   v2.2.0   2024-01-16 11:00
+```
+
+**JSON (for `--json` flag):**
+
+```json
+[
+  {
+    "environment": "production",
+    "status": "healthy",
+    "version": "v2.1.0",
+    "lastDeploy": "2024-01-15T14:30:00Z"
+  },
+  {
+    "environment": "staging",
+    "status": "healthy",
+    "version": "v2.2.0",
+    "lastDeploy": "2024-01-16T09:15:00Z"
+  }
+]
+```
+
+### Lists
+
+**Bulleted:**
+
+```
+  Installed plugins:
+    • mycli-plugin-docker (v1.2.0)
+    • mycli-plugin-aws (v0.8.3)
+    • mycli-plugin-monitoring (v2.0.1)
+```
+
+**Numbered:**
+
+```
+  Migration steps:
+    1. Back up database
+    2. Run schema migration
+    3. Deploy new version
+    4. Verify health checks
+    5. Update DNS records
+```
+
+**Tree:**
+
+```
+  my-project/
+  ├── src/
+  │   ├── index.ts
+  │   ├── config.ts
+  │   └── routes/
+  │       ├── auth.ts
+  │       └── users.ts
+  ├── tests/
+  │   └── index.test.ts
+  ├── package.json
+  └── tsconfig.json
+```
+
+---
+
+## Status Messages
+
+### Real-Time Multi-Step Updates
+
+```
+  ℹ Deploying to production...
+
+  ✓ Building application          3.2s
+  ✓ Running tests                 12.1s
+  ✓ Uploading artifacts           1.8s
+  ⠸ Running health checks...
+```
+
+Each step transitions from spinner → checkmark (or X on failure):
+
+```
+  ⠸ Building application...       # In progress (spinner)
+  ✓ Building application  3.2s    # Complete (green check + duration)
+  ✗ Running tests                  # Failed (red X)
+```
+
+### Summary / Completion
+
+```
+  ┌──────────────────────────────────────┐
+  │                                      │
+  │   ✓ Deployed to production           │
+  │                                      │
+  │   Version:  v2.1.0                   │
+  │   URL:      https://app.example.com  │
+  │   Duration: 17.1s                    │
+  │                                      │
+  └──────────────────────────────────────┘
+```
+
+Or simpler:
+
+```
+  ✓ Done! Deployed v2.1.0 to production in 17.1s
+
+    URL: https://app.example.com
+    Dashboard: https://dashboard.example.com/deploys/abc123
+```
+
+---
+
+## Debugging & Verbose Mode
+
+### Output Levels
+
+**Normal (default):**
+
+```
+  ✓ Project created at ./my-project
+```
+
+**Verbose (`--verbose` or `-v`):**
+
+```
+  ℹ Creating project directory: /Users/dev/projects/my-project
+  ℹ Using template: react (v3.2.0)
+  ℹ Copying 23 template files...
+  ℹ Installing 15 dependencies...
+  ℹ Initializing git repository
+  ✓ Project created at ./my-project
+```
+
+**Debug (`--debug` or `MYCLI_DEBUG=1`):**
+
+```
+  [DEBUG 14:30:01.123] Config loaded from: /Users/dev/.mycli/config.yaml
+  [DEBUG 14:30:01.124] Template registry: https://registry.example.com/v2
+  [DEBUG 14:30:01.125] GET https://registry.example.com/v2/templates/react
+  [DEBUG 14:30:01.340] Response: 200 OK (215ms) — 4.2KB
+  [DEBUG 14:30:01.341] Template version: 3.2.0 (latest)
+  [DEBUG 14:30:01.342] Target directory: /Users/dev/projects/my-project
+  [DEBUG 14:30:01.342] Directory created: /Users/dev/projects/my-project
+  [DEBUG 14:30:01.345] Copying template files (23 files, 48KB)...
+  ℹ Creating project directory: /Users/dev/projects/my-project
+  ℹ Using template: react (v3.2.0)
+  ...
+```
+
+**Rules:**
+
+- Normal: Only results and errors. Minimal noise.
+- Verbose: Add step-by-step progress. Useful for understanding what happened.
+- Debug: Add timestamps, HTTP requests/responses, file paths, config values. Useful for bug reports.
+- Debug output goes to stderr so stdout remains parseable.
+- Never log secrets (API keys, tokens) even in debug mode.

package/workflows/workflows/agent-environment-setup/platforms/cursor/skills/code-review-checklist/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: code-review-checklist
+description: "Compatibility alias skill. Deprecated: use code-reviewer."
+metadata:
+  deprecated: true
+  replaced_by: code-reviewer
+  removal_target: v0.6.0
+---
+
+# Code Review Checklist
+
+## Compatibility Alias
+
+This skill is deprecated and kept for backward compatibility.
+
+Use `code-reviewer` as the canonical skill.
+
+## Migration
+
+1. Replace direct references to `code-review-checklist` with `code-reviewer`.
+2. Apply the full workflow from `code-reviewer` for new work.

package/workflows/workflows/agent-environment-setup/platforms/cursor/skills/database-skills/LATEST_VERSIONS.md

@@ -0,0 +1,36 @@
+# Database Versions Baseline
+
+Last verified: 2026-02-20 (US)
+
+## Relational / SQL
+
+- PostgreSQL: **18.2** current minor for supported major 18.
+- MySQL:
+  - **8.4.8** current LTS patch.
+  - **9.6.0** latest Innovation release.
+- SQLite: **3.51.2** current stable release.
+- Vitess: **v23.0.2** current stable patch in v23.0 line.
+
+## Document / KV / Managed
+
+- MongoDB: **8.2.5** latest patch in current 8.2 minor line.
+- Redis Open Source: **8.4.0** latest GA major (8.2 remains an actively documented line).
+- Supabase Postgres:
+  - Managed projects may run **Postgres 17**.
+  - Self-hosted Docker docs currently call out **Postgres 15** compatibility constraints.
+- Neki: announced and in active development/waitlist stage (no GA semantic version yet).
+
+## Source links (official)
+
+- PostgreSQL versioning: https://www.postgresql.org/support/versioning/
+- MySQL release model: https://dev.mysql.com/doc/refman/8.4/en/mysql-releases.html
+- MySQL 8.4.8 LTS notes: https://dev.mysql.com/doc/relnotes/mysql/8.4/en/news-8-4-8.html
+- MySQL 9.6.0 Innovation notes: https://dev.mysql.com/doc/relnotes/mysql/9.6/en/news-9-6-0.html
+- SQLite current release: https://sqlite.org/releaselog/current.html
+- Vitess releases: https://vitess.io/docs/releases/
+- MongoDB 8.2 release notes: https://www.mongodb.com/docs/manual/release-notes/8.2/
+- Redis 8.4 updates: https://redis.io/docs/latest/develop/whats-new/8-4/
+- Redis OSS releases: https://github.com/redis/redis/releases
+- Supabase restore compatibility note: https://supabase.com/docs/guides/self-hosting/restore-from-platform
+- Neki announcement: https://planetscale.com/blog/announcing-neki
+- Neki product page: https://planetscale.com/neki

package/workflows/workflows/agent-environment-setup/platforms/cursor/skills/database-skills/README.md

@@ -0,0 +1,51 @@
+# database-skills
+
+Engine-specific database skill pack inspired by `planetscale/database-skills`, expanded for modern production stacks.
+
+## Layout
+
+```text
+database-skills/
+├── README.md
+├── LATEST_VERSIONS.md
+├── SKILL.md
+└── skills/
+    ├── postgres/
+    │   ├── SKILL.md
+    │   └── references/
+    ├── mysql/
+    │   ├── SKILL.md
+    │   └── references/
+    ├── vitess/
+    │   ├── SKILL.md
+    │   └── references/
+    ├── neki/
+    │   ├── SKILL.md
+    │   └── references/
+    ├── mongodb/
+    │   ├── SKILL.md
+    │   └── references/
+    ├── sqlite/
+    │   ├── SKILL.md
+    │   └── references/
+    ├── supabase/
+    │   ├── SKILL.md
+    │   └── references/
+    └── redis/
+        ├── SKILL.md
+        └── references/
+```
+
+## What each engine pack must cover
+
+- Index strategy for real query patterns.
+- Pagination strategy (keyset/seek first, offset only when justified).
+- Query plan workflow (`EXPLAIN` or engine equivalent).
+- Write/read tradeoff notes.
+- Safe rollout + rollback notes for schema and operational changes.
+
+## Notes
+
+- Use this package as the primary database hub in agents/workflows.
+- Keep `database-design`, `database-optimizer`, and `drift-flutter` active as companion skills for specialized or legacy-compatible flows.
+- Keep version-sensitive guidance synced with `LATEST_VERSIONS.md`.

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

@@ -0,0 +1,102 @@
+---
+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
+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
+---
+
+# Database Skills Hub
+
+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.
+
+## Engine selection
+
+| Situation | Engine |
+| --- | --- |
+| 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 `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.

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

@@ -0,0 +1,37 @@
+---
+name: mongodb
+description: MongoDB and Mongoose modeling, indexing, pagination, query tuning, and transaction guidance.
+---
+
+# MongoDB and Mongoose
+
+## Optimization workflow
+
+1. Model around dominant read/write paths (embed vs reference).
+2. Add compound indexes for real filter + sort patterns.
+3. Validate with `explain("executionStats")`.
+4. Prefer range/keyset pagination over deep `skip`.
+5. Re-check index selectivity and write overhead as data grows.
+
+## Indexing techniques
+
+- Compound indexes over isolated single-field indexes when query shape demands it.
+- Keep index count controlled on write-heavy collections.
+- Use partial/sparse strategies only when semantics are correct.
+
+## Pagination techniques
+
+- Avoid large-offset `skip` on large collections.
+- Use boundary-based pagination with indexed monotonic key (`_id` or timestamp+id).
+- Keep deterministic sort and cursor boundary state.
+
+## Mongoose/NestJS guardrails
+
+- Keep schema indexes explicit in model definitions/migrations.
+- Use projections to avoid over-fetching large documents.
+- Use transactions only when cross-document invariants require them.
+
+## References
+
+- `references/modeling.md`
+- `references/mongoose-nestjs.md`