@nextsparkjs/ai-workflow 0.1.0-beta.100

package/claude/commands/session/db-fix.md

@@ -0,0 +1,212 @@
+# /session:db:fix
+
+Test and fix database migrations iteratively until success.
+
+---
+
+## Syntax
+
+```
+/session:db:fix [--migration <name>]
+```
+
+---
+
+## Behavior
+
+Runs migrations, detects errors, fixes them, and retries until successful.
+
+---
+
+## Flow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  /session:db:fix                                                 │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  1. Run pending migrations                                      │
+│     ↓                                                           │
+│  2. Check for errors                                            │
+│     │                                                           │
+│     ├─► No errors: Done                                         │
+│     │                                                           │
+│     └─► Errors found:                                           │
+│         ↓                                                       │
+│  3. Analyze error                                               │
+│     - Syntax error?                                             │
+│     - Missing reference?                                        │
+│     - Type mismatch?                                            │
+│     ↓                                                           │
+│  4. Apply fix                                                   │
+│     ↓                                                           │
+│  5. Go to step 1                                                │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Example Output
+
+```
+🗃️ FIX DATABASE MIGRATIONS
+
+─────────────────────────────────────────
+
+📋 ITERATION 1
+
+Running migrations...
+
+❌ Migration failed: 008_products.sql
+
+Error:
+ERROR: relation "categories" does not exist
+LINE 10: categoryId UUID REFERENCES categories(id),
+
+─────────────────────────────────────────
+
+🔍 ANALYZING ERROR
+
+Type: Missing foreign key reference
+Table: categories
+Required by: products.categoryId
+
+Analysis:
+- categories table not created yet
+- Need to create categories before products
+- Or make categoryId nullable without FK constraint
+
+Options:
+[1] Create categories migration first
+[2] Make categoryId nullable (no FK)
+[3] Remove categoryId field
+
+> 1
+
+─────────────────────────────────────────
+
+🔧 APPLYING FIX
+
+Creating: 007_categories.sql
+
+```sql
+CREATE TABLE categories (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    name VARCHAR(255) NOT NULL,
+    teamId UUID NOT NULL REFERENCES teams(id),
+    createdAt TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+ALTER TABLE categories ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY categories_team_isolation ON categories
+    USING (teamId = current_setting('app.current_team_id')::UUID);
+```
+
+✓ Migration created
+
+Renumbering: 008_products.sql → 008_products.sql (unchanged)
+
+─────────────────────────────────────────
+
+📋 ITERATION 2
+
+Running migrations...
+
+✓ 007_categories.sql executed
+✓ 008_products.sql executed
+
+─────────────────────────────────────────
+
+📊 SUMMARY
+
+Iterations: 2
+Migrations fixed: 1
+Migrations created: 1
+
+Database is now up to date.
+```
+
+---
+
+## Common Error Fixes
+
+| Error | Auto-Fix |
+|-------|----------|
+| Missing table reference | Create migration or reorder |
+| Syntax error | Fix SQL syntax |
+| Type mismatch | Cast or change type |
+| Duplicate key | Update or skip |
+| RLS policy error | Fix policy syntax |
+
+---
+
+## With Specific Migration
+
+```
+/session:db:fix --migration 008_products
+```
+
+Output:
+
+```
+🗃️ FIX MIGRATION: 008_products.sql
+
+─────────────────────────────────────────
+
+Running 008_products.sql...
+
+⚠️ Warning: Migration partially applied
+
+Issues:
+1. Table created
+2. Indexes created
+3. ❌ RLS policy failed
+
+Error:
+ERROR: policy "products_team_isolation" already exists
+
+─────────────────────────────────────────
+
+🔧 FIX OPTIONS
+
+[1] Drop and recreate policy
+[2] Skip policy (already exists)
+[3] Rename new policy
+
+> 2
+
+Skipping existing policy...
+✓ Migration completed with skip
+
+─────────────────────────────────────────
+
+Verifying database state...
+✓ Table: products exists
+✓ Columns: 9 columns correct
+✓ Indexes: 3 indexes present
+✓ RLS: Enabled with policies
+
+Database is consistent.
+```
+
+---
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--migration <name>` | Fix specific migration |
+| `--max-iterations <n>` | Max fix attempts (default: 5) |
+| `--dry-run` | Show fixes without applying |
+| `--reset` | Drop and recreate tables |
+
+---
+
+## Related Commands
+
+| Command | Action |
+|---------|--------|
+| `/session:db:entity` | Create entity migration |
+| `/session:db:sample` | Generate sample data |

package/claude/commands/session/db-sample.md

@@ -0,0 +1,206 @@
+# /session:db:sample
+
+Generate coherent sample data for database entities.
+
+---
+
+## Required Skills
+
+**[MANDATORY]** Read before executing:
+- `.claude/skills/database-migrations/SKILL.md` - Understand sample data patterns
+
+---
+
+## Syntax
+
+```
+/session:db:sample <entity-name> [--count <n>]
+```
+
+---
+
+## Behavior
+
+Creates realistic sample data that respects foreign keys and business rules.
+
+---
+
+## Flow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  /session:db:sample                                              │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  1. Read entity schema                                          │
+│     - Fields and types                                          │
+│     - Foreign key relationships                                 │
+│     ↓                                                           │
+│  2. Analyze existing data                                       │
+│     - Reference tables for FKs                                  │
+│     - Available team/user IDs                                   │
+│     ↓                                                           │
+│  3. Generate sample data                                        │
+│     - Realistic names/values                                    │
+│     - Valid FK references                                       │
+│     - Varied data distribution                                  │
+│     ↓                                                           │
+│  4. Create SQL insert statements                                │
+│     ↓                                                           │
+│  5. Add to migration or seed file                               │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Example Output
+
+```
+🌱 GENERATE SAMPLE DATA
+
+Entity: products
+Count: 20 records
+
+─────────────────────────────────────────
+
+🔍 ANALYZING SCHEMA
+
+Fields:
+├─ name: VARCHAR(255) NOT NULL
+├─ description: TEXT
+├─ price: DECIMAL(10,2) NOT NULL
+├─ categoryId: UUID FK → categories
+├─ isActive: BOOLEAN
+├─ teamId: UUID FK → teams
+└─ createdById: UUID FK → user
+
+Foreign Keys:
+├─ categories: 5 existing records
+├─ teams: 3 existing records
+└─ user: 10 existing records
+
+─────────────────────────────────────────
+
+📝 GENERATED DATA
+
+File: core/db/seeds/008_products_sample.sql
+
+```sql
+-- ============================================
+-- Sample Data: products
+-- Count: 20 records
+-- Generated: 2026-01-11
+-- ============================================
+
+-- Using existing references
+-- Teams: team_alpha, team_beta, team_gamma
+-- Categories: Electronics, Clothing, Home, Sports, Books
+
+INSERT INTO products (
+    id, name, description, price, categoryId,
+    isActive, teamId, createdById
+) VALUES
+    -- Team Alpha products (Electronics focus)
+    (
+        'prod-001-uuid',
+        'Wireless Bluetooth Headphones',
+        'Premium noise-cancelling headphones with 30h battery',
+        149.99,
+        (SELECT id FROM categories WHERE name = 'Electronics'),
+        true,
+        (SELECT id FROM teams WHERE name = 'Team Alpha'),
+        (SELECT id FROM "user" WHERE email = 'admin@test.com')
+    ),
+    (
+        'prod-002-uuid',
+        'Smart Watch Pro',
+        'Fitness tracker with heart rate monitor',
+        299.99,
+        (SELECT id FROM categories WHERE name = 'Electronics'),
+        true,
+        (SELECT id FROM teams WHERE name = 'Team Alpha'),
+        (SELECT id FROM "user" WHERE email = 'admin@test.com')
+    ),
+    -- ... 18 more records with varied data
+    (
+        'prod-020-uuid',
+        'Yoga Mat Premium',
+        'Non-slip eco-friendly yoga mat',
+        45.00,
+        (SELECT id FROM categories WHERE name = 'Sports'),
+        true,
+        (SELECT id FROM teams WHERE name = 'Team Gamma'),
+        (SELECT id FROM "user" WHERE email = 'member@test.com')
+    );
+```
+
+─────────────────────────────────────────
+
+📊 DATA DISTRIBUTION
+
+By Team:
+├─ Team Alpha: 8 products
+├─ Team Beta: 7 products
+└─ Team Gamma: 5 products
+
+By Category:
+├─ Electronics: 6 products
+├─ Clothing: 4 products
+├─ Home: 4 products
+├─ Sports: 4 products
+└─ Books: 2 products
+
+Price Range: $15.00 - $499.99
+Active: 18 | Inactive: 2
+
+─────────────────────────────────────────
+
+✓ Sample data created: 008_products_sample.sql
+
+Run migration to insert data.
+```
+
+---
+
+## With Test Users
+
+Generates data distributed across test users from devKeyring:
+
+```
+/session:db:sample products --with-devkeyring
+```
+
+```sql
+-- Data for DevKeyring users
+INSERT INTO products (teamId, createdById, ...)
+VALUES
+    -- superadmin@test.com (sees all)
+    (..., (SELECT id FROM "user" WHERE email = 'superadmin@test.com')),
+
+    -- admin@test.com (Team Alpha)
+    (..., (SELECT id FROM "user" WHERE email = 'admin@test.com')),
+
+    -- member@test.com (Team Beta, limited role)
+    (..., (SELECT id FROM "user" WHERE email = 'member@test.com'));
+```
+
+---
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--count <n>` | Number of records (default: 20) |
+| `--with-devkeyring` | Use test users from devKeyring |
+| `--append` | Add to existing seed file |
+| `--dry-run` | Show SQL without creating |
+
+---
+
+## Related Commands
+
+| Command | Action |
+|---------|--------|
+| `/session:db:entity` | Create entity migration |
+| `/session:db:fix` | Fix data issues |

package/claude/commands/session/demo.md

@@ -0,0 +1,178 @@
+# /session:demo
+
+Run a live visual demo of the implemented feature.
+
+---
+
+## Syntax
+
+```
+/session:demo [--record]
+```
+
+---
+
+## Behavior
+
+Opens a browser and demonstrates the implemented feature visually using Playwright.
+
+---
+
+## Flow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  /session:demo                                                   │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  1. Load session context                                        │
+│     - Read requirements.md (ACs)                                │
+│     - Read plan.md (features)                                   │
+│     ↓                                                           │
+│  2. Start dev server (if not running)                           │
+│     ↓                                                           │
+│  3. Launch browser with Playwright                              │
+│     ↓                                                           │
+│  4. Execute demo flow                                           │
+│     - Navigate to relevant pages                                │
+│     - Demonstrate each AC                                       │
+│     - Explain what's happening                                  │
+│     ↓                                                           │
+│  5. Generate demo summary                                       │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Example Output
+
+```
+🎬 SESSION DEMO
+
+Session: stories/2026-01-11-new-products-entity
+ACs to demonstrate: 5
+
+─────────────────────────────────────────
+
+🚀 STARTING DEMO
+
+Starting dev server...
+✓ Server running at http://localhost:3000
+
+Launching browser...
+✓ Browser ready
+
+─────────────────────────────────────────
+
+📋 DEMO: AC1 - Create Product
+
+[Browser] Navigating to /dashboard/products
+[Browser] Clicking "New Product" button
+[Browser] Filling form:
+  - Name: "Demo Product"
+  - Price: 99.99
+  - Description: "Test product for demo"
+[Browser] Clicking "Save"
+
+✓ Product created successfully
+
+─────────────────────────────────────────
+
+📋 DEMO: AC2 - Upload Images
+
+[Browser] Clicking "Add Images"
+[Browser] Selecting test image
+[Browser] Uploading...
+
+✓ Image uploaded and displayed
+
+─────────────────────────────────────────
+
+📋 DEMO: AC3 - Assign Categories
+
+[Browser] Opening category selector
+[Browser] Selecting "Electronics"
+[Browser] Saving changes
+
+✓ Category assigned
+
+─────────────────────────────────────────
+
+📊 DEMO SUMMARY
+
+ACs Demonstrated: 5/5
+Issues Found: 0
+Screenshots: 5 saved to _tmp/demo/
+
+Demo complete!
+```
+
+---
+
+## With Recording
+
+```
+/session:demo --record
+```
+
+Output:
+
+```
+🎬 SESSION DEMO (RECORDING)
+
+Recording to: _tmp/demo/2026-01-11-products-demo.mp4
+
+[Recording started]
+...
+[Recording stopped]
+
+✓ Video saved: _tmp/demo/2026-01-11-products-demo.mp4
+Duration: 2:34
+```
+
+---
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--record` | Record demo as video |
+| `--ac <number>` | Demo specific AC only |
+| `--mobile` | Demo in mobile viewport |
+| `--slow` | Slow down actions for visibility |
+
+---
+
+## Demo Configuration
+
+In session's `demo.config.json`:
+
+```json
+{
+  "baseUrl": "http://localhost:3000",
+  "credentials": {
+    "email": "admin@test.com",
+    "password": "Test1234"
+  },
+  "flows": [
+    {
+      "ac": "AC1",
+      "steps": [
+        { "action": "navigate", "path": "/dashboard/products" },
+        { "action": "click", "selector": "[data-cy=new-product]" }
+      ]
+    }
+  ]
+}
+```
+
+---
+
+## Related Commands
+
+| Command | Action |
+|---------|--------|
+| `/session:explain` | Explain code implementation |
+| `/session:validate` | Validate before demo |
+| `/session:close` | Close session |