jettypod 4.1.2 → 4.1.4

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

@@ -27,6 +27,34 @@ When this skill is activated, you are helping implement a speed mode chore to ma
 
 ---
 
+## ⚠️ CRITICAL: Speed Mode Workflow Requirements
+
+**DO NOT mark features as complete after speed mode implementation.**
+
+Speed mode is ONLY a checkpoint to prove the happy path works. Features are INCOMPLETE without stable mode chores that add:
+- Error handling and validation
+- Edge case coverage
+- Comprehensive testing
+- User-friendly error messages
+
+**Required workflow after speed mode implementation:**
+
+1. ✅ **Complete ALL speed mode chores** - Implement happy path functionality
+2. ✅ **Elevate to stable mode** - Use `node jettypod.js work set-mode <feature-id> stable` to auto-generate stable mode chores
+3. ✅ **Implement stable mode chores** - Add error handling and edge cases
+4. ❌ **NEVER mark feature complete in speed mode** - This bypasses critical quality gates
+
+**If you attempt to mark a feature complete while in speed mode, the system will block you with an error.**
+
+The validation will require you to:
+- Elevate to stable mode: `node jettypod.js work set-mode <feature-id> stable`
+- This will automatically analyze the implementation and generate appropriate stable mode chores
+- Or explicitly skip (not recommended): `node jettypod.js work set-mode <feature-id> stable --force`
+
+**Remember:** Speed mode proves it works on the happy path. Stable mode makes it production-ready.
+
+---
+
 ## Implementation Steps
 
 ### Step 1: Check for Breadcrumbs and Analyze Scenario
@@ -129,13 +157,22 @@ Now analyzing codebase to propose implementation...
 
 **Check for architectural decisions:**
 
