jettypod 4.4.0 → 4.4.2

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

@@ -22,15 +22,28 @@ Guides Claude Code through speed mode implementation with autonomous analysis an
 
 ## Instructions
 
-When this skill is activated, you are helping implement a speed mode chore to make the happy path scenario pass. Follow this structured approach:
+When this skill is activated, you are helping implement a speed mode chore to make all success scenarios pass. Follow this structured approach:
+
+## 🔑 Critical Context
+
+**You are working in an isolated git worktree:**
+- `work start [chore-id]` created a dedicated worktree for this chore
+- All file operations must use **absolute paths** from the worktree (not relative paths)
+- The worktree has its own branch - changes are isolated from main
+- BDD tests and unit tests run in the worktree context
+
+**Worktree path is available in Step 0 output** - use it for all file operations.
+
+---
 
 ### Overview
 
-**Speed Mode Goal:** Implement ALL scoped functionality to make the happy path BDD scenario pass, assuming everything works correctly.
+**Speed Mode Goal:** Make it work - implement ALL functionality (required + optional features) to make success scenarios pass, assuming everything works correctly.
 
 **Key Principles:**
-- **Implement ALL features/functions** defined in the scenario - do not skip functionality
-- **Assume happy path** - assume inputs are valid, files upload successfully, types are correct
+- **Implement ALL features/functions** defined in scenarios - both required and optional functionality
+- **All success paths** - every workflow that should work when inputs are valid
+- **Assume success** - 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
 - **Use real infrastructure** - use the actual database/storage from your tech stack, not mocks
@@ -40,20 +53,136 @@ When this skill is activated, you are helping implement a speed mode chore to ma
 
 ---
 
