jettypod 4.3.0 → 4.4.1

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

@@ -11,21 +11,6 @@ Guides Claude through feature planning including UX approach exploration, option
 
 When this skill is activated, you are helping discover the best approach for a feature. Follow this structured approach:
 
-## 🔑 Critical Command Distinction
-
-**Two different commands, two different purposes:**
-
-| Command | Used For | When | Phase |
-|---------|----------|------|-------|
-| `work implement <feature-id>` | Transition feature to implementation phase | During feature planning (Step 8B) | Feature Planning |
-| `work start <chore-id>` | Start implementing a specific chore | After feature planning complete (Step 8D) | Speed Mode |
-
-**CRITICAL:** Both commands are run by **Claude**, not the user. The distinction is:
-- `work implement` = Ends feature planning, creates chores
-- `work start` = Begins implementing a chore (triggers speed-mode skill)
-
----
-
 ### Step 1: Understand the Feature Context
 
 You'll receive context about:
@@ -111,42 +96,15 @@ If user wants prototypes:
 1. **Build prototypes** in `/prototypes/feature-[id]-[approach-name]/`
 2. **Name format**: `YYYY-MM-DD-[feature-slug]-[option].ext`
 3. **Focus on UX**: Show the feel, not production code
-4. **Add visible banner header at TOP of page** (for HTML/web prototypes):
-   ```html
-   <div style="background: #f0f0f0; border: 2px solid #333; padding: 16px; margin-bottom: 24px; font-family: monospace;">
-     <strong>🧪 PROTOTYPE</strong><br>
-     Feature: [feature name]<br>
-     Option: [option number/name]<br>
-     Created: [YYYY-MM-DD]<br>
-     Purpose: [what this explores]<br>
-     Decision: [to be filled after testing]
-   </div>
+4. **Add prototype header**:
+   ```
+   // Prototype: [feature] - [option]
+   // Created: [date]
+   // Purpose: [what this explores]
+   // Decision: [to be filled after testing]
    ```
-   For CLI/terminal prototypes, add similar info as first output.
 5. **Offer to open them**: "Want me to open these in your browser?"
 
-<details>
-<summary><strong>📋 Prototyping Guidelines (click to expand)</strong></summary>
-
-**Use fastest tech to demonstrate UX:**
-- Quick HTML+JS for web UX
-- Simple CLI scripts for command-line UX
-- Minimal frameworks, maximum clarity
-
-**What to prototype:**
-- User interaction flow
-- Visual layout (if UI)
-- Command structure (if CLI)
-- API shape (if API)
-
-**What NOT to prototype:**
-- Production error handling
-- Database layer
-- Authentication (unless that's the feature)
-- Test coverage
-
-</details>
-
 ### Step 5: Choose Winner
 
 After user tests (or skips prototyping):
@@ -166,12 +124,10 @@ Based on chosen approach, generate:
 **A. Scenario file** at `features/[feature-slug].feature` using Write tool:
 
 1. **Create file** at `features/[feature-slug].feature` using Write tool
-2. **Include all "make it work" scenarios**:
-   - All success paths - required functionality AND optional features
-   - Multiple valid workflows if the feature supports them
-   - Success variations (different outcomes that are all correct)
+2. **ONLY include happy path scenario**:
+   - Happy path ONLY - the core user journey that proves it works
    - NO error handling scenarios (added in stable mode)
-   - NO validation failures (added in stable mode)
+   - NO edge cases (added in stable mode)
    - NO security/compliance scenarios (added in production mode)
 
 **B. Step definitions file** at `features/step_definitions/[feature-slug].steps.js` using Write tool:
@@ -191,7 +147,7 @@ Based on chosen approach, generate:
    sqlite3 .jettypod/work.db "UPDATE work_items SET scenario_file = 'features/[feature-slug].feature' WHERE id = <feature-id>"
    ```
 
