jettypod 4.2.11 → 4.3.0

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

@@ -5,18 +5,14 @@ description: Guide implementation of stable mode chores with comprehensive testi
 
 # Stable Mode Skill
 
-```
-┌─────────────────────────────────────────────────────────────────────┐
-│  Mode Progression Flow                                               │
-│                                                                      │
-│  Feature Planning → Speed Mode → [STABLE MODE] → Production Mode     │
-│                                   ▲▲▲▲▲▲▲▲▲▲▲▲▲                      │
-│                                   YOU ARE HERE                       │
-│                                                                      │
-│  Next: After stable mode implementation, feature can be marked       │
-│        complete, or elevated to production mode if needed.           │
-└─────────────────────────────────────────────────────────────────────┘
-```
+**Mode Progression:**
+Feature Planning → Speed Mode → **[STABLE MODE]** → Done (Internal) OR Production Mode (External)
+
+**You are here:** Adding error handling, validation, and edge cases to speed mode implementation.
+
+**Next steps:**
+- INTERNAL projects: Feature complete after stable mode (no production mode needed)
+- EXTERNAL projects: Continue to production mode for security/scale/monitoring
 
 Guides Claude Code through stable mode implementation with comprehensive testing focus. Users confirm approach but Claude Code writes the code.
 
@@ -24,13 +20,33 @@ Guides Claude Code through stable mode implementation with comprehensive testing
 
 When this skill is activated, you are helping implement a stable mode chore to add comprehensive testing and error handling. 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
 
-**Stable Mode Goal:** Transform speed mode's "prove it works" implementation into production-ready code with comprehensive robustness.
+**Stable Mode Goal:** Transform speed mode's "make it work" implementation into robust, reliable code with comprehensive error handling and validation.
 
 **CRITICAL DISTINCTION:**
-- **Speed mode implemented ALL functionality** - every feature/function is already working on the happy path
-- **Stable mode adds COMPLETE robustness** - NOT just error handling, but comprehensive production readiness
+- **Speed mode implemented ALL functionality** - every feature/function is already working (all success scenarios)
+- **Stable mode adds COMPLETE robustness** - error handling, validation, and edge cases
+
+**Key Principles:**
+- **Build on speed implementation** - do not re-implement features, ADD robustness to them
+- **Autonomous execution** - Claude Code writes code, user confirms approach
+- **Quality focus** - code should be stable, maintainable, and reliable (ready for internal use)
+
+<details>
+<summary><strong>📋 What Stable Mode Includes (click to expand)</strong></summary>
 
 **Stable Mode is NOT just error handling. It includes:**
 
@@ -61,34 +77,72 @@ When this skill is activated, you are helping implement a stable mode chore to a
    - Handle interrupted operations
 
 5. **All BDD Scenarios Pass**
-   - Happy path (already passing from speed mode)
+   - Success scenarios (already passing from speed mode - required + optional features)
    - Error scenarios (how does it handle failures?)
    - Edge case scenarios (boundary conditions, unusual inputs)
    - Concurrent access scenarios (multiple instances)
 
-**Key Principles:**
-- **Build on speed implementation** - do not re-implement features, ADD robustness to them
-- **Autonomous execution** - Claude Code writes code, user confirms approach
-- **Quality focus** - code should be stable, maintainable, and production-ready
+</details>
 
 **User Profile:** May not know how to code - Claude Code does the implementation autonomously.
 
 ---
 
