jettypod 4.4.120 → 4.4.121

package/skills-templates/design-system-selection/SKILL.md

@@ -0,0 +1,273 @@
+# Design System Selection Skill
+
+Walks users through discovering, configuring, and documenting their project's design system. Produces a standardized Brand Kit page.
+
+## When to Use
+
+Invoke when the user says things like:
+- "set up my design system"
+- "configure design system"
+- "help me with my brand kit"
+- "add my design tokens"
+
+## Instructions
+
+### Opening
+
+Start the conversation with enthusiasm. Design systems are the foundation of a polished product — they deserve excitement. Open with something like:
+
+> Design systems are one of the highest-leverage things you can set up. Once Claude knows your colors, typography, spacing, and component patterns, every piece of UI it builds will feel like *your* product — not a generic template.
+>
+> I'm going to walk you through a few decisions, scan your project for what you already have, and we'll leave with two things:
+>
+> 1. **Your design system directory configured** — so Claude always has your tokens as context
+> 2. **A Brand Kit page** — a living reference you (and Claude) can always check
+>
+> Here's what a finished Brand Kit looks like: `app/design-system/page.tsx` in this project.
+>
+> Let's start.
+
+**Then proceed to Step 1.**
+
+### Step 1: Scan for What Exists
+
+Before asking questions, scan the project to understand what's already in place. Run these in parallel:
+
+**Directory search:**
+```bash
+find . -maxdepth 3 -type d \( -name "design-system" -o -name "design-tokens" -o -name "tokens" -o -name "theme" -o -name "styles" -o -name "ui-kit" -o -name "foundations" -o -name "primitives" \) -not -path "*/node_modules/*" -not -path "*/.git/*" 2>/dev/null
+```
+
+**File pattern search** (use Glob tool):
+- `**/tokens.{css,scss,json,ts,js}`
+- `**/theme.{css,scss,json,ts,js}`
+- `**/variables.{css,scss}`
+- `**/_variables.scss`
+- `**/design-tokens/**`
+- `**/globals.css`
+- `**/tailwind.config.*`
+
+**Content signals** (use Grep tool):
+- CSS custom properties: `--color-`, `--spacing-`, `--font-`
+- Tailwind theme config: `colors:`, `spacing:`, `fontFamily:`
+- Design token patterns: `$color-`, `$spacing-`
+
+**Present what you found:**
+
+If tokens/theme files exist:
+> I found some existing design assets. Here's what I see:
+> - [list files with brief content summary]
+>
+> Let me ask you a few questions to fill in the gaps.
+
+If nothing found:
+> Starting fresh — that's fine. Let me walk you through the key decisions.
+
+### Step 2: Walk Through Decisions
+
+Guide the user through each design system category. For each, present a focused question. Don't overwhelm — one topic at a time.
+
+**2a. Brand Palette**
+
+> **Colors first.** Every brand needs at minimum:
+> - **Primary** — your main action color (buttons, links, active states)
+> - **Accent** — warm emphasis (CTAs, highlights, banners)
+> - **Neutral black** — text, borders, outlined buttons
+>
+> Do you have brand colors already? Paste hex codes, a brand guide link, or describe the vibe you want (e.g., "calm and professional", "bold and energetic").
+
+**WAIT for user response.**
+
+For each color, derive three shades:
+- **Solid** — the main color (buttons, fills)
+- **Tint** — light background version (badges, callouts) — mix ~85% white
+- **Text** — darker version for text on the tint — darken ~30%
+
+**2b. Typography**
+
+> **Typography.** What font does your project use? Check your CSS/config, or tell me what you'd like.
+>
+> I also need to know your heading style preference — tight tracking (modern/bold) or normal tracking (classic/readable)?
+
+**WAIT for user response.**
+
+**2c. Surface & Elevation**
+
+> **Surfaces.** Two quick decisions:
+> 1. **Background warmth** — Pure white canvas, or slightly warm (cream/gray tint)?
+> 2. **Cards** — Separated by borders, or by shadow + background contrast (no borders)?
+
+**WAIT for user response.**
+
+**2d. Border Philosophy**
+
+> **Borders.** I recommend the binary approach: thick borders (2px) on interactive elements (inputs, outlined buttons), and NO borders on containers (use shadow + background contrast instead). Sound good, or do you prefer a different approach?
+
+**WAIT for user response.**
+
+**2e. Spacing & Radius**
+
+> **Last two quick ones:**
+> - **Border radius** — Rounded (16px cards, 12px buttons) or sharp (4-8px everywhere)?
+> - **Spacing** — Generous (lots of breathing room) or compact (dense, information-heavy)?
+
+**WAIT for user response.**
+
+### Step 3: Configure the Design System Directory
+
+Based on the scan results from Step 1, identify or create the design system directory.
+
+**If a clear candidate exists:**
+> I'll configure `[path]` as your design system directory.
+
+**If no directory exists, create one:**
+> I'll create a `design-system/` directory with your tokens.
+
+Write a CSS tokens file with all the decisions from Step 2:
+
+```css
+/* design-system/tokens.css */
+:root {
+  /* Brand Palette - Primary */
+  --color-primary: [solid];
+  --color-primary-tint: [tint];
+  --color-primary-text: [text-on-tint];
+
+  /* Brand Palette - Accent */
+  --color-accent: [solid];
+  --color-accent-tint: [tint];
+  --color-accent-text: [text-on-tint];
+
+  /* Brand Palette - Neutral */
+  --color-black: [black];
+
+  /* Surfaces */
+  --color-background: [background];
+  --color-card: [card];
+
+  /* Typography */
+  --font-sans: [font];
+  --font-mono: [mono font];
+
+  /* Spacing */
+  --space-xs: [value];
+  --space-sm: [value];
+  --space-md: [value];
+  --space-lg: [value];
+  --space-xl: [value];
+
+  /* Radius */
+  --radius-sm: [value];
+  --radius-md: [value];
+  --radius-lg: [value];
+
+  /* Shadows */
+  --shadow-sm: [value];
+  --shadow-md: [value];
+  --shadow-lg: [value];
+}
+```
+
+Then configure it:
+
+```bash
+node -e "
+const fs = require('fs');
+const path = require('path');
+const dir = path.resolve('<selected-directory>');
+const configPath = '.jettypod/config.json';
+const config = fs.existsSync(configPath) ? JSON.parse(fs.readFileSync(configPath, 'utf-8')) : {};
+config.designSystemDir = dir;
+fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+console.log('Set designSystemDir to:', dir);
+"
+```
+
+Regenerate CLAUDE.md:
+```bash
+jettypod claude generate
+```
+
+Verify:
+```bash
+grep -c "design_system" CLAUDE.md
+```
+
+### Step 4: Generate the Brand Kit Page
+
+**This is the key deliverable.** Create a standardized Brand Kit page that serves as a living reference.
+
+The page MUST follow this exact structure (same sections, same order, every time):
+
+```
+app/design-system/page.tsx
+```
+
+**Required sections (in order):**
+
+| # | Section | What it shows |
+|---|---------|---------------|
+| 0 | Border Philosophy | Binary borders rule — thick on interactive, none on containers |
+| 1 | Brand Palette | Each color with solid/tint/text swatches + in-context badges |
+| 2 | Surface Hierarchy | Background → card → content layering with actual nesting demo |
+| 3 | Elevation Scale | Shadow levels (sm/md/lg/overlay) with visual boxes |
+| 4 | Typography | Full type scale from display (4xl) to caption (xs) |
+| 5 | Motion & Easing | Duration, easing, and live hover demos |
+| 6 | Border Radius | Visual comparison of radius tiers |
+| 7 | Button Variants | All variants × all sizes, including loading states |
+| 8 | Hover/Active/Disabled | Interactive state demos |
+| 9 | Input Focus States | Resting vs focused with live interaction |
+| 10 | Focus Rings | Tab-accessible focus-visible demos |
+| 11 | Loading States | Skeletons and spinners |
+| 12 | Toast Patterns | Success, error, info, warning static examples |
+| 13 | Composition Examples | Cards with actions, forms, banners — how pieces fit together |
+| 14 | Design Decisions | Resolved decisions (with DECIDED labels) and open questions |
+
+**Each section uses:**
+- `<Section title="N. Section Name" description="One-line explanation">` wrapper
+- `<Card>` container with shadow (no borders)
+- Monospace labels (`text-xs font-mono text-zinc-400`) for technical annotations
+- Live interactive demos where applicable (hover, focus, click)
+
+**Page infrastructure:**
+- Dark mode toggle in header
+- `max-w-5xl mx-auto` content width
+- `space-y-20` between sections
+- Helper components: `Section`, `ColorSwatch`, `Card`
+
+**The page should use the user's actual tokens from Step 2** — not placeholder values. Every color swatch, button, and example should reflect their real brand.
+
+Present the generated page to the user:
+
+> Here's your Brand Kit page. It's a living reference — you and Claude can always check `app/design-system/page.tsx` to see your design system in action.
+>
+> Every section is interactive: hover the cards, click the inputs, tab through the buttons.
+
+### Step 5: Wrap Up
+
+Summarize what was accomplished:
+
+> **Done! Here's what we set up:**
+>
+> 1. **Design system directory** — `[path]` configured in `.jettypod/config.json`
+> 2. **CLAUDE.md updated** — Claude now sees your design tokens as context in every conversation
+> 3. **Brand Kit page** — `app/design-system/page.tsx` is your living reference
+>
+> From now on, when Claude builds UI for you, it'll use your exact colors, typography, spacing, and component patterns. No more generic-looking output.
+
+## Clearing
+
+If user wants to remove the design system:
+
+```bash
+node -e "
+const fs = require('fs');
+const configPath = '.jettypod/config.json';
+const config = fs.existsSync(configPath) ? JSON.parse(fs.readFileSync(configPath, 'utf-8')) : {};
+delete config.designSystemDir;
+fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+console.log('Removed designSystemDir');
+"
+```
+
+Then: `jettypod claude generate`

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