-**Template for speed mode (make it work):**
+**Template for speed mode (happy path only):**
 
 ```gherkin
 Feature: [Feature Name]
@@ -200,20 +156,15 @@ Feature: [Feature Name]
   Epic: [Epic name if applicable]
   Approach: [Chosen approach name]
 
-Scenario: [Core functionality - required workflow]
+Scenario: [Happy path scenario - core user journey]
   Given [initial state]
   When [user takes main action]
   Then [expected successful outcome]
   And [observable UI/system state change]
 
-Scenario: [Optional feature 1 - if applicable]
-  Given [initial state]
-  When [user uses optional feature]
-  Then [feature works correctly]
-
-# SPEED MODE: All success scenarios above (required + optional functionality)
-# STABLE MODE: Will add error handling, validation failures, edge cases
-# These failure scenarios are added by stable-mode skill, NOT during feature discovery
+# SPEED MODE: Only happy path above
+# STABLE MODE: Will add error handling, edge cases, validation scenarios
+# These additional scenarios are added by stable-mode skill, NOT during feature discovery
 ```
 
 **Example for Login feature (speed mode):**
@@ -231,66 +182,8 @@ Scenario: User successfully logs in with valid credentials
   Then I am redirected to the dashboard
   And I see a welcome message with my name
   And I have an active session token
-
-Scenario: User logs in with "Remember me" option (optional feature)
-  Given I am on the login page
-  When I enter valid credentials
-  And I check the "Remember me" checkbox
-  And I click the login button
-  Then I am redirected to the dashboard
-  And my session persists for 30 days
-```
-
-<details>
-<summary><strong>📋 BDD Scenario Guidelines (click to expand)</strong></summary>
-
-**Scenario naming:**
-- Use present tense
-- Be specific about what's being tested
-- Focus on user behavior
-
-**Given/When/Then structure:**
-- **Given**: Set up initial state
-- **When**: User action
-- **Then**: Observable outcome
-
-**What feature planning creates:**
-
-Feature planning creates speed mode scenarios (make it work - all success paths):
-```gherkin
-Scenario: User successfully [does the required thing]
-  Given [setup]
-  When [action]
-  Then [success]
-
-Scenario: User successfully [uses optional feature]
-  Given [setup]
-  When [uses optional capability]
-  Then [feature works correctly]
-```
-
-**Additional scenarios are added LATER by stable-mode skill:**
-
-Stable mode adds error handling and validation:
-```gherkin
-Scenario: Handle invalid input
-  Given [setup]
-  When [invalid action]
-  Then [appropriate error]
 ```
 
-Production mode adds security/scale/compliance:
-```gherkin
-Scenario: Prevent unauthorized access
-  Given [unauthorized user]
-  When [attempts action]
-  Then [access denied with proper error]
-```
-
-**IMPORTANT:** Feature planning creates all success scenarios (required + optional). Stable/production chores add failure scenarios later.
-
-</details>
-
 ### Step 6.5: Validate BDD Infrastructure
 
 **CRITICAL:** After creating both scenario and step definition files, automatically validate them with cucumber dry-run to catch errors immediately.
@@ -343,7 +236,7 @@ console.log(''); // Extra line before continuing
 
 The speed-mode skill guides Claude to:
 1. Implement the feature code
-2. Create corresponding unit tests for all success scenarios
+2. Create corresponding unit tests for the happy path
 3. Ensure tests pass before completing the chore
 
 This keeps feature planning focused on BDD scenarios (what users experience) while speed mode handles unit tests (implementation details).
@@ -353,7 +246,7 @@ This keeps feature planning focused on BDD scenarios (what users experience) whi
 **CRITICAL:** After BDD validation passes, analyze the codebase and propose technical implementation chores. **DO NOT CREATE CHORES YET** - the feature must transition to implementation mode first (Step 8).
 
 **Your analysis should consider:**
-- The BDD scenarios (all success paths - required + optional features)
+- The BDD scenarios (especially the happy path)
 - Existing codebase structure and patterns
 - Epic's architectural decisions (if any)
 - Tech stack and framework conventions
@@ -393,7 +286,7 @@ Based on the scenario and my understanding of the codebase, here are the chores
 
 [etc.]
 
-These chores will make all success scenarios pass (required + optional features).
+These chores will make the happy path scenario pass.
 
 Sound good? Any adjustments?
 ```