+## 🧪 Unit Testing in Speed Mode - True TDD
+
+**Unit tests are written DURING the RED→GREEN loop, not after.**
+
+**The TDD workflow (each iteration):**
+1. **Identify next failing BDD step** - Which scenario step needs to pass next?
+2. **Write unit test for the function** - Test the specific function/logic needed
+3. **Watch unit test fail (RED)** - Confirm test catches the missing implementation
+4. **Write minimal code** - Just enough to make the unit test pass
+5. **Run unit test (GREEN)** - Verify the function works in isolation
+6. **Run BDD scenarios** - Check if this makes any BDD steps pass
+7. **Next iteration** - Repeat for next failing step
+
+**What to unit test:**
+- New functions you're creating (not framework/library code)
+- Core logic and business rules
+- Success scenarios only (no error cases - that's stable mode)
+
+**Where to put unit tests:**
+- Follow project conventions: `test/`, `__tests__/`, or `*.test.js` alongside code
+- Check existing test files for patterns
+
+**Example of TDD iteration:**
+```javascript
+// Iteration 1: BDD step "Given a user exists" is failing
+
+// 1. Write unit test first (RED)
+test('createUser creates user with valid data', () => {
+  const user = createUser('John', 'john@example.com');
+  expect(user.name).toBe('John');
+  expect(user.email).toBe('john@example.com');
+});
+// Run: FAILS - createUser doesn't exist
+
+// 2. Write minimal implementation (GREEN)
+function createUser(name, email) {
+  return { name, email };
+}
+// Run unit test: PASSES
+// Run BDD: "Given a user exists" now passes
+
+// Iteration 2: Next failing BDD step...
+```
+
+**Unit test scope in speed mode:**
+```javascript
+// ✅ Speed mode unit tests (success paths)
+test('createUser creates user with valid data', () => {
+  const user = createUser('John', 'john@example.com');
+  expect(user.name).toBe('John');
+  expect(user.email).toBe('john@example.com');
+});
+
+// ❌ NOT in speed mode (stable mode adds these)
+test('createUser throws error for invalid email', () => {
+  expect(() => createUser('John', 'invalid')).toThrow();
+});
+```
+
+<details>
+<summary><strong>📋 Speed Mode Constraints (click to expand)</strong></summary>
+
+**What to implement:**
+- ALL scoped functionality - required features AND optional features from all success scenarios
+- Multiple valid workflows if the feature supports them
+- Success variations (different outcomes that are all correct)
+
+**What NOT to implement:**
+- ❌ Error handling (try/catch, validation, edge cases)
+- ❌ Input validation (null checks, type checks, range validation)
+- ❌ Error messages for failures
+- ❌ Edge case handling (empty arrays, boundary values, race conditions)
+
+**Code organization:**
+- Single file when possible - keep it simple
+- Inline code over separate modules initially
+- Use real infrastructure (actual database/storage from your tech stack, not mocks)
+- Focus: Make. All. Features. Work. (all success paths)
+
+</details>
+
+---
+
+### Step 0: Initialize Speed Mode Context
+
+**You are now in speed mode,** implementing a chore to make success scenarios pass.
+
+**Get the current work context:**
+
+```bash
+sqlite3 .jettypod/work.db "SELECT wi.id, wi.title, wi.parent_id, parent.title as parent_title, parent.scenario_file, wt.worktree_path, wt.branch_name FROM work_items wi LEFT JOIN work_items parent ON wi.parent_id = parent.id LEFT JOIN worktrees wt ON wi.id = wt.work_item_id WHERE wi.status = 'in_progress' AND wi.type = 'chore'"
+```
+
+**Display to user:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🚀 SPEED MODE: Implementing Chore #[id]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Chore: [title]
+Feature: #[parent-id] [parent-title]
+Worktree: [worktree_path]
+Branch: [branch_name]
+
+Analyzing BDD scenarios to determine implementation approach...
+```
+
+**Then proceed to Step 1.**
+
+---
+
 ## 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 |
+| Phase | Location | Why | Condition |
+|-------|----------|-----|-----------|
+| Step 3A | Before implementing (conditional) | User confirms implementation approach | Only if approach is ambiguous or multiple valid paths |
+| Step 6 Phase 2 | Before creating stable chores | User confirms proposed stable mode chores | Always |
 
 **Where Claude Code executes autonomously:**
-- Step 1: Scenario analysis
+- Step 0: Initialize context
+- Step 1: Scenario analysis and breadcrumb check
 - Step 2: Codebase analysis
-- Step 3 Phase 2: RED→GREEN→REFACTOR loop
-- Step 4 Phases 3-4: Create chores and elevate
+- Step 3: Decision to skip/ask for confirmation
+- Step 4: Establish RED baseline
+- Step 5: RED→GREEN→REFACTOR loop (true TDD)
+- Step 6 Phase 1: Generate stable mode scenarios/steps
+- Step 6 Phases 3-5: Create chores and invoke stable-mode skill
 
 ---
 
@@ -61,7 +190,7 @@ When this skill is activated, you are helping implement a speed mode chore to ma
 
 **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:
+Speed mode is ONLY a checkpoint to prove functionality works. Features are INCOMPLETE without stable mode chores that add:
 - Error handling and validation
 - Edge case coverage
 - Comprehensive testing
@@ -69,7 +198,7 @@ Speed mode is ONLY a checkpoint to prove the happy path works. Features are INCO
 
 **Required workflow after speed mode implementation:**
 
-1. ✅ **Complete ALL speed mode chores** - Implement happy path functionality
+1. ✅ **Complete ALL speed mode chores** - Implement all success scenarios (required + optional features)
 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
@@ -81,17 +210,12 @@ The validation will require you to:
 - 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.
+**Remember:** Speed mode makes it work (all success scenarios). Stable mode makes it robust (handles failures).
 
 ---
 
 ## 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.
@@ -106,15 +230,8 @@ The validation will require you to:
 **To get current work and check for breadcrumbs:**
 
 ```bash
-# Get current work item with description
-jettypod work current
-
-# Get parent feature details including scenario_file
-jettypod work show <parent-feature-id>
-
-# Or query database directly
-sqlite3 .jettypod/work.db "SELECT id, title, description, parent_id FROM work_items WHERE status = 'in_progress' AND type = 'chore'"
-sqlite3 .jettypod/work.db "SELECT id, title, scenario_file FROM work_items WHERE id = <parent-feature-id>"
+# Get current work item with description and parent feature's scenario_file
+sqlite3 .jettypod/work.db "SELECT wi.id, wi.title, wi.description, wi.parent_id, parent.title as parent_title, parent.scenario_file FROM work_items wi LEFT JOIN work_items parent ON wi.parent_id = parent.id WHERE wi.status = 'in_progress' AND wi.type = 'chore'"
 ```
 
 **Check for breadcrumbs** by examining the chore's description for:
@@ -127,8 +244,8 @@ If all three sections exist, use them. Otherwise, fall back to autonomous analys
 **Then read the scenario file** using the Read tool on the path returned by `scenario_file`.
 
 **Parse Gherkin:**
-- Extract first `Scenario:` block (happy path)
-- Parse Given/When/Then/And steps
+- Extract all `Scenario:` blocks (all success paths - required + optional features)
+- Parse Given/When/Then/And steps for each scenario
 - Identify:
   - Initial state setup (Given)
   - User actions (When)
@@ -241,65 +358,62 @@ Integration Points:
 Now proposing implementation approach...
 ```
 
-**Move to Step 3 automatically.**
+### Step 3: Decide if Confirmation Needed
+
+**Evaluate if you need user confirmation before implementing:**
 
-<!-- ═══════════════════════════════════════════════════════════════════════════
-     PHASE 2: USER CONFIRMATION REQUIRED
-     ⚡ ASYNC BOUNDARY - Must wait for user response before proceeding
-     ═══════════════════════════════════════════════════════════════════════════ -->
+**Skip confirmation (proceed directly to Step 4) if:**
+- Breadcrumbs are comprehensive (files, patterns, functions all specified)
+- Implementation approach is clear and unambiguous
+- Only one reasonable way to implement the scenario
+- Epic architectural decisions are clear and constraining
 
-### Step 3: Propose and Execute Implementation
+**Ask for confirmation (Step 3A) if:**
+- Multiple valid implementation approaches exist
+- Breadcrumbs are vague or missing key details
+- Architectural choice impacts other features
+- You're uncertain about the right approach
 
-**Two phases: Propose (get user confirmation) → Execute (autonomous)**
+### Step 3A: Propose Implementation Approach (Conditional)
 
-#### Phase 1: Propose Implementation Approach
+**⚡ ASYNC BOUNDARY - Only execute this if confirmation needed**
 
-**Present your analysis and proposal:**
+**Present your analysis and proposal to the user:**
 
 ```
 💡 Implementation Proposal
 
-Based on scenario analysis and codebase patterns, here's how I'll make the scenario pass:
+I see multiple ways to approach this. Here's what I'm thinking:
 
-**Files to create/modify:**
-1. [file path] - [what it will do]
-2. [file path] - [what it will do]
+**Option I'm recommending:**
+• Files to create/modify: [specific paths]
+• Key approach: [what makes this the right choice]
+• Why: [rationale - why this over alternatives]
 
-**Key implementation points:**
-• [Point 1]: [specific approach]
-• [Point 2]: [specific approach]
-• [Point 3]: [specific approach]
+**Alternative considered:**
+• [Brief description] - not choosing because [reason]
 
-**Why this approach:**
-[Brief explanation of how this satisfies the scenario while following codebase patterns]
-
-Sound good? I'll implement this autonomously once you confirm.
+Sound good, or would you prefer a different approach?
 ```
 
-**WAIT for user confirmation or adjustments.**
+**⚡ WAIT for user confirmation or adjustments.**
 
-If user adjusts: revise proposal and confirm again.
+If user adjusts: revise proposal and confirm again before proceeding.
 
-<!-- ═══════════════════════════════════════════════════════════════════════════
-     PHASE 3: AUTONOMOUS EXECUTION
-     User has confirmed - Claude Code executes RED→GREEN loop independently
-     ═══════════════════════════════════════════════════════════════════════════ -->
+**If you skipped this step:** Proceed directly to Step 4.
 
-#### Phase 2: Autonomous Execution
+---
 
-**CRITICAL:** After user confirms, Claude Code executes autonomously - no permission needed for individual code changes.
+### Step 4: Establish RED Baseline
 
-**Step 1: Establish RED Baseline**
+**CRITICAL:** After user confirms, execute autonomously - no permission needed for code changes.
 
 Before writing any implementation code, run tests to establish the RED state:
 
 ```bash
 # Get current work and parent feature's scenario file
-jettypod work current
-# Note the parent_id from output
-
-sqlite3 .jettypod/work.db "SELECT scenario_file FROM work_items WHERE id = <parent-feature-id>"
-# This gives you the path to the .feature file
+sqlite3 .jettypod/work.db "SELECT wi.id, wi.parent_id, parent.scenario_file FROM work_items wi LEFT JOIN work_items parent ON wi.parent_id = parent.id WHERE wi.status = 'in_progress'"
+# This gives you the chore ID, parent feature ID, and path to the .feature file
 
 # Run BDD tests to establish RED baseline
 npx cucumber-js <scenario-file-path> --format progress
@@ -334,441 +448,360 @@ First error:
 Now implementing...
 ```
 
-**Step 2: RED→GREEN Iteration Loop**
+---
 
-Iterate until all tests pass or MAX_ITERATIONS reached:
+### Step 5: RED→GREEN→REFACTOR Loop
 
-<!-- ┌─────────────────────────────────────────────────────────────────────────┐
-     │ 🔄 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         │
-     └─────────────────────────────────────────────────────────────────────────┘ -->
+**Execute autonomously** - iterate until tests pass (max 10 iterations).
 
-```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} ━━━`);
-
-  // --- Make code changes ---
-  console.log(`\n✍️  Making code changes...`);
-  // [Claude Code writes implementation code here using Write/Edit tools]
-
-  // --- 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;
-  }
+**Each iteration (True TDD):**
 
