jettypod 4.4.115 → 4.4.118

package/lib/seed-onboarding.js

@@ -11,118 +11,150 @@ const ONBOARDING_EPIC = {
   description: 'Get your project set up and planned. Work through these chores one at a time — each one is a short conversation.'
 };
 
+const TONE = `HOW TO RESPOND:
+You are a collaborator, not an AI assistant. You're a knowledgeable partner having a real conversation.
+- Do NOT open with a summary or recap of what you've been asked to do
+- Do NOT list steps or outline a plan before starting
+- Do NOT say "I'll help you with...", "Let me guide you through...", or "Great question!"
+- Do NOT use headers, bullet lists, or formatted option blocks in your first message
+- DO jump straight into conversation like a person who just sat down across the table
+- DO ask one question at a time, then actually listen to the response
+- DO keep responses short — a few sentences, not paragraphs
+- DO respond naturally to what the user says, adapting your follow-ups accordingly`;
+
 const ONBOARDING_CHORES = [
   {
     title: 'Align on the user journey',
-    description: `This is the first onboarding chore. Help the user define what their product does.
+    description: `${TONE}
+
+YOUR ROLE: Help the user articulate what their product does and how people will use it.
 
-CLAUDE SESSION GUIDANCE:
-Open with: "What do users DO in this product? Walk me through the flow from opening it to getting value from it."
+CONVERSATION FLOW:
 
-If the user isn't sure, suggest 3 different user journey options:
-- Journey 1: [Simple/Direct approach] with flow, pros, cons
-- Journey 2: [Balanced approach] with flow, pros, cons
-- Journey 3: [Advanced/Guided approach] with flow, pros, cons
+1. OPEN — Jump straight in. Something like:
+   "So — what are you building? Walk me through what happens when someone opens this thing up."
+   (Adapt to context. Be casual. No preamble.)
 
-Ask: "Which journey resonates? Or describe your own."
+2. LISTEN AND DIG — Based on what they say, ask natural follow-ups. One at a time:
+   - "And then what? What happens after [thing they mentioned]?"
+   - "How do they find that the first time?"
+   - "What's the moment where it clicks — like, this is actually useful?"
+   Don't rush this. Let them think. Some people need 2-3 exchanges to articulate their vision.
 
-OUTCOME:
-- A clear description of the core user journey
-- Agreement on the main actions users take
+3. IF THEY'RE VAGUE — Don't present a formatted options list. Talk through possibilities naturally:
+   "I could see this going a few ways. You could do [approach A] — really simple, users just [action]. Or something more like [approach B] where they [different flow]. What feels closer?"
+   If they're really stuck, describe 2-3 directions conversationally and ask what resonates.
 
-RECORD DECISION:
-After the user picks/describes their journey, run:
-  jettypod work epic-implement <onboarding-epic-id> --aspect="User Journey" --decision="<chosen journey>" --rationale="<why>"
+4. CONFIRM — Once the journey is clear, reflect it back casually:
+   "Cool, so basically: user shows up, [does X], then [does Y], and the payoff is [Z]. That feel right?"
+   Wait for them to confirm or adjust.
 
-Then tell the user: "Got it. Close this chat and start the next chore from your backlog to continue."`
+5. RECORD — After they confirm, run:
+   jettypod work epic-implement <onboarding-epic-id> --aspect="User Journey" --decision="<summary of chosen journey>" --rationale="<why this flow>"
+
+6. HAND OFF — Say something like: "Nice. Close this chat and start the next chore in your backlog to keep going."`
   },
   {
     title: 'Explore UX approaches',
-    description: `This is the second onboarding chore. Help the user decide how the product should feel.
+    description: `${TONE}
+
+YOUR ROLE: Help the user decide how their product should FEEL to use. This is about the experience, not the tech.
 
-CONTEXT FROM PREVIOUS CHORE:
-Read the user journey decision first:
+CONTEXT: Read the user journey decision first:
   jettypod decisions --epic=<onboarding-epic-id>
 
-CLAUDE SESSION GUIDANCE:
-Open with: "Based on your user journey: [quote decision]. Now let's figure out how it should feel to use."
+CONVERSATION FLOW:
 
-Present exactly 3 UX approaches (NOT tech stacks — focus on the experience):
-- Option 1: [Simple approach] — pros, cons, what it feels like
-- Option 2: [Balanced approach] — pros, cons, what it feels like
-- Option 3: [Advanced approach] — pros, cons, what it feels like
+1. OPEN — Reference what they already decided and pivot naturally:
+   "So last time you said users would [brief journey recap]. Now I'm curious — what should that actually feel like? Like, when someone [key action], are you imagining something minimal and fast, or more guided and hand-holdy?"
+   (Use their actual words from the decision. Don't be generic.)
 
-Ask: "Would you like me to create working prototypes of these?"
+2. EXPLORE THROUGH CONVERSATION — Don't dump three formatted options. Talk through directions:
+   "One direction would be something really stripped down — [describe the feel]. That works well when [context]. But you could also go more toward [different feel] where [description]. The trade-off is [honest assessment]."
+   Let them react. Follow their energy.
 
-If yes, build quick throwaway prototypes using jettypod project prototype commands.
-If no, ask which option they prefer.
+3. GET SPECIFIC — Once a direction emerges, push on it:
+   "OK so if we go that route, the main screen would probably be [description]. Does that feel right or is that too [much/little]?"
 
-OUTCOME:
-- 3 UX options compared
-- A winner chosen
-- Optionally: working prototypes tested
+4. OFFER PROTOTYPES (if it would help) — If they're torn or want to see it:
+   "Want me to throw together a quick prototype of that? Nothing fancy — just enough to feel it out."
+   If yes, use: jettypod project prototype start <approach-name>
+   Build a minimal throwaway prototype, then: jettypod project prototype merge
+   After they try it: "What did you think? Does that feel like the right direction, or should we adjust?"
 
-RECORD DECISION:
-  jettypod work epic-implement <onboarding-epic-id> --aspect="UX Approach" --decision="<chosen approach>" --rationale="<why>"
+5. CONFIRM — Lock in the winner:
+   "Alright, so the feel is [description]. I'll record that."
 
-Then tell the user: "Close this chat and start the next chore from your backlog."`
+6. RECORD — Run:
+   jettypod work epic-implement <onboarding-epic-id> --aspect="UX Approach" --decision="<chosen approach>" --rationale="<why>"
+
+7. HAND OFF — "Close this chat and start the next chore from your backlog."`
   },
   {
     title: 'Choose a tech stack',
-    description: `This is the third onboarding chore. Help the user pick the right tech stack.
+    description: `${TONE}
+
+YOUR ROLE: Help the user pick the right tech stack based on what they're building and how it should feel.
 
-CONTEXT FROM PREVIOUS CHORES:
-Read previous decisions first:
+CONTEXT: Read previous decisions first:
   jettypod decisions --epic=<onboarding-epic-id>
 
-CLAUDE SESSION GUIDANCE:
-Open with: "You're building [journey] with a [UX approach] experience. Let's pick the tech stack."
+CONVERSATION FLOW:
 
-Present exactly 3 tech stack options appropriate for their UX approach:
-- Option 1: [Stack name] — pros, cons, what development will feel like
-- Option 2: [Stack name] — pros, cons, what development will feel like
-- Option 3: [Stack name] — pros, cons, what development will feel like
+1. OPEN — Connect the dots from previous decisions:
+   "You're building [journey] and you want it to feel [UX approach]. That actually narrows down the tech quite a bit."
+   Then lead with your honest take:
+   "I'd probably go with [recommendation] for this. Here's why — [reason]."
+   (Have an opinion. Don't just present options neutrally.)
 
-Include "Other options considered" with brief reasons for not recommending.
+2. HAVE A REAL DISCUSSION — After giving your take, open it up:
+   "That said — do you have a preference? Are you already comfortable with something, or is there a stack you've been wanting to try?"
+   Respond to what they say. If they push back, engage with it honestly:
+   "Yeah, [their preference] could work. The main thing you'd lose is [trade-off]. The main thing you'd gain is [benefit]. Honestly, either would be fine for this."
 
-OUTCOME:
-- 3 tech stack options compared
-- A winner chosen with rationale
+3. IF THEY WANT OPTIONS — Talk through 2-3 stacks conversationally, not as formatted comparison blocks:
+   "[Stack A] would be the fastest to get going — you'd have [benefit] out of the box. [Stack B] is more flexible but you'd need to wire up [thing] yourself. And then there's [Stack C] which is honestly overkill here unless you specifically want [thing]."
 
-RECORD DECISION:
-  jettypod work epic-implement <onboarding-epic-id> --aspect="Tech Stack" --decision="<chosen stack>" --rationale="<why>"
+4. LAND ON A DECISION — Once they choose:
+   "Solid choice. [One sentence of genuine validation — why it fits their specific project, not generic praise]."
 
-Then tell the user: "Close this chat and start the last onboarding chore."`
+5. RECORD — Run:
+   jettypod work epic-implement <onboarding-epic-id> --aspect="Tech Stack" --decision="<chosen stack>" --rationale="<why>"
+
+6. HAND OFF — "One more chore left — close this chat and start it from your backlog."`
   },
   {
     title: 'Break the project into epics',
-    description: `This is the final onboarding chore. Break the project into buildable phases.
+    description: `${TONE}
+
+YOUR ROLE: Break the project into buildable phases (epics) based on everything they've decided.
 
-CONTEXT FROM PREVIOUS CHORES:
-Read all previous decisions first:
+CONTEXT: Read all previous decisions first:
   jettypod decisions --epic=<onboarding-epic-id>
 
-CLAUDE SESSION GUIDANCE:
-Open with: "You're building [journey] as a [UX approach] experience using [tech stack]. Let's break this into phases."
+CONVERSATION FLOW:
 
-Explain: "Epics are phase-level chunks of work. Each epic contains features — things users can actually do."
+1. OPEN — Bring it all together and jump straight to the breakdown:
+   "Alright — you're building [journey], it should feel [UX approach], and you're using [tech stack]. Let me suggest how to break this into phases."
+   Then just propose the epics conversationally:
+   "I'd start with [Epic 1] — that's the foundation, stuff like [examples]. Then [Epic 2] which covers [what]. And then [Epic 3] for [what]."
+   (Don't over-explain what an epic is. Keep it natural.)
 
-Propose 3-5 epics based on everything they've decided:
-- Epic 1: [Name] — what it covers
-- Epic 2: [Name] — what it covers
-- Epic 3: [Name] — what it covers
+2. QUICK CONTEXT (only if needed) — If they seem unsure about the structure:
+   "Each of these is a phase. Inside each one we'll define specific features — things users can actually do. You don't need to think about that yet though."
 
-Ask: "Sound right? What would you add or change?"
+3. GET FEEDBACK — After proposing:
+   "Does that breakdown make sense? Anything you'd add, cut, or reorder?"
+   Adjust based on their input. Don't be precious about your proposal.
 
-After confirmation, create each epic:
-  jettypod work create epic "<title>" "<description>"
+4. CREATE — Once they confirm, create each epic:
+   jettypod work create epic "<title>" "<description>"
+   Do this for each one.
 
-OUTCOME:
-- 3-5 epics created in the backlog
-- A recommendation for which epic to start first
+5. RECOMMEND A STARTING POINT:
+   "If I were you, I'd start with [Epic name] — [brief reason, like 'everything else depends on it' or 'it's the quickest win to get something real']."
 
-CLOSING:
-Tell the user: "Your project is planned! Pick an epic from the backlog and tell Claude 'Let's plan [epic name]' to start building."`
+6. CLOSE — "Your project is planned. Pick an epic from the backlog and tell Claude 'Let's plan [epic name]' to start building."`
   }
 ];
 

package/lib/work-commands/index.js

@@ -1902,20 +1902,50 @@ async function mergeWork(options = {}) {
         `Test worktrees (tests/* branches) merge BDD scenarios without completing the feature.`
       ));
     } else {
-      // Chore or bug worktree: mark as done
-      console.log(`Marking ${currentWork.type} as done...`);
-      const completedAt = new Date().toISOString();
-      await new Promise((resolve, reject) => {
-        db.run(
-          `UPDATE work_items SET status = 'done', completed_at = ? WHERE id = ?`,
-          [completedAt, currentWork.id],
-          (err) => {
+      // Chore or bug worktree
+      // Check if this is a standalone kanban-visible item (no parent or parent is epic)
+      let isStandalone = !currentWork.parent_id;
+      if (!isStandalone && currentWork.parent_id) {
+        const parentItem = await new Promise((resolve, reject) => {
+          db.get('SELECT type FROM work_items WHERE id = ?', [currentWork.parent_id], (err, row) => {
             if (err) return reject(err);
-            resolve();
-          }
-        );
-      });
-      console.log(`✅ ${currentWork.type.charAt(0).toUpperCase() + currentWork.type.slice(1)} #${currentWork.id} marked as done`);
+            resolve(row);
+          });
+        });
+        isStandalone = parentItem && parentItem.type === 'epic';
+      }
+
+      if (isStandalone) {
+        // Standalone item: set ready_for_review instead of marking done
+        // Keep status as in_progress so it stays in the In Flight column
+        // User accepts/rejects via the kanban board
+        await new Promise((resolve, reject) => {
+          db.run(
+            `UPDATE work_items SET ready_for_review = 1 WHERE id = ?`,
+            [currentWork.id],
+            (err) => {
+              if (err) return reject(err);
+              resolve();
+            }
+          );
+        });
+        console.log(`✅ ${currentWork.type.charAt(0).toUpperCase() + currentWork.type.slice(1)} #${currentWork.id} ready for review`);
+      } else {
+        // Chore/bug under a feature: mark as done (feature handles the accept flow)
+        console.log(`Marking ${currentWork.type} as done...`);
+        const completedAt = new Date().toISOString();
+        await new Promise((resolve, reject) => {
+          db.run(
+            `UPDATE work_items SET status = 'done', completed_at = ? WHERE id = ?`,
+            [completedAt, currentWork.id],
+            (err) => {
+              if (err) return reject(err);
+              resolve();
+            }
+          );
+        });
+        console.log(`✅ ${currentWork.type.charAt(0).toUpperCase() + currentWork.type.slice(1)} #${currentWork.id} marked as done`);
+      }
     }
 
     // Mark worktree as merged but DON'T delete it yet

package/lib/work-tracking/index.js

@@ -256,6 +256,22 @@ function create(type, title, description = '', parentId = null, mode = null, nee
     }
 
     function continueWithValidatedParent(epicId) {
+      // Read current plan from auth.json for usage tracking
+      let planAtCreation = null;
+      try {
+        const os = require('os');
+        const path = require('path');
+        const fs = require('fs');
+        const authPath = path.join(os.homedir(), 'Library', 'Application Support', 'jettypod', 'auth.json');
+        if (fs.existsSync(authPath)) {
+          const authData = JSON.parse(fs.readFileSync(authPath, 'utf8'));
+          planAtCreation = authData?.user?.plan || 'free';
+        } else {
+          planAtCreation = 'free';
+        }
+      } catch {
+        planAtCreation = 'free';
+      }
 
       // Only features have modes - they start with mode=NULL (no mode until implementation starts)
       // Epics, chores, and bugs don't have modes (always NULL)
@@ -282,8 +298,8 @@ function create(type, title, description = '', parentId = null, mode = null, nee
       // Set phase for features (discovery when mode=NULL, implementation when mode is set, NULL for everything else)
       const phase = type === 'feature' ? (mode ? 'implementation' : 'discovery') : null;
 
-      const sql = `INSERT INTO work_items (type, title, description, parent_id, epic_id, mode, needs_discovery, phase, status) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`;
-      db.run(sql, [type, title, description, parentId, epicId, mode, needsDiscovery ? 1 : 0, phase, 'backlog'], function(err) {
+      const sql = `INSERT INTO work_items (type, title, description, parent_id, epic_id, mode, needs_discovery, phase, status, plan_at_creation) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`;
+      db.run(sql, [type, title, description, parentId, epicId, mode, needsDiscovery ? 1 : 0, phase, 'backlog', planAtCreation], function(err) {
         if (err) {
           return reject(err);
         }
@@ -776,31 +792,19 @@ function updateStatus(id, status) {
               return resolve();
             }
 
-            // Auto-close epics when all children are done
+            // Items under epics: set ready_for_review and keep in_progress for accept/reject
             if (parent.type === 'epic') {
-              // Check if all children of this epic are done
-              db.all(
-                'SELECT id, status FROM work_items WHERE parent_id = ?',
-                [parent.id],
-                (err, children) => {
+              // Set ready_for_review on the item and revert to in_progress
+              db.run(
+                'UPDATE work_items SET ready_for_review = 1, status = ?, completed_at = NULL WHERE id = ?',
+                ['in_progress', item.id],
+                (err) => {
                   if (err) {
-                    return resolve();
-                  }
-
-                  const allDone = children.every(child => child.status === 'done');
-                  if (allDone) {
-                    const epicCompletedAt = new Date().toISOString();
-                    db.run('UPDATE work_items SET status = ?, completed_at = ? WHERE id = ?', ['done', epicCompletedAt, parent.id], (err) => {
-                      if (err) {
-                        console.error(`Failed to auto-close epic: ${err.message}`);
-                      } else {
-                        console.log(`✓ Epic #${parent.id} also completed (all children done)`);
-                      }
-                      resolve();
-                    });
+                    console.error(`Failed to set ready_for_review: ${err.message}`);
                   } else {
-                    resolve();
+                    console.log(`✓ Work item #${item.id} ready for review`);
                   }
+                  resolve();
                 }
               );
             }
@@ -838,12 +842,12 @@ function updateStatus(id, status) {
                     }
 
                     if (featureComplete) {
-                      const featureCompletedAt = new Date().toISOString();
-                      db.run('UPDATE work_items SET status = ?, completed_at = ? WHERE id = ?', ['done', featureCompletedAt, parent.id], (err) => {
+                      // Set ready_for_review instead of auto-closing — let user accept/reject
+                      db.run('UPDATE work_items SET ready_for_review = 1 WHERE id = ?', [parent.id], (err) => {
                         if (err) {
-                          console.error(`Failed to auto-close feature: ${err.message}`);
+                          console.error(`Failed to set ready_for_review: ${err.message}`);
                         } else {
-                          console.log(`✓ Feature #${parent.id} completed (all ${featureMode} mode chores done)`);
+                          console.log(`✓ Feature #${parent.id} ready for review (all ${featureMode} mode chores done)`);
                         }
                         resolve();
                       });
@@ -860,6 +864,21 @@ function updateStatus(id, status) {
               resolve();
             }
           });
+        } else if (status === 'done' && !item.parent_id) {
+          // Standalone item (no parent) marked done via CLI
+          // Set ready_for_review and revert to in_progress so user can accept/reject via kanban
+          db.run(
+            'UPDATE work_items SET ready_for_review = 1, status = ?, completed_at = NULL WHERE id = ?',
+            ['in_progress', item.id],
+            (err) => {
+              if (err) {
+                console.error(`Failed to set ready_for_review: ${err.message}`);
+              } else {
+                console.log(`✓ Work item #${item.id} ready for review`);
+              }
+              resolve();
+            }
+          );
         } else {
           resolve();
         }

package/package.json

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

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

@@ -342,13 +342,10 @@ jettypod work cleanup <bug-id>
 
 ---
 
-### Step 5: Mark Bug as Done
+### Step 5: Completion
 
-**After the fix is merged, mark the bug as done:**
-
-```bash
-jettypod work status <bug-id> done
-```
+**The merge command automatically sets the bug as ready for review.**
+It will appear with accept/reject buttons on the kanban board. Do NOT call `jettypod work status <bug-id> done` — that bypasses the review gate.
 
 **Emit gate signal:**
 
@@ -387,7 +384,7 @@ Before ending bug-mode skill, ensure:
 - [ ] Fix committed with descriptive message
 - [ ] Bug merged to main
 - [ ] Worktree cleaned up
-- [ ] Bug marked as done
+- [ ] Bug merged (review gate set automatically by merge command)
 
 ---
 
@@ -403,7 +400,4 @@ cd <main-repo>                   # Change to main repo
 jettypod work cleanup <bug-id>   # Clean up worktree
 ```
 
-**Mark bug complete:**
-```bash
-jettypod work status <bug-id> done
-```
+**⚠️ Do NOT mark bug as done manually — the merge command sets the review gate automatically.**

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

@@ -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
@@ -120,7 +122,7 @@ Is this truly atomic?
 | **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 |
+| **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
@@ -71,6 +86,8 @@ 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 |
@@ -78,16 +95,19 @@ Scan the user's description for these patterns:
 | Architectural changes | "refactor", "restructure", "new system" |
 
 ❌ **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:**
@@ -309,11 +329,8 @@ Need help? Run: git status (in worktree) to see conflict status
 
 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:**
 
@@ -367,6 +384,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
 ```