+## 🧪 Unit Testing in Stable Mode - True TDD
+
+**Unit tests are written DURING implementation, not after.**
+
+**The TDD workflow (each iteration):**
+1. **Identify next failing BDD step** - Which error/edge case scenario step needs to pass?
+2. **Write unit test for the validation/error handling** - Test the specific error condition
+3. **Watch unit test fail (RED)** - Confirm test catches the missing validation
+4. **Write minimal code** - Add error handling, validation, or edge case handling
+5. **Run unit test (GREEN)** - Verify the validation/error handling works in isolation
+6. **Run BDD scenarios** - Check if this makes any error/edge case BDD steps pass
+7. **Next iteration** - Repeat for next failing step
+
+**What to unit test in stable mode:**
+- Validation functions (null checks, type checks, range validation)
+- Error handling logic (catch blocks, error recovery)
+- Edge case handling (empty arrays, boundary values)
+- State consistency (transaction rollback, cleanup on failure)
+
+**Unit test scope in stable mode:**
+```javascript
+// ✅ Stable mode unit tests (error paths and edge cases)
+test('createUser throws ValidationError for null email', () => {
+  expect(() => createUser('John', null)).toThrow(ValidationError);
+  expect(() => createUser('John', null)).toThrow('Email is required');
+});
+
+test('createUser handles empty string email', () => {
+  expect(() => createUser('John', '')).toThrow(ValidationError);
+});
+
+test('getUserById returns null for non-existent user', () => {
+  const user = getUserById(99999);
+  expect(user).toBeNull();
+});
+```
+
+---
+
 ## 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 |
+| Phase | Location | Why | Condition |
+|-------|----------|-----|-----------|
+| Step 3A | Before implementing (conditional) | User confirms implementation approach | Only if approach is ambiguous or multiple valid paths |
 
 **Where Claude Code executes autonomously:**
-- Step 0: Create additional scenarios (if first stable chore)
+- Step 0: Initialize context
 - Step 1: Scenario analysis
 - Step 2: Speed mode implementation review
-- Step 3 Phase 2: Autonomous execution loop
-- Step 4: Completion check and routing
+- Step 3: Decision to skip/ask for confirmation
+- Step 4: Establish RED baseline
+- Step 5: RED→GREEN→REFACTOR loop (true TDD)
+- Step 6: Check progress and route to next chore or completion
 
 ---
 
@@ -105,7 +159,7 @@ For external products accepting real users, stable mode is NOT the final step. P
 **Required workflow for EXTERNAL products after stable mode implementation:**
 
 1. ✅ **Complete ALL stable mode chores** - Add error handling and edge cases
-2. ✅ **Generate production mode chores** - Use `jettypod work elevate <feature-id> production`
+2. ✅ **Set feature to production mode** - Use `jettypod work set-mode <feature-id> production`
 3. ✅ **Implement production mode chores** - Add performance, security, monitoring
 4. ❌ **NEVER mark feature complete in stable mode for external products** - This bypasses critical production hardening
 
@@ -114,8 +168,8 @@ For external products accepting real users, stable mode is NOT the final step. P
 **If you attempt to mark an external product feature complete while in stable mode, the system will block you with an error.**
 
 The validation will require you to either:
-- Generate production mode chores: `jettypod work elevate <feature-id> production`
-- Or explicitly skip (not recommended): `jettypod work set-mode <feature-id> production --force`
+- Set feature to production mode: `jettypod work set-mode <feature-id> production`
+- Or explicitly force skip (not recommended): `jettypod work set-mode <feature-id> production --force`
 
 **Remember:** Stable mode makes it robust. Production mode makes it ready for real users at scale.
 
@@ -123,48 +177,34 @@ The validation will require you to either:
 
 ## Implementation Steps
 
-<!-- ═══════════════════════════════════════════════════════════════════════════
-     PHASE 1: AUTONOMOUS SETUP
-     No user input required - Claude Code executes independently
-     ═══════════════════════════════════════════════════════════════════════════ -->
+### Step 0: Initialize Stable Mode Context
 
-### Step 0: Create Additional Scenarios (If First Stable Chore)
+**You are now in stable mode,** implementing a chore to add error handling and edge case coverage.
 
-**CRITICAL:** If this is the FIRST stable mode chore for this feature, you must ADD edge case scenarios and step definitions.
+**Get the current work context:**
 
-**Check if scenarios exist beyond happy path:**
-1. Read the feature's `.feature` file
-2. Count scenarios - if only 1 (happy path), ADD edge case scenarios
-3. Update step definitions to include new scenarios
+```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'"
+```
 
-**Add to `.feature` file:**
-```gherkin
-# Error handling scenario
-Scenario: [Error case title]
-  Given [setup for error condition]
-  When [action that triggers error]
-  Then [expected error handling]
-  And [system remains stable]
+**Display to user:**
 
-# Edge case scenario
-Scenario: [Edge case title]
-  Given [edge condition setup]
-  When [action at boundary]
-  Then [expected edge case behavior]
 ```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🛡️  STABLE MODE: Implementing Chore #[id]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-**Add to `features/step_definitions/[feature-slug].steps.js`:**
