jettypod 4.4.118 → 4.4.121

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

@@ -18,7 +18,7 @@ description: Guide implementation of speed mode chores with autonomous code anal
 └─────────────────────────────────────────────────────────────────────┘
 ```
 
-## 🛑 CRITICAL HANDOFF REQUIREMENT
+## CRITICAL HANDOFF REQUIREMENT
 
 **After completing ALL speed mode chores, you MUST:**
 1. Generate stable mode BDD scenarios and step definitions
@@ -26,18 +26,18 @@ description: Guide implementation of speed mode chores with autonomous code anal
 3. Set feature mode to stable
 4. **IMMEDIATELY invoke stable-mode using the Skill tool**
 
-**🛑 STOP GATE:** DO NOT end this skill without invoking stable-mode. Speed mode is ONLY a checkpoint - features are INCOMPLETE without stable mode.
+**STOP GATE:** DO NOT end this skill without invoking stable-mode. Speed mode is ONLY a checkpoint - features are INCOMPLETE without stable mode.
 
 ---
 
-## 🚫 FORBIDDEN: Skipping Stable Mode
+## FORBIDDEN: Skipping Stable Mode
 
 ```
-❌ Ending speed-mode skill without invoking stable-mode skill
-❌ Using `jettypod work status <feature-id> done` to mark feature complete
-❌ Telling user "feature is complete" after speed mode
-❌ Skipping Step 7 (Transition to Stable Mode)
-❌ Any action that bypasses the speed→stable progression
+Ending speed-mode skill without invoking stable-mode skill
+Using `jettypod work status <feature-id> done` to mark feature complete
+Telling user "feature is complete" after speed mode
+Skipping Step 7 (Transition to Stable Mode)
+Any action that bypasses the speed→stable progression
 ```
 
 **What "Feature Complete" Actually Means:**
@@ -60,7 +60,7 @@ Guides Claude Code through speed mode implementation with autonomous analysis an
 
 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
+## Critical Context
 
 **You are working in an isolated git worktree:**
 - `work start [chore-id]` created a dedicated worktree for this chore
@@ -72,7 +72,7 @@ When this skill is activated, you are helping implement a speed mode chore to ma
 
 ---
 
-## 🚨 SHELL CWD RECOVERY
+## SHELL CWD RECOVERY
 
 **If ALL bash commands start failing with "Error: Exit code 1" and no output:**
 
@@ -93,7 +93,7 @@ cd /Users/erikspangenberg/personal-assistant && pwd
 
 ---
 
-## 🛑 PRE-FLIGHT VALIDATION (REQUIRED)
+## PRE-FLIGHT VALIDATION (REQUIRED)
 
 **Before proceeding with ANY implementation, you MUST validate the worktree exists.**
 
@@ -107,11 +107,11 @@ sqlite3 .jettypod/work.db "SELECT wi.id, wi.title, wi.status, wt.worktree_path,
 
 | worktree_path | What it means | Action |
 |---------------|---------------|--------|
-| **Has a path** (e.g., `/path/to/.jettypod-work/...`) | ✅ Worktree exists, ready to proceed | Continue to Step 0 |
-| **NULL or empty** | ❌ `work start` was not called | **STOP - run `jettypod work start [chore-id]` first** |
-| **No rows returned** | ❌ No chore is in progress | **STOP - verify the chore exists and run `work start`** |
+| **Has a path** (e.g., `/path/to/.jettypod-work/...`) | Worktree exists, ready to proceed | Continue to Step 0 |
+| **NULL or empty** | `work start` was not called | **STOP - run `jettypod work start [chore-id]` first** |
+| **No rows returned** | No chore is in progress | **STOP - verify the chore exists and run `work start`** |
 
-**🛑 STOP GATE:** If `worktree_path` is NULL or no rows returned, you MUST run `jettypod work start [chore-id]` before continuing. DO NOT proceed without a valid worktree.
+**STOP GATE:** If `worktree_path` is NULL or no rows returned, you MUST run `jettypod work start [chore-id]` before continuing. DO NOT proceed without a valid worktree.
 
 **Example of valid output:**
 ```