@@ -221,6 +221,14 @@ Based on [epic name], here are the features I recommend:
 **Feature 3: [Name]** - [Brief description]
 ...
 
+**UX Completeness Check:**
+For each feature above, I've considered:
+- How users discover/reach it (entry point)
+- What they see while waiting (loading states)
+- What they see when there's no data (empty states)
+- What feedback they get after actions (success/error)
+- How screens transition between states
+
 **Questions:**
 - [Any clarifying questions about scope]
 - [Missing features to consider]
@@ -335,6 +343,12 @@ This creates a worktree at `.jettypod-work/prototype-<id>-<slug>-<approach>/` wh
 
 **Sub-step 2: Build prototypes in the worktree**
 
+**Design system check:** Before building, check if a design system directory is configured:
+```bash
+node -e "const c=JSON.parse(require('fs').readFileSync('.jettypod/config.json','utf-8')); c.designSystemDir && console.log(c.designSystemDir)"
+```
+If a path is returned, read the files in that directory and apply the project's design tokens (colors, typography, spacing, border radii, component patterns) to all prototypes.
+
 1. Build prototypes using **absolute paths** to the worktree:
    - `<worktree_path>/prototypes/epic-${EPIC_ID}-${APPROACH_NAME}/`
 2. Build 2-3 working prototypes demonstrating the architectural difference

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

