jettypod 4.4.10 → 4.4.11

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

@@ -22,37 +22,50 @@ When this skill is activated, you are helping discover the best approach for a f
 
 **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)
+- `work start` = Creates worktree/branch for chore (does NOT auto-invoke speed-mode)
+
+**🛑 STOP GATE:** DO NOT run `work start` until Step 8D. If you're in Steps 1-8C, use `work implement` only.
+
+**🛑 HANDOFF REQUIREMENT:** After `work start`, you MUST invoke speed-mode using the Skill tool. See Step 8D.
 
 ---
 
-### Step 1: Understand the Feature Context
+### Step 1: Get Feature Context
 
-You'll receive context about:
-- Feature title and description
-- Parent epic (if any)
-- Project context
+**Extract the feature ID from:**
+- Previous message from epic-planning (e.g., "I'll start planning Feature #42")
+- User's request (e.g., "plan feature 42", "help me with feature #42")
 
-### Step 2: Check Epic Architectural Decisions
+**Then run:**
+```bash
+jettypod work show ${FEATURE_ID}
+```
 
-**CRITICAL:** If this feature belongs to an epic, check for existing architectural decisions.
+This returns: title, description, parent epic (if any), mode, phase, and any existing discovery decisions.
 
-**⚠️ IMPORTANT - USE EXACT CODE BELOW:**
-- Import from `./lib/decisions-helpers` (NOT `./features/decisions/index.js`)
-- The function name is `getDecisionsForEpic` (matches the import)
-- Use `await` because it returns a Promise
+**Capture from the output:**
+- `FEATURE_ID` - the feature's ID (shown as `#XX` in output)
+- `FEATURE_TITLE` - the feature's title
+- `PARENT_EPIC_ID` - the parent epic ID from "Parent:" line (may be null for standalone features)
+
+**If the feature is not found**, ask the user to verify the ID or run `jettypod backlog` to find it.
+
+**Proceed to Step 2** (or Step 3 if this is a standalone feature with no parent epic).
+
+### Step 2: Check Epic Architectural Decisions
 
-**Execute this EXACT code (copy/paste as-is):**
+**Skip this step and proceed to Step 3 if `PARENT_EPIC_ID` from Step 1 is null (standalone feature).**
 
-```javascript
-const { getDecisionsForEpic } = require('./lib/decisions-helpers');
+If this feature belongs to an epic, check for existing architectural decisions.
 
-if (parentEpicId) {
-  const epicDecisions = await getDecisionsForEpic(parentEpicId);
-  console.log('Epic decisions:', JSON.stringify(epicDecisions, null, 2));
-}
+**Run this command** (replace `${PARENT_EPIC_ID}` with actual ID):
+
+```bash
+jettypod decisions --epic=${PARENT_EPIC_ID}
 ```
 
+This outputs any architectural decisions recorded for the parent epic. If no decisions exist, it will say so.
+
 Display the context with decisions:
 
 ```
@@ -73,6 +86,8 @@ Let's explore different approaches for this feature [that align with these decis
 
 **IMPORTANT:** When suggesting UX approaches in the next step, ensure they respect/align with the epic's architectural decisions.
 
+**Proceed to Step 3.**
+
 ### Step 3: Suggest 3 UX Approaches
 
 Propose exactly 3 approaches with varying complexity/trade-offs:
@@ -104,6 +119,11 @@ Here are 3 different approaches for [feature name]:
 Would you like me to create working prototypes of these approaches?
 ```
 
+**WAIT for user response.**
+
+- If user wants prototypes → Continue to Step 4
+- If user declines prototypes → Skip to Step 5
+
 ### Step 4: Optional Prototyping
 
 If user wants prototypes:
@@ -125,6 +145,8 @@ If user wants prototypes:
    For CLI/terminal prototypes, add similar info as first output.
 5. **Offer to open them**: "Want me to open these in your browser?"
 
+**WAIT for user to test prototypes.**
+
 <details>
 <summary><strong>📋 Prototyping Guidelines (click to expand)</strong></summary>
 
@@ -155,12 +177,22 @@ After user tests (or skips prototyping):
 Which approach works best?
 ```
 
+**WAIT for user response.**
+
 User picks winner. Note their choice - you'll record it formally in Step 8 when transitioning to implementation.
 
+**Proceed to Step 6.**
+
 ### Step 6: Generate BDD Scenarios AND Step Definitions
 
 **CRITICAL:** BDD scenarios and step definitions must ALWAYS be created together. Never create scenarios without step definitions.
 
+**Feature slug:** Derive `FEATURE_SLUG` from the feature title:
+- Lowercase
+- Replace spaces with hyphens
+- Remove special characters
+- Examples: "Email Password Login" → "email-password-login", "User's Profile (v2)" → "users-profile-v2"
+
 Based on chosen approach, generate:
 
 **A. Scenario file** at `features/[feature-slug].feature` using Write tool:
@@ -185,11 +217,18 @@ Based on chosen approach, generate:
    - All When steps (execute actions)
    - All Then steps (verify outcomes)
 