@@ -126,7 +126,7 @@ sqlite3 .jettypod/work.db "SELECT wi.id, wi.title, wi.status, wt.worktree_path,
 
 ---
 
-## 🔒 WORKTREE PATH LOCK
+## WORKTREE PATH LOCK
 
 **After pre-flight validation passes, capture and lock the worktree path:**
 
@@ -135,7 +135,7 @@ From the pre-flight query output, extract and store:
 
 **Display:**
 ```
-🔒 WORKTREE LOCK ACTIVE
+WORKTREE LOCK ACTIVE
 Path: ${WORKTREE_PATH}
 
 All file writes will use this path.
@@ -171,7 +171,7 @@ jettypod ui gate worktree-started --data='{"path":"${WORKTREE_PATH}"}'
 **User Profile:** May not know how to code - Claude Code does the implementation autonomously.
 
 <details>
-<summary><strong>📋 Speed Mode Constraints (click to expand)</strong></summary>
+<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)
@@ -180,10 +180,10 @@ jettypod ui gate worktree-started --data='{"path":"${WORKTREE_PATH}"}'
 - 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)
+- 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
@@ -195,7 +195,7 @@ jettypod ui gate worktree-started --data='{"path":"${WORKTREE_PATH}"}'
 
 ---
 
-## 🧪 Unit Testing in Speed Mode - True TDD
+## Unit Testing in Speed Mode - True TDD
 
 **Unit tests are written DURING the RED→GREEN loop, not after.**
 
@@ -218,7 +218,7 @@ jettypod ui gate worktree-started --data='{"path":"${WORKTREE_PATH}"}'
 - Check existing test files for patterns
 
 <details>
-<summary><strong>📋 TDD Example (click to expand)</strong></summary>
+<summary><strong>TDD Example (click to expand)</strong></summary>
 
 ```javascript
 // Iteration 1: BDD step "Given a user exists" is failing