-- Implement Given/When/Then steps for new scenarios
-- Follow existing patterns from happy path steps
-- Include proper error assertions
+Chore: [title]
+Feature: #[parent-id] [parent-title]
+Worktree: [worktree_path]
+Branch: [branch_name]
+
+Analyzing stable mode BDD scenarios to determine what error handling and validation to add...
+```
 
-**Update unit tests with edge cases:**
-- Speed mode generated basic unit tests with TODO placeholders
-- Stable mode should fill in edge case tests for error handling
-- Add tests for: null/undefined inputs, invalid data, boundary conditions
-- Use existing test files at `test/[path]/[file].test.js`
+**Then proceed to Step 1.**
 
-**IMPORTANT:** Only do this ONCE per feature (first stable chore). Subsequent stable chores implement existing scenarios.
+---
 
 ### Step 1: Analyze Scenario to Implement
 
@@ -172,21 +212,18 @@ Scenario: [Edge case title]
 
 **Your task:**
 1. Get current work item and parent feature's scenario file
-2. Read the full scenario file (should now have happy path + edge cases)
+2. Read the full scenario file (should have success scenarios + stable mode error/edge case scenarios)
 3. Identify which scenario this chore addresses
 4. Extract requirements from the scenario's Given/When/Then steps
+5. Check chore description for breadcrumbs (implementation guidance from feature-planning)
+
+**NOTE:** Scenarios and step definitions already exist, created by the speed-mode skill during transition to stable mode. Chore descriptions may contain breadcrumbs with implementation guidance (files to modify, patterns to follow, functions to add validation to).
 
 **To get scenario information, use these commands:**
 
 ```bash
-# Get current work (chore) and its parent feature
-jettypod work current
-
-# Get parent feature details including scenario_file
-jettypod work show <parent-feature-id>
-
-# Or query database directly for scenario file
-sqlite3 .jettypod/work.db "SELECT id, title, scenario_file, mode FROM work_items WHERE id = <parent-feature-id>"
+# Get current work (chore) and its parent feature with scenario_file
+sqlite3 .jettypod/work.db "SELECT wi.id, wi.title, wi.description, wi.parent_id, parent.title as parent_title, parent.scenario_file, parent.mode FROM work_items wi LEFT JOIN work_items parent ON wi.parent_id = parent.id WHERE wi.status = 'in_progress'"
 ```
 
 **Then read the scenario file** using the Read tool on the path returned by `scenario_file`.
@@ -223,6 +260,12 @@ What needs to happen:
 • [When] Action/condition: [requirement]
 • [Then] Expected behavior: [requirement]
 
+[If breadcrumbs exist in chore description:]
+Implementation guidance:
+• Files: [files to modify]
+• Patterns: [patterns to follow]
+• Functions: [specific functions to add validation to]
+
 Now reviewing speed mode implementation...
 ```
 
@@ -266,7 +309,7 @@ Then use the Read tool to examine the implementation files.
 
 Current Implementation:
 • Files: [list]
-• Happy path: ✅ Working
+• Success scenarios: ✅ Working (from speed mode)
 • Error handling: ❌ Missing [specific gaps]
 • Validation: ❌ Missing [specific gaps]
 • Edge cases: ❌ Not handled [specific gaps]
