@nextsparkjs/ai-workflow 0.1.0-beta.86

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 |

package/claude/commands/session/doc-bdd.md

@@ -0,0 +1,207 @@
+# /session:doc:bdd
+
+Generate BDD documentation (.bdd.md) from Cypress tests.
+
+---
+
+## Required Skills
+
+**[MANDATORY]** Read before executing:
+- `.claude/skills/cypress-api/SKILL.md` - Understand API test structure
+- `.claude/skills/cypress-e2e/SKILL.md` - Understand UAT test structure
+- `.claude/skills/documentation/SKILL.md` - Documentation patterns
+
+---
+
+## Syntax
+
+```
+/session:doc:bdd [--spec <pattern>]
+```
+
+---
+
+## Behavior
+
+Creates human-readable BDD documentation from existing Cypress test files.
+
+---
+
+## Flow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  /session:doc:bdd                                                │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  1. Find Cypress test files                                     │
+│     ↓                                                           │
+│  2. Parse test structure                                        │
+│     - describe blocks                                           │
+│     - it statements                                             │
+│     - grep tags                                                 │
+│     ↓                                                           │
+│  3. Generate Gherkin scenarios                                  │
+│     - Feature description                                       │
+│     - Scenarios from tests                                      │
+│     - Multi-locale support                                      │
+│     ↓                                                           │
+│  4. Create .bdd.md files                                        │
+│     ↓                                                           │
+│  5. Update test registry                                        │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Example Output
+
+```
+📝 GENERATE BDD DOCUMENTATION
+
+Session: stories/2026-01-11-new-products-entity
+
+─────────────────────────────────────────
+
+🔍 FINDING TEST FILES
+
+Spec pattern: cypress/e2e/**/*products*.cy.ts
+
+Found:
+├─ cypress/e2e/api/products.cy.ts (12 tests)
+└─ cypress/e2e/uat/products.cy.ts (8 tests)
+
+─────────────────────────────────────────
+
+📝 PARSING: products.cy.ts (API)
+
+Extracting structure...
+├─ describe: "@api @products Products API"
+│   ├─ describe: "@crud CRUD Operations"
+│   │   ├─ it: "@create should create a product"
+│   │   ├─ it: "@read should get product by ID"
+│   │   └─ ...
+│   └─ describe: "@auth Authentication"
+│       └─ ...
+
+─────────────────────────────────────────
+
+📝 GENERATING BDD
+
+File: cypress/e2e/api/products.bdd.md
+
+```markdown
+# Products API
+
+**File:** `cypress/e2e/api/products.cy.ts`
+**Tags:** `@api` `@products`
+
+## Feature: Products CRUD Operations
+
+As an API consumer
+I want to manage products via REST API
+So that I can integrate product management into my application
+
+### Scenario: Create a new product
+**Tags:** `@api` `@crud` `@create`
+
+```gherkin
+Given I am authenticated with a valid API key
+When I POST to /api/v1/products with valid data
+  | name        | Test Product |
+  | price       | 99.99        |
+  | categoryId  | {category}   |
+Then the response status should be 201
+And the response should contain the created product
+And the product should have a generated UUID
+```
+
+### Scenario: Get product by ID
+**Tags:** `@api` `@crud` `@read`
+
+```gherkin
+Given a product exists with ID {productId}
+When I GET /api/v1/products/{productId}
+Then the response status should be 200
+And the response should contain the product details
+```
+
+### Scenario: Reject unauthenticated request
+**Tags:** `@api` `@auth` `@unauthorized`
+
+```gherkin
+Given I am not authenticated
+When I POST to /api/v1/products
+Then the response status should be 401
+And the response should contain "Unauthorized"
+```
+
+---
+
+## Multi-Locale Support (en, es)
+
+### Scenario: Create a new product
+
+**English:**
+```gherkin
+Given I am authenticated with a valid API key
+When I POST to /api/v1/products with valid data
+Then the response status should be 201
+```
+
+**Español:**
+```gherkin
+Dado que estoy autenticado con una API key válida
+Cuando hago POST a /api/v1/products con datos válidos
+Entonces el código de respuesta debe ser 201
+```
+```
+
+─────────────────────────────────────────
+
+📁 FILES CREATED
+
+├─ cypress/e2e/api/products.bdd.md
+└─ cypress/e2e/uat/products.bdd.md
+
+─────────────────────────────────────────
+
+📊 SUMMARY
+
+Tests documented: 20
+Scenarios generated: 20
+Locales: 2 (en, es)
+
+BDD documentation complete.
+```
+
+---
+
+## BDD Format
+
+Each `.bdd.md` file includes:
+
+1. **Feature header** - File reference and tags
+2. **Feature description** - User story format
+3. **Scenarios** - Gherkin format with tags
+4. **Multi-locale** - Translations if configured
+
+---
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--spec <pattern>` | Specific test files |
+| `--locale <code>` | Generate for specific locale |
+| `--update` | Update existing BDD files |
+
+---
+
+## Related Commands
+
+| Command | Action |
+|---------|--------|
+| `/session:test:write` | Write Cypress tests |
+| `/session:doc:feature` | Feature documentation |