-3. **Update database** with scenario file path:
-   ```bash
-   # After creating scenario file AND step definitions
-   sqlite3 .jettypod/work.db "UPDATE work_items SET scenario_file = 'features/[feature-slug].feature' WHERE id = <feature-id>"
-   ```
+**C. Update database** with scenario file path (run from project root):
+
+```bash
+sqlite3 .jettypod/work.db "UPDATE work_items SET scenario_file = 'features/${FEATURE_SLUG}.feature' WHERE id = ${FEATURE_ID}"
+```
+
+Replace `${FEATURE_SLUG}` and `${FEATURE_ID}` with actual values. Example:
+```bash
+sqlite3 .jettypod/work.db "UPDATE work_items SET scenario_file = 'features/email-password-login.feature' WHERE id = 42"
+```
+
+**Proceed to Step 6.5.**
 
 **Template for speed mode (make it work):**
 
@@ -293,60 +332,61 @@ Scenario: Prevent unauthorized access
 
 ### 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.
+**CRITICAL:** After creating both scenario and step definition files, validate them with cucumber dry-run to catch errors immediately.
 
-**Execute validation:**
+**Run this command** (replace `${FEATURE_SLUG}` with actual slug):
 
-```javascript
-const { validateBddInfrastructure } = require('../../lib/skills/feature-planning/dry-run-validator');
-const { formatValidationResult } = require('../../lib/skills/feature-planning/validation-formatter');
-const path = require('path');
+```bash
+npx cucumber-js --dry-run features/${FEATURE_SLUG}.feature
+```
 
-console.log('🧪 Validating BDD infrastructure...\n');
+Example:
+```bash
+npx cucumber-js --dry-run features/email-password-login.feature
+```
 
-const featurePath = path.join(process.cwd(), 'features', '[feature-slug].feature');
-const result = await validateBddInfrastructure(featurePath);
+**What the output means:**
 
-// Format and display results with colors and guidance
-const formattedOutput = formatValidationResult(result, featurePath);
-console.log(formattedOutput);
+✅ **Success** - No errors, all steps have definitions:
+```
+0 scenarios
+0 steps
+```
+(Dry-run doesn't execute, so 0 is correct)
 
-if (!result.success) {
-  console.log(''); // Extra line before halting
-  return; // Halt - do not generate chores yet
-}
+❌ **Undefined steps** - Missing step definitions:
+```
+Undefined. Implement with the following snippet:
+  Given('I am on the login page', function () {
+    ...
+  });
+```
+→ Add the missing step definition to your `.steps.js` file
 
-// Continue to Step 7
-console.log(''); // Extra line before continuing
+❌ **Syntax error** - Invalid Gherkin:
 ```
+Parse error in features/foo.feature
+```
+→ Fix the feature file syntax
 
-**Validation checks:**
-- ✅ Feature file has valid Gherkin syntax
-- ✅ All scenario steps have matching step definitions
-- ✅ No duplicate step definitions
-- ✅ Cucumber can parse the files
-- ✅ Validation completes in < 5 seconds
+❌ **Duplicate steps** - Multiple definitions match:
+```
+Multiple step definitions match
+```
+→ Remove or rename one of the duplicate step definitions
 
 **If validation fails:**
-1. Show clear error messages with file locations
-2. Provide actionable guidance on how to fix
-3. DO NOT proceed to chore generation
-4. Wait for user to fix issues
+1. Read the error message carefully
+2. Fix the step definitions or scenario file
+3. Re-run the dry-run command
+4. **Loop until validation passes** - do NOT proceed to Step 7 until green
 
 **If validation succeeds:**
-1. Confirm success with checkmarks
-2. Proceed immediately to Step 6.75
-
-### Step 6.75: Note About Unit Tests
+Display: "✅ BDD infrastructure validated - all steps have definitions"
 
-**Unit tests will be created during speed mode implementation**, not during feature planning.
+**Proceed to Step 7.**
 
-The speed-mode skill guides Claude to:
-1. Implement the feature code
-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).
+**Note:** Unit tests are created during speed mode implementation, not during feature planning. Feature planning focuses on BDD scenarios (user experience); speed mode handles unit tests (implementation details).
 
 ### Step 7: Propose Speed Mode Chores
 
@@ -398,7 +438,11 @@ These chores will make all success scenarios pass (required + optional features)
 Sound good? Any adjustments?
 ```
 
-**Wait for user confirmation/adjustments, then proceed to Step 8.**
+**WAIT for user response.**
+
+- If user confirms → Proceed to Step 8
+- If user requests changes → Revise chore proposals, then WAIT again
+- If user adds/removes chores → Update your list accordingly
 
 ### Step 8: Transition to Implementation
 