@@ -279,392 +322,286 @@ To pass the target scenario, I need to:
 Now proposing comprehensive implementation...
 ```
 
-**Move to Step 3 automatically.**
+### Step 3: Decide if Confirmation Needed
+
+**Evaluate if you need user confirmation before implementing:**
+
+**Skip confirmation (proceed directly to Step 4) if:**
+- Chore description is comprehensive (specific validation/error handling described)
+- Implementation approach is clear and unambiguous
+- Only one reasonable way to add the error handling
+- Similar patterns exist in codebase to follow
+
+**Ask for confirmation (Step 3A) if:**
+- Multiple valid error handling approaches exist
+- Chore description is vague about specific validation
+- Architectural choice impacts other features
+- You're uncertain about the right approach
 
-<!-- ═══════════════════════════════════════════════════════════════════════════
-     PHASE 2: USER CONFIRMATION REQUIRED
-     ⚡ ASYNC BOUNDARY - Must wait for user response before proceeding
-     ═══════════════════════════════════════════════════════════════════════════ -->
+### Step 3A: Propose Implementation Approach (Conditional)
 
-### Step 3: Propose and Execute Comprehensive Implementation
+**⚡ ASYNC BOUNDARY - Only execute this if confirmation needed**
 
-**Two phases: Propose (get user confirmation) → Execute (autonomous)**
+**Present your analysis and proposal to the user:**
 
-#### Phase 1: Propose Comprehensive Implementation
+```
+💡 Implementation Proposal
+
+I see multiple ways to approach this error handling. Here's what I'm thinking:
 
-**Present your analysis and proposal:**
+**Option I'm recommending:**
+• Error handling strategy: [specific approach]
+• Validation approach: [what to validate and how]
+• Why: [rationale - why this over alternatives]
+
+**Alternative considered:**
+• [Brief description] - not choosing because [reason]
 
 ```
-💡 Comprehensive Implementation Proposal
 
-Based on scenario and code analysis, here's how I'll add proper error handling and make the scenario pass:
+**⚡ WAIT for user confirmation or adjustments.**
 
-**Changes needed:**
-1. [File]: Add [specific error handling/validation]
-2. [File]: Add [specific edge case handling]
-3. [File]: Add [specific tests]
+If user adjusts: revise proposal and confirm again before proceeding.
 
-**Error handling approach:**
-• [Specific errors to catch and how to handle them]
-• [User-friendly error messages]
-• [Graceful failure behavior]
+**If you skipped this step:** Proceed directly to Step 4.
 
-**Validation approach:**
-• [Input validation checks]
-• [Boundary condition handling]
-• [State validation]
+---
 
-**Why this approach:**
-[Brief explanation of how this satisfies the scenario with proper quality]
+### Step 4: Establish RED Baseline
 
-Sound good? I'll implement this autonomously once you confirm.
+**CRITICAL:** After user confirms (or skips confirmation), 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
+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
 ```
 
-**WAIT for user confirmation or adjustments.**
+Parse the output to identify:
+- Total steps and how many are failing
+- Which specific stable mode steps are failing (error/edge case scenarios)
+- The first error message
 
-If user adjusts: revise proposal and confirm again.
+This establishes your RED baseline - stable mode scenarios should be failing initially.
 