@@ -438,11 +331,16 @@ node jettypod.js work implement [feature-id] \
 
 **CRITICAL: NOW create the chores.** The feature has transitioned to implementation mode, so chore creation will succeed.
 
-For each chore that the user confirmed in Step 7, use the Bash tool to create it:
+**IMPORTANT:** You MUST pass `--parent=<FEATURE_ID>` with the actual numeric feature ID. Without this, chores won't be linked to the feature.
+
+For each chore that the user confirmed in Step 7, use the Bash tool to create it. Replace `<FEATURE_ID>` with the actual feature ID number:
 
 ```bash
-# Use Bash tool to execute for each chore:
-node jettypod.js work create chore "[Chore title]" "[Chore description with all the implementation guidance]" --parent=[feature-id]
+# CORRECT - uses actual numeric feature ID:
+node jettypod.js work create chore "Implement cursor position broadcast" "Broadcast cursor positions..." --parent=12
+
+# WRONG - missing parent flag (chore won't be linked to feature):
+node jettypod.js work create chore "Implement cursor position broadcast" "Broadcast cursor positions..."
 ```
 
 **Build the description from your Step 7 proposal:**
@@ -469,7 +367,7 @@ After creating all chores, display:
 ✅ Created X chores for speed mode
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-🎯 Feature Planning Complete!
+🎯 Feature Discovery Complete!
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 📋 BDD scenarios: features/[feature-slug].feature
@@ -480,30 +378,97 @@ After creating all chores, display:
 Ready to start implementation?
 ```
 
-#### Step 8D: Start First Chore
+#### Step 8D: Transition to Speed Mode
 
-**Feature planning is now complete.** The feature has been transitioned to implementation phase and chores are ready.
+**WAIT for user confirmation.**
 
-**Ask user which chore to start with:**
+When user confirms they want to proceed with implementation (responds with "yes", "let's go", "proceed", "start", or similar):
+
+**IMMEDIATELY invoke the speed-mode skill using the Skill tool:**
 
 ```