-  // --- Parse results and track progress ---
-  const currentResult = parseTestProgress(result.stdout + result.stderr);
-  const errors = extractErrors(result.stdout + result.stderr);
-  const newlyPassing = findNewlyPassingSteps(previousResult, currentResult);
+1. **Identify next failing BDD step** - Which scenario step to tackle?
+2. **Write unit test** - Test the function/logic needed for that step (watch it fail - RED)
+3. **Write minimal implementation** - Just enough code to pass the unit test
+4. **Run unit test** - Verify it passes (GREEN)
+5. **Run BDD scenarios** - Check if BDD step now passes
+6. **Display progress** - Show what's passing, what's next
+7. **Continue or exit** - If all BDD scenarios pass → REFACTOR. Otherwise, repeat.
 
-  // --- 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}`));
-  }
+**Show progress each iteration:**
+```
+━━━ Iteration 3/10 ━━━
+📝 Unit test: test/dashboard.test.js - sortActivityByDate()
+   RED: Test fails - function doesn't exist yet
+✍️  Implementation: src/dashboard.js - added sortActivityByDate()
+   GREEN: Unit test passes
+🧪 Running BDD scenarios...
+📊 Progress: 7/8 BDD steps passing
+✅ Newly passing: And activity should be sorted by date
+🔧 Next failure: And activity should be filterable
+    BDD step: When I filter by category "work"
+```
 
