@nextsparkjs/ai-workflow 0.1.0-beta.100

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 |

package/claude/commands/session/explain.md

@@ -0,0 +1,202 @@
+# /session:explain
+
+Provide an interactive walkthrough of the implemented code.
+
+---
+
+## Syntax
+
+```
+/session:explain [--file <path>] [--concept <name>]
+```
+
+---
+
+## Behavior
+
+Explains the implementation details of the current session, walking through key files and decisions.
+
+---
+
+## Flow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  /session:explain                                                │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  1. Load session context                                        │
+│     - Read scope.json (modified files)                          │
+│     - Read plan.md (decisions)                                  │
+│     ↓                                                           │
+│  2. Organize explanation                                        │
+│     - Group by layer (DB/API/UI)                                │
+│     - Order by importance                                       │
+│     ↓                                                           │
+│  3. Walk through implementation                                 │
+│     - Show key code sections                                    │
+│     - Explain patterns used                                     │
+│     - Highlight decisions                                       │
+│     ↓                                                           │
+│  4. Answer questions (interactive)                              │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Example Output
+
+```
+📚 CODE WALKTHROUGH
+
+Session: stories/2026-01-11-new-products-entity
+Files modified: 12
+
+─────────────────────────────────────────
+
+## 1. DATABASE LAYER
+
+### Migration: 008_products.sql
+
+```sql
+CREATE TABLE products (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  name VARCHAR(255) NOT NULL,
+  price DECIMAL(10,2) NOT NULL,
+  -- Using camelCase per project conventions
+  categoryId UUID REFERENCES categories(id),
+  createdAt TIMESTAMPTZ DEFAULT NOW()
+);
+```
+
+**Why these choices:**
+- UUID for distributed ID generation
+- DECIMAL for precise currency handling
+- TIMESTAMPTZ for timezone awareness
+
+─────────────────────────────────────────
+
+## 2. BACKEND LAYER
+
+### Entity Config: products.ts
+
+```typescript
+export const productsEntity: EntityConfig = {
+  name: 'products',
+  table: 'products',
+  fields: {
+    name: { type: 'string', required: true },
+    price: { type: 'number', required: true },
+    // ...
+  }
+};
+```
+
+**Pattern:** Using the entity config system for automatic:
+- CRUD API generation
+- Form schema generation
+- Type inference
+
+─────────────────────────────────────────
+
+## 3. FRONTEND LAYER
+
+### ProductForm.tsx
+
+```typescript
+export function ProductForm({ product }: Props) {
+  const { mutate, isPending } = useEntityMutation('products');
+  // Using TanStack Query pattern from project
+}
+```
+
+**Pattern:** Standard form component following:
+- Controlled inputs with react-hook-form
+- Zod validation from entity schema
+- Optimistic updates
+
+─────────────────────────────────────────
+
+Questions? Type your question or press Enter to continue.
+> Why did you use DECIMAL instead of FLOAT for price?
+
+DECIMAL provides exact precision for financial calculations.
+FLOAT can have rounding errors (e.g., 0.1 + 0.2 = 0.30000000000000004).
+For money, we need exact values, so DECIMAL(10,2) ensures
+exactly 2 decimal places with no rounding issues.
+
+More questions? [Type question or Enter to finish]
+```
+
+---
+
+## Explain Specific File
+
+```
+/session:explain --file core/services/ProductsService.ts
+```
+
+Output:
+
+```
+📚 FILE EXPLANATION
+
+File: core/services/ProductsService.ts
+Lines: 45
+Purpose: Custom business logic for products
+
+─────────────────────────────────────────
+
+## Overview
+
+This service extends BaseEntityService to add
+custom price calculation logic.
+
+## Key Sections
+
+### Lines 12-25: Price Calculation
+
+```typescript
+calculateFinalPrice(product: Product, discount: number): number {
+  const basePrice = product.price;
+  const discountAmount = basePrice * (discount / 100);
+  return Math.round((basePrice - discountAmount) * 100) / 100;
+}
+```
+
+**Why:** Centralizes pricing logic for consistency.
+The rounding ensures no floating point issues.
+
+### Lines 30-40: Validation
+
+```typescript
+async validateProduct(data: ProductInput): Promise<void> {
+  if (data.price <= 0) {
+    throw new ValidationError('Price must be positive');
+  }
+}
+```
+
+**Why:** Business rule enforcement at service layer,
+not just form validation.
+```
+
+---
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--file <path>` | Explain specific file |
+| `--concept <name>` | Explain specific concept/pattern |
+| `--detailed` | Include all files, not just key ones |
+
+---
+
+## Related Commands
+
+| Command | Action |
+|---------|--------|
+| `/session:demo` | Visual demonstration |
+| `/session:review` | Code review |

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

@@ -0,0 +1,210 @@
+# /session:fix:bug
+
+Fix a bug with a simplified workflow.
+
+**Aliases:** `/fix`
+
+---
+
+## Workflow Detection
+
+**[MANDATORY]** This command determines workflow based on complexity:
+
+| Evaluation | Workflow | Session |
+|------------|----------|---------|
+| XS-S (1-3 files, low risk) | TWEAK | tweaks/ |
+| M+ (4+ files or high risk) | TASK | tasks/ |
+
+---
+
+## Syntax
+
+```
+/session:fix:bug <description>
+```
+
+---
+
+## Behavior
+
+Optimized workflow for bug fixes:
+1. **Analyze** the bug
+2. **Determine** T-Shirt size
+3. **Implement** fix
+4. **Validate** no regressions
+5. **Create** test to prevent recurrence
+
+---
+
+## Flow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  /session:fix:bug                                                │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  1. Analyze bug description                                     │
+│     - Where does it occur?                                      │
+│     - How to reproduce?                                         │
+│     - What is the expected behavior?                            │
+│     ↓                                                           │
+│  2. Search related code                                         │
+│     - Grep for relevant terms                                   │
+│     - Identify affected files                                   │
+│     ↓                                                           │
+│  3. Evaluate complexity                                         │
+│     │                                                           │
+│     ├─► XS-S (1-3 files): TWEAK workflow                        │
+│     │   - Direct fix                                            │
+│     │   - Validate build/tests                                  │
+│     │                                                           │
+│     └─► M+ (4+ files or risk): TASK workflow                │
+│         - Create task session                                   │
+│         - Document analysis                                     │
+│         - Fix with tests                                        │
+│     ↓                                                           │
+│  4. Implement fix                                               │
+│     ↓                                                           │
+│  5. Validate                                                    │
+│     - Build passes                                              │
+│     - Existing tests pass                                       │
+│     - Bug reproduced → fixed                                    │
+│     ↓                                                           │
+│  6. Create regression test (if doesn't exist)                   │
+│     ↓                                                           │
+│  7. Ready for commit                                            │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Example
+
+```
+/session:fix:bug The submit button doesn't disable during submission
+```
+
+Output:
+
+```
+🐛 ANALYZING BUG
+
+Description: The submit button doesn't disable during submission
+
+─────────────────────────────────────────
+
+🔍 ANALYSIS
+
+Searching related code...
+├─ "submit" in components... 5 files
+├─ "disabled" in forms... 3 files
+└─ "loading" state... 2 files
+
+Probable file:
+core/components/forms/SubmitButton.tsx
+
+─────────────────────────────────────────
+
+📐 EVALUATION
+
+Affected files: ~2
+Risk: Low (UI only)
+T-Shirt: XS
+
+Workflow: TWEAK
+
+─────────────────────────────────────────
+
+🔧 IMPLEMENTING FIX
+
+[Reading SubmitButton.tsx]
+[Identifying problem: missing isLoading prop]
+[Applying fix...]
+
+─────────────────────────────────────────
+
+✅ VALIDATION
+
+- Build: ✓ Passes
+- Tests: ✓ 45/45 pass
+- Visual: Button now disables
+
+─────────────────────────────────────────
+
+📝 REGRESSION TEST
+
+Create test to prevent recurrence? [Yes/No]
+
+> Yes
+
+Creating test in __tests__/components/SubmitButton.test.tsx
+✓ Test created
+
+─────────────────────────────────────────
+
+✓ Bug fixed. Ready for commit.
+```
+
+---
+
+## With Complex Bug
+
+```
+🐛 ANALYZING BUG
+
+Description: Orders are not being calculated correctly
+
+─────────────────────────────────────────
+
+🔍 ANALYSIS
+
+Searching related code...
+├─ "order" in services... 8 files
+├─ "calculate" in orders... 3 files
+└─ "total" in cart... 4 files
+
+Probable files:
+- core/services/orders.ts
+- core/services/cart.ts
+- core/api/orders/route.ts
+
+─────────────────────────────────────────
+
+📐 EVALUATION
+
+Affected files: ~6
+Risk: HIGH (affects revenue)
+T-Shirt: M
+
+⚠️ ALERT: This bug affects critical flow (Orders)
+
+Recommended workflow: TASK
+
+─────────────────────────────────────────
+
+Proceed with TASK workflow? [Yes/Use TWEAK]
+
+> Yes
+
+Creating task session: tasks/2026-01-11-fix-order-calculation
+```
+
+---
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--quick` | Force TWEAK workflow |
+| `--with-test` | Always create regression test |
+| `--no-test` | Don't create test (not recommended) |
+
+---
+
+## Related Commands
+
+| Command | Action |
+|---------|--------|
+| `/session:fix:build` | Fix build errors |
+| `/session:fix:test` | Fix failing tests |