@@ -243,14 +243,14 @@ function createUser(name, email) {
 
 **Unit test scope in speed mode:**
 ```javascript
-// ✅ Speed mode unit tests (success paths)
+// 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)
+// NOT in speed mode (stable mode adds these)
 test('createUser throws error for invalid email', () => {
   expect(() => createUser('John', 'invalid')).toThrow();
 });
@@ -267,14 +267,17 @@ test('createUser throws error for invalid email', () => {
 | Step | Location | Why |
 |------|----------|-----|
 | Step 3A | Before implementing (conditional) | User confirms implementation approach - only if ambiguous |
-| Step 7B | Before creating stable chores | User confirms proposed stable mode chores - always |
+| Step 7C | Before writing stable scenarios | User confirms stable mode BDD scenarios - always |
+| Step 7E | Before creating stable chores | User confirms proposed stable mode chores - always |
 
 **Where Claude Code executes autonomously:**
 - Steps 0-2: Initialize, analyze scenarios, analyze codebase
 - 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 (after confirmation): Create chores, commit, set mode, invoke stable-mode
+- Step 7A-7B: Validate BDD, merge final speed chore
+- Step 7D: Write and merge confirmed stable scenarios
+- Step 7F-7G (after chore confirmation): Create chores, set mode, invoke stable-mode
 
 ---
 
@@ -290,7 +293,7 @@ test('createUser throws error for invalid email', () => {
 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'"
 ```
 
-**🔄 WORKFLOW INTEGRATION: Start workflow tracking**
+**WORKFLOW INTEGRATION: Start workflow tracking**
 
 After getting the work context, register this skill execution:
 
@@ -304,7 +307,7 @@ This validates that `feature_planning_complete` gate is passed and creates an ex
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-🚀 SPEED MODE: Implementing Chore #[id]
+SPEED MODE: Implementing Chore #[id]
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 Chore: [title]
@@ -321,11 +324,11 @@ Analyzing BDD scenarios to determine implementation approach...
 
 ### Step 1: Check for Breadcrumbs and Analyze Scenario
 
-**🚫 FORBIDDEN: Writing Files at This Step**
+**FORBIDDEN: Writing Files at This Step**
 ```
-❌ Write tool to any path
-❌ Edit tool to any path
-❌ Any file creation or modification
+Write tool to any path
+Edit tool to any path
+Any file creation or modification
 ```
 **This is an ANALYSIS step.** File writes happen in Step 5.
 
@@ -347,9 +350,10 @@ sqlite3 .jettypod/work.db "SELECT wi.id, wi.title, wi.description, wi.parent_id,
 **Check for breadcrumbs** by examining the chore's description for:
 - "Scenario steps addressed:"
 - "Implementation guidance:"
+- "UX acceptance criteria:" (loading states, success feedback, empty states, micro-interactions)
 - "Verification:"
 
-If all three sections exist, use them. Otherwise, fall back to autonomous analysis.
+If at least "Scenario steps addressed:", "Implementation guidance:", and "Verification:" exist, use them. "UX acceptance criteria:" is optional but MUST be implemented if present — these define the visual states and micro-interactions the user expects to see during QA.
 
 **Then read the scenario file** using the Read tool on the path returned by `scenario_file`.
 
@@ -365,7 +369,7 @@ If all three sections exist, use them. Otherwise, fall back to autonomous analys
 **Display to user (with breadcrumbs):**
 
 ```
-🚀 Speed Mode: [Chore Title]
+Speed Mode: [Chore Title]
 
 Scenario steps addressed:
 [Steps from breadcrumbs]
@@ -373,6 +377,9 @@ Scenario steps addressed:
 Implementation guidance:
 [Files, patterns, functions from breadcrumbs]
 
+UX acceptance criteria:
+[Loading states, success feedback, empty states, micro-interactions from breadcrumbs — if present]
+
 Verification:
 [Step definitions from breadcrumbs]
 
@@ -382,7 +389,7 @@ Now analyzing codebase to finalize implementation approach...
 **Display to user (without breadcrumbs):**
 
 ```
-🚀 Speed Mode: [Feature Name]
+Speed Mode: [Feature Name]
 
 Happy Path Scenario:
 [Scenario title]
@@ -400,11 +407,11 @@ Now analyzing codebase to propose implementation...
 
 ### Step 2: Autonomous Codebase Analysis
 
-**🚫 FORBIDDEN: Writing Files at This Step**
+**FORBIDDEN: Writing Files at This Step**
 ```
-❌ Write tool to any path
-❌ Edit tool to any path
-❌ Any file creation or modification
+Write tool to any path
+Edit tool to any path
+Any file creation or modification
 ```
 **This is an ANALYSIS step.** File writes happen in Step 5.
 
@@ -458,7 +465,7 @@ Decisions constrain your implementation approach - use them to guide technology
 **Display analysis results:**
 
 ```
-📊 Codebase Analysis Complete
+Codebase Analysis Complete
 
 Architectural Constraints:
 [List any epic decisions that apply]
@@ -476,7 +483,7 @@ Integration Points:
 Now proposing implementation approach...
 ```
 
-**🔄 WORKFLOW CHECKPOINT: Codebase analysis complete**
+**WORKFLOW CHECKPOINT: Codebase analysis complete**
 
 ```bash
 jettypod workflow checkpoint <feature-id> --step=2
@@ -484,11 +491,11 @@ jettypod workflow checkpoint <feature-id> --step=2
 
 ### Step 3: Decide if Confirmation Needed
 
-**🚫 FORBIDDEN: Writing Files at This Step**
+**FORBIDDEN: Writing Files at This Step**
 ```
-❌ Write tool to any path
-❌ Edit tool to any path
-❌ Any file creation or modification
+Write tool to any path
+Edit tool to any path
+Any file creation or modification
 ```
 **This is a DECISION step.** File writes happen in Step 5.
 
@@ -508,20 +515,20 @@ jettypod workflow checkpoint <feature-id> --step=2
 
 ### Step 3A: Propose Implementation Approach (Conditional)
 
-**🚫 FORBIDDEN: Writing Files at This Step**
+**FORBIDDEN: Writing Files at This Step**
 ```
-❌ Write tool to any path
-❌ Edit tool to any path
-❌ Any file creation or modification
+Write tool to any path
+Edit tool to any path
+Any file creation or modification
 ```
 **This is a PROPOSAL step.** File writes happen in Step 5.
 
-**⚡ ASYNC BOUNDARY - Only execute this if confirmation needed**
+**ASYNC BOUNDARY - Only execute this if confirmation needed**
 
 **Present your analysis and proposal to the user:**
 
 ```
-💡 Implementation Proposal
+Implementation Proposal
 
 I see multiple ways to approach this. Here's what I'm thinking:
 
@@ -536,7 +543,7 @@ I see multiple ways to approach this. Here's what I'm thinking:
 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 before proceeding.
 
@@ -544,6 +551,16 @@ If user adjusts: revise proposal and confirm again before proceeding.
 
 ---
 
+### BDD Step Definition Constraints (ENFORCED)
+
+Before writing any step definitions, read `templates/bdd-guidance.md`. BANNED in step defs: `setTimeout`/`sleep`, module-level `let`/`var`, raw SQL, assertions in Given/When, loops/branching, self-fulfilling mocks (setting state then asserting it). Steps must be 1-5 lines calling one helper via Cucumber World (`this`). Read `features/support/helpers/` and reuse before creating.
+
+**Scaffolding:** If `features/support/helpers/` does not exist in the project, scaffold it before writing step definitions. Copy `templates/bdd-scaffolding/wait.js` to `features/support/helpers/wait.js` and `templates/bdd-scaffolding/world.js` to `features/support/world.js`.
+
+**Helper Reuse:** Before writing step definitions, glob `features/support/helpers/**/*.js` and read each file. Import and call existing helpers in your steps — never duplicate functionality that already exists.
+
+---
+
 ### Step 4: Establish RED Baseline
 
 **CRITICAL:** After user confirms, execute autonomously - no permission needed for code changes.
@@ -568,27 +585,27 @@ This establishes your RED baseline - all or most steps should be failing initial
 
 **Display RED baseline:**
 ```
-🔴 Establishing RED baseline...
+Establishing RED baseline...
 
 RED Baseline: 5 of 8 steps failing
 
 Failing steps:
-  ✖ Given a user is logged in
-  ✖ When they click the dashboard button
-  ✖ Then they should see their dashboard
-  ✖ And the dashboard should show their username
-  ✖ And the dashboard should show their recent activity
+  Given a user is logged in
+  When they click the dashboard button
+  Then they should see their dashboard
+  And the dashboard should show their username
+  And the dashboard should show their recent activity
 
 First error:
   Step: Given a user is logged in
   Error: Error: login function is not defined
 
-🎯 Goal: Make all steps pass
+Goal: Make all steps pass
 
 Now implementing...
 ```
 
-**🔄 WORKFLOW CHECKPOINT: RED baseline established**
+**WORKFLOW CHECKPOINT: RED baseline established**
 
 ```bash
 jettypod workflow checkpoint <feature-id> --step=4
@@ -598,9 +615,9 @@ jettypod workflow checkpoint <feature-id> --step=4
 
 ### Step 5: RED→GREEN→REFACTOR Loop
 
-**🔒 WORKTREE PATH REQUIRED:** All file writes MUST use the `WORKTREE_PATH` captured after pre-flight validation.
+**WORKTREE PATH REQUIRED:** All file writes MUST use the `WORKTREE_PATH` captured after pre-flight validation.
 
-**✅ NOW you may write files** - worktree is locked, approach is confirmed.
+**NOW you may write files** - worktree is locked, approach is confirmed.
 
 **Emit gate signal:**
 
@@ -623,23 +640,23 @@ jettypod ui gate implementing --data='{"description":"[speed mode implementation
 **Show progress each iteration:**
 ```
 ━━━ Iteration 3/10 ━━━
-📝 Unit test: test/dashboard.test.js - sortActivityByDate()
+Unit test: test/dashboard.test.js - sortActivityByDate()
    RED: Test fails - function doesn't exist yet
-✍️  Implementation: src/dashboard.js - added sortActivityByDate()
+ 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
+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"
 ```
 
 **When GREEN achieved:**
 ```
-🎉 GREEN: All success scenarios passing!
+GREEN: All success scenarios passing!
 ```
 
-**🔄 WORKFLOW CHECKPOINT: GREEN achieved**
+**WORKFLOW CHECKPOINT: GREEN achieved**
 
 ```bash
 jettypod workflow checkpoint <feature-id> --step=5
@@ -654,7 +671,7 @@ jettypod workflow checkpoint <feature-id> --step=5
 **Re-run tests after refactor** to ensure nothing broke.
 
 <details>
-<summary><strong>📋 TDD Loop Guidelines (click to expand)</strong></summary>
+<summary><strong>TDD Loop Guidelines (click to expand)</strong></summary>
 
 **Iteration strategy:**
 - Start with first failing step
@@ -674,6 +691,8 @@ jettypod workflow checkpoint <feature-id> --step=5
 
 </details>
 
+**Quality Gate:** Before committing, review every `.steps.js` file you wrote or modified. Check for banlist violations: `setTimeout`/`sleep`, module-level `let`/`var`, raw SQL, assertions in Given/When, self-fulfilling mocks, steps longer than 5 lines. Fix violations before proceeding.
+
 ---
 
 ### Step 6: Route After Chore Completion
@@ -696,10 +715,10 @@ sqlite3 .jettypod/work.db "SELECT id, title FROM work_items WHERE parent_id = <f
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-🎯 Speed Mode Chore Complete
+Speed Mode Chore Complete
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-✅ Success scenarios pass for this chore
+Success scenarios pass for this chore
 
 More speed mode chores remain. Starting next chore:
 #[next-chore-id]: [next-chore-title]
@@ -717,6 +736,8 @@ git add . && git commit -m "feat: [brief description of what was implemented]"
 jettypod work merge [current-chore-id]
 ```
 
+**If merge fails with `Uncommitted changes detected`:** `git stash` from main repo CWD → create a work item for the stashed changes → `jettypod work start <id>` → `git stash pop` in that worktree → commit → merge → cleanup → then retry your original merge.
+
 ```bash
 # Step 2: cd to main repo
 cd /path/to/main/repo
@@ -741,7 +762,7 @@ If the query returns no remaining chores, proceed to Step 7.
 
 ### Step 7: Transition to Stable Mode
 
-**🛑 CRITICAL: This step ONLY runs after ALL speed chores are complete.**
+**CRITICAL: This step ONLY runs after ALL speed chores are complete.**
 
 This is the transition from speed mode to stable mode. Follow these phases in order.
 
@@ -804,8 +825,8 @@ git add . && git commit -m "feat: [brief description of what was implemented]"
 ```
 
 ```bash
-# Step 1: Merge with transition flag (can run from worktree - it won't delete it)
-jettypod work merge [current-chore-id] --with-transition
+# Step 1: Merge (works from anywhere — ALWAYS include chore ID)
+jettypod work merge [current-chore-id]
 ```
 
 ```bash
@@ -821,42 +842,95 @@ jettypod work cleanup [current-chore-id]
 
 After cleanup, you are on main branch. Ready to generate stable mode scenarios.
 
-#### Step 7C: Generate and Propose Stable Mode Chores
+#### Step 7C: Present Stable Mode Scenarios for Review
 
-**⚡ ASYNC BOUNDARY - Must wait for user confirmation**
+**FORBIDDEN: Writing Files at This Step**
+```
+Write tool to any path
+Edit tool to any path
+Any file creation or modification
+```
+**This is a PROPOSAL step.** File writes happen in Step 7D after user confirmation.
 
-**1. Create a test worktree for writing stable mode scenarios:**
+**ASYNC BOUNDARY - Must wait for user confirmation**
+
+**1. Read the feature's scenario file and analyze for stable mode needs:**
 
-**🚫 FORBIDDEN: Manual Git Worktree Commands**
+```bash
+sqlite3 .jettypod/work.db "SELECT id, title, scenario_file FROM work_items WHERE id = <feature-id>"
 ```
-❌ git worktree add ...
-❌ git checkout -b tests/...
-❌ git branch tests/...
+
+**2. Generate stable mode BDD scenarios** covering:
+- **Error scenarios** - Invalid input, missing params, system errors, permission failures
+- **Edge cases** - Empty inputs, boundary values, special characters
+- **State consistency** - Concurrent ops, partial failures, invalid state transitions
+
+**3. Present proposed scenarios to user for review:**
+
 ```
-**ALWAYS use jettypod commands** - they handle branch naming, path conventions, database tracking, and cleanup. Manual git commands will create orphaned worktrees that break the merge workflow.
+Stable Mode Scenarios
+
+I've drafted [N] stable mode scenarios covering error handling and edge cases.
+Please review — these are the contract for what stable mode will implement.
+
+**Error Handling:**
+
+Scenario: [Error scenario title]
+  Given [context]
+  When [error condition]
+  Then [expected error handling]
+
+Scenario: [Error scenario title]
+  Given [context]
+  When [error condition]
+  Then [expected error handling]
+
+**Edge Cases:**
+
+Scenario: [Edge case title]
+  Given [context]
+  When [edge case input]
+  Then [expected behavior]
+
+Does this capture the error handling and edge cases correctly?
+Any scenarios to add, change, or remove?
+```
+
+**WAIT for user confirmation or adjustments.**
+
+If user requests changes, revise the scenarios and re-present until confirmed.
+
+**WORKFLOW CHECKPOINT: Stable mode scenarios confirmed**
 
 ```bash
-jettypod work tests <feature-id>
+jettypod workflow checkpoint <feature-id> --step=7C
 ```
 
-This creates an isolated worktree at `.jettypod-work/tests-<id>-<slug>` with branch `tests/feature-<id>-<slug>`.
+#### Step 7D: Write and Merge Stable Mode Scenarios
 
-**🛑 CRITICAL:** All BDD file operations MUST use absolute paths in the test worktree:
-- ✅ `/path/to/.jettypod-work/tests-42-login/features/login.feature`
-- ❌ `features/login.feature` (this would write to main repo!)
+**After user confirms scenarios, execute autonomously.**
 
-**2. Read the feature's scenario file and analyze for stable mode needs:**
+**1. Create a test worktree for writing stable mode scenarios:**
+
+**FORBIDDEN: Manual Git Worktree Commands**
+```
+git worktree add ...
+git checkout -b tests/...
+git branch tests/...
+```
+**ALWAYS use jettypod commands** - they handle branch naming, path conventions, database tracking, and cleanup. Manual git commands will create orphaned worktrees that break the merge workflow.
 
 ```bash
-sqlite3 .jettypod/work.db "SELECT id, title, scenario_file FROM work_items WHERE id = <feature-id>"
+jettypod work tests <feature-id>
 ```
 
-**3. Generate stable mode BDD scenarios** covering:
-- **Error scenarios** - Invalid input, missing params, system errors, permission failures
-- **Edge cases** - Empty inputs, boundary values, special characters
-- **State consistency** - Concurrent ops, partial failures, invalid state transitions
+This creates an isolated worktree at `.jettypod-work/tests-<id>-<slug>` with branch `tests/feature-<id>-<slug>`.
 
-**4. Append scenarios to the feature file IN THE TEST WORKTREE:**
+**CRITICAL:** All BDD file operations MUST use absolute paths in the test worktree:
+- `/path/to/.jettypod-work/tests-42-login/features/login.feature`
+- `features/login.feature` (this would write to main repo!)
+
+**2. Append confirmed scenarios to the feature file IN THE TEST WORKTREE:**
 
 Use the Edit tool to append to `<worktree-path>/features/<feature-file>`:
 
@@ -874,11 +948,11 @@ Scenario: [Edge case title]
   Then [expected behavior]
 ```
 
-**5. Create step definitions IN THE TEST WORKTREE** at `<worktree-path>/features/step_definitions/<feature-slug>-stable.steps.js`
+**3. Create step definitions IN THE TEST WORKTREE** at `<worktree-path>/features/step_definitions/<feature-slug>-stable.steps.js`
 
-**6. Commit and merge the test worktree:**
+**4. Commit and merge the test worktree:**
 
-**🚨 CRITICAL: Shell CWD Corruption Prevention**
+**CRITICAL: Shell CWD Corruption Prevention**
 
 The merge will delete the test worktree. If your shell is inside that worktree, ALL subsequent commands will fail. You MUST:
 1. Chain the cd and merge in a SINGLE bash command
@@ -911,14 +985,16 @@ pwd && ls .jettypod  # verify
 jettypod work cleanup <feature-id>
 ```
 
-**7. Present proposal to user:**
+#### Step 7E: Propose Stable Mode Chores
 
-```
-📋 Stable Mode Transition
+**ASYNC BOUNDARY - Must wait for user confirmation**
 
-I've generated [N] stable mode scenarios covering error handling and edge cases.
+**Present chore proposals to user:**
 
-Here are the chores needed to make these scenarios pass:
+```
+Stable Mode Chores
+
+Scenarios are committed. Here are the chores needed to make them pass:
 
 **Chore 1: [Title]**
 - Why: [What gap this fills]
@@ -933,9 +1009,9 @@ Here are the chores needed to make these scenarios pass:
 Sound good? I'll create these chores once you confirm.
 ```
 
-**⚡ WAIT for user confirmation or adjustments.**
+**WAIT for user confirmation or adjustments.**
 
-#### Step 7D: Create Chores and Complete Transition
+#### Step 7F: Create Chores and Complete Transition
 
 **After user confirms, execute autonomously:**
 
@@ -945,27 +1021,28 @@ Sound good? I'll create these chores once you confirm.
 jettypod work set-mode <feature-id> stable
 ```
 
-**🛑 CRITICAL:** You MUST set mode to stable BEFORE creating chores. The system blocks chore creation while feature is in speed mode.
+**CRITICAL:** You MUST set mode to stable BEFORE creating chores. The system blocks chore creation while feature is in speed mode.
 
 **2. Create stable mode chores:**
 
-```bash
-jettypod work create chore "[Chore title]" "[Description with scenarios addressed]" --parent=<feature-id>
+For each confirmed chore, use the **Write** tool to create `/tmp/jettypod-create.json`:
+```json
+{
+  "type": "chore",
+  "title": "[Chore title]",
+  "description": "[Description with scenarios addressed]",
+  "parent": <feature-id>
+}
 ```
 
-Repeat for each confirmed chore. **Do NOT use `--mode` flag** - chores inherit mode from their parent feature.
-
-**3. Release merge lock (CRITICAL: separate Bash calls):**
-
+Then run via **Bash**:
 ```bash
-cd <main-repo>                           # Bash call 1
+jettypod work create --from=/tmp/jettypod-create.json
 ```
 
-```bash
-jettypod work merge <last-chore-id> --release-lock   # Bash call 2
-```
+Repeat for each confirmed chore. **Do NOT add a `mode` field** - chores inherit mode from their parent feature.
 
-**🔄 WORKFLOW COMPLETE: Speed mode finished**
+**WORKFLOW COMPLETE: Speed mode finished**
 
 Mark speed mode as complete (this passes the `speed_mode_complete` gate, enabling stable-mode):
 
@@ -979,9 +1056,9 @@ jettypod workflow complete speed-mode <feature-id>
 jettypod ui gate complete --data='{"summary":"Speed mode complete - transitioning to stable mode","files":["[files implemented]"]}'
 ```
 
-#### Step 7E: Start First Stable Chore and Invoke Stable Mode Skill
+#### Step 7G: Start First Stable Chore and Invoke Stable Mode Skill
 
-**🛑 CRITICAL HANDOFF - You MUST start the first chore BEFORE invoking stable-mode.**
+**CRITICAL HANDOFF - You MUST start the first chore BEFORE invoking stable-mode.**
 
 **1. Get the first stable chore:**
 
@@ -997,12 +1074,12 @@ Note: Chores don't have a `mode` column - they inherit context from their parent
 jettypod work start <first-stable-chore-id>
 ```
 
-**🛑 STOP AND CHECK:** Look at the output. You should see:
+**STOP AND CHECK:** Look at the output. You should see:
 ```
-✅ Created worktree: /path/to/.jettypod-work/[id]-[title-slug]
+Created worktree: /path/to/.jettypod-work/[id]-[title-slug]
 ```
 
-If you see `⚠️ Working in main repository (worktree creation failed)`, fix the issue before continuing.
+If you see `Working in main repository (worktree creation failed)`, fix the issue before continuing.
 
 **3. Verify worktree exists:**
 
@@ -1016,21 +1093,21 @@ If empty, **STOP** - worktree wasn't created properly.
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-🎯 Speed Mode Complete! Transitioning to Stable Mode
+Speed Mode Complete! Transitioning to Stable Mode
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-⚠️  CRITICAL: Speed mode is ONLY a checkpoint.
+ CRITICAL: Speed mode is ONLY a checkpoint.
 The feature is INCOMPLETE without stable mode.
 
 What we accomplished:
-✅ All speed mode chores complete
-✅ Generated [N] stable mode BDD scenarios
-✅ Created step definitions for stable scenarios
-✅ Created [N] stable mode chores
-✅ Feature mode set to stable
-✅ Started first stable chore #[id]
+All speed mode chores complete
+Generated [N] stable mode BDD scenarios
+Created step definitions for stable scenarios
+Created [N] stable mode chores
+Feature mode set to stable
+Started first stable chore #[id]
 
-🚀 Now invoking stable-mode skill...
+Now invoking stable-mode skill...
 ```
 
 **5. Invoke stable-mode:**
@@ -1039,7 +1116,7 @@ What we accomplished:
 Use the Skill tool with skill: "stable-mode"
 ```
 
-**🛑 CRITICAL:** You MUST:
+**CRITICAL:** You MUST:
 1. Run `work start` for the first stable chore
 2. Verify the worktree was created
 3. THEN invoke stable-mode using the Skill tool
@@ -1075,8 +1152,7 @@ cd <main-repo>
 ```bash
 # Bash call 2: Merge (ALWAYS include chore ID)
 jettypod work merge <chore-id>                    # Merge chore by ID
-jettypod work merge <chore-id> --with-transition  # Hold lock for transition
-jettypod work merge <chore-id> --release-lock     # Release held lock
+jettypod work merge --release-lock                # Force-release stuck lock
 ```
 
 **Start chores:**
@@ -1097,12 +1173,12 @@ jettypod work cleanup <feature-id>      # Clean up worktree
 jettypod work set-mode <feature-id> stable
 ```
 
-**Create chores (AFTER setting mode):**
+**Create chores (AFTER setting mode) — use Write tool for JSON, then:**
 ```bash
-jettypod work create chore "<title>" "<description>" --parent=<feature-id>
+jettypod work create --from=/tmp/jettypod-create.json
 ```
-Note: Do NOT use `--mode` flag - chores inherit mode from parent feature.
+Note: Do NOT add `mode` field in JSON - chores inherit mode from parent feature.
 
-**❌ DO NOT use these to complete chores:**
+**DO NOT use these to complete chores:**
 - `jettypod work status <id> done`
 - `jettypod work complete <id>`