-  // --- Check for GREEN state ---
-  if (currentResult.exitCode === 0 || currentResult.passed === currentResult.total) {
-    console.log(`\n🎉 GREEN: All tests passing!`);
-    break;
-  }
+**When GREEN achieved:**
+```
+🎉 GREEN: All success scenarios passing!
+```
 
-  // --- 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]}`);
-    }
-  } 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`);
-    }
-  }
+**Then REFACTOR (quick pass, 5 min max):**
+- Extract duplicated code
+- Rename unclear variables  
+- Simplify complex expressions
+- Remove dead code
 
-  previousResult = currentResult;
-}
+**Re-run tests after refactor** to ensure nothing broke.
 
-// --- 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`);
-  console.log(`\nConsider:`);
-  console.log(`  • Breaking down the chore into smaller pieces`);
-  console.log(`  • Reviewing the implementation approach`);
-  console.log(`  • Checking for incorrect assumptions`);
-}
-```
+<details>
+<summary><strong>📋 TDD Loop Guidelines (click to expand)</strong></summary>
 
-**Display example:**
-```
-━━━ Iteration 1/10 ━━━
+**Iteration strategy:**
+- Start with first failing step
+- Make minimal change to pass that step
+- Run tests immediately
+- Move to next failure
 
-✍️  Making code changes...
-Created src/login.js
-Modified src/app.js
+**If stuck after 5 iterations:**
+- Review approach - is there a simpler path?
+- Check assumptions - are you solving the right problem?
+- Break down the change - can you make smaller steps?
 
-🧪 Running tests...
+**Max 10 iterations:**
+- If you hit max without GREEN, stop
+- Display final progress and suggest next steps
+- Consider breaking chore into smaller pieces
 
-📊 Progress: 2/8 steps passing
+</details>
 
-✅ 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)
+**CRITICAL: Check if ALL speed mode chores are complete. Stable mode transition happens ONLY after all speed chores are done.**
 
-━━━ Iteration 2/10 ━━━
+<!-- ┌─────────────────────────────────────────────────────────────────────────┐
+     │ 🔍 COMPLETION CHECK: Speed Chores                                      │
+     │                                                                         │
+     │ Progress Tracking:                                                      │
+     │ • Query: Count incomplete speed chores for feature                     │
+     │ • Display: "X speed mode chores remaining" or "All complete"           │
+     │ • Action: Generate stable scenarios/steps/chores if all complete       │
+     │                                                                         │
+     │ Return Point:                                                           │
+     │ • CHECKPOINT_CHORE_COUNT: Known incomplete count from last check       │
+     │ • If session interrupted, re-query to get current count                │
+     └─────────────────────────────────────────────────────────────────────────┘ -->
 
-✍️  Making code changes...
-Created src/dashboard.js
-Modified src/app.js
+**Check for incomplete speed chores:**
 
-🧪 Running tests...
+```bash
+# Get current work to find parent feature ID
+sqlite3 .jettypod/work.db "SELECT wi.parent_id FROM work_items wi WHERE wi.status = 'in_progress'"
 
-📊 Progress: 5/8 steps passing
+# Get list of remaining speed chores (excluding current chore)
+sqlite3 .jettypod/work.db "SELECT id, title FROM work_items WHERE parent_id = <feature-id> AND type = 'chore' AND mode = 'speed' AND status != 'done' AND id != <current-chore-id> ORDER BY created_at LIMIT 1"
+```
 
-✅ Newly passing:
-  • Then they should see their dashboard
-  • And the dashboard should show their username
-  • And the dashboard should show their recent activity
+**If speed chores remain, display and start next chore:**
 
-🔧 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']
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🎯 Speed Mode Chore Complete
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-━━━ Iteration 3/10 ━━━
+✅ Success scenarios pass for this chore
 