-<!-- ═══════════════════════════════════════════════════════════════════════════
-     PHASE 3: AUTONOMOUS EXECUTION
-     User has confirmed - Claude Code executes iteration loop independently
-     ═══════════════════════════════════════════════════════════════════════════ -->
+**Display RED baseline:**
+```
+🔴 Establishing RED baseline...
 
-#### Phase 2: Autonomous Execution
+RED Baseline: 3 of 11 steps failing (stable mode scenarios)
 
-**CRITICAL:** After user confirms, Claude Code executes autonomously - no permission needed for individual code changes.
+Failing steps:
+  ✖ Then it should throw a validation error
+  ✖ And the error message should be "Email is required"
+  ✖ When I provide an empty string as input
 
-**Execution loop (with iteration limits and error handling):**
+First error:
+  Step: Then it should throw a validation error
+  Error: Error: Expected function to throw but it didn't
 
-<!-- ┌─────────────────────────────────────────────────────────────────────────┐
-     │ 🔄 ITERATION LOOP: Stable Mode Scenario                                │
-     │                                                                         │
-     │ Progress Tracking:                                                      │
-     │ • Display: "Iteration X/10" at start of each cycle                     │
-     │ • Track: scenarios passing, steps passing, newly passing               │
-     │ • Goal: Target scenario + all scenarios pass                           │
-     │                                                                         │
-     │ Return Points:                                                          │
-     │ • CHECKPOINT_ITERATION: Resume at specific iteration number            │
-     │ • CHECKPOINT_SCENARIO: Resume with known scenario status               │
-     │ • If session interrupted, can resume from last known iteration         │
-     └─────────────────────────────────────────────────────────────────────────┘ -->
+🎯 Goal: Make all stable mode scenarios pass
 
-```javascript
-// --- Imports ---
-const {
-  MAX_ITERATIONS, TEST_TIMEOUT, runBddTestWithTimeout,
-  runBddScenarioWithTimeout, getScenarioLineByName,
-  parseTestProgress, extractErrors, findNewlyPassingSteps
-} = require('../../.claude/skills/speed-mode/test-runner');
-
-// --- Find scenario line number ---
-const scenarioLine = getScenarioLineByName(feature.scenario_file, targetScenario.title);
-if (!scenarioLine) {
-  console.error('❌ Cannot find scenario line number for:', targetScenario.title);
-  return;
-}
-
-let iteration = 0;
-let scenarioPasses = false;
-let previousResult = null;
-
-// --- Main iteration loop ---
-// 📊 PROGRESS: Iteration {iteration}/{MAX_ITERATIONS} | Scenario: {scenarioPasses ? 'PASS' : 'FAIL'}
-while (!scenarioPasses && iteration < MAX_ITERATIONS) {
-  iteration++;
-  console.log(`\n🔄 Iteration ${iteration}/${MAX_ITERATIONS}`);
-
-  // --- Make code changes ---
-  try {
-    console.log('✍️  Adding error handling to [file]...');
-    // ... use Edit tool ...
-    console.log('✅ Updated [file]');
-  } catch (editErr) {
-    console.error('❌ Error modifying files:', editErr.message);
-    continue;
-  }
-
-  // --- Run tests ---
-  console.log('🧪 Running tests...');
-  const result = await runBddScenarioWithTimeout(feature.scenario_file, scenarioLine, TEST_TIMEOUT);
-
-  // --- Handle timeout ---
-  if (result.timedOut) {
-    console.error('❌ Tests timed out after 60 seconds');
-    console.log('Suggestion: Check for blocking operations or missing async/await');
-    break;
-  }
-
-  // --- Parse and track progress ---
-  const currentResult = parseTestProgress(result.stdout);
-  const newlyPassing = findNewlyPassingSteps(previousResult, currentResult);
-
-  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}`));
-  }
-
-  // --- Check for success ---
-  if (currentResult.passed === currentResult.total && currentResult.total > 0) {
-    console.log('\n✅ Target scenario passing!');
-
-    // --- Run full verification ---
-    console.log('\n🔍 Running full verification (all scenarios)...');
-    const fullResult = await runBddTestWithTimeout(feature.scenario_file, TEST_TIMEOUT);
-
-    if (fullResult.timedOut) {
-      console.log('⚠️  Full verification timed out');
-    } else if (fullResult.exitCode !== 0) {
-      const fullProgress = parseTestProgress(fullResult.stdout + fullResult.stderr);
-      console.log(`⚠️  Regressions found: ${fullProgress.total - fullProgress.passed} scenarios failing`);
-      scenarioPasses = false;
-    } else {
-      console.log('✅ Full verification passed!');
-      scenarioPasses = true;
-    }
-  } else {
-    // --- Display errors ---
-    console.log(`\n❌ ${currentResult.total - currentResult.passed} scenarios still failing`);
-    const errors = extractErrors(result.stdout + result.stderr);
-    if (errors.errors.length > 0) {
-      console.log('\n🔧 Next failure to address:');
-      console.log(`  Step: ${errors.errors[0].step}`);
-      console.log(`  Error: ${errors.errors[0].message}`);
-    }
-  }
-
-  previousResult = currentResult;
-}
-
-// --- Handle max iterations reached ---
-if (!scenarioPasses && iteration >= MAX_ITERATIONS) {
-  console.error('\n❌ Maximum iterations reached without passing scenario');
-  console.log('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
-  console.log('🛑 Unable to make scenario pass automatically');
-  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
-  console.log('\nPossible reasons:');
-  console.log('• Scenario requirements may need clarification');
-  console.log('• Implementation approach may need rethinking');
-  console.log('• External dependencies may be missing');
-  console.log('\nHow would you like to proceed?');
-  console.log('  1. Review changes made so far');
-  console.log('  2. Try a different approach');
-  console.log('  3. Debug manually');
-  return;
-}
-```
-
-**Display progress:**
-```
-🔄 Iteration 1/10
-
-✍️  Adding error handling to [file]...
-✅ Updated [file]
-
-🧪 Running tests...
-✅ Target scenario passes!
-✅ All scenarios still passing!
-```
-
-**Stable mode focus:**
-- **Add to existing implementation** - speed mode already implemented all features
-- **Comprehensive error handling** - wrap existing code with try/catch, handle failures gracefully
-- **Input validation** - add checks before existing logic (null checks, type checks, range validation)
-- **Edge case handling** - handle empty arrays, missing properties, boundary values, concurrent access
-- **Clear error messages** - user-friendly, actionable feedback for all failure modes
-- **All BDD scenarios pass** - happy path (already passing from speed) AND error/edge scenarios
-
-**When all scenarios pass:**
-
-```
-🎉 Stable mode scenario passes!
-
-Implementation complete:
-• Modified: [list files]
-• Error handling: ✅ Comprehensive
-• Validation: ✅ Complete
-• All scenarios: ✅ Passing
-```
-
-**Run unit test coverage (if configured):**
-```bash
-# If project has coverage configured, run it:
-npm run test:coverage
-# Or with Jest:
-npx jest --coverage
+Now implementing...
 ```
 