+**⚠️ IMPORTANT - USE EXACT CODE BELOW:**
+- Import from `./lib/decisions-helpers` (NOT `../../lib/decisions-helpers` or `./features/decisions/index.js`)
+- Function returns a Promise, must use `await`
+
+**Execute this EXACT code (copy/paste as-is):**
+
 ```javascript
-const { getDecisionsForEpic } = require('../../lib/decisions-helpers');
+const { getDecisionsForEpic } = require('./lib/decisions-helpers');
+const { getDb } = require('./lib/database');
+const db = getDb();
 
 // Get epic from current work
 db.get('SELECT epic_id FROM work_items WHERE id = ?', [currentWork.parent_id], async (err, feature) => {
-  if (feature.epic_id) {
+  if (feature && feature.epic_id) {
     const decisions = await getDecisionsForEpic(feature.epic_id);
+    console.log('Epic decisions:', JSON.stringify(decisions, null, 2));
     // Decisions constrain your implementation approach
   }
 });
@@ -226,42 +263,226 @@ If user adjusts: revise proposal and confirm again.
 
 **CRITICAL:** After user confirms, Claude Code executes autonomously - no permission needed for individual code changes.
 
-**Execution loop:**
-
-1. **Create/modify files** using Write/Edit tools
-   - Follow the proposed plan
-   - Write minimal code (speed mode - happy path only)
-   - Add basic comments for clarity
-   - Use inline code over abstractions
-
-2. **Run BDD tests** to verify step definitions pass
-   ```javascript
-   // Run the feature's BDD tests (scenarios + step definitions)
-   const { exec } = require('child_process');
-   exec('npm run test:bdd -- [feature-file].feature', (err, stdout) => {
-     // Check if step definitions pass
-     // Step definitions were created during feature discovery
-     // Your implementation must make them pass
-   });
-   ```
-
-3. **Check if BDD scenario passes**
-   - Run: `npm run test:bdd -- features/[feature-slug].feature`
-   - Step definitions execute your implementation code
-   - If yes: Move to final step
-   - If no: Analyze failure, adjust code, iterate
-   - **CRITICAL:** Tests must pass before moving on
-
-4. **Display progress:**
-   ```
-   ✍️  Writing [file name]...
-   ✅ Created [file name]
-
-   🧪 Running tests...
-   ❌ Scenario failed: [error message]
-   🔧 Adjusting [specific fix]...
-   ✅ Scenario passes!
-   ```
+**Step 1: Establish RED Baseline**
+
+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');
+const { getCurrentWork } = require('./lib/current-work');
+const { getDb } = require('./lib/database');
+
+const currentWork = getCurrentWork();
+const db = getDb();
+
+// 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;
+  }
+
+  console.log('🔴 Establishing RED baseline...\n');
+
+  // Find happy path scenario (first scenario in file)
+  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
+  const result = await runBddScenarioWithTimeout(feature.scenario_file, happyPathLine);
+
+  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);
+    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}`));
+
+    if (errors.errors.length > 0) {
+      console.log('\nFirst error:');
+      const firstError = errors.errors[0];
+      console.log(`  Step: ${firstError.step}`);
+      console.log(`  Error: ${firstError.message}`);
+    }
+
+    console.log('\n🎯 Goal: Make all steps pass\n');
+  }
+
+  // Store baseline for comparison in iteration loop (chore #115)
+  global.redBaseline = {
+    passed: progress.passed,
+    total: progress.total,
+    failedSteps: progress.failedSteps
+  };
+});
+```
+
+**Display RED baseline:**
+```
+🔴 Establishing RED baseline...
+
+RED Baseline: 5 of 8 steps failing
+
+Failing steps:
+  ✖ Given a user is logged in
+  ✖ When they click the dashboard button
+  ✖ Then they should see their dashboard
+  ✖ And the dashboard should show their username
+  ✖ And the dashboard should show their recent activity
+
+First error:
+  Step: Given a user is logged in
+  Error: Error: login function is not defined
+
+🎯 Goal: Make all steps pass
+
+Now implementing...
+```
+
+**Step 2: RED→GREEN Iteration Loop**
+
+Iterate until all tests pass or MAX_ITERATIONS reached:
+
+```javascript
+const { runBddScenarioWithTimeout, parseTestProgress, findNewlyPassingSteps, extractErrors, MAX_ITERATIONS } = require('./.claude/skills/speed-mode/test-runner');
+
+let previousResult = global.redBaseline; // From Step 1
+let iteration = 0;
+
+while (iteration < MAX_ITERATIONS) {
+  iteration++;
+
+  console.log(`\n━━━ Iteration ${iteration}/${MAX_ITERATIONS} ━━━`);
+
+  // 1. Make code changes based on current failure
+  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
+  console.log(`\n🧪 Running tests...`);
+  const result = await runBddScenarioWithTimeout(feature.scenario_file, happyPathLine);
+
+  if (result.timedOut) {
+    console.log(`⚠️  Test execution timed out - tests may be hanging`);
+    console.log(`Stopping iteration loop`);
+    break;
+  }
+
+  // 3. Parse results
+  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
+  console.log(`\n📊 Progress: ${currentResult.passed}/${currentResult.total} steps passing`);
+
+  if (newlyPassing.length > 0) {
+    console.log(`\n✅ Newly passing:`);
+    newlyPassing.forEach(step => console.log(`  • ${step}`));
+  }
+
+  // 6. Check if all tests pass (GREEN state achieved)
+  if (currentResult.exitCode === 0 || currentResult.passed === currentResult.total) {
+    console.log(`\n🎉 GREEN: All tests passing!`);
+    break;
+  }
+
+  // 7. Display next failure to address
+  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
+    }
+  } else if (currentResult.failedSteps.length > 0) {
+    console.log(`\n🔧 Still failing:`);
+    currentResult.failedSteps.slice(0, 3).forEach(step => console.log(`  • ${step}`));
+    if (currentResult.failedSteps.length > 3) {
+      console.log(`  ... and ${currentResult.failedSteps.length - 3} more`);
+    }
+  }
+
+  // Store for next iteration comparison
+  previousResult = currentResult;
+}
+
+// After loop ends
+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`);
+  console.log(`\nConsider:`);
+  console.log(`  • Breaking down the chore into smaller pieces`);
+  console.log(`  • Reviewing the implementation approach`);
+  console.log(`  • Checking for incorrect assumptions`);
+}
+```
+
+**Display example:**
+```
+━━━ Iteration 1/10 ━━━
+
+✍️  Making code changes...
+Created src/login.js
+Modified src/app.js
+
+🧪 Running tests...
+
+📊 Progress: 2/8 steps passing
+
+✅ Newly passing:
+  • Given a user is logged in
+  • When they click the dashboard button
+
+🔧 Next failure to address:
+  Step: Then they should see their dashboard
+  Error: Cannot read property 'innerText' of null
+  Stack: at Dashboard.render (src/dashboard.js:12:15)
+
+━━━ Iteration 2/10 ━━━
+
+✍️  Making code changes...
+Created src/dashboard.js
+Modified src/app.js
+
+🧪 Running tests...
+
+📊 Progress: 5/8 steps passing
+
+✅ Newly passing:
+  • Then they should see their dashboard
+  • And the dashboard should show their username
+  • And the dashboard should show their recent activity
+
+🔧 Next failure to address:
+  Step: And the activity should be sorted by date
+  Error: Expected ['Post 2', 'Post 1'] but got ['Post 1', 'Post 2']
+
+━━━ Iteration 3/10 ━━━
+
+✍️  Making code changes...
+Modified src/dashboard.js
+
+🧪 Running tests...
+
+📊 Progress: 8/8 steps passing
+
+✅ Newly passing:
+  • And the activity should be sorted by date
+
+🎉 GREEN: All tests passing!
+```
 
 **Speed mode constraints:**
 - **Implement ALL scoped functionality** - if the scenario requires file upload, implement it (just assume it works)