-✍️  Making code changes...
-Modified src/dashboard.js
+More speed mode chores remain. Starting next chore:
+#[next-chore-id]: [next-chore-title]
+```
 
-🧪 Running tests...
+**Then immediately merge current chore and start next:**
 
-📊 Progress: 8/8 steps passing
+```bash
+# Commit changes in the worktree
+git add . && git commit -m "feat: [brief description of what was implemented]"
 
-✅ Newly passing:
-  • And the activity should be sorted by date
+# Merge current chore - this automatically marks it as done
+jettypod work merge
 
-🎉 GREEN: All tests passing!
+# Start next speed chore
+jettypod work start [next-chore-id]
 ```
 
-**Speed mode constraints:**
-- **Implement ALL scoped functionality** - if the scenario requires file upload, implement it (just assume it works)
-- **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
-- **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)
+**CRITICAL: Use ONLY `jettypod work merge` to complete chores.**
+- ❌ DO NOT use `jettypod work status <id> done`
+- ❌ DO NOT use `jettypod work complete <id>`
+- ❌ DO NOT use `jettypod work set-mode <id> done`
+- ✅ ONLY use `jettypod work merge`
 
-**Step 3: REFACTOR**
+The merge command handles everything: pushes branch, merges to main, marks chore done, cleans up worktree.
 
-After GREEN is achieved, do a quick refactor pass:
+The speed-mode skill will automatically re-invoke for the next chore.
 
-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
+**If all speed chores are done (count = 0), continue to Step 6 below.**
 
-**Keep it fast** - 5 minutes max. Major refactoring happens in stable mode.
+---
 
-**Re-run tests after refactoring** to ensure nothing broke:
+### Step 6: Transition to Stable Mode (After All Speed Chores Complete)
 
-```javascript
-const result = await runBddScenarioWithTimeout(feature.scenario_file, scenarioLine);
-if (result.exitCode !== 0) {
-  console.log('⚠️  Refactoring broke tests - revert and try again');
-}
-```
+**⚡ ASYNC BOUNDARY - Must wait for user to confirm proposed scenarios/chores**
 
-**Step 4: Final Verification and Completion**
+**CRITICAL:** This step ONLY runs after ALL speed chores are complete. This is the transition from speed mode to stable mode.
 
-After GREEN + REFACTOR, run full feature file once to verify no regressions:
+**Workflow: Merge last chore → Generate scenarios → Generate step definitions → Propose chores → Commit BDD files → Create chores → Set mode to stable → Invoke stable-mode skill**
 
-```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
-  // 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`);
-  } 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:
+#### Phase 1: Merge Final Speed Chore
 
-**On SUCCESS (GREEN achieved):**
+**Complete the current (final) speed chore:**
 
-```javascript
-// Track what files were created/modified during implementation
-const filesCreated = [/* list of created files */];
-const filesModified = [/* list of modified files */];
+```bash
+# Commit changes in the worktree
+git add . && git commit -m "feat: [brief description of what was implemented]"
 