@@ -169,6 +169,12 @@ This creates a worktree at `.jettypod-work/prototype-<id>-<slug>-<approach>/` wh
 
 **Sub-step 2: Build prototypes in the worktree**
 
+**Design system check:** Before building, check if a design system directory is configured:
+```bash
+node -e "const c=JSON.parse(require('fs').readFileSync('.jettypod/config.json','utf-8')); c.designSystemDir && console.log(c.designSystemDir)"
+```
+If a path is returned, read the files in that directory and apply the project's design tokens (colors, typography, spacing, border radii, component patterns) to all prototypes. Prototypes should look like they belong to the product, not use generic browser defaults.
+
 1. **Build prototypes** using **absolute paths** to the worktree:
    - `<worktree_path>/prototypes/feature-[id]-[approach-name]/`
 2. **Name format**: `YYYY-MM-DD-[feature-slug]-[option].ext`
@@ -247,6 +253,59 @@ User picks winner. Note their choice - you'll record it formally in Step 11 when
 jettypod workflow checkpoint <feature-id> --step=5
 ```
 
+**Proceed to Step 5B.**
+
+### Step 5B: UX States Inventory
+
+**CRITICAL:** Before defining scenarios, enumerate every UI state the feature will need. Features fail QA when states like loading, empty, and transition are left unspecified — Claude implements the literal happy path and skips everything else.
+
+**For each screen/view/component the chosen approach touches, list:**
+
+```
+UX States Inventory
+
+**[Screen/View/Component 1: e.g., Login Form]**
+| State | What the user sees |
+|-------|-------------------|
+| Default | [Initial state when user arrives] |
+| Loading | [What shows during async operations — spinner, skeleton, disabled button, etc.] |
+| Success | [Feedback after successful action — toast, redirect, animation, message] |
+| Empty | [What shows when there's no data — illustration, CTA, placeholder text] |
+| Partial | [What shows when some data is loaded but not all — progressive loading] |
+
+**[Screen/View/Component 2: e.g., Dashboard after login]**
+| State | What the user sees |
+|-------|-------------------|
+| Default | [...] |
+| Loading | [...] |
+| ... | ... |
+
+**Micro-interactions:**
+- [Button click] → [immediate visual feedback: disable + spinner? ripple? color change?]
+- [Form submission] → [what happens between click and response?]
+- [Data appears] → [instant swap? fade in? skeleton → content?]
+- [Navigation] → [instant page swap? transition animation?]
+```
+
+**What to inventory (checklist):**
+- [ ] Every screen/view the feature adds or modifies
+- [ ] Loading states for every async operation (API calls, file uploads, data fetches)
+- [ ] Success feedback for every user action (toasts, redirects, inline messages)
+- [ ] Empty states where data might not exist yet
+- [ ] Transition animations between states
+- [ ] Button/input states (default, hover, active, disabled, loading)
+- [ ] What happens between user action and system response (micro-interactions)
+
+**Display the inventory to user and ask:**
+
+```
+Does this cover all the states? Anything missing for how this should feel?
+```
+
+**WAIT for user confirmation or additions.**
+
+Store the confirmed UX States Inventory — it feeds into BDD scenarios (Step 8) and chore UX acceptance criteria (Step 10).
+
 **Proceed to Step 6.**
 
 ### Step 6: Define Integration Contract
@@ -435,6 +494,11 @@ Does this capture the feature correctly? Any scenarios to add/change?
   - NO error handling scenarios (added in stable mode)
   - NO validation failures (added in stable mode)
   - NO security/compliance scenarios (added in production mode)
+- **Incorporate UX states from Step 5B** into scenario Then/And steps:
+  - Loading indicators: "And I see a loading indicator while [action] completes"
+  - Success feedback: "And I see a success confirmation"
+  - Empty states: "Then I see an empty state with [description]"
+  - Transitions: "And the [content] appears with [transition description]"
 
 **WAIT for user confirmation.**
 
@@ -702,6 +766,11 @@ Based on the scenario and my understanding of the codebase, here are the chores
   • Files to create/modify: [specific paths]
   • Patterns to follow: [reference existing similar code]
   • Key functions/components needed: [list]
+- UX acceptance criteria (from Step 5B):
+  • [Loading state: what shows during async operations in this chore's scope]
+  • [Success feedback: what the user sees after the action completes]
+  • [Empty state: what shows when there's no data, if applicable]
+  • [Micro-interactions: button states, transitions, visual feedback]
 - Verification:
   • [Which step definitions should pass]
 
@@ -760,7 +829,7 @@ jettypod work create --from=/tmp/jettypod-create.json
 
 Replace `${FEATURE_ID}` with actual ID. Example: Write `{"type":"chore","title":"Set up auth routes","description":"Create login/logout endpoints...","parent":42}` to `/tmp/jettypod-create.json`, then run `jettypod work create --from=/tmp/jettypod-create.json`.
 
-**CRITICAL: Copy the EXACT proposal from Step 10 into each chore description.** Do not paraphrase or summarize - the implementation guidance must be preserved verbatim:
+**CRITICAL: Copy the EXACT proposal from Step 10 into each chore description.** Do not paraphrase or summarize - the implementation guidance AND UX acceptance criteria must be preserved verbatim:
 
 ```
 [Technical description from Step 10]
@@ -773,6 +842,9 @@ Implementation guidance:
 • Patterns to follow: [EXACT references from Step 10]
 • Key functions/components needed: [EXACT list from Step 10]
 
+UX acceptance criteria:
+• [EXACT UX criteria from Step 10 — loading states, success feedback, empty states, micro-interactions]
+
 Verification:
 • [EXACT step definitions from Step 10]
 ```
@@ -827,6 +899,8 @@ The BDD files were written in Step 9. Now merge them to main.
 jettypod work tests merge ${FEATURE_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 <main-repo-path>
@@ -968,6 +1042,20 @@ If you skip `work start` or proceed when worktree creation failed, the merge wor
 
 **User picks:** Option 1 (Simple inline form)
 
+**UX States Inventory:**
+
+| State | Login Form | Dashboard (after login) |
+|-------|-----------|----------------------|
+| Default | Email + password fields, "Sign In" button | N/A (redirected here) |
+| Loading | Button shows spinner, fields disabled | Skeleton cards for activity |
+| Success | Brief checkmark animation, then redirect | Full dashboard with welcome toast |
+| Empty | N/A | "No recent activity" with illustration |
+
+**Micro-interactions:**
+- Sign In click → button disabled + spinner → redirect on success
+- "Remember me" checkbox → toggle animation
+- Page transition → fade/slide to dashboard
+
 **Scenarios generated (speed mode - all success paths):**
 ```gherkin
 Feature: Email/Password Login
@@ -1002,6 +1090,7 @@ Before completing feature planning, ensure:
 - [ ] Epic's architectural decision is shown (if exists)
 - [ ] Exactly 3 approaches suggested
 - [ ] Winner chosen (with prototypes or without)
+- [ ] **UX States Inventory completed** (all screens/states/micro-interactions enumerated, confirmed by user)
 - [ ] **Integration Contract defined** (entry point, caller code, integration scenario)
 - [ ] **Test worktree created** with `work tests start` (Step 7)
 - [ ] **Integration Scenario is FIRST scenario** in proposed scenarios

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

@@ -444,6 +444,26 @@ Once all production chores complete:
 2. Can be deployed to external environment
 3. Meets all standards for scale, security, compliance
 
+**Prove It Works (REQUIRED):**
+
+Before completing the feature, demonstrate it works in practice — not just that tests pass.
+
+1. **Run or build the actual code** — compile, start the server, execute the command, or trigger the relevant workflow
+2. **Show real output** — display console output, build result, or observable behavior
+3. **Confirm it matches expectations** — verify the output is what was requested
+
+**Display:**
+
+```
+Verifying in practice...
+
+[Actual output from running/building the code]
+
+Verified: [what was confirmed]
+```
+
+**If the change cannot be run directly** (requires hardware, external service, or manual UI interaction), state what the user should verify manually and why you can't verify it yourself.
+
 **WORKFLOW INTEGRATION: Complete workflow**
 
 When all production chores are complete:

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

@@ -281,6 +281,26 @@ Verifying...
 
 **If verification passes:**
 
+**Prove It Works (REQUIRED):**
+
+Before committing, demonstrate the change works in practice.
+
+1. **Run or build the actual code** — compile, start the server, execute the command, or trigger the relevant workflow
+2. **Show real output** — display console output, build result, or observable behavior
+3. **Confirm it matches expectations** — verify the output is what was requested
+
+**Display:**
+
+```
+Verifying in practice...
+
+[Actual output from running/building the code]
+
+Verified: [what was confirmed]
+```
+
+**If the change cannot be run directly** (requires hardware, external service, or manual UI interaction), state what the user should verify manually and why you can't verify it yourself.
+
 **WORKTREE PATH REQUIRED:** Use the `WORKTREE_PATH` captured in Step 3.
 
 ```bash
@@ -309,9 +329,11 @@ jettypod work merge <chore-id>
 jettypod work cleanup <chore-id>
 ```
 
-**If merge fails:**
+**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.
+
+**If merge fails with merge conflicts:**
 
-When `jettypod work merge` encounters an error (e.g., merge conflicts), the worktree is preserved for debugging.
+When `jettypod work merge` encounters a merge conflict, the worktree is preserved for debugging.
 
 ```
 Merge failed: [error message from git]
@@ -340,6 +362,21 @@ Do NOT attempt to auto-resolve conflicts - let the user handle them manually.
 **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.
 
+**Generate QA checklist:**
+
+Based on the change you just made, generate specific QA steps a tester can verify manually. Write a JSON array to `/tmp/qa-steps.json`:
+```json
+[
+  {"section": "Section Name", "text": "Action to perform and expected result", "detail": "Additional context"},
+  ...
+]
+```
+Be specific (e.g., "Click the Save button — confirmation toast appears") not generic. 3-8 steps for simple improvements.
+
+```bash
+jettypod work set-qa-steps <chore-id> --from=/tmp/qa-steps.json
+```
+
 **Emit gate signal:**
 
 ```bash

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

@@ -350,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`.
 
@@ -376,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]
 
@@ -732,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
@@ -819,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
@@ -1036,16 +1042,6 @@ jettypod work create --from=/tmp/jettypod-create.json
 
 Repeat for each confirmed chore. **Do NOT add a `mode` field** - chores inherit mode from their parent feature.
 
-**3. Release merge lock (CRITICAL: separate Bash calls):**
-
-```bash
-cd <main-repo>                           # Bash call 1
-```
-
-```bash
-jettypod work merge <last-chore-id> --release-lock   # Bash call 2
-```
-
 **WORKFLOW COMPLETE: Speed mode finished**
 
 Mark speed mode as complete (this passes the `speed_mode_complete` gate, enabling stable-mode):
@@ -1156,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:**

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

@@ -687,6 +687,8 @@ git add . && git commit -m "feat: [brief description of error handling added]"
 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,6 +743,31 @@ pwd && ls .jettypod  # verify
 jettypod work cleanup [current-chore-id]
 ```
 
+**Then generate QA checklist for the parent feature:**
+
+Read the BDD scenario file for the parent feature. Based on the scenarios and your knowledge of what was implemented, generate specific, human-actionable QA checklist steps. Each step should be something a QA tester can verify manually in the running app.
+
+Write a JSON array to `/tmp/qa-steps.json`:
+```json
+[
+  {"section": "Section Name", "text": "Action to perform and expected result", "detail": "Additional context if needed"},
+  ...
+]
+```
+
+Guidelines for good QA steps:
+- Be specific: "Open Settings, click Claude Code section" not "Navigate to the feature"
+- Include expected outcomes: "dropdown shows Haiku as selected" not "model is selected"
+- One verifiable action per step
+- Group into sections (e.g., "Model Selection", "Persistence", "Error Handling")
+- Cover happy paths AND edge cases from the BDD scenarios
+- 5-15 steps total (not too few to be useless, not too many to be tedious)
+
+Then store them:
+```bash
+jettypod work set-qa-steps [parent-feature-id] --from=/tmp/qa-steps.json
+```
+
 **Then check project state:**
 
 ```bash
@@ -753,6 +780,26 @@ sqlite3 .jettypod/work.db "SELECT project_state FROM project_config WHERE id = 1
 
 **If project_state = 'internal':**
 
+**Prove It Works (REQUIRED):**
+
+Before marking the feature complete, demonstrate it works in practice — not just that tests pass.
+
+1. **Run or build the actual code** — compile, start the server, execute the command, or trigger the relevant workflow
+2. **Show real output** — display console output, build result, or observable behavior
+3. **Confirm it matches expectations** — verify the output is what was requested
+
+**Display:**
+
+```
+Verifying in practice...
+
+[Actual output from running/building the code]
+
+Verified: [what was confirmed]
+```
+
+**If the change cannot be run directly** (requires hardware, external service, or manual UI interaction), state what the user should verify manually and why you can't verify it yourself.
+
 **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.