bobs-workshop 0.3.3 → 3.1.0

package/src/skills/database-design/SKILL.md

@@ -0,0 +1,271 @@
+---
+name: database-design
+description: Database design principles and decision-making. Schema design, indexing strategy, ORM selection, serverless databases.
+---
+
+# Database Design
+
+> Data modeling principles and best practices for relational and non-relational databases.
+
+---
+
+## Database Selection Framework
+
+### When to Use Each Type
+
+| Database Type | Best For | Examples |
+|---------------|-----------|-----------|
+| **Relational (SQL)** | Structured data, complex queries, ACID requirements | PostgreSQL, MySQL, SQLite |
+| **Document (NoSQL)** | Flexible schema, hierarchical data, rapid iteration | MongoDB, CouchDB |
+| **Key-Value** | High-speed lookups, caching, simple queries | Redis, DynamoDB |
+| **Graph** | Complex relationships, social networks, recommendations | Neo4j, ArangoDB |
+| **Time-Series** | Metrics, monitoring, IoT data | InfluxDB, TimescaleDB |
+| **Serverless** | Low-traffic apps, pay-per-use, no maintenance | Neon, PlanetScale, Supabase |
+
+### Selection Questions
+
+1. **Data Structure**: Structured (SQL) vs. flexible (NoSQL)?
+2. **Query Complexity**: Simple lookups (NoSQL) vs. complex joins (SQL)?
+3. **ACID Requirements**: Need transactions (SQL) vs. eventual consistency OK (NoSQL)?
+4. **Scale**: Small-medium (SQL) vs. massive scale (NoSQL)?
+5. **Team Expertise**: What does the team know?
+
+---
+
+## Schema Design Principles
+
+### Normalization vs. Denormalization
+
+| Approach | When to Use | Pros | Cons |
+|----------|-------------|-------|-------|
+| **Normalized** | OLTP systems, data integrity, frequent writes | No redundancy, consistent | More joins, slower reads |
+| **Denormalized** | OLAP systems, read-heavy, fast queries needed | Fast reads, simple | Redundant data, updates hard |
+
+**Rule**: Start normalized, denormalize when you have data proving it helps.
+
+---
+
+### Table Design Best Practices
+
+| Principle | Rule | Example |
+|-----------|------|---------|
+| **Primary Keys** | Always have one, prefer UUIDs over auto-increment | `id UUID PRIMARY KEY` |
+| **Foreign Keys** | Use for relationships, add indexes | `user_id UUID REFERENCES users(id)` |
+| **Timestamps** | Always track created_at, updated_at | `created_at TIMESTAMP DEFAULT NOW()` |
+| **Soft Deletes** | Use deleted_at instead of DELETE | `deleted_at TIMESTAMP NULL` |
+| **Not NULL** | Use when data is required | `name VARCHAR(255) NOT NULL` |
+| **Defaults** | Use for common values | `status VARCHAR(20) DEFAULT 'active'` |
+
+---
+
+### Naming Conventions
+
+| Element | Convention | Example |
+|---------|-------------|---------|
+| **Tables** | snake_case, plural | `users`, `user_sessions` |
+| **Columns** | snake_case, singular | `user_id`, `created_at` |
+| **Primary Keys** | `id` | `id UUID PRIMARY KEY` |
+| **Foreign Keys** | `{table}_id` | `user_id`, `post_id` |
+| **Indexes** | `idx_{table}_{columns}` | `idx_users_email` |
+| **Constraints** | `chk_{table}_{rule}` | `chk_users_email_format` |
+
+---
+
+## Indexing Strategy
+
+### When to Add Indexes
+
+| Scenario | Action |
+|----------|--------|
+| WHERE clause column | Add index |
+| JOIN column | Add index |
+| ORDER BY column | Add index |
+| Frequently queried column | Add index |
+
+### Index Types
+
+| Type | Best For | Example |
+|-------|-----------|---------|
+| **B-Tree** | Most queries (default) | `CREATE INDEX idx_users_email ON users(email)` |
+| **Hash** | Exact equality only | `CREATE INDEX idx_cache ON cache USING HASH (key)` |
+| **Composite** | Multiple columns together | `CREATE INDEX idx_posts_user_date ON posts(user_id, created_at)` |
+| **Partial** | Filtered index | `CREATE INDEX idx_active ON users(id) WHERE status = 'active'` |
+| **Full-Text** | Text search | `CREATE INDEX idx_search ON posts USING GIN (content)` |
+
+### Index Best Practices
+
+| Principle | Rule |
+|-----------|------|
+| **Don't over-index** | Indexes slow down writes |
+| **Index foreign keys** | Always index `user_id`, `post_id`, etc. |
+| **Composite order matters** | Put most selective column first |
+| **Analyze slow queries** | Use `EXPLAIN ANALYZE` to find missing indexes |
+
+---
+
+## ORM Selection
+
+### When to Use ORM
+
+| Tool | Best For | Pros | Cons |
+|-------|----------|-------|-------|
+| **Prisma** | TypeScript, type-safe, migrations | Type-safe, great DX | Learning curve, build step |
+| **TypeORM** | TypeScript, flexible, decorators | Flexible, mature | Performance overhead |
+| **Sequelize** | JavaScript, Promise-based | Mature, battle-tested | TypeScript support limited |
+| **Drizzle** | TypeScript, SQL-like, no magic | Fast, minimal | Manual migrations |
+| **Raw SQL** | Performance critical, complex queries | Max control, fastest | No safety, verbose |
+
+### Selection Guide
+
+- **TypeScript + Type Safety**: Prisma, Drizzle
+- **JavaScript + Flexibility**: Sequelize, TypeORM
+- **Performance Critical**: Raw SQL, Drizzle
+- **Rapid Prototyping**: Prisma (best DX)
+
+---
+
+## Migration Strategy
+
+### Migration Tools
+
+| Tool | Database | Features |
+|------|----------|-----------|
+| **Liquibase** | Any DB | Version control, rollback support |
+| **Flyway** | Any DB | Simple, SQL-based |
+| **Prisma Migrate** | PostgreSQL, MySQL | Type-safe, auto-generate |
+| **Alembic** | Python/PostgreSQL | Flexible, widely used |
+
+### Best Practices
+
+| Practice | Rule |
+|----------|------|
+| **Version control migrations** | Always commit migration files |
+| **Reversible migrations** | Always write `up` and `down` |
+| **Test migrations** | Run on test DB before prod |
+| **Never edit committed migrations** | Create new migration instead |
+| **Rollback plan** | Know how to rollback every migration |
+
+---
+
+## Performance Optimization
+
+### Query Optimization
+
+| Issue | Solution |
+|-------|----------|
+| Slow SELECT | Add index, use EXPLAIN ANALYZE |
+| N+1 queries | Use eager loading (JOIN/include) |
+| Large result sets | Use pagination (LIMIT/OFFSET or cursor) |
+| Full table scans | Add index, optimize WHERE clause |
+| Complex joins | Consider denormalization or materialized views |
+
+### Connection Pooling
+
+| Tool | Recommended Pool Size |
+|-------|---------------------|
+| PostgreSQL (pg) | 10-20 per app instance |
+| MySQL (mysql2) | 10-20 per app instance |
+| MongoDB | 10-50 per app instance |
+
+---
+
+## Data Integrity
+
+### Constraints
+
+| Constraint | Purpose | Example |
+|------------|----------|---------|
+| **NOT NULL** | Data must have value | `email VARCHAR(255) NOT NULL` |
+| **UNIQUE** | No duplicates | `email VARCHAR(255) UNIQUE` |
+| **CHECK** | Validation rules | `CHECK (age >= 18)` |
+| **FOREIGN KEY** | Referential integrity | `FOREIGN KEY (user_id) REFERENCES users(id)` |
+| **EXCLUDE** | Advanced exclusions | `EXCLUDE USING gist (period WITH &&)` |
+
+### Transactions
+
+```sql
+BEGIN;
+-- Multiple operations
+INSERT INTO orders (...) VALUES (...);
+UPDATE inventory SET quantity = quantity - 1 WHERE ...;
+COMMIT; -- or ROLLBACK on error
+```
+
+---
+
+## Bob's Workshop Integration
+
+This skill is used by **alice (architect)** agent during PLAN phase and **bob-eng (engineer)** during BUILD phase.
+
+### MANUAL Integration
+
+Add database section to MANUAL:
+```markdown
+## 🏗️ Architecture Analysis
+
+### Database Design
+
+#### Database Selection
+- **Type:** [PostgreSQL / MongoDB / Redis / etc.]
+- **Rationale:** [Why this database?]
+- **ORM:** [Prisma / TypeORM / Raw SQL / etc.]
+- **Migration Tool:** [Prisma Migrate / Liquibase / Flyway / etc.]
+
+#### Schema Overview
+
+```
+[ER Diagram]
+┌─────────────┐       ┌─────────────┐
+│    users    │       │    posts    │
+├─────────────┤       ├─────────────┤
+│ id (PK)     │◀──────│ id (PK)     │
+│ email       │       │ user_id (FK) │
+│ ...         │       │ title       │
+└─────────────┘       │ ...         │
+                      └─────────────┘
+```
+
+#### Tables
+
+**users**
+| Column | Type | Constraints | Index |
+|--------|------|-------------|--------|
+| id | UUID | PRIMARY KEY | idx_users_id |
+| email | VARCHAR(255) | UNIQUE, NOT NULL | idx_users_email |
+| ... | ... | ... | ... |
+
+#### Relationships
+- `users.id` ← `posts.user_id` (One-to-Many)
+- `users.id` ← `comments.user_id` (One-to-Many)
+```
+
+### Implementation Tasks
+
+```markdown
+#### DB-001: Database Schema
+- [ ] Create `users` table → Verify: Schema matches design
+- [ ] Create `posts` table → Verify: Has foreign key to users
+- [ ] Add indexes → Verify: Queries run efficiently
+- [ ] Write migration → Verify: `npm run migrate` succeeds
+- [ ] Add rollback migration → Verify: `npm run migrate:down` works
+```
+
+### Testing Strategy
+
+```markdown
+#### DB-TEST-001: Database Tests
+- [ ] Test CRUD operations → Verify: Insert/read/update/delete work
+- [ ] Test constraints → Verify: NOT NULL, UNIQUE enforced
+- [ ] Test foreign keys → Verify: Cascade delete works
+- [ ] Test indexes → Verify: Queries use indexes (EXPLAIN)
+- [ ] Test transactions → Verify: Rollback works on error
+```
+
+### Handoff Format
+
+```markdown
+## 🤝 Agent Handoffs
+
+🤝 alice: Database schema designed - PostgreSQL + Prisma
+🤝 alice → bob-eng: Schema ready, proceeding to implementation
+```

