@nextsparkjs/ai-workflow 0.1.0-beta.86

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) |

package/claude/commands/session/execute.md

@@ -0,0 +1,204 @@
+# /session:execute
+
+Execute the development of the active session.
+
+**Aliases:** `/execute`
+
+---
+
+## Workflow Detection
+
+**[MANDATORY]** Before executing, determine the workflow type:
+
+1. Check session path:
+   - `stories/*` → STORY workflow
+   - `tasks/*` → TASK workflow
+   - No session files → TWEAK workflow
+
+2. Read `progress.md` (if exists) for current phase
+
+3. Adapt execution based on workflow type
+
+---
+
+## Syntax
+
+```
+/session:execute [--from-phase <phase>]
+```
+
+---
+
+## Behavior
+
+Continues workflow execution from the current phase (or from a specific phase).
+
+---
+
+## Flow by Workflow
+
+### TWEAK
+
+```
+Does not use /session:execute
+Development is direct without phases.
+```
+
+### TASK
+
+```
+/session:execute
+
+1. Read requirements.md
+2. Implement changes
+   - Call subagents if needed
+3. Validate
+   - Build passes?
+   - Tests pass?
+4. Update progress.md
+5. Ready for commit
+```
+
+### STORY
+
+```
+/session:execute
+
+1. Read progress.md (current phase)
+2. Execute next phase:
+   - Call corresponding subagent
+   - Wait for result
+   - Validate gate (if applicable)
+3. Update progress.md
+4. Repeat until complete or blocker
+```
+
+---
+
+## Example: TASK
+
+```
+🚀 EXECUTING: improve-search
+
+Reading requirements.md...
+✓ 3 ACs defined
+
+─────────────────────────────────────────
+
+📋 EXECUTION PLAN
+
+1. [ ] Optimize query in SearchService
+2. [ ] Add index in DB
+3. [ ] Update tests
+
+─────────────────────────────────────────
+
+Starting implementation...
+
+[backend-developer] Optimizing SearchService...
+✓ Query optimized
+
+[backend-developer] Verifying build...
+✓ Build successful
+
+─────────────────────────────────────────
+
+📊 PROGRESS: 66%
+
+- [x] Optimize query
+- [x] Add index
+- [ ] Update tests
+
+Continue with tests? [Yes/Pause]
+```
+
+---
+
+## Example: STORY
+
+```
+🚀 EXECUTING: new-products-entity
+
+Session: stories/2026-01-11-new-products-entity
+Iteration: 02-scope-change
+
+─────────────────────────────────────────
+
+📊 CURRENT STATE
+
+Completed phase: backend-validator [PASS]
+Current phase: api-tester
+
+─────────────────────────────────────────
+
+Starting Phase 9: api-tester...
+
+[api-tester] Running API tests...
+├─ POST /api/v1/products     ✓
+├─ GET /api/v1/products      ✓
+├─ GET /api/v1/products/:id  ✓
+├─ PATCH /api/v1/products/:id ✓
+└─ DELETE /api/v1/products/:id ✓
+
+[api-tester] Result: 5/5 tests passed
+
+─────────────────────────────────────────
+
+✓ GATE PASSED: api-tester
+
+Next phase: frontend-developer
+Continue? [Yes/Pause]
+```
+
+---
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--from-phase <phase>` | Start from specific phase |
+| `--skip-gates` | Skip gate validation (not recommended) |
+| `--dry-run` | Show what would be done without executing |
+
+---
+
+## Error Handling
+
+### Failed Gate
+
+```
+❌ GATE FAILED: backend-validator
+
+Errors found:
+- TypeScript error in products.ts:45
+- Test failing: products.test.ts
+
+Options:
+[1] Call backend-developer to fix
+[2] Fix manually
+[3] Pause execution
+```
+
+### Blocker
+
+```
+🚫 BLOCKER DETECTED
+
+The api-tester subagent reported:
+"API endpoint /products returns 500"
+
+Options:
+[1] Create new iteration (blocked)
+[2] Call backend-developer
+[3] Pause and review manually
+```
+
+---
+
+## Related Commands
+
+| Command | Action |
+|---------|--------|
+| `/session:status` | View current state |
+| `/session:scope-change` | If there's a scope change |
+| `/session:close` | When finished |