@cubis/foundry 0.3.71 → 0.3.73

package/workflows/powers/documentation-templates/SKILL.md

@@ -1,194 +1,225 @@
 ---
 name: documentation-templates
-description: Documentation templates and structure guidelines. README, API docs, code comments, and AI-friendly documentation.
-allowed-tools: Read, Glob, Grep
+description: Create API documentation, architecture decision records, runbooks, onboarding guides, and technical writing using proven templates and standards.
+license: Apache-2.0
+metadata:
+  author: cubis-foundry
+  version: "3.0"
+compatibility: Claude Code, Codex, GitHub Copilot, Gemini CLI
 ---
 
 # Documentation Templates
 
-> Templates and structure guidelines for common documentation types.
+## Purpose
 
----
+Provide templates and guidance for technical documentation: API docs, architecture decision records (ADRs), runbooks, README files, onboarding guides, and inline code documentation.
+
+## When to Use
+
+- Writing or improving a project README
+- Creating API documentation
+- Recording architecture decisions (ADRs)
+- Building operational runbooks
+- Writing onboarding guides for new team members
+- Documenting complex systems or workflows
 
-## 1. README Structure
+## Instructions
 
-### Essential Sections (Priority Order)
+### Step 1 — Choose the Right Template
 
-| Section | Purpose |
-|---------|---------|
-| **Title + One-liner** | What is this? |
-| **Quick Start** | Running in <5 min |
-| **Features** | What can I do? |
-| **Configuration** | How to customize |
-| **API Reference** | Link to detailed docs |
-| **Contributing** | How to help |
-| **License** | Legal |
+| Document Type    | Audience                          | When                       |
+| ---------------- | --------------------------------- | -------------------------- |
+| README           | New contributors, users           | Every project              |
+| API docs         | API consumers (internal/external) | Every API                  |
+| ADR              | Future developers                 | Every significant decision |
+| Runbook          | On-call engineers                 | Every production system    |
+| Onboarding guide | New team members                  | Every team                 |
+| RFC / Design doc | Reviewers before implementation   | Complex features           |
 
-### README Template
+### Step 2 — README Template
 
 ```markdown
 # Project Name
 
-Brief one-line description.
+One-line description of what this project does.
 
 ## Quick Start
 
-[Minimum steps to run]
+\`\`\`bash
+npm install
+npm run dev
+\`\`\`
 
 ## Features
 
-- Feature 1
-- Feature 2
+- Feature 1: brief description
+- Feature 2: brief description
 
-## Configuration
+## Architecture
 
-| Variable | Description | Default |
-|----------|-------------|---------|
-| PORT | Server port | 3000 |
+Brief overview or link to architecture docs.
 
-## Documentation
+## Development
 
-- [API Reference](./docs/api.md)
-- [Architecture](./docs/architecture.md)
+### Prerequisites
 
-## License
+- Node.js >= 20
+- PostgreSQL >= 15
 
-MIT
-```
+### Setup
 
----
+Step-by-step local development setup.
 
-## 2. API Documentation Structure
+### Testing
 
-### Per-Endpoint Template
+How to run tests.
 
-```markdown
-## GET /users/:id
+### Deployment
+
+How to deploy (or link to deployment docs).
 
-Get a user by ID.
+## Contributing
 
-**Parameters:**
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| id | string | Yes | User ID |
+Link to CONTRIBUTING.md or brief guidelines.
 
-**Response:**
-- 200: User object
-- 404: User not found
+## License
 
-**Example:**
-[Request and response example]
+MIT (or appropriate license)
 ```
 
----
+### Step 3 — Architecture Decision Record (ADR)
 
