jettypod 4.4.116 → 4.4.120

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

@@ -30,7 +30,7 @@ When this skill is activated, you are helping implement a production mode chore
 
 ---
 
-## 🛑 PRE-FLIGHT VALIDATION (REQUIRED)
+## PRE-FLIGHT VALIDATION (REQUIRED)
 
 **Before proceeding with ANY implementation, you MUST validate the worktree exists.**
 
@@ -44,23 +44,23 @@ 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.
 
-**🚫 FORBIDDEN: Manual Git Worktree Commands**
+**FORBIDDEN: Manual Git Worktree Commands**
 ```
-❌ git worktree add ...
-❌ git checkout -b feature/...
-❌ git branch feature/...
+git worktree add ...
+git checkout -b feature/...
+git branch feature/...
 ```
 **ALWAYS use `jettypod work start`** - it handles branch naming, path conventions, database tracking, and cleanup. Manual git commands will create orphaned worktrees that break the merge workflow.
 
 ---
 
-## 🔒 WORKTREE PATH LOCK
+## WORKTREE PATH LOCK
 
 **After pre-flight validation passes, capture and lock the worktree path:**
 
@@ -70,7 +70,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.
@@ -94,11 +94,11 @@ jettypod ui gate worktree-started --data='{"path":"${WORKTREE_PATH}"}'
 
 **MUST RUN FIRST:** Detect which scenario applies to this feature.
 
-**🚫 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 DETECTION step.** File writes happen in Step 3.
 
@@ -120,7 +120,7 @@ sqlite3 .jettypod/work.db "SELECT completed_at FROM work_items WHERE parent_id =
 
 Based on these checks, determine which scenario applies.
 
-**🔄 WORKFLOW INTEGRATION: Start workflow tracking**
+**WORKFLOW INTEGRATION: Start workflow tracking**
 
 After detecting context, register this skill execution:
 
@@ -155,11 +155,11 @@ This validates that `stable_mode_complete` gate is passed and creates an executi
 
 **For all scenarios:** Read production standards file.
 
-**🚫 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 READ step.** File writes happen in Step 3.
 
@@ -173,7 +173,7 @@ cat .jettypod/production-standards.json
 
 If the file doesn't exist, run external-transition first to generate production standards.
 
-**🔄 WORKFLOW CHECKPOINT: Standards read**
+**WORKFLOW CHECKPOINT: Standards read**
 
 ```bash
 jettypod workflow checkpoint <feature-id> --step=1
@@ -185,11 +185,11 @@ jettypod workflow checkpoint <feature-id> --step=1
 
 **For Scenario A only:** Quick validation of existing scenarios.
 
-**🚫 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 VALIDATION step.** File writes happen in Step 3.
 
@@ -208,19 +208,19 @@ try {
   });
 
   if (!feature.scenario_file) {
-    console.error('❌ Feature has no scenario file.');
+    console.error('Feature has no scenario file.');
     return;
   }
 
   // Validate scenarios against standards
   const validation = await validateScenarios(feature.scenario_file, standards);
 
-  console.log(`✅ Validation complete:`);
+  console.log(`Validation complete:`);
   console.log(`  - Covered: ${validation.covered}/${validation.total} standards`);
   console.log(`  - Gaps: ${validation.gaps.length}`);
 
   if (validation.hasGaps) {
-    console.log('\n⚠️  Missing scenarios for:');
+    console.log('\n Missing scenarios for:');
     validation.gaps.forEach(gap => {
       console.log(`  - ${gap.domain}: ${gap.standardId}`);
       console.log(`    ${gap.reasoning}`);
@@ -234,12 +234,12 @@ try {
     const newScenarios = await generateScenariosFromStandards(missingStandards);
 
     await appendScenarios(feature.scenario_file, newScenarios);
-    console.log(`✅ Added ${newScenarios.length} missing scenarios`);
+    console.log(`Added ${newScenarios.length} missing scenarios`);
   } else {
-    console.log('✅ All standards are covered by existing scenarios');
+    console.log('All standards are covered by existing scenarios');
   }
 } catch (err) {
-  console.error('❌ Validation failed:', err.message);
+  console.error('Validation failed:', err.message);
   return;
 }
 ```