-Note: Coverage tracking is project-specific. Check your package.json for the appropriate coverage command.
+---
+
+### Step 5: RED→GREEN→REFACTOR Loop
+
+**Execute autonomously** - iterate until tests pass (max 10 iterations).
+
+**Each iteration (True TDD):**
+
+1. **Identify next failing BDD step** - Which error/edge case scenario step to tackle?
+2. **Write unit test** - Test the validation/error handling needed (watch it fail - RED)
+3. **Write minimal implementation** - Add error handling, validation, or edge case code
+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.
+
+**Show progress each iteration:**
+```
+━━━ Iteration 3/10 ━━━
+📝 Unit test: test/user.test.js - validates email format
+   RED: Test fails - no validation exists yet
+✍️  Implementation: src/user.js - added email format validation
+   GREEN: Unit test passes
+🧪 Running BDD scenarios...
+📊 Progress: 9/11 BDD steps passing
+✅ Newly passing: Then it should throw a validation error
+🔧 Next failure: And the error message should be user-friendly
+    BDD step: Then the error message should be "Email format is invalid"
+```
 
-**Display coverage summary:**
+**When GREEN achieved:**
 ```
-📊 Unit Test Coverage Report
-─────────────────────────────
-Statements: ✅ 85.23%
-Branches:   ✅ 82.15%
-Functions:  ✅ 88.50%
-Lines:      ✅ 84.90%
-─────────────────────────────
-✅ All coverage metrics meet 80% threshold
+🎉 GREEN: All stable mode scenarios passing!
 ```
 
-<!-- ═══════════════════════════════════════════════════════════════════════════
-     PHASE 4: COMPLETION AND ROUTING
-     Conditional phase - route based on project state (internal vs external)
-     ═══════════════════════════════════════════════════════════════════════════ -->
+**Then REFACTOR (quick pass, 5 min max):**
+- Extract duplicated validation logic
+- Rename unclear error variables
+- Simplify complex error handling
+- Remove dead code
 
-### Step 4: Check for Production Mode (When All Stable Chores Complete)
+**Re-run tests after refactor** to ensure nothing broke.
 
-**CRITICAL: This step ONLY happens when ALL stable chores for the feature are complete. Otherwise skip to marking chore as done.**
+<details>
+<summary><strong>📋 TDD Loop Guidelines (click to expand)</strong></summary>
 
-<!-- ┌─────────────────────────────────────────────────────────────────────────┐
-     │ 🔍 COMPLETION CHECK: Stable Chores                                     │
-     │                                                                         │
-     │ Progress Tracking:                                                      │
-     │ • Query: Count incomplete chores for feature                           │
-     │ • Display: "X chores remaining" or "All complete"                      │
-     │ • Action: Route based on project state (internal vs external)          │
-     │                                                                         │
-     │ Return Point:                                                           │
-     │ • CHECKPOINT_CHORE_COUNT: Known incomplete count from last check       │
-     │ • CHECKPOINT_PROJECT_STATE: Known project state for routing            │
-     │ • If session interrupted, re-query to get current counts               │
-     └─────────────────────────────────────────────────────────────────────────┘ -->
+**Iteration strategy:**
+- Start with first failing stable mode step
+- Make minimal change to pass that step
+- Run tests immediately
+- Move to next failure
 