@@ -272,20 +493,190 @@ If user adjusts: revise proposal and confirm again.
 - **Inline code over separate modules** - keep it simple
 - **Focus: Make. All. Features. Work.** (on the happy path)
 
-**When scenario passes:**
+**Step 3: Final Verification and Completion**
+
+After GREEN is achieved, run full feature file once to verify no regressions:
+
+```javascript
+// After iteration loop succeeds (GREEN achieved)
+if (currentResult.exitCode === 0 || currentResult.passed === currentResult.total) {
+  console.log(`\n🎉 GREEN: Happy path scenario passing!`);
+  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);
+
+  if (fullResult.timedOut) {
+    console.log(`⚠️  Full verification timed out`);
+  } else if (fullResult.exitCode !== 0) {
+    const fullProgress = parseTestProgress(fullResult.stdout + fullResult.stderr);
+    console.log(`⚠️  Full verification found regressions: ${fullProgress.total - fullProgress.passed} scenarios failing`);
+    console.log(`This is expected in speed mode - stable mode will address additional scenarios.`);
+  } else {
+    console.log(`✅ Full verification passed - all scenarios passing!`);
+  }
+}
+```
+
+Display comprehensive results:
+
+**On SUCCESS (GREEN achieved):**
+
+```javascript
+// Track what files were created/modified during implementation
+const filesCreated = [/* list of created files */];
+const filesModified = [/* list of modified files */];
+
+console.log(`\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
+console.log(`✅ SPEED MODE COMPLETE - GREEN STATE ACHIEVED`);
+console.log(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`);
+
+console.log(`🎉 Happy path scenario: ALL TESTS PASSING\n`);
+
+console.log(`Implementation Summary:`);
+console.log(`  Iterations: ${iteration}/${MAX_ITERATIONS}`);
+console.log(`  Test steps: ${currentResult.passed}/${currentResult.total} passing\n`);
+
+if (filesCreated.length > 0) {
+  console.log(`Files created:`);
+  filesCreated.forEach(file => console.log(`  ✅ ${file}`));
+  console.log();
+}
+
+if (filesModified.length > 0) {
+  console.log(`Files modified:`);
+  filesModified.forEach(file => console.log(`  ✏️  ${file}`));
+  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}`);
+    }
+  }
+}
+
+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`);
+}
+
+console.log(`Next step: Elevate to stable mode using 'node jettypod.js work set-mode <feature-id> stable'\n`);
+```
 
+**Display:**
 ```
-🎉 Happy path scenario passes!
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+✅ SPEED MODE COMPLETE - GREEN STATE ACHIEVED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+🎉 Happy path scenario: ALL TESTS PASSING
 
-Implementation complete:
-• Created: [list files]
-• Modified: [list files]
-• Tests: ✅ Passing
+Implementation Summary:
+  Iterations: 3/10
+  Test steps: 8/8 passing
 
-Now analyzing what was built to propose stable mode chores...
+Files created:
+  ✅ src/login.js
+  ✅ src/dashboard.js
+
+Files modified:
+  ✏️  src/app.js
+  ✏️  src/index.html
+
+Next step: Elevate to stable mode using 'node jettypod.js work set-mode <feature-id> stable'
 ```
 