@@ -250,11 +250,11 @@ try {
 
 **For Scenario B only:** Re-validate with current standards.
 
-**🚫 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 VALIDATION step.** File writes happen in Step 3.
 
@@ -263,7 +263,7 @@ const { validateScenarios } = require('../../lib/production-scenario-validator')
 const config = require('../../lib/config');
 
 try {
-  console.log('🔄 Re-validating scenarios against current standards...');
+  console.log('Re-validating scenarios against current standards...');
 
   // Check if project state changed
   const projectConfig = config.read();
@@ -281,12 +281,12 @@ try {
   // Validate scenarios
   const validation = await validateScenarios(feature.scenario_file, standards);
 
-  console.log(`✅ Re-validation complete:`);
+  console.log(`Re-validation complete:`);
   console.log(`  - Covered: ${validation.covered}/${validation.total} standards`);
   console.log(`  - New gaps: ${validation.gaps.length}`);
 
   if (validation.hasGaps) {
-    console.log('\n⚠️  Standards added/changed since last run:');
+    console.log('\n Standards added/changed since last run:');
     validation.gaps.forEach(gap => {
       console.log(`  - ${gap.domain}: ${gap.standardId}`);
     });
@@ -299,10 +299,10 @@ try {
     const newScenarios = await generateScenariosFromStandards(missingStandards);
 
     await appendScenarios(feature.scenario_file, newScenarios);
-    console.log(`✅ Updated with ${newScenarios.length} new scenarios`);
+    console.log(`Updated with ${newScenarios.length} new scenarios`);
   }
 } catch (err) {
-  console.error('❌ Re-validation failed:', err.message);
+  console.error('Re-validation failed:', err.message);
   return;
 }
 ```
@@ -313,11 +313,11 @@ try {
 
 **For Scenario C only:** Generate production scenarios from standards.
 
-**🚫 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 GENERATION step (via jettypod commands, not direct file writes).** File writes happen in Step 3.
 
@@ -335,7 +335,7 @@ This will:
 3. Append scenarios to the feature file
 4. Create production chores
 
-**🔄 WORKFLOW CHECKPOINT: Scenarios validated/generated** (after any Step 2 variant)
+**WORKFLOW CHECKPOINT: Scenarios validated/generated** (after any Step 2 variant)
 
 ```bash
 jettypod workflow checkpoint <feature-id> --step=2
@@ -345,9 +345,9 @@ jettypod workflow checkpoint <feature-id> --step=2
 
 ### Step 3: Implement Production Chore
 
-**🔒 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, context is detected.
+**NOW you may write files** - worktree is locked, context is detected.
 
 **Emit gate signal:**
 
@@ -373,7 +373,7 @@ Parse the chore description to find which scenario it addresses (look for "Scena
    npx cucumber-js <scenario-file> --name "<scenario-name>"
    ```
 
-   **🔄 WORKFLOW CHECKPOINT: RED baseline established**
+   **WORKFLOW CHECKPOINT: RED baseline established**
 
    ```bash
    jettypod workflow checkpoint <feature-id> --step=3
@@ -444,7 +444,7 @@ Once all production chores complete:
 2. Can be deployed to external environment
 3. Meets all standards for scale, security, compliance
 
-**🔄 WORKFLOW INTEGRATION: Complete workflow**
+**WORKFLOW INTEGRATION: Complete workflow**
 
 When all production chores are complete:
 

package/skills-templates/request-routing/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: request-routing
-description: "⚡ ENTRY POINT FOR ALL WORK REQUESTS. Invoke this skill FIRST when user describes ANY work - 'build X', 'fix Y', 'add Z', 'create feature', 'implement'. Do NOT create work items or invoke other planning skills directly. This skill analyzes intent and routes to the correct workflow. (project)"
+description: "ENTRY POINT FOR ALL WORK REQUESTS. Invoke this skill FIRST when user describes ANY work - 'build X', 'fix Y', 'add Z', 'create feature', 'implement'. Do NOT create work items or invoke other planning skills directly. This skill analyzes intent and routes to the correct workflow. (project)"
 ---
 
 # Request Routing Skill
 
-**⚡ UNIVERSAL ENTRY POINT** - This skill MUST be invoked FIRST when a user describes work they want done.
+**UNIVERSAL ENTRY POINT** - This skill MUST be invoked FIRST when a user describes work they want done.
 
 **DO NOT:**
 - Create work items (`jettypod work create`) before invoking this skill
@@ -35,7 +35,7 @@ From the user's request, identify work type and complexity signals:
 | refactor, rename, move, clean up, upgrade, migrate, infrastructure | chore-planning |
 | add, build, create, implement, new feature, capability, workflow | feature-planning |
 | epic, initiative, project, roadmap, multi-feature | epic-planning |
-| tweak, change, update, adjust + small scope | simple-improvement |
+| tweak, change, update, adjust + PURELY COSMETIC (text, color, spacing, copy only) | simple-improvement |
 
 **Complexity signals:**
 | Signal | Indicates |
@@ -46,6 +46,8 @@ From the user's request, identify work type and complexity signals:
 | Has edge cases to consider (validation, failures, states) | Higher complexity |
 | Could fail in interesting ways | Higher complexity |
 | Needs error handling design | Higher complexity |
+| Adds or changes behavior (tracking, counting, filtering, sorting, state) | Higher complexity — NOT simple-improvement |
+| Creates new capabilities (even small ones) | Higher complexity — NOT simple-improvement |
 
 ### Step 2: Gather Context (Silent - No Questions)
 
@@ -101,14 +103,14 @@ Are there edge cases to consider?
      │         (The speed→stable split helps: make it work, then handle edge cases)
      │
      ▼
-Is this substantial technical work?
-(Refactoring, infrastructure, migrations, multi-file changes)
-     ├─► Yes → chore-planning
+Is this PURELY COSMETIC?
+(Only changes text, copy, color, spacing, or static visual appearance?)
+(Does NOT add/change any behavior, logic, tracking, data, or capabilities?)
+     ├─► Yes → simple-improvement
      │
      ▼
-Is this truly atomic?
-(No edge cases. Happy path IS the complete implementation.)
-     └─► Yes → simple-improvement
+Default → chore-planning
+(When in doubt, route to chore-planning, NEVER to simple-improvement)
 ```
 
 ## Route Definitions
@@ -119,8 +121,8 @@ Is this truly atomic?
 | **epic-planning (technical)** | Large technical initiative (refactor, migration, infrastructure) with no user-facing features | Break down → chores directly (no features, no modes) |
 | **epic-planning** | Large initiative spanning multiple features | Break down → plan features |
 | **feature-planning** | New behavior needing UX exploration OR has edge cases worth sequencing | UX exploration → BDD → speed → stable → production |
-| **chore-planning** | Substantial technical work, clear implementation | speed → stable → production |
-| **simple-improvement** | Atomic change where happy path IS the complete implementation | Direct implementation |
+| **chore-planning** | Substantial technical work OR behavior-adding without edge cases | Type-specific verification → done (enhancement type uses TDD) |
+| **simple-improvement** | PURELY COSMETIC: text, copy, color, spacing changes only. No behavior change. | Direct implementation |
 
 ## Routing Examples
 
@@ -170,11 +172,22 @@ Is this truly atomic?
 **→ simple-improvement**
 - "Change the button text from 'Submit' to 'Save'"
 - "Make the error message more descriptive"
-- "Add a loading spinner to the save button"
 - "Change the header color to blue"
-- "Add a tooltip to the settings icon"
+- "Update the placeholder text in the search box"
+- "Increase the font size of the title"
 
-*(Truly atomic: no edge cases, no error states to design, happy path IS the complete implementation)*
+*(PURELY COSMETIC: only text, copy, color, spacing, or static visual changes. Zero behavior change.)*
+
+**NOT simple-improvement (common mistakes):**
+- "Add a loading spinner to the save button" → **chore-planning** (adds behavior: state tracking, show/hide logic)
+- "Add a tooltip to the settings icon" → **chore-planning** (adds behavior: hover state, positioning)
+- "Track work item counts" → **feature-planning** (adds behavior: counting, state, display logic)
+- "Add sorting to the list" → **feature-planning** (adds behavior: sort logic, state, UI interaction)
+- "Show a count next to the tab" → **chore-planning** (adds behavior: data fetching, count computation)
+- "Add a confirmation dialog" → **feature-planning** (adds behavior: modal state, user interaction, edge cases)
+- "Make the sidebar collapsible" → **feature-planning** (adds behavior: toggle state, animation, persistence)
+
+*(If it adds ANY new behavior — even "small" behavior — it is NOT a simple improvement.)*
 
 ## Stating Your Routing Decision
 

package/skills-templates/simple-improvement/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: simple-improvement
-description: Guide implementation of simple improvements to existing functionality. Invoked by request-routing for straightforward changes like copy changes, styling tweaks, or minor behavior adjustments where the implementation is obvious. (project)
+description: Guide implementation of PURELY COSMETIC changes. Invoked by request-routing ONLY for text, copy, color, and spacing changes that add zero new behavior. (project)
 ---
 
 # Simple Improvement Skill
@@ -18,24 +18,39 @@ description: Guide implementation of simple improvements to existing functionali
 └─────────────────────────────────────────────────────────────────────┘
 ```
 
-Lightweight workflow for basic enhancements to existing functionality. Bypasses the full speed/stable mode progression for simple changes.
+Lightweight workflow for PURELY COSMETIC changes. Bypasses the full speed/stable mode progression because these changes have zero behavior impact.
 
 ## When to Use
 
-This skill is invoked by request-routing when work is identified as a **simple improvement**:
-- Copy/text changes
-- Styling tweaks
-- Minor behavior adjustments
-- Small bug fixes to existing functionality
+This skill is invoked by request-routing ONLY for **purely cosmetic changes**:
+- Text/copy changes (button labels, headings, descriptions, placeholder text)
+- Color changes (background, text color, border color)
+- Spacing/sizing changes (padding, margin, font size, width)
+- Static visual appearance (border radius, opacity, font weight)
+
+**The litmus test:** Could a non-developer make this change with a find-and-replace in a design tool? If yes, it's simple. If no, it's not.
 
 ## When NOT to Use
 
-Route back to request-routing for:
-- New functionality (even if small)
+**If it adds or changes ANY behavior, it is NOT a simple improvement.** Route back to request-routing for:
+
+- Adding interactive elements (tooltips, spinners, modals, collapsibles)
+- Adding tracking/counting/state (counters, badges, progress indicators)
+- Adding data fetching or computation
+- Adding conditional logic (show/hide, enable/disable)
+- Adding user interactions (hover effects with logic, drag-and-drop, sorting)
+- New functionality of ANY size
 - Changes requiring new data models
 - Complex logic changes
 - Features needing error handling design
 
+**Common misroutes — these are NOT simple improvements:**
+- "Add a loading spinner" → has state (loading/not loading), show/hide logic
+- "Show item count" → needs data query, computation, display logic
+- "Add a tooltip" → hover detection, positioning, content logic
+- "Make sidebar collapsible" → toggle state, persistence, animation
+- "Add sorting" → sort logic, state management, UI interaction
+
 ---
 
 ## Instructions
@@ -58,7 +73,7 @@ Use the description from the user's initial request (passed through request-rout
 I need more details. What specifically needs to change?
 ```
 
-**⚡ WAIT for user to clarify, then proceed.**
+**WAIT for user to clarify, then proceed.**
 
 **Otherwise, proceed directly with the clear description you already have.**
 
@@ -71,29 +86,34 @@ Scan the user's description for these patterns:
 
 | Signal | Keywords/Patterns |
 |--------|-------------------|
+| New behavior | "add", "track", "count", "show", "display", "when", "toggle", "sort", "filter" |
+| State management | "loading", "spinner", "collapse", "expand", "hover", "active", "selected" |
 | New data models | "new table", "add column", "database", "schema" |
 | New API | "new endpoint", "API", "new route" |
 | Complex logic | "if/else", "conditional", "depends on", multiple "and" clauses |
 | Multiple components | mentions 3+ different files/areas, "also need to" |
 | Architectural changes | "refactor", "restructure", "new system" |
 
-❌ **Route back to request-routing if ANY complexity signal detected:**
+**Route back to request-routing if ANY complexity signal detected:**
+- Any new behavior (even "small" behavior like a spinner or tooltip)
+- Any state management (loading, toggle, hover, selection)
 - New database tables/columns needed
 - New API endpoints required
 - Complex conditional logic
 - Multiple interconnected changes
 - Need for error handling design
 
-✅ **Continue if the change is:**
+**Continue ONLY if the change is:**
+- Purely cosmetic (text, color, spacing, static visual appearance)
 - Single file or 2-3 related files
-- Modifying existing code (not creating new features)
-- Clear, specific scope
+- Modifying existing static values (not adding logic)
+- Zero new behavior, zero new state
 - No architectural decisions needed
 
 **If too complex:**
 
 ```
-⚠️ This change appears to require new data models or architectural changes. This is more than a simple improvement.
+This change appears to require new data models or architectural changes. This is more than a simple improvement.
 
 I'm routing you back to request-routing for proper planning.
 ```
@@ -105,7 +125,7 @@ I'm routing you back to request-routing for proper planning.
 **If confirmed simple:**
 
 ```
-✅ Confirmed: This is a simple improvement.
+Confirmed: This is a simple improvement.
 
 Change: [summarize the specific change]
 Scope: [list files likely affected]
@@ -127,14 +147,22 @@ jettypod ui gate route-decided --data='{"route":"simple-improvement","title":"[b
 
 **Create a single chore with NO mode assigned.**
 
+Use the **Write** tool to create `/tmp/jettypod-create.json`:
+```json
+{
+  "type": "chore",
+  "title": "[Brief description of the change]",
+  "description": "[Detailed description including:\n- What to change\n- Where to change it\n- Expected outcome]",
+  "parent": <feature-id>
+}
+```
+
+Then run via **Bash**:
 ```bash
-jettypod work create chore "[Brief description of the change]" "[Detailed description including:
-- What to change
-- Where to change it
-- Expected outcome]" --parent=<feature-id>
+jettypod work create --from=/tmp/jettypod-create.json
 ```
 
-**IMPORTANT:** Do NOT use `--mode` flag. Simple improvements don't use speed/stable modes.
+**IMPORTANT:** Do NOT add a `mode` field. Simple improvements don't use speed/stable modes.
 
 **Emit gate signal:**
 
@@ -145,7 +173,7 @@ jettypod ui gate work-created --data='{"id":[chore-id],"title":"[title]"}'
 **Display to user:**
 
 ```
-✅ Created Chore #[id]: [title]
+Created Chore #[id]: [title]
 
 Ready to implement. Starting chore...
 ```
@@ -155,7 +183,7 @@ Ready to implement. Starting chore...
 When the `jettypod work create` command fails, display error details and suggest recovery:
 
 ```
-❌ Failed to create chore: [error message] ([error code if available])
+Failed to create chore: [error message] ([error code if available])
 
 This could be caused by:
 • Database is locked by another process
@@ -169,7 +197,7 @@ Suggested actions:
 4. If persistent, try: jettypod work cleanup --all
 ```
 
-**⚡ WAIT for user to acknowledge before retrying or investigating further.**
+**WAIT for user to acknowledge before retrying or investigating further.**
 
 Do NOT proceed to Step 3 until chore is successfully created.
 
@@ -185,7 +213,7 @@ Do NOT proceed to Step 3 until chore is successfully created.
 jettypod work start <chore-id>
 ```
 
-**🛑 STOP AND CHECK:** Verify worktree was created successfully before proceeding.
+**STOP AND CHECK:** Verify worktree was created successfully before proceeding.
 
 ```bash
 sqlite3 .jettypod/work.db "SELECT worktree_path FROM worktrees WHERE work_item_id = <chore-id> AND status = 'active'"
@@ -205,13 +233,13 @@ jettypod ui gate worktree-started --data='{"path":"${WORKTREE_PATH}"}'
 **Display confirmation:**
 
 ```
-📁 Worktree created: ${WORKTREE_PATH}
+Worktree created: ${WORKTREE_PATH}
 
 From this point forward, ALL file operations MUST use paths starting with:
 ${WORKTREE_PATH}/
 ```
 
-**🔒 WORKTREE PATH LOCK:** Store `WORKTREE_PATH` - all file operations in this skill MUST use this path prefix.
+**WORKTREE PATH LOCK:** Store `WORKTREE_PATH` - all file operations in this skill MUST use this path prefix.
 
 ---
 
@@ -230,7 +258,7 @@ jettypod ui gate implementing --data='{"description":"[what is being changed]","
 **Display progress:**
 
 ```
-📝 Implementing change...
+Implementing change...
 
 Modified: ${WORKTREE_PATH}/[relative path]
 Change: [what was changed]
@@ -253,7 +281,7 @@ Verifying...
 
 **If verification passes:**
 
-**🔒 WORKTREE PATH REQUIRED:** Use the `WORKTREE_PATH` captured in Step 3.
+**WORKTREE PATH REQUIRED:** Use the `WORKTREE_PATH` captured in Step 3.
 
 ```bash
 # Commit the change
@@ -261,14 +289,14 @@ cd ${WORKTREE_PATH}
 git add .
 git commit -m "fix: [brief description]
 
-🤖 Generated with [Claude Code](https://claude.com/claude-code)
+Generated with [Claude Code](https://claude.com/claude-code)
 
 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>"
 ```
 
 **Then merge (CRITICAL: run as separate Bash calls):**
 
-⚠️ Shell CWD persists. You MUST run `cd` as a SEPARATE Bash tool call before merge.
+Shell CWD persists. You MUST run `cd` as a SEPARATE Bash tool call before merge.
 
 ```bash
 # Bash call 1: Change to main repo
@@ -286,12 +314,12 @@ jettypod work cleanup <chore-id>
 When `jettypod work merge` encounters an error (e.g., merge conflicts), the worktree is preserved for debugging.
 
 ```
-❌ Merge failed: [error message from git]
+Merge failed: [error message from git]
 
 Conflicting files:
 • [list conflicting files if available]
 
-⚠️ IMPORTANT: The worktree has been PRESERVED for debugging at:
+IMPORTANT: The worktree has been PRESERVED for debugging at:
    [worktree-path]
 
 Resolution steps:
@@ -305,15 +333,12 @@ Resolution steps:
 Need help? Run: git status (in worktree) to see conflict status
 ```
 
-**⚡ WAIT for user to resolve conflicts before retrying.**
+**WAIT for user to resolve conflicts before retrying.**
 
 Do NOT attempt to auto-resolve conflicts - let the user handle them manually.
 
-**Mark feature as done:**
-
-```bash
-jettypod work status <feature-id> done
-```
+**The merge command automatically sets the feature as ready for review.**
+It will appear with accept/reject buttons on the kanban board. Do NOT call `jettypod work status <feature-id> done` — that bypasses the review gate.
 
 **Emit gate signal:**
 
@@ -325,7 +350,7 @@ jettypod ui gate complete --data='{"summary":"[what was changed]","files":["[fil
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-✅ Simple Improvement Complete!
+Simple Improvement Complete!
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 Change: [what was changed]
@@ -354,8 +379,8 @@ No further action needed.
 ## Command Reference
 
 ```bash
-# Create chore (no mode)
-jettypod work create chore "<title>" "<description>" --parent=<feature-id>
+# Create chore (no mode) - use Write tool for JSON, then:
+jettypod work create --from=/tmp/jettypod-create.json
 
 # Start chore
 jettypod work start <chore-id>
@@ -367,6 +392,5 @@ jettypod work merge <chore-id>      # Bash call 2
 # Cleanup
 jettypod work cleanup <chore-id>
 
-# Mark feature done
-jettypod work status <feature-id> done
+# Do NOT mark feature done manually — merge sets the review gate automatically
 ```