-**Check completion status and project state:**
+**If stuck after 5 iterations:**
+- Review approach - is there a simpler validation?
+- Check assumptions - are you handling the right error?
+- Break down the change - can you add validation incrementally?
+
+**Max 10 iterations:**
+- If you hit max without GREEN, stop
+- Display final progress and suggest next steps
+- Consider breaking chore into smaller pieces
+
+</details>
+
+---
+
+**CRITICAL: Check if ALL stable mode chores are complete. Route to next chore if any remain.**
+
+**Check for incomplete stable chores:**
 
 ```bash
 # Get current work to find parent feature ID
-jettypod work current
+sqlite3 .jettypod/work.db "SELECT wi.parent_id FROM work_items wi WHERE wi.status = 'in_progress'"
 
-# Count incomplete chores for the feature
-sqlite3 .jettypod/work.db "SELECT COUNT(*) FROM work_items WHERE parent_id = <feature-id> AND type = 'chore' AND status NOT IN ('done', 'cancelled')"
+# Get list of remaining stable chores (excluding current chore)
+sqlite3 .jettypod/work.db "SELECT id, title FROM work_items WHERE parent_id = <feature-id> AND type = 'chore' AND mode = 'stable' AND status != 'done' AND id != <current-chore-id> ORDER BY created_at LIMIT 1"
+```
+
+**If stable chores remain, display and start next chore:**
 
-# Check project state
-sqlite3 .jettypod/work.db "SELECT project_state FROM project_config WHERE id = 1"
 ```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🎯 Stable Mode Chore Complete
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+✅ Error handling and validation scenarios pass for this chore
 
-Based on the results:
-- If incomplete_count > 0: More stable chores remain
-- If incomplete_count = 0 AND project_state = 'internal': Feature is complete
-- If incomplete_count = 0 AND project_state = 'external': Need to generate production chores
+More stable mode chores remain. Starting next chore:
+#[next-chore-id]: [next-chore-title]
+```
 
-**CRITICAL: Check project state to determine next step:**
+**Then immediately merge current chore and start next:**
 
-Check if project is internal or external:
 ```bash
-# Check project_state in database
-node jettypod.js work show 1 | grep "Project state:"
-# OR read CLAUDE.md <project_state> tag
+# Commit changes in the worktree
+git add . && git commit -m "feat: [brief description of error handling added]"
+
+# Merge current chore - this automatically marks it as done
+jettypod work merge
+
+# Start next stable chore
+jettypod work start [next-chore-id]
 ```
 
+**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`
+
+The merge command handles everything: pushes branch, merges to main, marks chore done, cleans up worktree.
+
+The stable-mode skill will automatically re-invoke for the next chore.
+
+**If all stable chores are done (count = 0), continue to Step 6 below.**
+
 ---
 
-### Option A: Project is INTERNAL
+### Step 6: Route to Completion (After All Stable Chores Complete)
 
-**For internal projects, stable mode is the FINAL state.**
+**CRITICAL: This step ONLY happens when ALL stable chores for the feature are complete.**
+
+**Check project state:**
 
-**ACTION REQUIRED:** Mark the feature as done:
 ```bash