@@ -426,14 +470,22 @@ Does this rationale capture why you chose this approach? (You can edit it if nee
 **CRITICAL: After user confirms, use Bash tool to EXECUTE the work implement command:**
 
 ```bash
-# Use Bash tool to execute:
-jettypod work implement [feature-id] \
+jettypod work implement ${FEATURE_ID} \
   --winner="[approach-name or prototypes/winner-file]" \
   --rationale="[user's confirmed/edited rationale]"
 ```
 
+Replace `${FEATURE_ID}` with actual ID. Example:
+```bash
+jettypod work implement 42 --winner="Simple inline form" --rationale="Fastest UX, cleanest implementation"
+```
+
 **DO NOT display this as example text. EXECUTE IT using the Bash tool.**
 
+**If the command fails**, check the error message:
+- "Feature not found" → Verify the feature ID
+- "Already in implementation" → Feature was already transitioned, proceed to Step 8C
+
 #### Step 8C: Create the Chores
 
 **CRITICAL: NOW create the chores.** The feature has transitioned to implementation mode, so chore creation will succeed.
@@ -441,25 +493,33 @@ jettypod work implement [feature-id] \
 For each chore that the user confirmed in Step 7, use the Bash tool to create it:
 
 ```bash
-# Use Bash tool to execute for each chore:
-jettypod work create chore "[Chore title]" "[Chore description with all the implementation guidance]" --parent=[feature-id]
+jettypod work create chore "[Chore title]" "[Chore description]" --parent=${FEATURE_ID}
 ```
 
-**Build the description from your Step 7 proposal:**
+Replace `${FEATURE_ID}` with actual ID. Example:
+```bash
+jettypod work create chore "Set up auth routes" "Create login/logout endpoints..." --parent=42
+```
+
+**If chore creation fails**, check:
+- "Parent not found" → Verify the feature ID
+- "Parent not in implementation phase" → Run Step 8B first
+
+**CRITICAL: Copy the EXACT proposal from Step 7 into each chore description.** Do not paraphrase or summarize - the implementation guidance must be preserved verbatim:
+
 ```
-[Technical description]
+[Technical description from Step 7]
 
 Scenario steps addressed:
-• [Step 1]
-• [Step 2]
+• [EXACT steps from Step 7]
 
 Implementation guidance:
-• Files to create/modify: [paths]
-• Patterns to follow: [references]
-• Key functions/components needed: [list]
+• Files to create/modify: [EXACT paths from Step 7]
+• Patterns to follow: [EXACT references from Step 7]
+• Key functions/components needed: [EXACT list from Step 7]
 
 Verification:
-• [Which step definitions should pass]
+• [EXACT step definitions from Step 7]
 ```
 
 After creating all chores, display:
@@ -477,31 +537,55 @@ After creating all chores, display:
 ✅ Feature phase: Implementation
 🚀 Feature mode: Speed
 
-Ready to start implementation?
+💡 Recommendation: Start with Chore #[first-chore-id] ([chore-title])
+   [Brief reasoning - e.g., "It sets up the foundation the other chores depend on."]
+
+Start this one? [yes / pick different / done for now]
 ```
 
 #### Step 8D: Start First Chore
 
 **Feature planning is now complete.** The feature has been transitioned to implementation phase and chores are ready.
 
-**Ask user which chore to start with:**
+The completion message above already includes your recommendation. Now:
 
-```
-Ready to start implementation? Which chore should we start with?
-```
+**WAIT for user response.**
+
+**If user confirms (says "yes", "let's go", etc.):**
+
+1. Run `jettypod work start [chore-id]` using Bash tool
+2. **Then IMMEDIATELY invoke speed-mode using the Skill tool** (see below)
+
+**If user says "pick different":**
+
+1. List all chores and let them choose
+2. Run `work start` on their choice
+3. **Then IMMEDIATELY invoke speed-mode using the Skill tool** (see below)
 
-**After user picks a chore, use Bash tool to run:**
+**If user says "done for now":**
 
+End feature-planning skill without starting a chore. Do NOT invoke speed-mode.
+
+---
+
+**After user picks a chore, execute these steps IN ORDER:**
+
+**Step 1: Start the chore (creates worktree and branch):**
 ```bash
 jettypod work start [chore-id]
 ```
 
-**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
+**Step 2: State the chore ID clearly in your response:**
+> "I'll start implementing Chore #[id]: [title]"
+
+**Step 3: IMMEDIATELY invoke speed-mode using the Skill tool:**
+```
+Use the Skill tool with skill: "speed-mode"
+```
+
+**🛑 CRITICAL:** You MUST use the Skill tool to invoke speed-mode. The `work start` command only sets up the worktree - it does NOT automatically start the skill. If you skip this step, the user will be left without guidance.
 
-**The speed-mode skill takes over from here and handles the implementation.**
+**Feature-planning skill is now complete.** Speed-mode takes over and handles the implementation.
 
 ## Example: Feature Planning Flow
 
@@ -557,3 +641,4 @@ Before completing feature planning, ensure:
 - [ ] Feature transitioned to implementation with `work implement`
 - [ ] Speed mode chores created
 - [ ] First chore started with `work start [chore-id]` (Step 8D)
+- [ ] **Speed-mode skill invoked using Skill tool** (Step 8D)