jettypod 4.1.4 → 4.1.6

package/skills-templates/speed-mode/SKILL.md

@@ -5,6 +5,19 @@ description: Guide implementation of speed mode chores with autonomous code anal
 
 # Speed Mode Skill
 
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│  Mode Progression Flow                                               │
+│                                                                      │
+│  Feature Planning → [SPEED MODE] → Stable Mode → Production Mode     │
+│                      ▲▲▲▲▲▲▲▲▲▲▲                                     │
+│                      YOU ARE HERE                                    │
+│                                                                      │
+│  Next: After implementation, this skill generates stable mode        │
+│        chores and elevates the feature to stable mode.               │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
 Guides Claude Code through speed mode implementation with autonomous analysis and execution. Users confirm approach but Claude Code writes the code.
 
 ## Instructions
@@ -20,13 +33,30 @@ When this skill is activated, you are helping implement a speed mode chore to ma
 - **Assume happy path** - assume inputs are valid, files upload successfully, types are correct
 - **No error handling** - no validation, no edge case handling, no error messages (that's for stable mode)
 - **Fast iteration** - single file when possible, inline code over abstraction
-- **Pragmatic** - localStorage for data, simple implementations
+- **Use real infrastructure** - use the actual database/storage from your tech stack, not mocks
 - **Autonomous execution** - Claude Code writes code, user confirms approach
 
 **User Profile:** May not know how to code - Claude Code does the implementation autonomously.
 
 ---
 
+## Quick Reference: Async Boundaries
+
+**Where Claude Code MUST wait for user confirmation:**
+
+| Phase | Location | Why |
+|-------|----------|-----|
+| Step 3 Phase 1 | Before implementing | User confirms implementation approach |
+| Step 4 Phase 2 | Before creating chores | User confirms proposed stable mode chores |
+
+**Where Claude Code executes autonomously:**
+- Step 1: Scenario analysis
+- Step 2: Codebase analysis
+- Step 3 Phase 2: RED→GREEN→REFACTOR loop
+- Step 4 Phases 3-4: Create chores and elevate
+
+---
+
 ## ⚠️ CRITICAL: Speed Mode Workflow Requirements
 
 **DO NOT mark features as complete after speed mode implementation.**
@@ -57,6 +87,11 @@ The validation will require you to:
 
 ## Implementation Steps
 
+<!-- ═══════════════════════════════════════════════════════════════════════════
+     PHASE 1: AUTONOMOUS ANALYSIS
+     No user input required - Claude Code executes independently
+     ═══════════════════════════════════════════════════════════════════════════ -->
+
 ### Step 1: Check for Breadcrumbs and Analyze Scenario
 
 **CRITICAL:** Claude Code executes this autonomously - no user permission needed.
@@ -71,32 +106,42 @@ The validation will require you to:
 **Code to check for breadcrumbs:**
 
 ```javascript
+// --- Setup and imports ---
 const { getCurrentWork } = require('../../lib/current-work');
 const { getDb } = require('../../lib/database');
 const fs = require('fs');
 const path = require('path');
 
-const currentWork = getCurrentWork();
-
-// Check if description has breadcrumbs from feature-planning
-const hasBreadcrumbs = currentWork.description &&
-  currentWork.description.includes('Scenario steps addressed:') &&
-  currentWork.description.includes('Implementation guidance:') &&
-  currentWork.description.includes('Verification:');
+(async () => {
+  const currentWork = await getCurrentWork();
+
+  // --- Check for breadcrumbs ---
+  const hasBreadcrumbs = currentWork.description &&
+    currentWork.description.includes('Scenario steps addressed:') &&
+    currentWork.description.includes('Implementation guidance:') &&
+    currentWork.description.includes('Verification:');
+
+  // --- Get parent feature from database ---
+  const db = getDb();
+  const feature = await new Promise((resolve, reject) => {
+    db.get('SELECT * FROM work_items WHERE id = ?', [currentWork.parent_id], (err, row) => {
+      if (err) reject(err);
+      else resolve(row);
+    });
+  });
 
-// Get parent feature
-const db = getDb();
-db.get('SELECT * FROM work_items WHERE id = ?', [currentWork.parent_id], (err, feature) => {
+  // --- Validate scenario file exists ---
   if (!feature.scenario_file) {
     console.error('No scenario file found for this feature');
     return;
   }
 
+  // --- Read scenario content ---
   const scenarioPath = path.join(process.cwd(), feature.scenario_file);
   const scenarioContent = fs.readFileSync(scenarioPath, 'utf8');
 
   // Parse and analyze...
-});
+})();
 ```
 
 **Parse Gherkin:**
@@ -227,6 +272,11 @@ Now proposing implementation approach...
 
 **Move to Step 3 automatically.**
 
+<!-- ═══════════════════════════════════════════════════════════════════════════
+     PHASE 2: USER CONFIRMATION REQUIRED
+     ⚡ ASYNC BOUNDARY - Must wait for user response before proceeding
+     ═══════════════════════════════════════════════════════════════════════════ -->
+
 ### Step 3: Propose and Execute Implementation
 
 **Two phases: Propose (get user confirmation) → Execute (autonomous)**
@@ -259,6 +309,11 @@ Sound good? I'll implement this autonomously once you confirm.
 
 If user adjusts: revise proposal and confirm again.
 
+<!-- ═══════════════════════════════════════════════════════════════════════════
+     PHASE 3: AUTONOMOUS EXECUTION
+     User has confirmed - Claude Code executes RED→GREEN loop independently
+     ═══════════════════════════════════════════════════════════════════════════ -->
+
 #### Phase 2: Autonomous Execution
 
 **CRITICAL:** After user confirms, Claude Code executes autonomously - no permission needed for individual code changes.
@@ -268,15 +323,23 @@ If user adjusts: revise proposal and confirm again.
 Before writing any implementation code, run tests to establish the RED state:
 
 ```javascript
-const { runBddTestWithTimeout, runBddScenarioWithTimeout, getFirstScenarioLine, parseTestProgress, extractErrors } = require('./.claude/skills/speed-mode/test-runner');
+// --- Imports ---
+const { runBddScenarioWithTimeout, getFirstScenarioLine, parseTestProgress, extractErrors } = require('./.claude/skills/speed-mode/test-runner');
 const { getCurrentWork } = require('./lib/current-work');
 const { getDb } = require('./lib/database');
 
-const currentWork = getCurrentWork();
-const db = getDb();
+(async () => {
+  // --- Get current work and parent feature ---
+  const currentWork = await getCurrentWork();
+  const db = getDb();
+
+  const feature = await new Promise((resolve, reject) => {
+    db.get('SELECT * FROM work_items WHERE id = ?', [currentWork.parent_id], (err, row) => {
+      if (err) reject(err);
+      else resolve(row);
+    });
+  });
 
-// Get parent feature and its scenario file
-db.get('SELECT * FROM work_items WHERE id = ?', [currentWork.parent_id], async (err, feature) => {
   if (!feature.scenario_file) {
     console.error('No scenario file found for this feature');
     return;
@@ -284,28 +347,31 @@ db.get('SELECT * FROM work_items WHERE id = ?', [currentWork.parent_id], async (
 
   console.log('🔴 Establishing RED baseline...\n');
 
-  // Find happy path scenario (first scenario in file)
+  // --- Find happy path scenario ---
   const happyPathLine = getFirstScenarioLine(feature.scenario_file);
   if (!happyPathLine) {
     console.error('No scenario found in feature file');
     return;
   }
 
-  // Run only happy path scenario before any code is written
+  // --- Run tests before implementation ---
   const result = await runBddScenarioWithTimeout(feature.scenario_file, happyPathLine);
+  let progress = { passed: 0, total: 0, failedSteps: [] };
 
+  // --- Handle timeout ---
   if (result.timedOut) {
     console.log('⚠️  Test execution timed out - tests may be hanging');
     console.log('Proceeding with implementation...\n');
   } else {
-    // Parse the test output
-    const progress = parseTestProgress(result.stdout + result.stderr);
+    // --- Parse and display results ---
+    progress = parseTestProgress(result.stdout + result.stderr);
     const errors = extractErrors(result.stdout + result.stderr);
 
     console.log(`RED Baseline: ${progress.total - progress.passed} of ${progress.total} steps failing`);
     console.log('\nFailing steps:');
     progress.failedSteps.forEach(step => console.log(`  ✖ ${step}`));
 
+    // --- Show first error ---
     if (errors.errors.length > 0) {
       console.log('\nFirst error:');
       const firstError = errors.errors[0];
@@ -316,13 +382,13 @@ db.get('SELECT * FROM work_items WHERE id = ?', [currentWork.parent_id], async (
     console.log('\n🎯 Goal: Make all steps pass\n');
   }
 
-  // Store baseline for comparison in iteration loop (chore #115)
+  // --- Store baseline for iteration loop ---
   global.redBaseline = {
     passed: progress.passed,
     total: progress.total,
     failedSteps: progress.failedSteps
   };
-});
+})();
 ```
 
 **Display RED baseline:**
@@ -351,39 +417,54 @@ Now implementing...
 
 Iterate until all tests pass or MAX_ITERATIONS reached:
 
+<!-- ┌─────────────────────────────────────────────────────────────────────────┐
+     │ 🔄 ITERATION LOOP: RED→GREEN                                           │
+     │                                                                         │
+     │ Progress Tracking:                                                      │
+     │ • Display: "Iteration X/10" at start of each cycle                     │
+     │ • Track: steps passing vs total, newly passing steps                   │
+     │ • Goal: All steps pass (exit code 0)                                   │
+     │                                                                         │
+     │ Return Points:                                                          │
+     │ • CHECKPOINT_ITERATION: Resume at specific iteration number            │
+     │ • CHECKPOINT_PROGRESS: Resume with known passing step count            │
+     │ • If session interrupted, can resume from last known iteration         │
+     └─────────────────────────────────────────────────────────────────────────┘ -->
+
 ```javascript
+// --- Imports and setup ---
 const { runBddScenarioWithTimeout, parseTestProgress, findNewlyPassingSteps, extractErrors, MAX_ITERATIONS } = require('./.claude/skills/speed-mode/test-runner');
 
 let previousResult = global.redBaseline; // From Step 1
 let iteration = 0;
 
+// --- Main iteration loop ---
+// 📊 PROGRESS: Iteration {iteration}/{MAX_ITERATIONS} | Steps: {passed}/{total}
 while (iteration < MAX_ITERATIONS) {
   iteration++;
-
   console.log(`\n━━━ Iteration ${iteration}/${MAX_ITERATIONS} ━━━`);
 
-  // 1. Make code changes based on current failure
+  // --- Make code changes ---
   console.log(`\n✍️  Making code changes...`);
   // [Claude Code writes implementation code here using Write/Edit tools]
 
-  // 2. Run tests - only happy path scenario during iteration
+  // --- Run tests ---
   console.log(`\n🧪 Running tests...`);
   const result = await runBddScenarioWithTimeout(feature.scenario_file, happyPathLine);
 
+  // --- Handle timeout ---
   if (result.timedOut) {
     console.log(`⚠️  Test execution timed out - tests may be hanging`);
     console.log(`Stopping iteration loop`);
     break;
   }
 
-  // 3. Parse results
+  // --- Parse results and track progress ---
   const currentResult = parseTestProgress(result.stdout + result.stderr);
   const errors = extractErrors(result.stdout + result.stderr);
-
-  // 4. Track progress
   const newlyPassing = findNewlyPassingSteps(previousResult, currentResult);
 
-  // 5. Display progress
+  // --- Display progress ---
   console.log(`\n📊 Progress: ${currentResult.passed}/${currentResult.total} steps passing`);
 
   if (newlyPassing.length > 0) {
@@ -391,20 +472,20 @@ while (iteration < MAX_ITERATIONS) {
     newlyPassing.forEach(step => console.log(`  • ${step}`));
   }
 
-  // 6. Check if all tests pass (GREEN state achieved)
+  // --- Check for GREEN state ---
   if (currentResult.exitCode === 0 || currentResult.passed === currentResult.total) {
     console.log(`\n🎉 GREEN: All tests passing!`);
     break;
   }
 
-  // 7. Display next failure to address
+  // --- Display next failure ---
   if (errors.errors.length > 0) {
     const nextError = errors.errors[0];
     console.log(`\n🔧 Next failure to address:`);
     console.log(`  Step: ${nextError.step}`);
     console.log(`  Error: ${nextError.message}`);
     if (nextError.stack) {
-      console.log(`  Stack: ${nextError.stack.split('\n')[0]}`); // First line only
+      console.log(`  Stack: ${nextError.stack.split('\n')[0]}`);
     }
   } else if (currentResult.failedSteps.length > 0) {
     console.log(`\n🔧 Still failing:`);
@@ -414,11 +495,10 @@ while (iteration < MAX_ITERATIONS) {
     }
   }
 
-  // Store for next iteration comparison
   previousResult = currentResult;
 }
 
-// After loop ends
+// --- Handle max iterations reached ---
 if (iteration >= MAX_ITERATIONS) {
   console.log(`\n⚠️  Maximum iterations (${MAX_ITERATIONS}) reached without achieving GREEN`);
   console.log(`Final progress: ${previousResult.passed}/${previousResult.total} steps passing`);
@@ -489,13 +569,33 @@ Modified src/dashboard.js
 - **Single file when possible** - keep it simple
 - **NO error handling** - no try/catch, no validation, no edge cases
 - **Assume everything works** - valid inputs, successful operations, correct types
-- **localStorage/memory for data** - no full database setup
+- **Use real infrastructure** - actual database/storage from your tech stack
 - **Inline code over separate modules** - keep it simple
 - **Focus: Make. All. Features. Work.** (on the happy path)
 
-**Step 3: Final Verification and Completion**
+**Step 3: REFACTOR**
+
+After GREEN is achieved, do a quick refactor pass:
+
+1. **Extract duplicated code** - DRY up any copy-pasted logic
+2. **Rename unclear variables** - make intent obvious
+3. **Simplify complex expressions** - break into readable steps
+4. **Remove dead code** - delete unused variables/functions
+
+**Keep it fast** - 5 minutes max. Major refactoring happens in stable mode.
 
-After GREEN is achieved, run full feature file once to verify no regressions:
+**Re-run tests after refactoring** to ensure nothing broke:
+
+```javascript
+const result = await runBddScenarioWithTimeout(feature.scenario_file, scenarioLine);
+if (result.exitCode !== 0) {
+  console.log('⚠️  Refactoring broke tests - revert and try again');
+}
+```
+
+**Step 4: Final Verification and Completion**
+
+After GREEN + REFACTOR, run full feature file once to verify no regressions:
 
 ```javascript
 // After iteration loop succeeds (GREEN achieved)
@@ -504,8 +604,8 @@ if (currentResult.exitCode === 0 || currentResult.passed === currentResult.total
   console.log(`\n🔍 Running full verification (all scenarios)...`);
 
   // Run entire feature file once for regression detection
-  const { runBddTestWithTimeout } = require('./.claude/skills/speed-mode/test-runner');
-  const fullResult = await runBddTestWithTimeout(feature.scenario_file);
+  // Uses the already imported runBddScenarioWithTimeout with no line number to run all scenarios
+  const fullResult = await runBddScenarioWithTimeout(feature.scenario_file);
 
   if (fullResult.timedOut) {
     console.log(`⚠️  Full verification timed out`);
@@ -550,35 +650,34 @@ if (filesModified.length > 0) {
   console.log();
 }
 
-// Generate unit tests for new functions after GREEN
-console.log(`📝 Generating unit tests for new functions...\n`);
-const { generateTestsAfterGreen } = require('./lib/unit-test-generator');
-
-const allFiles = [...filesCreated, ...filesModified];
-const testsGenerated = [];
-
-for (const file of allFiles) {
-  if (file.endsWith('.js') && !file.includes('test')) {
-    try {
-      const result = generateTestsAfterGreen(file);
-      if (result.created || result.functionsAdded > 0) {
-        testsGenerated.push({ file: result.testFile, functionsAdded: result.functionsAdded });
-        console.log(`  ✅ ${result.testFile} (${result.functionsAdded} functions)`);
-      }
-    } catch (err) {
-      console.log(`  ⚠️  Could not generate tests for ${file}: ${err.message}`);
-    }
-  }
-}
+// --- Create unit tests for new functions ---
+// For each new function implemented, create a unit test file with happy path coverage
 
-if (testsGenerated.length > 0) {
-  console.log(`\n🧪 Generated tests for ${testsGenerated.length} files`);
-  console.log(`   Tests have TODO placeholders - stable mode will add edge cases\n`);
-} else {
-  console.log(`No unit tests generated (no functions found)\n`);
-}
+// Unit test template for new functions:
+// test/[filename].test.js or __tests__/[filename].test.js
+/*
+const { functionName } = require('../src/path/to/module');
+
+describe('functionName', () => {
+  it('should handle valid input successfully', () => {
+    // Arrange
+    const input = validTestData;
+
+    // Act
+    const result = functionName(input);
 
-console.log(`Next step: Elevate to stable mode using 'node jettypod.js work set-mode <feature-id> stable'\n`);
+    // Assert
+    expect(result).toEqual(expectedOutput);
+  });
+});
+*/
+
+// Speed mode unit tests focus on:
+// - Happy path with valid input
+// - One successful operation per function
+// - Basic return value verification
+
+console.log(`Next step: Elevate to stable mode using 'jettypod work set-mode <feature-id> stable'\n`);
 ```
 
 **Display:**
@@ -607,10 +706,12 @@ Next step: Elevate to stable mode using 'node jettypod.js work set-mode <feature
 **On FAILURE (max iterations or timeout):**
 
 ```javascript
+// --- Display failure header ---
 console.log(`\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
 console.log(`⚠️  SPEED MODE INCOMPLETE - STILL IN RED STATE`);
 console.log(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`);
 
+// --- Handle timeout case ---
 if (result.timedOut) {
   console.log(`❌ Test execution timed out`);
   console.log(`\nPossible causes:`);
@@ -618,15 +719,18 @@ if (result.timedOut) {
   console.log(`  • Test is waiting for async operation that never completes`);
   console.log(`  • Step definition has blocking code`);
 } else {
+  // --- Handle max iterations case ---
   console.log(`❌ Maximum iterations (${MAX_ITERATIONS}) reached\n`);
   console.log(`Final Progress: ${previousResult.passed}/${previousResult.total} steps passing\n`);
 
+  // --- Display failing steps ---
   if (previousResult.failedSteps.length > 0) {
     console.log(`Still failing:`);
     previousResult.failedSteps.forEach(step => console.log(`  ✖ ${step}`));
     console.log();
   }
 
+  // --- Display remaining errors ---
   const errors = extractErrors(result.stdout + result.stderr);
   if (errors.errors.length > 0) {
     console.log(`Remaining errors:`);
@@ -637,6 +741,7 @@ if (result.timedOut) {
   }
 }
 
+// --- Display next steps ---
 console.log(`\nWhat to do:`);
 console.log(`  • Review implementation approach - is it the right strategy?`);
 console.log(`  • Check for incorrect assumptions about existing code`);
@@ -678,6 +783,11 @@ DO NOT proceed to generate stable mode chores until GREEN is achieved.
 
 **Move to Step 4 only if GREEN achieved.**
 
+<!-- ═══════════════════════════════════════════════════════════════════════════
+     PHASE 4: STABLE CHORE GENERATION
+     ⚡ ASYNC BOUNDARY - Must wait for user to confirm proposed chores
+     ═══════════════════════════════════════════════════════════════════════════ -->
+
 ### Step 4: Generate Stable Mode Chores
 
 **Two phases: Analyze and propose → Get confirmation → Create autonomously**
@@ -741,6 +851,11 @@ Sound good? I'll create these chores once you confirm.
 
 If user adjusts: revise chores and confirm again.
 
+<!-- ═══════════════════════════════════════════════════════════════════════════
+     PHASE 5: AUTONOMOUS COMPLETION
+     User has confirmed chores - create them and finalize
+     ═══════════════════════════════════════════════════════════════════════════ -->
+
 #### Phase 3: Create Chores Autonomously
 
 **CRITICAL:** After user confirms, create chores programmatically - no additional permission needed.
@@ -751,11 +866,13 @@ If user adjusts: revise chores and confirm again.
 const { create } = require('./features/work-tracking');
 const { getCurrentWork } = require('../../lib/current-work');
 
-const currentWork = getCurrentWork();
-const featureId = currentWork.parent_id; // Parent feature
+(async () => {
+  const currentWork = await getCurrentWork();
+  const featureId = currentWork.parent_id; // Parent feature
 
-// For each confirmed chore:
-await create('chore', 'Chore Title', 'Description', featureId, 'stable', false);
+  // For each confirmed chore:
+  await create('chore', 'Chore Title', 'Description', featureId, 'stable', false);
+})();
 ```
 
 **Display results:**
@@ -773,42 +890,56 @@ Chores created:
 
 **CRITICAL: Check if ALL speed mode chores are complete. If yes, auto-elevate to stable mode.**
 
+<!-- ┌─────────────────────────────────────────────────────────────────────────┐
+     │ 🔍 COMPLETION CHECK: Speed Chores                                      │
+     │                                                                         │
+     │ Progress Tracking:                                                      │
+     │ • Query: Count incomplete speed chores for feature                     │
+     │ • Display: "X speed mode chores remaining" or "All complete"           │
+     │ • Action: Auto-elevate if all complete                                 │
+     │                                                                         │
+     │ Return Point:                                                           │
+     │ • CHECKPOINT_CHORE_COUNT: Known incomplete count from last check       │
+     │ • If session interrupted, re-query to get current count                │
+     └─────────────────────────────────────────────────────────────────────────┘ -->
+
 ```javascript
-// Check if all speed chores for this feature are done
+// --- Imports ---
 const { getDb } = require('../../lib/database');
 const { getCurrentWork } = require('../../lib/current-work');
 
-const currentWork = getCurrentWork();
-const featureId = currentWork.parent_id;
-
-const db = getDb();
-db.get(`
-  SELECT COUNT(*) as incomplete_count
-  FROM work_items
-  WHERE parent_id = ?
-    AND type = 'chore'
-    AND mode = 'speed'
-    AND status != 'done'
-`, [featureId], async (err, result) => {
-  if (err) {
-    console.error('Error checking speed chores:', err.message);
-    db.close();
-    return;
-  }
+(async () => {
+  // --- Get current work context ---
+  const currentWork = await getCurrentWork();
+  const featureId = currentWork.parent_id;
+  const db = getDb();
+
+  // --- Query for incomplete speed chores ---
+  const result = await new Promise((resolve, reject) => {
+    db.get(`
+      SELECT COUNT(*) as incomplete_count
+      FROM work_items
+      WHERE parent_id = ?
+        AND type = 'chore'
+        AND mode = 'speed'
+        AND status != 'done'
+    `, [featureId], (err, row) => {
+      if (err) reject(err);
+      else resolve(row);
+    });
+  });
 
+  // --- Handle completion or remaining chores ---
   if (result.incomplete_count === 0) {
-    // All speed chores done - auto-elevate to stable
     console.log('\n✅ All speed mode chores complete!');
     console.log('Auto-elevating feature to stable mode...\n');
-
     // Use Bash tool to execute elevation
-    // DO NOT display as text - EXECUTE IT
   } else {
     console.log(`\n📋 ${result.incomplete_count} speed mode chores remaining`);
   }
 
   db.close();
-});
+})();
 ```
 
 **If all speed chores are done, use Bash tool to EXECUTE elevation:**