-## 3. Code Comment Guidelines
-
-### JSDoc/TSDoc Template
-
-```typescript
-/**
- * Brief description of what the function does.
- * 
- * @param paramName - Description of parameter
- * @returns Description of return value
- * @throws ErrorType - When this error occurs
- * 
- * @example
- * const result = functionName(input);
- */
-```
+```markdown
+# ADR-001: Use PostgreSQL for primary datastore
 
-### When to Comment
+## Status
 
-| ✅ Comment | ❌ Don't Comment |
-|-----------|-----------------|
-| Why (business logic) | What (obvious) |
-| Complex algorithms | Every line |
-| Non-obvious behavior | Self-explanatory code |
-| API contracts | Implementation details |
+Accepted | Proposed | Deprecated | Superseded by ADR-xxx
 
----
+## Context
 
-## 4. Changelog Template (Keep a Changelog)
+What is the problem? What constraints exist?
 
-```markdown
-# Changelog
-
-## [Unreleased]
-### Added
-- New feature
-
-## [1.0.0] - 2025-01-01
-### Added
-- Initial release
-### Changed
-- Updated dependency
-### Fixed
-- Bug fix
+## Decision
+
+What did we decide and why?
+
+## Consequences
+
+What are the trade-offs? What becomes easier/harder?
+
+## Alternatives Considered
+
+What else did we evaluate and why did we reject it?
 ```
 
----
+**Rules**:
 
-## 5. Architecture Decision Record (ADR)
+- ADRs are immutable — supersede, don't edit
+- Number sequentially (ADR-001, ADR-002)
+- Title should be a decision, not a question
+- Keep it short (1-2 pages max)
+
+### Step 4 — Runbook Template
 
 ```markdown
-# ADR-001: [Title]
+# Runbook: [System/Alert Name]
 
-## Status
-Accepted / Deprecated / Superseded
+## Overview
 
-## Context
-Why are we making this decision?
+What this system does and why it matters.
 
-## Decision
-What did we decide?
+## Alerts
 
-## Consequences
-What are the trade-offs?
-```
+| Alert           | Severity | Meaning                   |
+| --------------- | -------- | ------------------------- |
+| high_error_rate | Critical | Error rate > 5% for 5 min |
+| high_latency    | Warning  | p95 > 2s for 10 min       |
 
----
+## Diagnosis Steps
 
-## 6. AI-Friendly Documentation (2025)
+1. Check dashboards: [link]
+2. Check logs: `kubectl logs -l app=service-name --tail=100`
+3. Check dependencies: [list of upstream services]
 
-### llms.txt Template
+## Common Fixes
 
-For AI crawlers and agents:
+### High error rate
 
-```markdown
-# Project Name
-> One-line objective.
+1. Check recent deployments: `git log --since="2 hours ago"`
+2. If recent deploy caused it: rollback with `./deploy rollback`
+3. If not deployment-related: check database connections
+
+### High latency
+
+1. Check database slow query log
+2. Check connection pool saturation
+3. Scale up if under heavy load: `kubectl scale --replicas=5`
 
-## Core Files
-- [src/index.ts]: Main entry
-- [src/api/]: API routes
-- [docs/]: Documentation
+## Escalation
 
-## Key Concepts
-- Concept 1: Brief explanation
-- Concept 2: Brief explanation
+- L1: On-call engineer (PagerDuty)
+- L2: Service owner (@team-backend)
+- L3: Infrastructure team (@team-infra)
 ```
 
-### MCP-Ready Documentation
+### Step 5 — API Documentation
 
-For RAG indexing:
-- Clear H1-H3 hierarchy
-- JSON/YAML examples for data structures
-- Mermaid diagrams for flows
-- Self-contained sections
+**Document every endpoint with**:
 
----
+```markdown
+## POST /api/users
+
+Create a new user account.
+
+### Request
+
+**Headers**:
+| Header | Required | Description |
+|--------|----------|-------------|
+| Authorization | Yes | Bearer token |
+| Content-Type | Yes | application/json |
+
+**Body**:
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| email | string | Yes | Valid email address |
+| name | string | Yes | Full name (2-100 chars) |
+| role | string | No | "user" (default) or "admin" |
+
+**Example**:
+\`\`\`json
+{ "email": "alice@example.com", "name": "Alice Smith" }
+\`\`\`
+
+### Response
+
+**201 Created**:
+\`\`\`json
+{ "id": "usr_abc123", "email": "alice@example.com", "name": "Alice Smith", "role": "user" }
+\`\`\`
+
+**400 Bad Request**:
+\`\`\`json
+{ "error": { "code": "VALIDATION_ERROR", "message": "Email already registered" } }
+\`\`\`
+
+**401 Unauthorized**:
+\`\`\`json
+{ "error": { "code": "UNAUTHORIZED", "message": "Invalid or expired token" } }
+\`\`\`
+```
 