package/src/skills/exploration/SKILL.md

@@ -0,0 +1,257 @@
+---
+name: exploration
+description: LSP-powered codebase exploration covering all architectural layers. Use for systematic code navigation, definition tracing, and architectural understanding.
+---
+
+# Exploration Skill
+
+Comprehensive LSP and search-based codebase exploration for understanding architecture across all layers: Database, Backend, Integrations, Frontend, and UI/UX.
+
+## When to Use
+
+- Before implementing new features (bob-arc)
+- When navigating unfamiliar code (bob-eng)
+- During debugging to trace execution paths (bob-fix)
+- When reviewing code for architectural compliance (bob-rev)
+
+## Core Tools
+
+### LSP Navigation
+```
+LspDefinition: Jump to where a symbol is defined
+LspReferences: Find all places a symbol is used
+LspHover: Get type information and documentation
+```
+
+### Search Tools
+```
+grep: Pattern search across codebase (use rg for speed)
+glob: Find files by path pattern
+Semantic Search: Find code by meaning when exact text unknown
+```
+
+### MCP Tools (if available)
+```
+grep-app: High-speed grep across entire project
+context7: Documentation lookup for frameworks
+```
+
+## Layer-Specific Exploration
+
+### 🗄️ Database Layer
+
+**Find schemas and migrations**:
+```bash
+glob("**/migrations/**", "**/schema/**", "**/*.sql")
+glob("**/prisma/**", "**/drizzle/**", "**/typeorm/**")
+```
+
+**Find models/entities**:
+```bash
+grep("Model|Entity|Schema|Table|@Entity|@Table", "src/")
+grep("createTable|alterTable|addColumn", "migrations/")
+```
+
+**Trace relationships**:
+```bash
+grep("@ManyToOne|@OneToMany|@ManyToMany|references|foreignKey", "src/")
+LspReferences on entity classes
+```
+
+### 🔧 Backend Layer
+
+**Find services and controllers**:
+```bash
+grep("Service|Controller|Handler|@Injectable", "src/")
+glob("**/services/**", "**/controllers/**", "**/handlers/**")
+```
+
+**Find API routes**:
+```bash
+grep("router\.|app\.(get|post|put|delete|patch)", "src/")
+grep("@Get|@Post|@Put|@Delete|@Controller", "src/")
+```
+
+**Find middleware and auth**:
+```bash
+grep("middleware|authenticate|authorize|guard", "src/")
+grep("jwt|token|session|passport", "src/")
+```
+
+**Trace service dependencies**:
+```bash
+LspDefinition on service imports
+LspReferences on service methods
+```
+
+### 🔗 Integration Layer
+
+**Find external API clients**:
+```bash
+grep("fetch|axios|http|request|client", "src/")
+glob("**/lib/**", "**/clients/**", "**/api/**")
+```
+
+**Find configuration**:
+```bash
+glob("**/.env*", "**/config/**", "**/*.config.*")
+grep("process\.env|config\.", "src/")
+```
+
+**Find deployment files**:
+```bash
+glob("**/Dockerfile", "**/docker-compose*", "**/*.yml")
+glob("**/.github/workflows/**", "**/ci/**")
+```
+
+### 🎨 Frontend Layer
+
+**Find components**:
+```bash
+glob("**/components/**", "**/pages/**", "**/views/**")
+glob("**/*.tsx", "**/*.vue", "**/*.svelte")
+```
+
+**Find state management**:
+```bash
+grep("useState|useReducer|useContext|createContext", "src/")
+grep("createStore|createSlice|atom|store", "src/")
+glob("**/store/**", "**/stores/**", "**/state/**")
+```
+
+**Find routing**:
+```bash
+grep("Route|router|navigate|Link|useRouter", "src/")
+glob("**/routes/**", "**/pages/**")
+```
+
+**Trace component hierarchy**:
+```bash
+LspReferences on component names
+grep("import.*from.*components", "src/")
+```
+
+### 🎯 UI/UX Layer
+
+**Find styles**:
+```bash
+glob("**/*.css", "**/*.scss", "**/*.less")
+glob("**/styles/**", "**/css/**")
+grep("className|styled|css|tw", "src/")
+```
+
+**Find design tokens**:
+```bash
+glob("**/theme/**", "**/tokens/**")
+grep("colors|spacing|typography|breakpoints", "src/")
+```
+
+**Find assets**:
+```bash
+glob("**/assets/**", "**/public/**", "**/images/**")
+glob("**/*.svg", "**/*.png", "**/*.ico")
+```
+
+## Exploration Patterns
+
+### Pattern 1: Trace a Feature End-to-End
+
+```markdown
+1. Start at UI: Find component handling user interaction
+   glob("**/components/**/*Button*")
+   
+2. Trace to handler: Find what the button calls
+   LspDefinition on onClick handler
+   
+3. Follow to service: Find API call
+   LspDefinition on service method
+   
+4. Trace to backend: Find API endpoint
+   grep("POST /api/feature", "src/")
+   
+5. Follow to database: Find data operations
+   LspDefinition on repository/model methods
+```
+
+### Pattern 2: Understand a Module
+
+```markdown
+1. Find module entry point
+   glob("**/[module]/index.ts")
+   
+2. List all exports
+   grep("export", "[module]/index.ts")
+   
+3. Find all usages
+   LspReferences on module exports
+   
+4. Understand dependencies
+   grep("import.*from", "[module]/")
+```
+
+### Pattern 3: Find Integration Points
+
+```markdown
+1. Find where module is imported
+   grep("from.*[module]", "src/")
+   
+2. Find interface definitions
+   grep("interface.*[Module]", "src/")
+   
+3. Find implementations
+   LspReferences on interface
+   
+4. Find tests (show expected behavior)
+   glob("**/*.test.*", "**/*.spec.*")
+   grep("[module]", "tests/")
+```
+
+## Best Practices
+
+### Be Systematic
+- Start broad, narrow down
+- Explore all layers, not just the obvious one
+- Document what you find
+
+### Be Thorough
+- Trace symbols to their definitions
+- Find all references, not just the first
+- Check test files for behavior documentation
+
+### Understand Intent
+- Read function/class comments
+- Look at test descriptions
+- Check commit history for context
+
+### Identify Patterns
+- Note recurring coding styles
+- Identify architectural decisions
+- Document conventions for consistency
+
+## Output Format
+
+When reporting exploration findings:
+
+```markdown
+## Exploration: [What was explored]
+
+### Files Discovered
+- `path/to/file.ts` - [Purpose/Role]
+- `path/to/file.ts` - [Purpose/Role]
+
+### Key Patterns Identified
+1. [Pattern name]: [Description]
+2. [Pattern name]: [Description]
+
+### Dependencies Mapped
+- [Module A] → [Module B]: [Relationship]
+- [Module A] → [Module C]: [Relationship]
+
+### Insights for Implementation
+- [Insight 1]
+- [Insight 2]
+```
+
+---
+
+**Remember**: Good exploration prevents bad implementation. Time spent understanding the codebase pays dividends in code that fits naturally with existing patterns.

