@nextsparkjs/ai-workflow 0.1.0-beta.86

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 |

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

@@ -0,0 +1,182 @@
+# /session:fix:build
+
+Fix build errors automatically.
+
+---
+
+## Syntax
+
+```
+/session:fix:build [--max-iterations <n>]
+```
+
+---
+
+## Behavior
+
+Automatically diagnoses and fixes build errors in a loop until the build passes.
+
+---
+
+## Flow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  /session:fix:build                                              │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  1. Run build                                                   │
+│     ↓                                                           │
+│  2. Parse errors                                                │
+│     - TypeScript errors                                         │
+│     - Import errors                                             │
+│     - Config errors                                             │
+│     ↓                                                           │
+│  3. Categorize by type                                          │
+│     - Type mismatch                                             │
+│     - Missing import                                            │
+│     - Missing dependency                                        │
+│     - Syntax error                                              │
+│     ↓                                                           │
+│  4. Fix each error                                              │
+│     - Apply targeted fix                                        │
+│     ↓                                                           │
+│  5. Re-run build                                                │
+│     │                                                           │
+│     ├─► Errors remain: Go to step 2                             │
+│     │                                                           │
+│     └─► Build passes: Done                                      │
+│     ↓                                                           │
+│  6. Show summary                                                │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Example Output
+
+```
+🔧 FIX BUILD ERRORS
+
+─────────────────────────────────────────
+
+📋 ITERATION 1
+
+Running build...
+❌ Build failed with 5 errors
+
+Errors:
+1. TS2345: products.ts:23 - Type mismatch
+2. TS2307: ProductForm.tsx:5 - Missing import
+3. TS2307: ProductForm.tsx:8 - Missing import
+4. TS2339: ProductList.tsx:45 - Property does not exist
+5. TS2345: ProductService.ts:12 - Type mismatch
+
+─────────────────────────────────────────
+
+🔧 FIXING ERRORS
+
+[1/5] products.ts:23 - Type mismatch
+      Fix: Cast to correct type
+      ✓ Fixed
+
+[2/5] ProductForm.tsx:5 - Missing import
+      Fix: Add import for 'useForm'
+      ✓ Fixed
+
+[3/5] ProductForm.tsx:8 - Missing import
+      Fix: Add import for 'zodResolver'
+      ✓ Fixed
+
+[4/5] ProductList.tsx:45 - Property does not exist
+      Fix: Update property name
+      ✓ Fixed
+
+[5/5] ProductService.ts:12 - Type mismatch
+      Fix: Update function signature
+      ✓ Fixed
+
+─────────────────────────────────────────
+
+📋 ITERATION 2
+
+Running build...
+✓ Build successful
+
+─────────────────────────────────────────
+
+📊 SUMMARY
+
+Iterations: 2
+Errors fixed: 5
+Files modified: 4
+
+Build is now passing.
+```
+
+---
+
+## With Max Iterations
+
+```
+/session:fix:build --max-iterations 3
+```
+
+Output when limit reached:
+
+```
+🔧 FIX BUILD ERRORS
+
+─────────────────────────────────────────
+
+📋 ITERATION 3
+
+Running build...
+❌ Build failed with 2 errors
+
+⚠️ MAX ITERATIONS REACHED
+
+Remaining errors:
+1. TS2322: complex-type.ts:45 - Complex type error
+2. TS2339: api-handler.ts:23 - Missing property
+
+These errors may require manual intervention.
+
+Options:
+[1] Continue fixing (increase limit)
+[2] Show detailed error analysis
+[3] Stop and fix manually
+```
+
+---
+
+## Error Categories
+
+| Category | Auto-Fix | Example |
+|----------|----------|---------|
+| Missing import | Yes | `import { X } from 'y'` |
+| Type mismatch | Usually | Cast or update type |
+| Syntax error | Usually | Missing bracket, etc. |
+| Missing property | Sometimes | Add property to interface |
+| Complex type | Manual | Generic constraints |
+
+---
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--max-iterations <n>` | Max fix attempts (default: 5) |
+| `--dry-run` | Show fixes without applying |
+| `--verbose` | Show detailed fix reasoning |
+
+---
+
+## Related Commands
+
+| Command | Action |
+|---------|--------|
+| `/session:fix:test` | Fix failing tests |
+| `/session:fix:bug` | Fix reported bug |
+| `/session:validate` | Full validation |