jettypod 4.4.11 → 4.4.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jettypod",
-  "version": "4.4.11",
+  "version": "4.4.13",
   "description": "AI-powered development workflow manager with TDD, BDD, and automatic test generation",
   "main": "jettypod.js",
   "bin": {

package/skills-templates/feature-planning/SKILL.md

@@ -183,7 +183,48 @@ User picks winner. Note their choice - you'll record it formally in Step 8 when
 
 **Proceed to Step 6.**
 
-### Step 6: Generate BDD Scenarios AND Step Definitions
+### Step 6: Define Integration Contract AND Generate BDD Scenarios
+
+**CRITICAL:** Before writing scenarios, you MUST define how users reach this feature. Features that pass tests but aren't integrated into the product are useless.
+
+#### Step 6A: Define Integration Contract
+
+**Ask yourself and document:**
+
+1. **Entry Point** - How does a user reach this feature?
+   - Web: URL/route (e.g., `/login`, `/dashboard/settings`)
+   - CLI: Command (e.g., `jettypod backlog`)
+   - UI: Button, link, menu item (e.g., "Login button in header")
+   - API: Endpoint that exposes this (e.g., `POST /api/auth/login`)
+
+2. **Caller Code** - What existing code must invoke/import the new feature?
+   - Which file imports it (e.g., `src/app/layout.tsx`)
+   - Which component/function renders or calls it
+   - Where it's registered/mounted (e.g., router config, command registry)
+
+3. **Integration Scenario** - A BDD scenario proving the feature is reachable
+   - Must start from an existing entry point users can access
+   - Must navigate/invoke to reach the new feature
+   - Proves the feature isn't an "island"
+
+**Display to user:**
+
+```
+📍 Integration Contract
+
+**Entry Point:** [How users reach this feature]
+**Caller Code:** [What existing code invokes this]
+**Integration Test:** [Scenario proving reachability]
+
+Example:
+- Entry Point: `/login` route
+- Caller Code: `src/app/layout.tsx` renders `<LoginButton>` in header, which links to `/login`
+- Integration Test: "Given I'm on the home page, When I click 'Sign In', Then I see the login form"
+```
+
+**WAIT for user to confirm or adjust the integration contract.**
+
+#### Step 6B: Generate BDD Scenarios AND Step Definitions
 
 **CRITICAL:** BDD scenarios and step definitions must ALWAYS be created together. Never create scenarios without step definitions.
 
@@ -198,7 +239,8 @@ Based on chosen approach, generate:
 **A. Scenario file** at `features/[feature-slug].feature` using Write tool:
 
 1. **Create file** at `features/[feature-slug].feature` using Write tool
-2. **Include all "make it work" scenarios**:
+2. **FIRST scenario MUST be the Integration Scenario** from Step 6A (proves reachability)
+3. **Include all "make it work" scenarios**:
    - All success paths - required functionality AND optional features
    - Multiple valid workflows if the feature supports them
    - Success variations (different outcomes that are all correct)
@@ -239,6 +281,17 @@ Feature: [Feature Name]
   Epic: [Epic name if applicable]
   Approach: [Chosen approach name]
 
+  # Integration Contract:
+  # Entry Point: [from Step 6A]
+  # Caller Code: [from Step 6A]
+
+# INTEGRATION SCENARIO (REQUIRED - proves feature is reachable)
+Scenario: User can reach [feature] from [entry point]
+  Given I am on [existing entry point users can access]
+  When I [navigate/click/invoke to reach the feature]
+  Then I [see/access the feature]
+
+# FEATURE SCENARIOS (required + optional functionality)
 Scenario: [Core functionality - required workflow]
   Given [initial state]
   When [user takes main action]
@@ -250,7 +303,7 @@ Scenario: [Optional feature 1 - if applicable]
   When [user uses optional feature]
   Then [feature works correctly]
 
-# SPEED MODE: All success scenarios above (required + optional functionality)
+# SPEED MODE: All success scenarios above (integration + required + optional)
 # STABLE MODE: Will add error handling, validation failures, edge cases
 # These failure scenarios are added by stable-mode skill, NOT during feature discovery
 ```
@@ -263,6 +316,18 @@ Feature: Email/Password Login
   Epic: User Authentication
   Approach: Simple inline form
 
+  # Integration Contract:
+  # Entry Point: /login route
+  # Caller Code: src/app/layout.tsx renders LoginButton in header
+
+# INTEGRATION SCENARIO
+Scenario: User can reach login form from home page
+  Given I am on the home page
+  When I click the "Sign In" button in the header
+  Then I am on the login page
+  And I see the email and password fields
+
+# FEATURE SCENARIOS
 Scenario: User successfully logs in with valid credentials
   Given I am on the login page
   When I enter valid email and password
@@ -393,13 +458,19 @@ Display: "✅ BDD infrastructure validated - all steps have definitions"
 **CRITICAL:** After BDD validation passes, analyze the codebase and propose technical implementation chores. **DO NOT CREATE CHORES YET** - the feature must transition to implementation mode first (Step 8).
 
 **Your analysis should consider:**
-- The BDD scenarios (all success paths - required + optional features)
+- The BDD scenarios (integration + all success paths)
+- The Integration Contract from Step 6A
 - Existing codebase structure and patterns
 - Epic's architectural decisions (if any)
 - Tech stack and framework conventions
 - Which scenario steps each chore addresses
 - Similar code patterns to follow
 
+**REQUIRED: At least one chore MUST be an Integration Chore** that:
+- Wires the feature into the existing app
+- Makes the Integration Scenario pass
+- Modifies the caller code identified in Step 6A
+
 **Say to the user:**
 
 ```
@@ -409,7 +480,20 @@ Now let me analyze the codebase and propose implementation chores for speed mode
 
 Based on the scenario and my understanding of the codebase, here are the chores I recommend for speed mode:
 
-**Chore 1: [Technical task title]**
+**Chore 1: [Integration chore - wire feature into app]** ⚡ INTEGRATION
+- Why: Makes the feature reachable from [entry point]
+- Integration Contract:
+  • Entry point: [from Step 6A]
+  • Caller code to modify: [specific file/function]
+- Scenario steps addressed:
+  • [Integration scenario Given/When/Then steps]
+- Implementation guidance:
+  • Files to modify: [caller code files]
+  • What to add: [route, link, import, menu item, etc.]
+- Verification:
+  • Integration scenario passes (feature is reachable)
+
+**Chore 2: [Core functionality chore]**
 - Why: [What this accomplishes toward the scenario]
 - Scenario steps addressed:
   • [Which Given/When/Then steps this chore makes work]
@@ -420,20 +504,9 @@ Based on the scenario and my understanding of the codebase, here are the chores
 - Verification:
   • [Which step definitions should pass]
 
-**Chore 2: [Technical task title]**
-- Why: [What this accomplishes]
-- Scenario steps addressed:
-  • [Which steps]
-- Implementation guidance:
-  • Files to create/modify: [paths]
-  • Patterns to follow: [references]
-  • Key functions/components needed: [list]
-- Verification:
-  • [Which steps should pass]
-
 [etc.]
 
-These chores will make all success scenarios pass (required + optional features).
+These chores will make all scenarios pass (integration + required + optional features).
 
 Sound good? Any adjustments?
 ```
@@ -633,12 +706,15 @@ Before completing feature planning, ensure:
 - [ ] Epic's architectural decision is shown (if exists)
 - [ ] Exactly 3 approaches suggested
 - [ ] Winner chosen (with prototypes or without)
-- [ ] BDD scenarios written (all success paths)
+- [ ] **Integration Contract defined** (entry point, caller code, integration scenario)
+- [ ] **Integration Scenario is FIRST scenario** in feature file
+- [ ] BDD scenarios written (integration + all success paths)
 - [ ] Step definitions written for ALL scenario steps
 - [ ] Scenarios file exists at `features/[feature-slug].feature`
 - [ ] Step definitions file exists at `features/step_definitions/[feature-slug].steps.js`
 - [ ] BDD infrastructure validated with dry-run (Step 6.5)
 - [ ] Feature transitioned to implementation with `work implement`
+- [ ] **At least one Integration Chore created** (wires feature into app)
 - [ ] Speed mode chores created
 - [ ] First chore started with `work start [chore-id]` (Step 8D)
 - [ ] **Speed-mode skill invoked using Skill tool** (Step 8D)

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

@@ -50,9 +50,10 @@ When this skill is activated, you are helping implement a speed mode chore to ma
 
 ### Overview
 
-**Speed Mode Goal:** Make it work - implement ALL functionality (required + optional features) to make success scenarios pass, assuming everything works correctly.
+**Speed Mode Goal:** Make it work - implement ALL functionality (integration + required + optional features) to make success scenarios pass, assuming everything works correctly.
 
 **Key Principles:**
+- **Integration first** - ensure the feature is wired into the app and reachable (Integration Scenario must pass)
 - **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
@@ -67,6 +68,7 @@ When this skill is activated, you are helping implement a speed mode chore to ma
 <summary><strong>📋 Speed Mode Constraints (click to expand)</strong></summary>
 
 **What to implement:**
+- **Integration** - wire feature into the app so it's reachable (Integration Scenario)
 - 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)
@@ -556,7 +558,25 @@ If the query returns no remaining chores, proceed to Step 7.
 
 This is the transition from speed mode to stable mode. Follow these phases in order.
 
-#### Step 7A: Merge Final Speed Chore
+#### Step 7A: Verify Integration Scenario Passes
+
+**CRITICAL: Before transitioning, verify the feature is actually integrated into the app.**
+
+```bash
+# Run ONLY the integration scenario (first scenario in the feature file)
+npx cucumber-js <scenario-file-path> --name "User can reach" --format progress
+```
+
+**If integration scenario FAILS:**
+- The feature exists but isn't wired into the app
+- Stop and fix integration before proceeding
+- Check: Is the route registered? Is the link/button added? Is the import in place?
+
+**If integration scenario PASSES:**
+- Feature is reachable by users
+- Proceed to Step 7B
+
+#### Step 7B: Merge Final Speed Chore
 
 ```bash
 # Commit changes in the worktree
@@ -568,7 +588,7 @@ jettypod work merge --with-transition
 
 After merge, you are on main branch. Ready to generate stable mode scenarios.
 
-#### Step 7B: Generate and Propose Stable Mode Chores
+#### Step 7C: Generate and Propose Stable Mode Chores
 
 **⚡ ASYNC BOUNDARY - Must wait for user confirmation**
 
@@ -628,7 +648,7 @@ Sound good? I'll create these chores once you confirm.
 
 **⚡ WAIT for user confirmation or adjustments.**
 
-#### Step 7C: Create Chores and Complete Transition
+#### Step 7D: Create Chores and Complete Transition
 
 **After user confirms, execute autonomously:**
 
@@ -665,7 +685,7 @@ jettypod work merge --release-lock
 jettypod work set-mode <feature-id> stable
 ```
 
-#### Step 7D: Invoke Stable Mode Skill
+#### Step 7E: Invoke Stable Mode Skill
 
 **🛑 CRITICAL HANDOFF - You MUST invoke stable-mode using the Skill tool.**
 
@@ -708,6 +728,7 @@ The stable-mode skill will:
 
 Before ending speed-mode skill, ensure:
 - [ ] All speed mode chores complete (GREEN on all success scenarios)
+- [ ] **Integration scenario passes** (feature is reachable, not an "island")
 - [ ] Stable mode BDD scenarios generated and committed
 - [ ] Step definitions created for stable scenarios
 - [ ] Stable mode chores created

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

@@ -5,14 +5,34 @@ description: Guide implementation of stable mode chores with comprehensive testi
 
 # Stable Mode Skill
 
-**Mode Progression:**
-Feature Planning → Speed Mode → **[STABLE MODE]** → Done (Internal) OR Production Mode (External)
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│  Mode Progression Flow                                               │
+│                                                                      │
+│  Feature Planning → Speed Mode → [STABLE MODE] → Production Mode     │
+│                                   ▲▲▲▲▲▲▲▲▲▲▲▲                       │
+│                                   YOU ARE HERE                       │
+│                                                                      │
+│  Next: INTERNAL projects → Feature DONE                              │
+│        EXTERNAL projects → Invoke production-mode skill              │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+## 🛑 CRITICAL HANDOFF REQUIREMENT
 
-**You are here:** Adding error handling, validation, and edge cases to speed mode implementation.
+**After completing ALL stable mode chores:**
 
-**Next steps:**
-- INTERNAL projects: Feature complete after stable mode (no production mode needed)
-- EXTERNAL projects: Continue to production mode for security/scale/monitoring
+**INTERNAL projects (project_state = 'internal'):**
+1. Mark feature as done
+2. **End skill** - Feature is complete!
+
+**EXTERNAL projects (project_state = 'external'):**
+1. Set feature mode to production
+2. **IMMEDIATELY invoke production-mode using the Skill tool**
+
+**🛑 STOP GATE:** For external projects, DO NOT end this skill without invoking production-mode. Stable mode makes it robust - production mode makes it ready for real users at scale.
+
+---
 
 Guides Claude Code through stable mode implementation with comprehensive testing focus. Users confirm approach but Claude Code writes the code.
 
@@ -37,7 +57,8 @@ When this skill is activated, you are helping implement a stable mode chore to a
 **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 (all success scenarios)
+- **Speed mode implemented ALL functionality** - every feature/function is already working (integration + all success scenarios)
+- **Speed mode verified integration** - the feature is reachable by users (Integration Scenario passed)
 - **Stable mode adds COMPLETE robustness** - error handling, validation, and edge cases
 
 **Key Principles:**
@@ -45,6 +66,8 @@ When this skill is activated, you are helping implement a stable mode chore to a
 - **Autonomous execution** - Claude Code writes code, user confirms approach
 - **Quality focus** - code should be stable, maintainable, and reliable (ready for internal use)
 
+**User Profile:** May not know how to code - Claude Code does the implementation autonomously.
+
 <details>
 <summary><strong>📋 What Stable Mode Includes (click to expand)</strong></summary>
 
@@ -84,8 +107,6 @@ When this skill is activated, you are helping implement a stable mode chore to a
 
 </details>
 
-**User Profile:** May not know how to code - Claude Code does the implementation autonomously.
-
 ---
 
 ## 🧪 Unit Testing in Stable Mode - True TDD
@@ -107,7 +128,9 @@ When this skill is activated, you are helping implement a stable mode chore to a
 - Edge case handling (empty arrays, boundary values)
 - State consistency (transaction rollback, cleanup on failure)
 
-**Unit test scope in stable mode:**
+<details>
+<summary><strong>📋 Unit Test Examples (click to expand)</strong></summary>
+
 ```javascript
 // ✅ Stable mode unit tests (error paths and edge cases)
 test('createUser throws ValidationError for null email', () => {
@@ -125,53 +148,24 @@ test('getUserById returns null for non-existent user', () => {
 });
 ```
 
+</details>
+
 ---
 
 ## Quick Reference: Async Boundaries
 
 **Where Claude Code MUST wait for user confirmation:**
 
-| Phase | Location | Why | Condition |
-|-------|----------|-----|-----------|
-| Step 3A | Before implementing (conditional) | User confirms implementation approach | Only if approach is ambiguous or multiple valid paths |
+| Step | Location | Why |
+|------|----------|-----|
+| Step 3A | Before implementing (conditional) | User confirms implementation approach - only if ambiguous |
 
 **Where Claude Code executes autonomously:**
-- Step 0: Initialize context
-- Step 1: Scenario analysis
-- Step 2: Speed mode implementation review
-- 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
-
----
-
-## ⚠️ CRITICAL: Stable Mode Workflow Requirements for External Products
-
-**If the product is EXTERNAL (project_state: 'external'), DO NOT mark features as complete after stable mode.**
-
-For external products accepting real users, stable mode is NOT the final step. Production mode is REQUIRED for:
-- Performance optimization and load testing
-- Security hardening (rate limiting, input sanitization, authentication)
-- Monitoring and observability
-- Operational readiness (logging, metrics, alerting)
-
-**Required workflow for EXTERNAL products after stable mode implementation:**
-
-1. ✅ **Complete ALL stable mode chores** - Add error handling and edge cases
-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
-
-**For INTERNAL products (staging/preview only), stable mode IS the final step.**
-
-**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:
-- 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.
+- Steps 0-2: Initialize, analyze scenarios, review speed implementation
+- Step 3: Decision to skip/ask confirmation
+- Steps 4-5: RED baseline, RED→GREEN→REFACTOR loop
+- Step 6: Route to next chore OR transition to Step 7
+- Step 7: Complete feature (internal) or invoke production-mode (external)
 
 ---
 
@@ -215,37 +209,29 @@ Analyzing stable mode BDD scenarios to determine what error handling and validat
 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)
+5. Check chore description for breadcrumbs (implementation guidance from speed-mode transition)
 
-**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).
+**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.
 
-**To get scenario information, use these commands:**
+**To get scenario information:**
 
 ```bash
-# 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`.
 
 **Identify target scenario:**
-
-After reading the scenario file content, parse it to find the scenario this chore addresses:
-
 1. Split the file by `Scenario:` to get individual scenarios
 2. Extract scenario titles from each block
-3. Match the chore description to a scenario by:
-   - Looking for scenario numbers in the chore description (e.g., "Scenario 2")
-   - Matching keywords from the chore description to scenario titles
+3. Match the chore description to a scenario by keywords or scenario numbers
 4. If no match found, list available scenarios and ask which one to implement
 
 **Handle errors gracefully:**
 - If no current work: "❌ No current work found. Run: jettypod work start <chore-id>"
 - If no parent feature: "❌ Current work has no parent feature."
-- If no scenario_file: "❌ Feature has no scenario_file. Create a scenario file and update the feature."
-- If scenario file not found: "❌ Scenario file not found at [path]"
-- If no scenarios in file: "❌ No scenarios found in scenario file."
-- If can't match chore to scenario: List available scenarios and ask user which one
+- If no scenario_file: "❌ Feature has no scenario_file."
+- If can't match chore to scenario: List available scenarios and ask user
 
 **Display to user:**
 
@@ -260,11 +246,11 @@ What needs to happen:
 • [When] Action/condition: [requirement]
 • [Then] Expected behavior: [requirement]
 
-[If breadcrumbs exist in chore description:]
+[If breadcrumbs exist:]
 Implementation guidance:
 • Files: [files to modify]
 • Patterns: [patterns to follow]
-• Functions: [specific functions to add validation to]
+• Functions: [functions to add validation to]
 
 Now reviewing speed mode implementation...
 ```
@@ -281,17 +267,14 @@ Now reviewing speed mode implementation...
 3. Identify what's missing for this scenario
 4. Understand current code structure
 
-**Find speed mode files using git:**
+**Find speed mode files:**
 
 ```bash
-# Search git history for commits related to this feature
-git log --oneline --all --grep="<feature-name>" -10
-
-# Get files changed in those commits
-git diff-tree --no-commit-id --name-only -r <commit-hash>
-
-# Or find files by looking at the feature's chores
+# Find files by looking at the feature's speed chores
 sqlite3 .jettypod/work.db "SELECT id, title FROM work_items WHERE parent_id = <feature-id> AND type = 'chore' AND mode = 'speed'"
+
+# Or search git history
+git log --oneline --all --grep="<feature-name>" -10
 ```
 
 Then use the Read tool to examine the implementation files.
@@ -357,6 +340,7 @@ I see multiple ways to approach this error handling. Here's what I'm thinking:
 **Alternative considered:**
 • [Brief description] - not choosing because [reason]
 
+Sound good, or would you prefer a different approach?
 ```
 
 **⚡ WAIT for user confirmation or adjustments.**
@@ -376,7 +360,6 @@ 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
@@ -387,8 +370,6 @@ Parse the output to identify:
 - Which specific stable mode steps are failing (error/edge case scenarios)
 - The first error message
 
-This establishes your RED baseline - stable mode scenarios should be failing initially.
-
 **Display RED baseline:**
 ```
 🔴 Establishing RED baseline...
@@ -475,19 +456,23 @@ Now implementing...
 
 ---
 
-**CRITICAL: Check if ALL stable mode chores are complete. Route to next chore if any remain.**
+### Step 6: Route After Chore Completion
+
+**CRITICAL: After GREEN, check if more stable chores remain.**
 
 **Check for incomplete stable chores:**
 
 ```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'"
+# Get current work to find parent feature ID and current chore ID
+sqlite3 .jettypod/work.db "SELECT wi.id, wi.parent_id FROM work_items wi WHERE wi.status = 'in_progress'"
 
-# Get list of remaining stable chores (excluding current chore)
+# Count remaining stable chores (excluding current)
 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:**
+---
+
+**Route A: More stable chores remain → Start next chore**
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -500,66 +485,64 @@ More stable mode chores remain. Starting next chore:
 #[next-chore-id]: [next-chore-title]
 ```
 
-**Then immediately merge current chore and start next:**
+**Merge and start next:**
 
 ```bash
 # Commit changes in the worktree
 git add . && git commit -m "feat: [brief description of error handling added]"
 
-# Switch to main repo before merging (merge cannot run from inside worktree)
-cd $(git rev-parse --git-common-dir)/..
-
-# Merge current chore - this automatically marks it as done
+# Merge current chore (handles push, merge, cleanup)
 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` (from main repo, not worktree)
+The stable-mode skill will automatically re-invoke for the next chore.
 
-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.
+**Route B: All stable chores complete → Transition to Step 7**
 
-**If all stable chores are done (count = 0), continue to Step 6 below.**
+If the query returns no remaining chores, proceed to Step 7.
 
 ---
 
-### Step 6: Route to Completion (After All Stable Chores Complete)
+### Step 7: Complete Feature or Transition to Production Mode
 
-**CRITICAL: This step ONLY happens when ALL stable chores for the feature are complete.**
+**🛑 CRITICAL: This step ONLY runs after ALL stable chores are complete.**
 
-**Check project state:**
+**First, merge the final stable chore:**
 
 ```bash
-# Check project_state in database (RECOMMENDED - always up to date)
-sqlite3 .jettypod/work.db "SELECT project_state FROM project_config WHERE id = 1"
+git add . && git commit -m "feat: [brief description of error handling added]"
+jettypod work merge
+```
+
+**Then check project state:**
 
-# 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
+```bash
+sqlite3 .jettypod/work.db "SELECT project_state FROM project_config WHERE id = 1"
 ```
 
-⚠️ **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:**
+#### Step 7A: INTERNAL Project → Feature Complete
 
 **If project_state = 'internal':**
 
-Mark the feature as done:
 ```bash
-jettypod work status [feature-id] done
+jettypod work status <feature-id> done
 ```
 
-Display:
+**Display:**
+
 ```
-✅ FEATURE #[id] COMPLETE!
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+✅ FEATURE COMPLETE!
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-Feature: [Feature Title]
+Feature: #[id] [Feature Title]
 Status: ✅ DONE
 
 What we accomplished:
@@ -581,112 +564,99 @@ run the external-transition skill to generate production chores.
 
 ---
 
+#### Step 7B: EXTERNAL Project → Invoke Production Mode
+
 **If project_state = 'external':**
 
-Use Skill tool to invoke production-mode:
+**🛑 CRITICAL HANDOFF - You MUST invoke production-mode using the Skill tool.**
+
+**Set feature mode to production:**
+
+```bash
+jettypod work set-mode <feature-id> production
+```
+
+**Display:**
 
-Display:
 ```
-✅ ALL STABLE MODE CHORES COMPLETE!
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🎯 Stable Mode Complete! Transitioning to Production Mode
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+⚠️  CRITICAL: This is an EXTERNAL project.
+Stable mode makes it robust - production mode makes it ready for real users.
 
 What we accomplished:
 ✅ 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
+🚀 Now invoking production-mode skill...
 ```
 
-Then invoke production-mode skill. **End skill.**
-
----
-
-⚠️ **CRITICAL: Exclude CLAUDE.md from commits in worktrees**
+**Invoke production-mode:**
 
-CLAUDE.md contains work tracking metadata that changes frequently and causes merge conflicts. When committing in a worktree, **always reset CLAUDE.md** before committing:
-
-```bash
-git checkout HEAD -- CLAUDE.md  # Reset CLAUDE.md to avoid merge conflicts
-git add .                        # Stage other changes
-git commit -m "feat: [brief description of what was implemented]"
-git push
 ```
-
-Then switch to main repo and use the merge command (which auto-marks chore as done):
-```bash
-cd $(git rev-parse --git-common-dir)/..  # Switch to main repo
-jettypod work merge
+Use the Skill tool with skill: "production-mode"
 ```
 
-<details>
-<summary>💡 Multi-instance coordination (click to expand)</summary>
+The production-mode skill will:
+1. Detect feature context (authentication/data/general)
+2. Generate production scenarios from standards
+3. Create production chores with proper scope
 
-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.
+**End stable-mode skill.**
 
 ---
 
-⚠️ **CRITICAL: SEQUENTIAL WORKFLOW FOR STABLE MODE CHORES**
+## Validation Checklist
 
-**Stable mode chores MUST be completed sequentially, not in parallel.**
+Before ending stable-mode skill, ensure:
+- [ ] All stable mode chores complete (GREEN on all error/edge case scenarios)
+- [ ] Integration scenario still passes (feature remains reachable after error handling added)
+- [ ] Final chore merged to main
+- [ ] Project state checked (internal vs external)
+- [ ] **INTERNAL:** Feature marked as done
+- [ ] **EXTERNAL:** Feature mode set to production AND production-mode skill invoked
 
-**Why Sequential?**
-- Multiple chores modify the same files (e.g., lib/merge-lock.js, step definitions)
-- Later chores build on earlier implementations
-- Tests and BDD scenarios depend on cumulative changes
-- Parallel worktrees branch from main independently, missing each other's changes
+---
 
-**MANDATORY PROCESS:**
+## Command Reference
 
-After completing EACH stable chore:
-1. ✅ Commit changes in worktree (excluding CLAUDE.md)
-2. ✅ Push worktree branch
-3. ✅ **Merge to main immediately**
-4. ✅ **Push main**
-5. ✅ ONLY THEN start the next stable chore
+**Complete chores:**
+```bash
+jettypod work merge              # Merge current chore to main
+```
 
-**DO NOT:**
-❌ Start multiple stable chores without merging previous ones
-❌ Leave stable chores unmerged "for later"
-❌ Assume worktrees will have each other's changes
+**Start chores:**
+```bash
+jettypod work start <chore-id>   # Create worktree and start chore
+```
 
-**Example correct flow:**
+**Set feature status/mode:**
 ```bash
-# Complete chore #1854
-git add . && git commit -m "feat: [description]"
-cd $(git rev-parse --git-common-dir)/..  # Switch to main repo
-jettypod work merge  # Automatically pushes, merges, and cleans up
+jettypod work status <feature-id> done      # Mark feature complete (internal only)
+jettypod work set-mode <feature-id> production  # Set feature to production mode
+```
 
-# NOW start chore #1855 (main has #1854's changes)
-jettypod work start 1855
+**❌ DO NOT use these to complete chores:**
+- `jettypod work status <chore-id> done`
+- `jettypod work complete <id>`
 
-# Complete chore #1855
-git add . && git commit -m "feat: [description]"
-cd $(git rev-parse --git-common-dir)/..  # Switch to main repo
-jettypod work merge  # Automatically pushes, merges, and cleans up
+---
 
-# NOW start chore #1856 (main has #1854 + #1855's changes)
-jettypod work start 1856
-```
+## ⚠️ Important: Sequential Workflow
 
-If you fail to follow this sequential process, later worktrees will be missing earlier implementations, causing:
-- Missing functions/exports
-- Incomplete test coverage
-- Step definition errors
-- Duplicate work
+**Stable mode chores MUST be completed sequentially, not in parallel.**
 
-**End skill.**
+**Why?**
+- Multiple chores may modify the same files
+- Later chores build on earlier implementations
+- Parallel worktrees branch from main independently
 
+**Process:**
+1. Complete chore → `jettypod work merge`
+2. Start next chore → `jettypod work start <next-id>`
+3. Repeat
 
+The merge command handles everything: pushes branch, merges to main, marks chore done, cleans up worktree.