package/src/skills/frontend-ui-ux/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: frontend-ui-ux
+description: Designer-turned-developer who crafts stunning UI/UX even without design mockups
+---
+
+# Role: Designer-Turned-Developer
+
+You are a designer who learned to code. You see what pure developers miss—spacing, color harmony, micro-interactions, that indefinable "feel" that makes interfaces memorable. Even without mockups, you envision and create beautiful, cohesive interfaces.
+
+**Mission**: Create visually stunning, emotionally engaging interfaces users fall in love with. Obsess over pixel-perfect details, smooth animations, and intuitive interactions while maintaining code quality.
+
+---
+
+# Work Principles
+
+1. **Complete what's asked** — Execute the exact task. No scope creep. Work until it works. Never mark work complete without proper verification.
+2. **Leave it better** — Ensure the project is in a working state after your changes.
+3. **Study before acting** — Examine existing patterns, conventions, and commit history (git log) before implementing. Understand why code is structured the way it is.
+4. **Blend seamlessly** — Match existing code patterns. Your code should look like the team wrote it.
+5. **Be transparent** — Announce each step. Explain reasoning. Report both successes and failures.
+
+---
+
+# Design Process
+
+Before coding, commit to a **BOLD aesthetic direction**:
+
+1. **Purpose**: What problem does this solve? Who uses it?
+2. **Tone**: Pick an extreme—brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian
+3. **Constraints**: Technical requirements (framework, performance, accessibility)
+4. **Differentiation**: What's the ONE thing someone will remember?
+
+**Key**: Choose a clear direction and execute with precision. Intentionality > intensity.
+
+Then implement working code (HTML/CSS/JS, React, Vue, Angular, etc.) that is:
+- Production-grade and functional
+- Visually striking and memorable
+- Cohesive with a clear aesthetic point-of-view
+- Meticulously refined in every detail
+
+---
+
+# Aesthetic Guidelines
+
+## Typography
+Choose distinctive fonts. **Avoid**: Arial, Inter, Roboto, system fonts, Space Grotesk. Pair a characterful display font with a refined body font.
+
+## Color
+Commit to a cohesive palette. Use CSS variables. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. **Avoid**: purple gradients on white (AI slop).
+
+## Motion
+Focus on high-impact moments. One well-orchestrated page load with staggered reveals (animation-delay) > scattered micro-interactions. Use scroll-triggering and hover states that surprise. Prioritize CSS-only. Use Motion library for React when available.
+
+## Spatial Composition
+Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
+
+## Visual Details
+Create atmosphere and depth—gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, grain overlays. Never default to solid colors.
+
+---
+
+# Anti-Patterns (NEVER)
+
+- Generic fonts (Inter, Roboto, Arial, system fonts, Space Grotesk)
+- Cliched color schemes (purple gradients on white)
+- Predictable layouts and component patterns
+- Cookie-cutter design lacking context-specific character
+- Converging on common choices across generations
+
+---
+
+# Execution
+
+Match implementation complexity to aesthetic vision:
+- **Maximalist** → Elaborate code with extensive animations and effects
+- **Minimalist** → Restraint, precision, careful spacing and typography
+
+Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. You are capable of extraordinary creative work—don't hold back.