-node jettypod.js work status [feature-id] done
+# Check project_state in database (RECOMMENDED - always up to date)
+sqlite3 .jettypod/work.db "SELECT project_state FROM project_config WHERE id = 1"
+
+# OR read CLAUDE.md from git root (NOT from CWD - worktrees may have stale copies)
+grep -A1 "<project_state>" "$(git rev-parse --show-toplevel)/CLAUDE.md" | tail -1
 ```
 
-Then display to user:
+⚠️ **CRITICAL:** If reading CLAUDE.md, always read from git root using `$(git rev-parse --show-toplevel)/CLAUDE.md`, NOT from current directory. Worktrees branch from main and may have stale project_state values.
 
+**Route based on project state:**
+
+**If project_state = 'internal':**
+
+Mark the feature as done:
+```bash
+node jettypod.js work status [feature-id] done
+```
+
+Display:
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ✅ FEATURE #[id] COMPLETE!
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 Feature: [Feature Title]
 Status: ✅ DONE
 
 What we accomplished:
-✅ All BDD scenarios passing (happy path + error handling + edge cases)
+✅ All BDD scenarios passing (success + error handling + edge cases)
 ✅ Comprehensive error handling and validation
 ✅ Input validation and edge case coverage
 ✅ State consistency and data integrity
-✅ All code merged to main and pushed to GitHub
 
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 📝 INTERNAL PROJECT - STABLE MODE IS COMPLETE
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 This is an internal project - stable mode is the end state.
-No production hardening needed.
-
 Feature is complete and ready to use!
 
-Note: If you later transition to external state (accepting real users),
-you can run the external-transition skill to generate production chores.
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Note: If you later transition to external (accepting real users),
+run the external-transition skill to generate production chores.
 ```
 
-**End skill.** The feature is DONE.
+**End skill.** Feature is DONE.
 
 ---
 
-### Option B: Project is EXTERNAL
-
-**For external projects, continue to production mode.**
-
-Use the Skill tool to invoke the production-mode skill:
+**If project_state = 'external':**
 
-```javascript
-// Use Skill tool to invoke: production-mode
-// The production-mode skill will:
-// 1. Detect feature context (Scenario A/B/C)
-// 2. Generate production scenarios from standards
-// 3. Append scenarios to feature file
-// 4. Create production chores
-```
-
-Display to user:
+Use Skill tool to invoke production-mode:
 
+Display:
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ✅ ALL STABLE MODE CHORES COMPLETE!
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 What we accomplished:
-✅ All BDD scenarios passing (happy path + error handling + edge cases)
+✅ All BDD scenarios passing (success + error handling + edge cases)
 ✅ Comprehensive error handling and validation
 ✅ Feature stable and ready for production hardening
 
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 🚀 AUTO-GENERATING PRODUCTION CHORES
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 This project is external - invoking production-mode skill to:
   • Detect feature context (authentication/data/general)
   • Generate production scenarios from standards
   • Create production chores with proper scope
-
-[Invoke production-mode skill - it handles the rest autonomously]
 ```
 
-**If stable chores remain:**
+Then invoke production-mode skill. **End skill.**
 
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-🎯 Stable Mode Chore Complete!
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-What we accomplished:
-✅ Scenario passes with proper error handling
-✅ Input validation added
-✅ Edge cases handled
-
-Remaining stable mode chores: [count]
-
-**Next step:** Continue with next stable mode chore
-  jettypod work start [next-stable-chore-id]
-```
-
-**Mark current chore as done:**
+---
 
 ⚠️ **CRITICAL: Exclude CLAUDE.md from commits in worktrees**
 
@@ -682,6 +619,17 @@ Then use the merge command to merge to main (which auto-marks chore as done via
 jettypod work merge
 ```
 
+<details>
+<summary>💡 Multi-instance coordination (click to expand)</summary>
+
+The merge command uses a merge lock to prevent conflicts when multiple instances complete work simultaneously:
+- First instance acquires lock → merges → releases lock
+- Second instance waits → then acquires lock → merges
+- No manual coordination needed - happens automatically
+
+If you see "Acquiring merge lock..." message, another instance is merging. Wait 30-60 seconds.
+</details>
+
 The post-merge hook will automatically mark the chore as done when merged to main.
 
 ---
@@ -713,15 +661,15 @@ After completing EACH stable chore:
 **Example correct flow:**
 ```bash
 # Complete chore #1854
-git add . && git commit && git push
-jettypod work merge
+git add . && git commit -m "feat: [description]"
+jettypod work merge  # Automatically pushes, merges, and cleans up
 
 # NOW start chore #1855 (main has #1854's changes)
 jettypod work start 1855
 
 # Complete chore #1855
-git add . && git commit && git push
-jettypod work merge
+git add . && git commit -m "feat: [description]"
+jettypod work merge  # Automatically pushes, merges, and cleans up
 
 # NOW start chore #1856 (main has #1854 + #1855's changes)
 jettypod work start 1856