-**Move to final step automatically.**
+**On FAILURE (max iterations or timeout):**
+
+```javascript
+console.log(`\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
+console.log(`⚠️  SPEED MODE INCOMPLETE - STILL IN RED STATE`);
+console.log(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`);
+
+if (result.timedOut) {
+  console.log(`❌ Test execution timed out`);
+  console.log(`\nPossible causes:`);
+  console.log(`  • Infinite loop in implementation code`);
+  console.log(`  • Test is waiting for async operation that never completes`);
+  console.log(`  • Step definition has blocking code`);
+} else {
+  console.log(`❌ Maximum iterations (${MAX_ITERATIONS}) reached\n`);
+  console.log(`Final Progress: ${previousResult.passed}/${previousResult.total} steps passing\n`);
+
+  if (previousResult.failedSteps.length > 0) {
+    console.log(`Still failing:`);
+    previousResult.failedSteps.forEach(step => console.log(`  ✖ ${step}`));
+    console.log();
+  }
+
+  const errors = extractErrors(result.stdout + result.stderr);
+  if (errors.errors.length > 0) {
+    console.log(`Remaining errors:`);
+    errors.errors.slice(0, 3).forEach(err => {
+      console.log(`  Step: ${err.step}`);
+      console.log(`  Error: ${err.message}\n`);
+    });
+  }
+}
+
+console.log(`\nWhat to do:`);
+console.log(`  • Review implementation approach - is it the right strategy?`);
+console.log(`  • Check for incorrect assumptions about existing code`);
+console.log(`  • Consider breaking this chore into smaller pieces`);
+console.log(`  • Verify step definitions match what implementation provides`);
+console.log(`\nDO NOT proceed to generate stable mode chores until GREEN is achieved.`);
+```
+
+**Display (on failure):**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⚠️  SPEED MODE INCOMPLETE - STILL IN RED STATE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+❌ Maximum iterations (10) reached
+
+Final Progress: 5/8 steps passing
+
+Still failing:
+  ✖ Then they should see their dashboard
+  ✖ And the dashboard should show their username
+  ✖ And the dashboard should show their recent activity
+
+Remaining errors:
+  Step: Then they should see their dashboard
+  Error: Cannot read property 'innerText' of null
+
+  Step: And the dashboard should show their username
+  Error: Expected 'John Doe' but got undefined
+
+What to do:
+  • Review implementation approach - is it the right strategy?
+  • Check for incorrect assumptions about existing code
+  • Consider breaking this chore into smaller pieces
+  • Verify step definitions match what implementation provides
+
+DO NOT proceed to generate stable mode chores until GREEN is achieved.
+```
+
+**Move to Step 4 only if GREEN achieved.**
 
 ### Step 4: Generate Stable Mode Chores
 
@@ -424,7 +815,7 @@ db.get(`
 
 ```javascript
 // Use Bash tool to execute:
-node jettypod.js work elevate [feature-id] stable
+node jettypod.js work set-mode [feature-id] stable
 ```
 
 **DO NOT display this as example text. EXECUTE IT using the Bash tool.**
@@ -436,13 +827,25 @@ After execution, display:
 🎯 Speed Mode Complete! Feature Elevated to Stable Mode
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
+⚠️  CRITICAL: Speed mode is ONLY a checkpoint to prove functionality works.
+The feature is INCOMPLETE without stable mode - error handling, validation,
+edge cases, and comprehensive testing are ALL required.
+
 What we accomplished:
 ✅ Happy path scenario passes
 ✅ All speed mode chores complete
 ✅ Feature elevated to stable mode
 ✅ Stable mode chores created and ready
 
-**Next step:** Start the first stable mode chore
+🚀 NEVER leave a feature in speed mode - it's not production-ready.
+Stable mode adds:
+  • Comprehensive error handling and user-friendly error messages
+  • Input validation (null checks, type checks, range validation)
+  • Edge case handling (empty arrays, boundary values, race conditions)
+  • State consistency and data integrity
+  • All BDD scenarios passing (happy path + error/edge cases)
+
+**Next step:** IMMEDIATELY start the first stable mode chore
   jettypod work start [first-stable-chore-id]
 ```
 
@@ -465,14 +868,14 @@ Remaining speed mode chores: [count]
 
 **Mark current chore as done:**
 
-Use Bash tool to commit, push, and merge to main:
+Use Bash tool to commit and push:
 ```bash
 git add . && git commit -m "feat: [brief description of what was implemented]" && git push
 ```
 
-Then merge to main (which auto-marks chore as done via git hooks):
+Then use the merge command to merge to main (which auto-marks chore as done via post-merge hook):
 ```bash
-git checkout main && git pull && git merge [branch-name] && git push
+jettypod work merge
 ```
 
 The post-merge hook will automatically mark the chore as done when merged to main.