-console.log(`\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
-console.log(`✅ SPEED MODE COMPLETE - GREEN STATE ACHIEVED`);
-console.log(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`);
+# Merge to main with lock held for transition phase
+# This prevents race conditions when multiple instances generate BDD files simultaneously
+jettypod work merge --with-transition
+```
 
-console.log(`🎉 Happy path scenario: ALL TESTS PASSING\n`);
+<details>
+<summary>💡 Why --with-transition? (click to expand)</summary>
 
-console.log(`Implementation Summary:`);
-console.log(`  Iterations: ${iteration}/${MAX_ITERATIONS}`);
-console.log(`  Test steps: ${currentResult.passed}/${currentResult.total} passing\n`);
+The `--with-transition` flag holds the merge lock through the entire BDD generation phase (Phases 2-6).
 
-if (filesCreated.length > 0) {
-  console.log(`Files created:`);
-  filesCreated.forEach(file => console.log(`  ✅ ${file}`));
-  console.log();
-}
+**Without this flag:**
+- Instance A merges → generates BDD → appends to step_definitions/auth.steps.js
+- Instance B merges → generates BDD → appends to step_definitions/auth.steps.js (CONFLICT!)
+- Second write can overwrite first write, losing step definitions
 
-if (filesModified.length > 0) {
-  console.log(`Files modified:`);
-  filesModified.forEach(file => console.log(`  ✏️  ${file}`));
-  console.log();
-}
+**With this flag:**
+- Instance A acquires lock → merges → generates BDD → commits → releases lock
+- Instance B waits → acquires lock → merges → generates BDD → commits → releases lock
+- No conflicts, all step definitions preserved
 
-// --- Create unit tests for new functions ---
-// For each new function implemented, create a unit test file with happy path coverage
+You'll release the lock in Phase 6 after committing BDD files.
+</details>
 
-// Unit test template for new functions:
-// test/[filename].test.js or __tests__/[filename].test.js
-/*
-const { functionName } = require('../src/path/to/module');
+**CRITICAL: Use ONLY `jettypod work merge` to complete chores.**
+- ❌ DO NOT use `jettypod work status <id> done`
+- ❌ DO NOT use `jettypod work complete <id>`
+- ❌ DO NOT use `jettypod work set-mode <id> done`
+- ✅ ONLY use `jettypod work merge`
 
-describe('functionName', () => {
-  it('should handle valid input successfully', () => {
-    // Arrange
-    const input = validTestData;
+After merge, you are now on main branch. Ready to generate stable mode scenarios.
 
-    // Act
-    const result = functionName(input);
+#### Phase 2: Generate Stable Mode BDD Scenarios
 
-    // Assert
-    expect(result).toEqual(expectedOutput);
-  });
-});
-*/
+**Your task:** Create BDD scenarios for error handling, edge cases, and validation.
 
-// Speed mode unit tests focus on:
-// - Happy path with valid input
-// - One successful operation per function
-// - Basic return value verification
+**Read the feature's existing scenario file:**
 
-console.log(`Next step: Elevate to stable mode using 'jettypod work set-mode <feature-id> stable'\n`);
+```bash
+# Find the feature's scenario file
+sqlite3 .jettypod/work.db "SELECT id, title FROM work_items WHERE id = <feature-id>"
+# Look for: features/bdd/<epic-slug>/<feature-slug>.feature
 ```
 
-**Display:**
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-✅ GREEN STATE ACHIEVED - Now Creating Stable Chores
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+**Analysis checklist for new scenarios:**
+
+1. **Error scenarios** - What can go wrong?
+   - Invalid user input (wrong types, out of range, malformed data)
+   - Missing required parameters
+   - System errors (file not found, network errors, database errors)
+   - Permission/authorization failures
+
+2. **Edge case scenarios** - Boundary conditions
+   - Empty inputs (empty strings, empty arrays, null values)
+   - Maximum values (large numbers, long strings, many items)
+   - Minimum values (zero, negative numbers)
+   - Special characters and Unicode
 
-🎉 Happy path scenario: ALL TESTS PASSING
+3. **State consistency scenarios** - Data integrity
+   - Concurrent operations (race conditions)
+   - Partial failures (transaction rollbacks)
+   - State transitions (invalid state changes)
 
-Implementation Summary:
-  Iterations: 3/10
-  Test steps: 8/8 passing
+**Generate stable scenarios and append to feature file:**
 
-Files created:
-  ✅ src/login.js
-  ✅ src/dashboard.js
+```gherkin
+Scenario: Handle missing required parameter
+  Given the system is initialized
+  When I call the function with missing "name" parameter
+  Then it should throw a validation error
+  And the error message should be "Parameter 'name' is required"
 
-Files modified:
-  ✏️  src/app.js
-  ✏️  src/index.html
+Scenario: Handle empty input
+  Given the system is initialized
+  When I provide an empty string as input
+  Then it should return an appropriate error
+  And the error code should be "INVALID_INPUT"
 
-⚠️  Speed mode is NOT complete until stable chores exist.
-Proceeding to Step 4 to create stable mode chores...
+Scenario: Handle maximum boundary value
+  Given the system is initialized
+  When I provide the maximum allowed value
+  Then it should process successfully
+  And return the expected result
 ```
 
-**On FAILURE (max iterations or timeout):**
+**Append scenarios to the feature file** (don't overwrite existing speed scenarios):
 
-```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:`);
-  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 {
-  // --- 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();
-  }
+```bash
+# Append to existing .feature file
+cat >> features/bdd/<epic-slug>/<feature-slug>.feature << 'EOF'
 
-  // --- Display remaining errors ---
-  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`);
-    });
-  }
-}
+# Stable Mode Scenarios - Error Handling and Edge Cases
 
-// --- 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`);
-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.`);
-```
+Scenario: [Title]
+  Given [context]
+  When [action]
+  Then [expected behavior]
 
-**Display (on failure):**
+Scenario: [Title]
+  Given [context]
+  When [action]
+  Then [expected behavior]
+EOF
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-⚠️  SPEED MODE INCOMPLETE - STILL IN RED STATE
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-❌ Maximum iterations (10) reached
 
-Final Progress: 5/8 steps passing
+#### Phase 3: Generate Stable Mode Step Definitions
 
-Still failing:
-  ✖ Then they should see their dashboard
-  ✖ And the dashboard should show their username
-  ✖ And the dashboard should show their recent activity
+**Your task:** Create step definition files for the new stable scenarios.
 
-Remaining errors:
-  Step: Then they should see their dashboard
-  Error: Cannot read property 'innerText' of null
+**Identify new step definitions needed:**
 
-  Step: And the dashboard should show their username
-  Error: Expected 'John Doe' but got undefined
+1. Read the stable scenarios you just created
+2. Extract unique Given/When/Then steps
+3. Check if step definitions already exist in `features/bdd/<epic-slug>/steps/`
+4. Create new step definition files for missing steps
 