-## 7. Structure Principles
+## Output Format
 
-| Principle | Why |
-|-----------|-----|
-| **Scannable** | Headers, lists, tables |
-| **Examples first** | Show, don't just tell |
-| **Progressive detail** | Simple → Complex |
-| **Up to date** | Outdated = misleading |
+Use the appropriate template from above, filled in with project-specific details. Always include examples with realistic (not lorem ipsum) content.
 
----
+## Examples
+
+**User**: "Write a README for our API project"
+
+**Response approach**: Use the README template. Fill in actual project details. Include quick start with real commands. Link to API docs. Add architecture overview if the system has multiple components.
+
+**User**: "We need to document why we chose MongoDB over PostgreSQL"
 
-> **Remember:** Templates are starting points. Adapt to your project's needs.
+**Response approach**: Use the ADR template. Document the context (data model flexibility needs), decision (MongoDB for document storage), consequences (eventual consistency trade-off), and alternatives considered (PostgreSQL with JSONB).

package/workflows/powers/drizzle-expert/POWER.md

@@ -0,0 +1,66 @@
+````markdown
+---
+inclusion: manual
+name: drizzle-expert
+description: "Use when the task is specifically Drizzle ORM or drizzle-kit: schema-as-code, typed SQL, relations, migrations, config, runtime pairing, or TypeScript database access-layer decisions across Postgres, SQLite/libSQL, Neon, or Supabase."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "1.0"
+compatibility: Claude Code, Codex, GitHub Copilot
+---
+
+# Drizzle Expert
+
+## Purpose
+
+You are the narrow specialist for Drizzle ORM and drizzle-kit in TypeScript database stacks.
+
+Your job is to keep schema-as-code, typed query ergonomics, migration safety, and runtime pairing decisions explicit without replacing the underlying engine specialist.
+
+## When to Use
+
+- Drizzle schema files, relations, migrations, or drizzle-kit config are primary.
+- The real decision is Drizzle vs raw SQL or another ORM/query-builder posture.
+- The task depends on TypeScript-first database access patterns, typed queries, or edge or serverless runtime pairing.
+- The engine is Postgres, SQLite/libSQL, Neon, or Supabase and the access layer matters as much as the engine.
+
+## Instructions
+
+### STANDARD OPERATING PROCEDURE (SOP)
+
+1. Confirm the engine, runtime, migration path, and current Drizzle version or config shape.
+2. Separate access-layer concerns from engine concerns and load the engine or platform skill when needed.
+3. Check schema layout, relations, naming, and generated SQL implications before changing query code.
+4. Keep migration order, rollback posture, and deployment safety explicit.
+5. Verify how Drizzle pairs with the target runtime, pooling strategy, and serverless or edge constraints.
+
+### Constraints
+
+- Do not answer plain engine questions without also loading the matching engine or platform skill.
+- Do not blur Drizzle concerns into generic TypeScript or generic Postgres advice.
+- Do not recommend generated migrations, relation helpers, or runtime adapters without checking the deployment model.
+- Do not hide migration risk behind ORM abstraction.
+
+## 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/schema-and-migration-playbook.md` | You need the Drizzle-specific checklist for schema layout, relations, migrations, and rollout safety.                |
+| `references/runtime-pairing-matrix.md`        | You need the runtime and engine pairing rules for Postgres, Supabase, SQLite/libSQL, Neon, or serverless deployment. |
+
+## 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 drizzle expert best practices in this project"
+- "Review my drizzle expert implementation for issues"
+````