-Ready to start implementation? Which chore should we start with?
+Use the Skill tool with skill: "speed-mode"
 ```
 
-**After user picks a chore, use Bash tool to run:**
+**The speed-mode skill will then:**
+1. Guide the user to start the first chore with `jettypod work start [chore-id]`
+2. Create a worktree for the chore
+3. Follow TDD workflow to implement the chore
+4. Merge when complete
 
-```bash
-jettypod work start [chore-id]
+**End feature-planning skill after invoking speed-mode.**
+
+## Key Principles
+
+1. **Always suggest exactly 3 options** - Simple, Balanced, Advanced
+2. **Show epic's architectural decision** - Feature should align with epic's technical approach
+3. **UX first, tech second** - Focus on what it feels like to use, not implementation details
+4. **Prototypes are optional but valuable** - User can skip if approach is obvious
+5. **BDD scenarios are required** - Discovery isn't complete without scenarios
+6. **Guide to next step** - Always end with clear action
+
+## Prototyping Guidelines
+
+**Use fastest tech to demonstrate UX:**
+- Quick HTML+JS for web UX
+- Simple CLI scripts for command-line UX
+- Minimal frameworks, maximum clarity
+
+**What to prototype:**
+- User interaction flow
+- Visual layout (if UI)
+- Command structure (if CLI)
+- API shape (if API)
+
+**What NOT to prototype:**
+- Production error handling
+- Database layer
+- Authentication (unless that's the feature)
+- Test coverage
+
+## BDD Scenario Guidelines
+
+**Scenario naming:**
+- Use present tense
+- Be specific about what's being tested
+- Focus on user behavior
+
+**Given/When/Then structure:**
+- **Given**: Set up initial state
+- **When**: User action
+- **Then**: Observable outcome
+
+**What feature-discover creates:**
+
+**Feature discovery ONLY creates speed mode scenarios (happy path):**
+```gherkin
+Scenario: User successfully [does the thing]
+  Given [setup]
+  When [action]
+  Then [success]
+```
+
+**Additional scenarios are added LATER by stable-mode skill:**
+
+Stable mode adds error handling:
+```gherkin
+Scenario: Handle invalid input
+  Given [setup]
+  When [invalid action]
+  Then [appropriate error]
 ```
 
-**This command will:**
-1. Create a git worktree and branch for the chore
-2. Automatically invoke the speed-mode skill
-3. Begin TDD implementation workflow in the isolated worktree
+Production mode adds security/scale/compliance:
+```gherkin
+Scenario: Prevent unauthorized access
+  Given [unauthorized user]
+  When [attempts action]
+  Then [access denied with proper error]
+```
 
-**The speed-mode skill takes over from here and handles the implementation.**
+**IMPORTANT:** Feature discovery only creates happy path. Stable/production chores add more scenarios later.
 
-## Example: Feature Planning Flow
+## Example: Feature Discovery Flow
 
 **Feature:** "Email/password login"
 **Epic decision:** "Using Auth.js with JWT tokens"
@@ -515,25 +480,17 @@ jettypod work start [chore-id]
 
 **User picks:** Option 1 (Simple inline form)
 
-**Scenarios generated (speed mode - all success paths):**
+**Scenarios generated (happy path only for speed mode):**
 ```gherkin
 Feature: Email/Password Login
 
-Scenario: Successful login with credentials
+Scenario: Successful login
   Given I am on the login page
   When I enter valid credentials and submit
   Then I am redirected to the dashboard
   And I have an active JWT token
 
-Scenario: Login with "Remember me" option
-  Given I am on the login page
-  When I enter valid credentials
-  And I check "Remember me"
-  And I submit
-  Then I am redirected to the dashboard
-  And my session persists for 30 days
-
-# SPEED MODE: All success scenarios above (required + optional features)
+# SPEED MODE: Only happy path above
 # STABLE MODE: Will add error handling scenarios like "Invalid credentials"
 ```
 
@@ -543,17 +500,15 @@ User confirms: "Yes, perfect"
 
 **Transition:** `jettypod work implement 10 --winner="prototypes/2025-10-30-login-simple.html" --rationale="Simple inline form chosen - fastest for users, cleanest UX"`
 
-## Validation Checklist
+## Validation
 
-Before completing feature planning, ensure:
+Before completing feature discovery, ensure:
 - [ ] Epic's architectural decision is shown (if exists)
 - [ ] Exactly 3 approaches suggested
 - [ ] Winner chosen (with prototypes or without)
-- [ ] BDD scenarios written (all success paths)
+- [ ] BDD scenarios written
 - [ ] Step definitions written for ALL scenario steps
 - [ ] Scenarios file exists at `features/[feature-slug].feature`
 - [ ] Step definitions file exists at `features/step_definitions/[feature-slug].steps.js`
 - [ ] BDD infrastructure validated with dry-run (Step 6.5)
-- [ ] Feature transitioned to implementation with `work implement`
-- [ ] Speed mode chores created
-- [ ] First chore started with `work start [chore-id]` (Step 8D)
+- [ ] User knows next step .jettypod work start [feature-id])

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

@@ -39,8 +39,8 @@ When this skill is activated, you are helping implement a production mode chore
 **To detect context, check these conditions:**
 
 ```bash
-# Get current work item and parent feature
-sqlite3 .jettypod/work.db "SELECT wi.id, wi.title, wi.type, wi.parent_id, wi.epic_id, parent.title as parent_title FROM work_items wi LEFT JOIN work_items parent ON wi.parent_id = parent.id WHERE wi.status = 'in_progress'"
+# Get current work and parent feature
+jettypod work current
 
 # Check for production scenarios in the feature file
 # (Look for scenarios tagged with @production or containing production-related keywords)
@@ -230,8 +230,11 @@ This will:
 **Get current work and identify target scenario:**
 
 ```bash
-# Get current chore details and parent feature's scenario file
-sqlite3 .jettypod/work.db "SELECT wi.id, wi.title, wi.description, 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'"
+# Get current chore details
+jettypod work current
+
+# Get parent feature's scenario file
+sqlite3 .jettypod/work.db "SELECT scenario_file FROM work_items WHERE id = <parent-feature-id>"
 ```
 
 Parse the chore description to find which scenario it addresses (look for "Scenario: ..." in the description).