-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
+**Generate step definition files:**
 
-DO NOT proceed to generate stable mode chores until GREEN is achieved.
-```
+```javascript
+// features/bdd/<epic-slug>/steps/<feature-slug>-stable.steps.js
+
+const { Given, When, Then } = require('@cucumber/cucumber');
+const { expect } = require('chai');
+
+// Error handling steps
+When('I call the function with missing {string} parameter', async function(paramName) {
+  try {
+    // Implementation that calls function without parameter
+    this.error = null;
+  } catch (err) {
+    this.error = err;
+  }
+});
 
-**Move to Step 4 IMMEDIATELY if GREEN achieved.**
+Then('it should throw a validation error', function() {
+  expect(this.error).to.exist;
+  expect(this.error.name).to.equal('ValidationError');
+});
 
-**CRITICAL: GREEN is NOT completion - it's just a checkpoint. Speed mode is INCOMPLETE until stable mode chores are created. You MUST continue to Step 4.**
+Then('the error message should be {string}', function(expectedMessage) {
+  expect(this.error.message).to.equal(expectedMessage);
+});
 
-<!-- ═══════════════════════════════════════════════════════════════════════════
-     PHASE 4: STABLE CHORE GENERATION
-     ⚡ ASYNC BOUNDARY - Must wait for user to confirm proposed chores
-     ═══════════════════════════════════════════════════════════════════════════ -->
+// Edge case steps
+When('I provide an empty string as input', async function() {
+  this.result = await this.functionUnderTest('');
+});
 
-### Step 4: Generate Stable Mode Chores (REQUIRED - Do Not Skip)
+When('I provide the maximum allowed value', async function() {
+  this.result = await this.functionUnderTest(Number.MAX_SAFE_INTEGER);
+});
+```
 
-**CRITICAL:** This step is MANDATORY. Speed mode is NOT complete until stable mode chores exist. Without them, users cannot resume work on this feature.
+**Create step definition files:**
 
-**Two phases: Analyze and propose → Get confirmation → Create autonomously**
+```bash
+# Create the step definition file
+touch features/bdd/<epic-slug>/steps/<feature-slug>-stable.steps.js
+# Write the step definitions to the file
+```
 
-#### Phase 1: Analyze Implementation
+#### Phase 4: Analyze Implementation and Propose Stable Mode Chores
 
-**Your task:** Review what was built and identify what's needed for stable mode.
+**Your task:** Based on the stable scenarios and step definitions, identify what needs to be implemented.
 
 **Analysis checklist:**
 
 1. **Error handling gaps**
-   - What user errors are possible?
-   - What system errors could occur?
-   - What validation is missing?
-
-2. **Edge cases**
-   - Boundary conditions (empty inputs, max values, etc.)
-   - Race conditions
-   - State consistency issues
-
-3. **Non-happy-path scenarios**
-   - Read the full scenario file (not just happy path)
-   - Identify scenarios 2+ (error handling, edge cases)
-   - Check what additional behavior is needed
-
-4. **Code quality needs**
-   - What needs better structure/organization?
-   - What needs proper error messages?
-   - What needs logging/debugging support?
+   - What validation needs to be added?
+   - What error types need to be thrown?
+   - What error messages need to be user-friendly?
+
+2. **Edge case handling**
+   - What boundary checks are needed?
+   - What null/undefined checks are missing?
+   - What type validation is needed?
 
-#### Phase 2: Propose Stable Mode Chores
+3. **Code that needs refactoring**
+   - What needs better structure for error handling?
+   - What needs logging/debugging support?
+   - What needs better separation of concerns?
 
 **Present your analysis:**
 
 ```
 📋 Stable Mode Chores Proposal
 
-I've analyzed the implementation. Here are the chores needed for stable mode:
+I've generated [N] stable mode scenarios covering error handling and edge cases.
+I've created step definitions for these scenarios.
+
+Here are the chores needed to make these scenarios pass:
 
 **Chore 1: [Title]**
 - Why: [What gap this fills]
 - Scope: [What specifically needs to be done]
-- Scenario: [Which BDD scenario this addresses, if applicable]
+- Scenarios: [Which BDD scenarios this addresses]
 
 **Chore 2: [Title]**
 - Why: [What gap this fills]
 - Scope: [What specifically needs to be done]
-- Scenario: [Which BDD scenario this addresses, if applicable]
+- Scenarios: [Which BDD scenarios this addresses]
 
 **Chore 3: [Title]**
 - Why: [What gap this fills]
 - Scope: [What specifically needs to be done]
-- Scenario: [Which BDD scenario this addresses, if applicable]
+- Scenarios: [Which BDD scenarios this addresses]
 