package/workflows/powers/drizzle-expert/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: drizzle-expert
+description: "Use when the task is specifically Drizzle ORM or drizzle-kit: schema-as-code, typed SQL, relations, migrations, config, runtime pairing, or TypeScript database access-layer decisions across Postgres, SQLite/libSQL, Neon, or Supabase."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "1.0"
+compatibility: Claude Code, Codex, GitHub Copilot
+---
+
+# Drizzle Expert
+
+## Purpose
+
+You are the narrow specialist for Drizzle ORM and drizzle-kit in TypeScript database stacks.
+
+Your job is to keep schema-as-code, typed query ergonomics, migration safety, and runtime pairing decisions explicit without replacing the underlying engine specialist.
+
+## When to Use
+
+- Drizzle schema files, relations, migrations, or drizzle-kit config are primary.
+- The real decision is Drizzle vs raw SQL or another ORM/query-builder posture.
+- The task depends on TypeScript-first database access patterns, typed queries, or edge or serverless runtime pairing.
+- The engine is Postgres, SQLite/libSQL, Neon, or Supabase and the access layer matters as much as the engine.
+
+## Instructions
+
+### STANDARD OPERATING PROCEDURE (SOP)
+
+1. Confirm the engine, runtime, migration path, and current Drizzle version or config shape.
+2. Separate access-layer concerns from engine concerns and load the engine or platform skill when needed.
+3. Check schema layout, relations, naming, and generated SQL implications before changing query code.
+4. Keep migration order, rollback posture, and deployment safety explicit.
+5. Verify how Drizzle pairs with the target runtime, pooling strategy, and serverless or edge constraints.
+
+### Constraints
+
+- Do not answer plain engine questions without also loading the matching engine or platform skill.
+- Do not blur Drizzle concerns into generic TypeScript or generic Postgres advice.
+- Do not recommend generated migrations, relation helpers, or runtime adapters without checking the deployment model.
+- Do not hide migration risk behind ORM abstraction.
+
+## 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/schema-and-migration-playbook.md` | You need the Drizzle-specific checklist for schema layout, relations, migrations, and rollout safety.                |
+| `references/runtime-pairing-matrix.md`        | You need the runtime and engine pairing rules for Postgres, Supabase, SQLite/libSQL, Neon, or serverless deployment. |
+
+## 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 drizzle expert best practices in this project"
+- "Review my drizzle expert implementation for issues"

package/workflows/powers/drizzle-expert/references/runtime-pairing-matrix.md

@@ -0,0 +1,16 @@
+# Drizzle Runtime Pairing Matrix
+
+Load this when runtime choice or deployment model changes the Drizzle answer.
+
+## Pairing Rules
+
+- `postgres` or `neon-postgres` style stacks: verify connection strategy, pooling, and migration path before recommending long-lived clients.
+- `supabase`: keep auth, RLS, storage, and platform policy concerns in the Supabase skill; use Drizzle only for the data-access layer.
+- `sqlite` or `libsql` style stacks: keep write-concurrency and local-first limits visible.
+- Serverless or edge runtimes: prefer the smallest safe adapter surface and avoid assumptions about persistent connections.
+
+## Do Not Blur
+
+- Engine features belong to the engine skill.
+- Drizzle config, schema, and query ergonomics belong here.
+- Framework-specific wiring belongs to the matching backend or frontend framework skill.

package/workflows/powers/drizzle-expert/references/schema-and-migration-playbook.md

@@ -0,0 +1,18 @@
+# Drizzle Schema And Migration Playbook
+
+Load this when Drizzle schema files, relations, or drizzle-kit migrations are the active risk.
+
+## Focus Areas
+
+- Keep schema ownership obvious. Prefer feature-aware file boundaries over giant schema dumps.
+- Review relation helpers against the actual query patterns instead of assuming relations improve every call site.
+- Check generated migration SQL before trusting it in production.
+- Treat rename, backfill, and irreversible column changes as rollout events, not local refactors.
+
+## Minimum Review Loop
+
+1. Confirm engine and target runtime.
+2. Read current schema files and drizzle config before editing.
+3. Validate whether the migration is additive, destructive, or backfill-heavy.
+4. Pair with the engine skill for index, lock, or feature-specific tradeoffs.
+5. Keep rollback or fallback steps visible when the migration is not trivial.