jettypod 4.4.10 → 4.4.12

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

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