-These chores will make all BDD scenarios pass with proper error handling and edge case coverage.
+These chores will make all stable mode scenarios pass with proper error handling and edge case coverage.
 
 Sound good? I'll create these chores once you confirm.
 ```
@@ -777,12 +810,7 @@ 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
+#### Phase 5: Create Chores Autonomously
 
 **CRITICAL:** After user confirms, create chores programmatically - no additional permission needed.
 
@@ -790,7 +818,7 @@ If user adjusts: revise chores and confirm again.
 
 ```javascript
 const { create } = require('./features/work-tracking');
-const { getCurrentWork } = require('../../lib/current-work');
+const { getCurrentWork } = require('./lib/current-work');
 
 (async () => {
   const currentWork = await getCurrentWork();
@@ -812,46 +840,47 @@ Chores created:
 • #[ID]: [Title]
 ```
 
-#### Phase 4: Auto-Elevate to Stable Mode (If All Speed Chores Done)
+#### Phase 6: Commit Stable Mode Scenarios and Steps to Main
 
-**CRITICAL: Check if ALL speed mode chores are complete. If yes, auto-elevate to stable mode.**
+**CRITICAL: Commit the BDD files to main BEFORE starting stable chores.**
 
-<!-- ┌─────────────────────────────────────────────────────────────────────────┐
-     │ 🔍 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                │
-     └─────────────────────────────────────────────────────────────────────────┘ -->
+```bash
+# You're currently on main after merging the last speed chore
+# Commit the stable mode scenarios and step definitions
+git add features/
+git commit -m "test: Add stable mode BDD scenarios and step definitions
 
-**Check for incomplete speed chores:**
+Added error handling and edge case scenarios for stable mode implementation.
 
-```bash
-# Get current work to find parent feature ID
-jettypod work current
+- [N] new stable mode scenarios
+- Step definitions for validation, error handling, and edge cases"
 
-# Count incomplete speed chores for the feature
-sqlite3 .jettypod/work.db "SELECT COUNT(*) FROM work_items WHERE parent_id = <feature-id> AND type = 'chore' AND mode = 'speed' AND status != 'done'"
+# Push to remote
+git push
+
+# Release the merge lock (held since Phase 1)
+jettypod work merge --release-lock
 ```
 
-**If all speed chores are done (count = 0), EXECUTE elevation:**
+This ensures stable mode BDD files are in main and will be present in stable chore worktrees.
+
+The merge lock is now released - other instances can proceed with their transitions.
+
+#### Phase 7: Set Feature Mode to Stable
+
+**Set the feature mode:**
 
 ```bash
 jettypod work set-mode <feature-id> stable
 ```
 
-**DO NOT display this as example text. EXECUTE IT using the Bash tool.**
+#### Phase 8: Invoke Stable Mode Skill
 
-After execution, display:
+**CRITICAL: Immediately transition to stable-mode skill to start implementing stable chores.**
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-🎯 Speed Mode Complete! Feature Elevated to Stable Mode
+🎯 Speed Mode Complete! Transitioning to Stable Mode
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 ⚠️  CRITICAL: Speed mode is ONLY a checkpoint to prove functionality works.
@@ -859,56 +888,35 @@ 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
+✅ Generated [N] stable mode BDD scenarios
+✅ Created step definitions for stable scenarios
+✅ Created [N] stable mode chores
+✅ Feature mode set to stable
 
-🚀 NEVER leave a feature in speed mode - it's not production-ready.
+🚀 NEVER leave a feature in speed mode.
 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]
-```
-
-**If speed chores remain, display:**
+  • All BDD scenarios passing (success scenarios + error/edge cases)
 
+**Next step:** I'm now invoking the stable-mode skill to start implementing the first stable chore.
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-🎯 Speed Mode Chore Done - Stable Chores Created
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-What we accomplished:
-✅ Happy path scenario passes for this chore
-✅ Stable mode chores created for when speed mode finishes
 
-Remaining speed mode chores: [count]
+**Invoke the stable-mode skill:**
 
-⚠️  Speed mode is NOT complete yet - [count] chores remain.
-You can take a break here - stable mode chores exist and work can resume.
+Use the Skill tool to automatically transition to stable mode implementation:
 
-**Next step:** Continue with next speed mode chore
-  jettypod work start [next-speed-chore-id]
 ```
-
-**Mark current chore as done:**
-
-Use Bash tool to commit and push:
-```bash
-git add . && git commit -m "feat: [brief description of what was implemented]" && git push
-```
-
-Then use the merge command to merge to main (which auto-marks chore as done via post-merge hook):
-```bash
-jettypod work merge
+Skill tool with skill="stable-mode"
 ```
 
-The post-merge hook will automatically mark the chore as done when merged to main.
+The stable-mode skill will:
+1. Start the first stable chore automatically
+2. Guide implementation to make stable scenarios pass
+3. Continue with remaining stable chores
 
-**End skill.**
+**End speed-mode skill.**