jettypod 4.4.0 → 4.4.2

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

@@ -11,6 +11,21 @@ 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:
@@ -96,15 +111,42 @@ 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 prototype header**:
-   ```
-   // Prototype: [feature] - [option]
-   // Created: [date]
-   // Purpose: [what this explores]
-   // Decision: [to be filled after testing]
+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>
    ```
+   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):
@@ -124,10 +166,12 @@ 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. **ONLY include happy path scenario**:
-   - Happy path ONLY - the core user journey that proves it works
+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)
    - NO error handling scenarios (added in stable mode)
-   - NO edge cases (added in stable mode)
+   - NO validation failures (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:
@@ -147,7 +191,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 (happy path only):**
+**Template for speed mode (make it work):**
 
 ```gherkin
 Feature: [Feature Name]
@@ -156,15 +200,20 @@ Feature: [Feature Name]
   Epic: [Epic name if applicable]
   Approach: [Chosen approach name]
 
-Scenario: [Happy path scenario - core user journey]
+Scenario: [Core functionality - required workflow]
   Given [initial state]
   When [user takes main action]
   Then [expected successful outcome]
   And [observable UI/system state change]
 
-# 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
+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
 ```
 
 **Example for Login feature (speed mode):**
@@ -182,8 +231,66 @@ 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.
@@ -236,7 +343,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 the happy path
+2. Create corresponding unit tests for all success scenarios
 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).
@@ -246,7 +353,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 (especially the happy path)
+- The BDD scenarios (all success paths - required + optional features)
 - Existing codebase structure and patterns
 - Epic's architectural decisions (if any)
 - Tech stack and framework conventions
@@ -286,7 +393,7 @@ Based on the scenario and my understanding of the codebase, here are the chores
 
 [etc.]
 
-These chores will make the happy path scenario pass.
+These chores will make all success scenarios pass (required + optional features).
 
 Sound good? Any adjustments?
 ```
@@ -362,7 +469,7 @@ After creating all chores, display:
 ✅ Created X chores for speed mode
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-🎯 Feature Discovery Complete!
+🎯 Feature Planning Complete!
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 📋 BDD scenarios: features/[feature-slug].feature
@@ -373,97 +480,30 @@ After creating all chores, display:
 Ready to start implementation?
 ```
 
-#### Step 8D: Transition to Speed Mode
+#### Step 8D: Start First Chore
 
-**WAIT for user confirmation.**
+**Feature planning is now complete.** The feature has been transitioned to implementation phase and chores are ready.
 
-When user confirms they want to proceed with implementation (responds with "yes", "let's go", "proceed", "start", or similar):
+**Ask user which chore to start with:**
 
-**IMMEDIATELY invoke the speed-mode skill using the Skill tool:**
-
-```
-Use the Skill tool with skill: "speed-mode"
 ```
-
-**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
-
-**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]
+Ready to start implementation? Which chore should we start with?
 ```
 
-**Additional scenarios are added LATER by stable-mode skill:**
+**After user picks a chore, use Bash tool to run:**
 
-Stable mode adds error handling:
-```gherkin
-Scenario: Handle invalid input
-  Given [setup]
-  When [invalid action]
-  Then [appropriate error]
+```bash
+jettypod work start [chore-id]
 ```
 
-Production mode adds security/scale/compliance:
-```gherkin
-Scenario: Prevent unauthorized access
-  Given [unauthorized user]
-  When [attempts action]
-  Then [access denied with proper 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
 
-**IMPORTANT:** Feature discovery only creates happy path. Stable/production chores add more scenarios later.
+**The speed-mode skill takes over from here and handles the implementation.**
 
-## Example: Feature Discovery Flow
+## Example: Feature Planning Flow
 
 **Feature:** "Email/password login"
 **Epic decision:** "Using Auth.js with JWT tokens"
@@ -475,17 +515,25 @@ Scenario: Prevent unauthorized access
 
 **User picks:** Option 1 (Simple inline form)
 
-**Scenarios generated (happy path only for speed mode):**
+**Scenarios generated (speed mode - all success paths):**
 ```gherkin
 Feature: Email/Password Login
 
-Scenario: Successful login
+Scenario: Successful login with credentials
   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
 
-# SPEED MODE: Only happy path above
+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)
 # STABLE MODE: Will add error handling scenarios like "Invalid credentials"
 ```
 
@@ -495,15 +543,17 @@ 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
+## Validation Checklist
 
-Before completing feature discovery, ensure:
+Before completing feature planning, ensure:
 - [ ] Epic's architectural decision is shown (if exists)
 - [ ] Exactly 3 approaches suggested
 - [ ] Winner chosen (with prototypes or without)
-- [ ] BDD scenarios written
+- [ ] BDD scenarios written (all success paths)
 - [ ] 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)
-- [ ] User knows next step .jettypod work start [feature-id])
+- [ ] Feature transitioned to implementation with `work implement`
+- [ ] Speed mode chores created
+- [ ] First chore started with `work start [chore-id]` (Step 8D)

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 and parent feature
-jettypod work current
+# 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'"
 
 # Check for production scenarios in the feature file
 # (Look for scenarios tagged with @production or containing production-related keywords)
@@ -230,11 +230,8 @@ This will:
 **Get current work and identify target scenario:**
 
 ```bash
-# 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>"
+# 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'"
 ```
 
 Parse the chore description to find which scenario it addresses (look for "Scenario: ..." in the description).