@cubis/foundry 0.3.10

package/Ai Agent Workflow/skills/code-reviewer/references/spec-compliance-review.md

@@ -0,0 +1,261 @@
+# Spec Compliance Review
+
+> Reference for: Code Reviewer
+> Load when: reviewing implementations, PR review, spec verification
+
+---
+
+## Two-Stage Review Architecture
+
+```
+                    ┌─────────────────────┐
+                    │   Implementation    │
+                    └──────────┬──────────┘
+                               │
+                    ┌──────────▼──────────┐
+                    │  STAGE 1: Spec      │
+                    │  Compliance Review  │
+                    └──────────┬──────────┘
+                               │
+              ┌────────────────┴────────────────┐
+              │                                  │
+      ┌───────▼───────┐                ┌────────▼────────┐
+      │   ✗ Issues    │                │   ✓ Compliant   │
+      │     Found     │                │                 │
+      └───────┬───────┘                └────────┬────────┘
+              │                                  │
+              │                        ┌────────▼────────┐
+              │                        │  STAGE 2: Code  │
+              │                        │  Quality Review │
+              │                        └────────┬────────┘
+              │                                  │
+              │                    ┌─────────────┴─────────────┐
+              │                    │                           │
+              │            ┌───────▼───────┐         ┌────────▼────────┐
+              │            │   ✗ Issues    │         │   ✓ Approved    │
+              │            │     Found     │         │                 │
+              │            └───────┬───────┘         └─────────────────┘
+              │                    │
+              └────────────────────┴────────────────────┐
+                                                        │
+                                              ┌─────────▼─────────┐
+                                              │ Return to Author  │
+                                              └───────────────────┘
+```
+
+**Critical:** Complete Stage 1 (spec compliance) BEFORE Stage 2 (code quality). Never review code quality for functionality that doesn't meet the specification.
+
+---
+
+## Stage 1: Spec Compliance Review
+
+### Core Directive
+
+> "The implementer finished suspiciously quickly. Their report may be incomplete, inaccurate, or optimistic."
+
+Approach every review with professional skepticism. Verify claims independently.
+
+### The Three Verification Categories
+
+#### Category 1: Missing Requirements
+
+**Check for features that were requested but not implemented.**
+
+| Question | How to Verify |
+|----------|---------------|
+| Did they skip requested features? | Compare PR to original requirements line by line |
+| Are edge cases handled? | Check error paths, empty states, boundaries |
+| Were error scenarios addressed? | Look for try/catch, error boundaries, validation |
+| Is the happy path complete? | Trace through primary use case manually |
+
+```markdown
+## Example Review Finding
+
+**Missing Requirement:** Issue #42 requested "password must be at least 8 characters"
+
+**Found in code:**
+```typescript
+// No length validation present
+function validatePassword(password: string) {
+  return password.length > 0;  // Only checks non-empty
+}
+```
+
+**Status:** ❌ Incomplete - minimum length validation missing
+```
+
+#### Category 2: Unnecessary Additions
+
+**Check for scope creep and over-engineering.**
+
+| Question | How to Verify |
+|----------|---------------|
+| Features beyond specification? | Compare to original requirements |
+| Over-engineering? | Is complexity justified by requirements? |
+| Premature optimization? | Is performance cited without measurements? |
+| Unrequested abstractions? | Are there helpers/utils for one-time use? |
+
+```markdown
+## Example Review Finding
+
+**Unnecessary Addition:** Added caching layer not in requirements
+
+**Found in code:**
+```typescript
+// Original requirement: "Fetch user by ID"
+// Actual implementation:
+class CachedUserRepository {  // Not requested
+  private cache = new Map();
+  private ttl = 60000;
+
+  async getUser(id: string) {
+    if (this.cache.has(id)) { ... }
+    // 50 lines of cache logic
+  }
+}
+```
+
+**Status:** ⚠️ Scope creep - discuss before merging
+```
+
+#### Category 3: Interpretation Gaps
+
+**Check for misunderstandings of requirements.**
+
+| Question | How to Verify |
+|----------|---------------|
+| Different understanding of requirements? | Ask author to explain their interpretation |
+| Unclarified assumptions? | Look for comments like "assuming..." |
+| Ambiguous specs resolved incorrectly? | Compare to similar existing features |
+
+```markdown
+## Example Review Finding
+
+**Interpretation Gap:** "Sort by date" implemented as ascending
+
+**Requirement stated:** "Sort by date" (ambiguous)
+
+**Author implemented:** Oldest first (ascending)
+
+**Expected:** Most recent first is typical UX pattern
+
+**Status:** ❓ Clarify - which sort order was intended?
+```
+
+---
+
+## Why Order Matters
+
+### Stage 1 Must Come First
+
+| Scenario | Waste from Wrong Order |
+|----------|------------------------|
+| Skip Stage 1 | Review 500 lines of code quality, then discover wrong feature was built |
+| Stage 2 First | Suggest refactoring, then realize the code shouldn't exist |
+| Combined | Mix concerns, miss systematic issues |
+
+### Separation of Concerns
+
+- **Stage 1 (Spec):** Does it do the right thing?
+- **Stage 2 (Quality):** Does it do the thing right?
+
+Code quality review is meaningless if the code doesn't implement the correct functionality.
+
+---
+
+## Spec Compliance Checklist
+
+### Before You Start
+
+- [ ] Read the original issue/ticket completely
+- [ ] Identify all explicit requirements
+- [ ] Identify implicit requirements from context
+- [ ] Note any acceptance criteria listed
+
+### During Review
+
+**Missing Requirements:**
+- [ ] All required features present
+- [ ] Edge cases covered (empty, null, max values)
+- [ ] Error handling as specified
+- [ ] Happy path fully functional
+- [ ] UI matches mockups/specs if provided
+
+**Unnecessary Additions:**
+- [ ] No unrequested features
+- [ ] No speculative abstractions
+- [ ] No premature optimizations
+- [ ] Scope matches requirements exactly
+
+**Interpretation Gaps:**
+- [ ] Author's understanding matches spec
+- [ ] Ambiguities resolved correctly
+- [ ] Assumptions are documented and valid
+- [ ] Behavior matches similar existing features
+
+### After Review
+
+- [ ] Document all findings with file:line references
+- [ ] Categorize as missing/unnecessary/interpretation
+- [ ] Prioritize: blocking vs. non-blocking issues
+
+---
+
+## Output Format
+
+### Compliant Result
+
+```markdown
+## Spec Compliance Review: ✅ PASS
+
+All requirements verified:
+- ✅ User can upload profile image (req #1)
+- ✅ Image resized to 200x200 (req #2)
+- ✅ Invalid formats rejected with error message (req #3)
+- ✅ Progress indicator during upload (req #4)
+
+**Proceed to:** Code Quality Review
+```
+
+### Issues Found
+
+```markdown
+## Spec Compliance Review: ❌ ISSUES FOUND
+
+### Missing Requirements
+
+1. **Progress indicator not implemented** (req #4)
+   - File: `ProfileUpload.tsx`
+   - Expected: Progress bar during upload
+   - Found: No progress indication
+
+2. **Error messages not user-friendly** (req #3)
+   - File: `ProfileUpload.tsx:45`
+   - Expected: "Please upload a JPG or PNG file"
+   - Found: "Error: INVALID_FORMAT"
+
+### Unnecessary Additions
+
+1. **Image cropping feature not requested**
+   - File: `ImageCropper.tsx` (new file, 150 lines)
+   - Impact: Adds complexity, delays delivery
+   - Recommendation: Remove or create separate PR
+
+**Action Required:** Address missing requirements before code quality review
+```
+
+---
+
+## Common Mistakes to Avoid
+
+| Mistake | Why It's Wrong |
+|---------|----------------|
+| Reviewing code style before spec compliance | Wasted effort if wrong thing was built |
+| Assuming spec was followed | Verify independently |
+| Skipping edge cases | Bugs hide in boundaries |
+| Accepting "we can add it later" | Technical debt accumulates |
+| Missing scope creep | Unreviewed code enters codebase |
+
+---
+
+*Content adapted from [obra/superpowers](https://github.com/obra/superpowers) by Jesse Vincent (@obra), MIT License.*

package/Ai Agent Workflow/skills/code-reviewer/references/strict-rules.md

@@ -0,0 +1,69 @@
+# Strict Code Review Rules
+
+> Reference for: Code Reviewer
+> Load when: Enforcing strict review standards
+
+## Core Standard (Non‑Negotiable)
+
+- **Correctness first**: reject changes that introduce incorrect behavior, regressions, or incomplete edge cases.
+- **Readability is a feature**: if code is hard to understand, request changes.
+- **Consistency over preference**: match existing style and patterns within the codebase.
+
+## Change Size & Scope
+
+- **Small, focused changes**: large or multi‑purpose changes must be split.
+- **No scope creep**: remove unrequested features and speculative abstractions.
+- **Spec first**: if requirements are ambiguous, request clarification before approval.
+
+## Naming & File Organization
+
+- **Intention‑revealing names**: names must convey responsibility and behavior.
+- **One primary concern per file**: avoid “utility dump” files.
+- **Consistent file naming**: follow repo conventions strictly (case, separators).
+- **Acronyms as words**: prefer `UserId` over `UserID`, `HttpClient` over `HTTPClient`.
+
+## Error Handling & Reliability
+
+- **No empty catch blocks**: handle or rethrow with context.
+- **Avoid catch‑all**: don’t catch overly broad exceptions unless at top‑level boundary.
+- **Fail fast with clear errors**: avoid silent failures and partial updates.
+
+## Concurrency & Race Conditions
+
+- **Atomicity required**: read‑modify‑write must be transactional or atomic.
+- **Shared state must be protected**: use locks/transactions/queues as appropriate.
+- **Idempotency for retries**: requests and jobs should be safe to retry.
+
+## Design Principles (Strict)
+
+- **SRP**: split large classes/functions by responsibility.
+- **KISS**: prefer the simplest solution that meets requirements.
+- **DRY**: remove duplicated logic or clearly justify it.
+- **YAGNI**: no speculative features or “just in case” hooks.
+- **Composition over inheritance**: avoid deep inheritance chains.
+
+## Testing Requirements
+
+- **Critical paths covered**: happy path + failure path + edge cases.
+- **Concurrency tests**: required when shared state or ordering is involved.
+- **No flaky tests**: reject non‑deterministic tests.
+
+## Logging & Observability
+
+- **No sensitive data in logs**: redact secrets and PII.
+- **Log sparingly**: avoid noisy logs and repeated errors.
+- **Actionable logs**: include enough context to debug without leaking data.
+
+## Security Baseline
+
+- **Input validation** everywhere input crosses trust boundaries.
+- **Least privilege** for services, DB access, and API scopes.
+- **No unsafe defaults**: defaults must be secure, explicit opt‑in for risky behavior.
+
+## References
+
+- Google Engineering Practices – Code Review (reviewer): https://google.github.io/eng-practices/review/reviewer/
+- Google Engineering Practices – CL Author Guide: https://google.github.io/eng-practices/review/developer/
+- Google Style Guides (naming/style consistency): https://google.github.io/styleguide/
+- AOSP Code Style (strict rules + exceptions): https://source.android.com/docs/setup/contribute/code-style
+- Microsoft C# Coding Conventions (enforceable style): https://learn.microsoft.com/en-us/dotnet/csharp/fundamentals/coding-style/coding-conventions

package/Ai Agent Workflow/skills/database-design/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: database-design
+description: Database design principles and decision-making. Schema design, indexing strategy, ORM selection, serverless databases.
+allowed-tools: Read, Write, Edit, Glob, Grep
+---
+
+# Database Design
+
+> **Learn to THINK, not copy SQL patterns.**
+
+## 🎯 Selective Reading Rule
+
+**Read ONLY files relevant to the request!** Check the content map, find what you need.
+
+| File | Description | When to Read |
+|------|-------------|--------------|
+| `database-selection.md` | PostgreSQL vs Neon vs Turso vs SQLite | Choosing database |
+| `orm-selection.md` | Drizzle vs Prisma vs Kysely | Choosing ORM |
+| `schema-design.md` | Normalization, PKs, relationships | Designing schema |
+| `indexing.md` | Index types, composite indexes | Performance tuning |
+| `optimization.md` | N+1, EXPLAIN ANALYZE | Query optimization |
+| `migrations.md` | Safe migrations, serverless DBs | Schema changes |
+
+---
+
+## ⚠️ Core Principle
+
+- ASK user for database preferences when unclear
+- Choose database/ORM based on CONTEXT
+- Don't default to PostgreSQL for everything
+
+---
+
+## Decision Checklist
+
+Before designing schema:
+
+- [ ] Asked user about database preference?
+- [ ] Chosen database for THIS context?
+- [ ] Considered deployment environment?
+- [ ] Planned index strategy?
+- [ ] Defined relationship types?
+
+---
+
+## Anti-Patterns
+
+❌ Default to PostgreSQL for simple apps (SQLite may suffice)
+❌ Skip indexing
+❌ Use SELECT * in production
+❌ Store JSON when structured data is better
+❌ Ignore N+1 queries

package/Ai Agent Workflow/skills/database-design/database-selection.md

@@ -0,0 +1,43 @@
+# Database Selection (2025)
+
+> Choose database based on context, not default.
+
+## Decision Tree
+
+```
+What are your requirements?
+│
+├── Full relational features needed
+│   ├── Self-hosted → PostgreSQL
+│   └── Serverless → Neon, Supabase
+│
+├── Edge deployment / Ultra-low latency
+│   └── Turso (edge SQLite)
+│
+├── AI / Vector search
+│   └── PostgreSQL + pgvector
+│
+├── Simple / Embedded / Local
+│   └── SQLite
+│
+└── Global distribution
+    └── PlanetScale, CockroachDB, Turso
+```
+
+## Comparison
+
+| Database | Best For | Trade-offs |
+|----------|----------|------------|
+| **PostgreSQL** | Full features, complex queries | Needs hosting |
+| **Neon** | Serverless PG, branching | PG complexity |
+| **Turso** | Edge, low latency | SQLite limitations |
+| **SQLite** | Simple, embedded, local | Single-writer |
+| **PlanetScale** | MySQL, global scale | No foreign keys |
+
+## Questions to Ask
+
+1. What's the deployment environment?
+2. How complex are the queries?
+3. Is edge/serverless important?
+4. Vector search needed?
+5. Global distribution required?

package/Ai Agent Workflow/skills/database-design/indexing.md

@@ -0,0 +1,39 @@
+# Indexing Principles
+
+> When and how to create indexes effectively.
+
+## When to Create Indexes
+
+```
+Index these:
+├── Columns in WHERE clauses
+├── Columns in JOIN conditions
+├── Columns in ORDER BY
+├── Foreign key columns
+└── Unique constraints
+
+Don't over-index:
+├── Write-heavy tables (slower inserts)
+├── Low-cardinality columns
+├── Columns rarely queried
+```
+
+## Index Type Selection
+
+| Type | Use For |
+|------|---------|
+| **B-tree** | General purpose, equality & range |
+| **Hash** | Equality only, faster |
+| **GIN** | JSONB, arrays, full-text |
+| **GiST** | Geometric, range types |
+| **HNSW/IVFFlat** | Vector similarity (pgvector) |
+
+## Composite Index Principles
+
+```
+Order matters for composite indexes:
+├── Equality columns first
+├── Range columns last
+├── Most selective first
+└── Match query pattern
+```

package/Ai Agent Workflow/skills/database-design/migrations.md

@@ -0,0 +1,48 @@
+# Migration Principles
+
+> Safe migration strategy for zero-downtime changes.
+
+## Safe Migration Strategy
+
+```
+For zero-downtime changes:
+│
+├── Adding column
+│   └── Add as nullable → backfill → add NOT NULL
+│
+├── Removing column
+│   └── Stop using → deploy → remove column
+│
+├── Adding index
+│   └── CREATE INDEX CONCURRENTLY (non-blocking)
+│
+└── Renaming column
+    └── Add new → migrate data → deploy → drop old
+```
+
+## Migration Philosophy
+
+- Never make breaking changes in one step
+- Test migrations on data copy first
+- Have rollback plan
+- Run in transaction when possible
+
+## Serverless Databases
+
+### Neon (Serverless PostgreSQL)
+
+| Feature | Benefit |
+|---------|---------|
+| Scale to zero | Cost savings |
+| Instant branching | Dev/preview |
+| Full PostgreSQL | Compatibility |
+| Autoscaling | Traffic handling |
+
+### Turso (Edge SQLite)
+
+| Feature | Benefit |
+|---------|---------|
+| Edge locations | Ultra-low latency |
+| SQLite compatible | Simple |
+| Generous free tier | Cost |
+| Global distribution | Performance |

package/Ai Agent Workflow/skills/database-design/optimization.md

@@ -0,0 +1,36 @@
+# Query Optimization
+
+> N+1 problem, EXPLAIN ANALYZE, optimization priorities.
+
+## N+1 Problem
+
+```
+What is N+1?
+├── 1 query to get parent records
+├── N queries to get related records
+└── Very slow!
+
+Solutions:
+├── JOIN → Single query with all data
+├── Eager loading → ORM handles JOIN
+├── DataLoader → Batch and cache (GraphQL)
+└── Subquery → Fetch related in one query
+```
+
+## Query Analysis Mindset
+
+```
+Before optimizing:
+├── EXPLAIN ANALYZE the query
+├── Look for Seq Scan (full table scan)
+├── Check actual vs estimated rows
+└── Identify missing indexes
+```
+
+## Optimization Priorities
+
+1. **Add missing indexes** (most common issue)
+2. **Select only needed columns** (not SELECT *)
+3. **Use proper JOINs** (avoid subqueries when possible)
+4. **Limit early** (pagination at database level)
+5. **Cache** (when appropriate)

package/Ai Agent Workflow/skills/database-design/orm-selection.md

@@ -0,0 +1,30 @@
+# ORM Selection (2025)
+
+> Choose ORM based on deployment and DX needs.
+
+## Decision Tree
+
+```
+What's the context?
+│
+├── Edge deployment / Bundle size matters
+│   └── Drizzle (smallest, SQL-like)
+│
+├── Best DX / Schema-first
+│   └── Prisma (migrations, studio)
+│
+├── Maximum control
+│   └── Raw SQL with query builder
+│
+└── Python ecosystem
+    └── SQLAlchemy 2.0 (async support)
+```
+
+## Comparison
+
+| ORM | Best For | Trade-offs |
+|-----|----------|------------|
+| **Drizzle** | Edge, TypeScript | Newer, less examples |
+| **Prisma** | DX, schema management | Heavier, not edge-ready |
+| **Kysely** | Type-safe SQL builder | Manual migrations |
+| **Raw SQL** | Complex queries, control | Manual type safety |

package/Ai Agent Workflow/skills/database-design/schema-design.md

@@ -0,0 +1,56 @@
+# Schema Design Principles
+
+> Normalization, primary keys, timestamps, relationships.
+
+## Normalization Decision
+
+```
+When to normalize (separate tables):
+├── Data is repeated across rows
+├── Updates would need multiple changes
+├── Relationships are clear
+└── Query patterns benefit
+
+When to denormalize (embed/duplicate):
+├── Read performance critical
+├── Data rarely changes
+├── Always fetched together
+└── Simpler queries needed
+```
+
+## Primary Key Selection
+
+| Type | Use When |
+|------|----------|
+| **UUID** | Distributed systems, security |
+| **ULID** | UUID + sortable by time |
+| **Auto-increment** | Simple apps, single database |
+| **Natural key** | Rarely (business meaning) |
+
+## Timestamp Strategy
+
+```
+For every table:
+├── created_at → When created
+├── updated_at → Last modified
+└── deleted_at → Soft delete (if needed)
+
+Use TIMESTAMPTZ (with timezone) not TIMESTAMP
+```
+
+## Relationship Types
+
+| Type | When | Implementation |
+|------|------|----------------|
+| **One-to-One** | Extension data | Separate table with FK |
+| **One-to-Many** | Parent-children | FK on child table |
+| **Many-to-Many** | Both sides have many | Junction table |
+
+## Foreign Key ON DELETE
+
+```
+├── CASCADE → Delete children with parent
+├── SET NULL → Children become orphans
+├── RESTRICT → Prevent delete if children exist
+└── SET DEFAULT → Children get default value
+```