@nextsparkjs/ai-workflow 0.1.0-beta.100

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 |

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

@@ -0,0 +1,218 @@
+# /session:doc:feature
+
+Generate comprehensive documentation for a completed feature.
+
+---
+
+## Required Skills
+
+**[MANDATORY]** Read before executing:
+- `.claude/skills/documentation/SKILL.md` - Documentation structure and format
+
+---
+
+## Syntax
+
+```
+/session:doc:feature [--format <format>]
+```
+
+---
+
+## Behavior
+
+Creates feature documentation by analyzing session files and implementation.
+
+---
+
+## Flow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  /session:doc:feature                                            │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  1. Load session context                                        │
+│     - requirements.md                                           │
+│     - plan.md                                                   │
+│     - scope.json                                                │
+│     ↓                                                           │
+│  2. Analyze implementation                                      │
+│     - Read modified files                                       │
+│     - Extract key patterns                                      │
+│     ↓                                                           │
+│  3. Generate documentation                                      │
+│     - Overview                                                  │
+│     - API reference                                             │
+│     - Usage examples                                            │
+│     - Configuration                                             │
+│     ↓                                                           │
+│  4. Add to documentation system                                 │
+│     ↓                                                           │
+│  5. Update navigation                                           │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Example Output
+
+```
+📚 GENERATE FEATURE DOCUMENTATION
+
+Session: stories/2026-01-11-new-products-entity
+Feature: Products Management
+
+─────────────────────────────────────────
+
+🔍 ANALYZING SESSION
+
+From requirements.md:
+├─ 5 Acceptance Criteria
+└─ 3 PM Decisions
+
+From scope.json:
+├─ 12 files modified
+├─ API: 5 endpoints
+└─ UI: 4 components
+
+─────────────────────────────────────────
+
+📝 GENERATING DOCUMENTATION
+
+File: docs/features/products.md
+
+```markdown
+---
+title: Products Management
+description: Complete guide to the products entity and management system
+category: features
+order: 5
+---
+
+# Products Management
+
+The products system provides complete CRUD functionality for
+managing products with categories, images, and team isolation.
+
+## Overview
+
+Products are team-scoped entities that support:
+- Basic information (name, description, price)
+- Category assignment
+- Image uploads (max 5)
+- Active/inactive status
+
+## Quick Start
+
+### Creating a Product
+
+```typescript
+// Using the API
+const response = await fetch('/api/v1/products', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'Authorization': `Bearer ${apiKey}`
+  },
+  body: JSON.stringify({
+    name: 'My Product',
+    price: 99.99,
+    categoryId: 'cat-uuid'
+  })
+});
+```
+
+### Using the UI
+
+1. Navigate to Dashboard > Products
+2. Click "New Product"
+3. Fill in the required fields
+4. Upload images (optional)
+5. Click "Save"
+
+## API Reference
+
+### Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | /api/v1/products | List products |
+| GET | /api/v1/products/:id | Get product |
+| POST | /api/v1/products | Create product |
+| PATCH | /api/v1/products/:id | Update product |
+| DELETE | /api/v1/products/:id | Delete product |
+
+### Query Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| page | number | Page number |
+| limit | number | Items per page |
+| categoryId | uuid | Filter by category |
+| isActive | boolean | Filter by status |
+
+## Configuration
+
+### Entity Config
+
+Location: `core/config/entities/products.ts`
+
+```typescript
+export const productsEntity: EntityConfig = {
+  name: 'products',
+  displayName: 'Products',
+  icon: 'Package',
+  fields: {
+    // Field definitions
+  }
+};
+```
+
+## Permissions
+
+| Role | Create | Read | Update | Delete |
+|------|--------|------|--------|--------|
+| Admin | ✓ | ✓ | ✓ | ✓ |
+| Member | - | ✓ | - | - |
+| Viewer | - | ✓ | - | - |
+```
+
+─────────────────────────────────────────
+
+📁 FILE CREATED
+
+Location: docs/features/products.md
+Words: 450
+Sections: 6
+
+Updating navigation...
+✓ Added to docs sidebar
+
+─────────────────────────────────────────
+
+Preview: http://localhost:3000/docs/features/products
+
+✓ Documentation generated successfully
+```
+
+---
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--format <format>` | md, mdx, or notion |
+| `--api-only` | Only API documentation |
+| `--no-examples` | Skip code examples |
+
+---
+
+## Related Commands
+
+| Command | Action |
+|---------|--------|
+| `/session:doc:read` | Read existing docs |
+| `/session:doc:bdd` | Generate BDD docs |
+| `/session:close` | Close session |

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

@@ -0,0 +1,225 @@
+# /session:doc:read
+
+Gain context by reading documentation before working on a task.
+
+---
+
+## Syntax
+
+```
+/session:doc:read [topic] [--skill <name>]
+```
+
+---
+
+## Behavior
+
+Reads relevant documentation and skills to understand project patterns before development.
+
+---
+
+## Flow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  /session:doc:read                                               │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  1. Determine what to read                                      │
+│     - Topic provided?                                           │
+│     - Skill specified?                                          │
+│     - Infer from session context?                               │
+│     ↓                                                           │
+│  2. Locate relevant files                                       │
+│     - Skills (SKILL.md)                                         │
+│     - Documentation (docs/)                                     │
+│     - Architecture files (.rules/)                              │
+│     ↓                                                           │
+│  3. Read and summarize                                          │
+│     ↓                                                           │
+│  4. Present key information                                     │
+│     - Patterns to follow                                        │
+│     - Anti-patterns to avoid                                    │
+│     - Related files                                             │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Example: Read Topic
+
+```
+/session:doc:read authentication
+```
+
+Output:
+
+```
+📚 DOCUMENTATION: Authentication
+
+─────────────────────────────────────────
+
+📖 RELEVANT SKILLS
+
+## better-auth (SKILL.md)
+
+Key patterns:
+- Session-based auth for web app
+- API key auth for external access
+- Dual auth: both methods per endpoint
+
+```typescript
+// Dual auth pattern
+const { user, team } = await authenticateRequest(req, {
+  allowApiKey: true,
+  allowSession: true
+});
+```
+
+Anti-patterns:
+- DON'T use only session auth for API endpoints
+- DON'T skip team context validation
+
+─────────────────────────────────────────
+
+## api-bypass-layers (SKILL.md)
+
+Multi-layer security:
+1. Authentication layer
+2. Authorization layer
+3. Team context layer
+4. RLS layer
+
+Bypass rules:
+- Superadmin bypasses team context
+- Developer API key bypasses for testing
+
+─────────────────────────────────────────
+
+📖 RELATED DOCUMENTATION
+
+docs/features/authentication.md
+- Overview of auth flows
+- Token management
+- OAuth providers
+
+docs/architecture/security.md
+- Security best practices
+- OWASP guidelines
+
+─────────────────────────────────────────
+
+📖 KEY FILES
+
+core/lib/auth/
+├─ session.ts - Session management
+├─ api-key.ts - API key validation
+└─ middleware.ts - Auth middleware
+
+─────────────────────────────────────────
+
+📌 SUMMARY FOR DEVELOPMENT
+
+When implementing auth-related features:
+1. Use authenticateRequest() helper
+2. Enable both session AND API key
+3. Always validate team context
+4. RLS handles data isolation
+
+Questions? Ask about specific patterns.
+```
+
+---
+
+## Example: Read Skill
+
+```
+/session:doc:read --skill entity-system
+```
+
+Output:
+
+```
+📚 SKILL: entity-system
+
+─────────────────────────────────────────
+
+## Overview
+
+Config-driven entity system for automatic CRUDs.
+Creates API, UI, and types from configuration.
+
+## Key Files
+
+When creating an entity:
+1. config.ts - Entity configuration
+2. fields.ts - Field definitions
+3. schema.ts - Zod validation
+4. service.ts - Business logic (optional)
+5. messages.ts - i18n translations
+
+## Pattern Example
+
+```typescript
+// core/config/entities/products.ts
+export const productsEntity: EntityConfig = {
+  name: 'products',
+  table: 'products',
+  displayName: 'Products',
+  fields: {
+    name: { type: 'string', required: true },
+    price: { type: 'number', required: true },
+  }
+};
+```
+
+## Anti-Patterns
+
+- DON'T use snake_case in field names
+- DON'T skip RLS configuration
+- DON'T create custom API when entity system works
+
+## Related Skills
+
+- database-migrations
+- service-layer
+- nextjs-api-development
+```
+
+---
+
+## Auto-Read for Session
+
+When starting a session, relevant docs are auto-suggested:
+
+```
+📚 SUGGESTED READING
+
+Based on session "new-products-entity":
+
+1. entity-system (SKILL) - How to create entities
+2. database-migrations (SKILL) - Migration patterns
+3. cypress-api (SKILL) - API testing
+
+Read now? [Yes, all / Select specific / Skip]
+```
+
+---
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--skill <name>` | Read specific skill |
+| `--all` | Read all related docs |
+| `--brief` | Summary only |
+
+---
+
+## Related Commands
+
+| Command | Action |
+|---------|--------|
+| `/session:doc:feature` | Generate feature docs |
+| `/session:start` | Start session (auto-reads) |