jettypod 4.4.9 → 4.4.11

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

@@ -11,30 +11,82 @@ Guides Claude through comprehensive epic planning including feature identificati
 
 When this skill is activated, you are helping plan an epic. Follow this structured approach:
 
-### Step 1: Understand the Epic
+### Step 1: Determine Entry Point
 
-You'll receive context about the epic being planned. Review:
-- Epic title and description
-- Project context
-- Any parent context
+**Check how this skill was triggered:**
 
-### Step 2: Check Existing Features and Decisions
+---
 
-**CRITICAL:** Before suggesting features or approaches, check what already exists:
+**Scenario A: Epic ID provided** (e.g., "plan epic #5", "help me with epic 42")
 
-**Check for existing features:**
+Run this command to get epic context:
 ```bash
-jettypod backlog | grep -A 20 "Epic Name"
+jettypod work status ${EPIC_ID}
+```
+
+Capture the title, description, and any existing context. Proceed to Step 2.
+
+---
+
+**Scenario B: Just an idea** (e.g., "I want to add real-time collab", "plan an epic for auth")
+
+User has only provided a sentence or vague concept. **DO NOT suggest features yet.**
+
+Gather context first. Ask 2-4 of the most relevant questions from:
+
 ```
+I'd like to understand this epic better before suggesting features.
 
-If features already exist, acknowledge them and skip to Step 4 (Architectural Decision).
+**User Experience:**
+- What does the user journey look like? (How do users discover/use this?)
+- What's the "aha moment" - when does the user feel value?
+
+**Problem & Users:**
+- What problem does this solve? (pain point or business need)
+- Who are the primary users? (personas or roles)
+
+**Scope & Constraints:**
+- What's the scope? (MVP vs full vision)
+- Any technical constraints? (must integrate with X, existing patterns to follow)
+```
 
-**Check for existing decisions:**
+**WAIT for user answers.**
+
+Then synthesize into an epic title + description and create:
 ```bash
-node -e "const { showDecisionsForEpic } = require('./features/decisions/index.js'); showDecisionsForEpic(epicId)"
+jettypod work create epic "${EPIC_TITLE}" "${EPIC_DESCRIPTION}"
 ```
 
-If decisions exist, present them to the user:
+Capture the new epic ID from output. Proceed to Step 3 (skip Step 2 since nothing exists yet).
+
+### Step 2: Check Existing State
+
+**CRITICAL:** Before suggesting anything, check what already exists. Run BOTH commands using the epic ID from Step 1:
+
+```bash
+jettypod decisions --epic=${EPIC_ID}
+jettypod work children ${EPIC_ID}
+```
+
+**Example** (if epic ID is 5):
+```bash
+jettypod decisions --epic=5
+jettypod work children 5
+```
+
+Based on results, follow the appropriate path:
+
+---
+
+**Path A: Nothing exists (no decisions AND no features)**
+
+Fresh start. Proceed to Step 3 (Brainstorm Features).
+
+---
+
+**Path B: Decisions exist but NO features**
+
+Previous planning was started but not completed. Present existing decisions:
 
 ```
 🎯 **Existing Architectural Decisions for This Epic:**
@@ -42,20 +94,38 @@ If decisions exist, present them to the user:
 [For each decision:]
 - **[Aspect]:** [Decision]
   *Rationale:* [Why this was chosen]
-  *Decided:* [Date]
 
-These decisions were made previously. Before we continue:
-1. Do these decisions still apply?
-2. Should we revisit any of them?
-3. Are there additional aspects we need to decide?
+These decisions were made previously. I'll use them to guide feature suggestions.
+Do these still apply, or should we revisit any?
+```
+
+**WAIT for confirmation**, then proceed to Step 3 (Brainstorm Features) using these decisions as context.
+
+---
+
+**Path C: Features exist (with or without decisions)**
+
+Planning was previously completed or partially completed. Present what exists:
+
 ```
+🎯 **This epic already has children:**
 
-Only proceed with suggesting new architectural options if:
-- No decisions exist yet, OR
-- User confirms decisions need to be revisited, OR
-- User identifies new aspects to decide
+[List features/chores from children command]
+
+**Options:**
+1. **Add more** - Brainstorm additional features
+2. **Continue planning** - Start feature-planning for one of these
+3. **Review decisions** - Check/update architectural decisions
+
+What would you like to do?
+```
 
-### Step 3: Brainstorm Features (Skip if Features Already Exist)
+**Route based on response:**
+- "Add more" → Step 3 (Brainstorm Features)
+- "Continue planning" → Step 7B (skip 7A since you already have the children list)
+- "Review decisions" → Step 4 (Architectural Decision)
+
+### Step 3: Brainstorm Features
 
 Based on the epic's purpose, suggest features that belong in this epic:
 
@@ -76,185 +146,184 @@ Based on [epic name], here are the features I recommend:
 What features should we include? What am I missing?
 ```
 
-### Step 4: Architectural Decision (Optional)
-
-After features are defined, ask if this epic needs a shared technical approach:
-
-```
-**Architectural question:** Does this epic need a shared technical decision?
-
-For example:
-- Which library/framework for this capability?
-- What data structure or protocol?
-- What architectural pattern?
-
-Examples where architectural decisions matter:
-- Real-time features: WebSockets vs SSE vs polling?
-- Auth system: Which auth library and token strategy?
-- Data sync: Optimistic vs pessimistic locking?
-
-Should we explore different architectural approaches?
-```
-
-### Step 5A: If Architectural Decision Needed
-
-If the epic needs architectural decision, suggest exactly 3 approaches:
-
-```
-Here are 3 different architectural approaches for [epic name]:
-
-**Option 1: [Simple/Conservative approach name]**
-- **Pros**: ✅ [2-3 advantages - proven, reliable, fast to implement]
-- **Cons**: ❌ [2-3 trade-offs - limitations, constraints]
-- **Technical Impact**: [How this affects the features in this epic]
-
-**Option 2: [Balanced approach name]**
-- **Pros**: ✅ [2-3 advantages - good balance]
-- **Cons**: ❌ [2-3 trade-offs]
-- **Technical Impact**: [How this affects the features in this epic]
-
-**Option 3: [Advanced/Modern approach name]**
-- **Pros**: ✅ [2-3 advantages - powerful, flexible]
-- **Cons**: ❌ [2-3 trade-offs - complexity, learning curve]
-- **Technical Impact**: [How this affects the features in this epic]
+**WAIT for user response.**
 
-**Additional approaches considered but not recommended:**
-- *[Alternative 1]*: [Brief] - Not selected because [reason]
-- *[Alternative 2]*: [Brief] - Not selected because [reason]
+When user confirms features (says "looks good", "yes", lists modifications, etc.), finalize the feature list and proceed to Step 4.
 
-Would you like me to create working prototypes of these architectural approaches?
-```
+### Step 4: Architectural Decision (Optional)
 
-### Step 5B: If Prototyping Needed
+After features are defined, ask if this epic needs a shared technical approach.
+
+**Say to user:**
+> **Architectural question:** Does this epic need a shared technical decision?
+>
+> For example:
+> - Which library/framework for this capability?
+> - What data structure or protocol?
+> - What architectural pattern?
+>
+> Examples where architectural decisions matter:
+> - Real-time features: WebSockets vs SSE vs polling?
+> - Auth system: Which auth library and token strategy?
+> - Data sync: Optimistic vs pessimistic locking?
+>
+> Should we explore different architectural approaches?
+
+**Track the response:**
+- If user says YES → Go to Step 5A
+- If user says NO or "already know" → Go to Step 5C
+- If unclear → Ask for clarification
+
+### Step 5A: Present Architectural Options
+
+Present exactly 3 approaches. Fill in the bracketed parts with actual content based on the epic:
+
+**Say to user:**
+> Here are 3 different architectural approaches for **[fill in epic title]**:
+>
+> **Option 1: [Simple approach - you fill this in]**
+> - **Pros**: ✅ [2-3 actual advantages]
+> - **Cons**: ❌ [2-3 actual trade-offs]
+> - **Technical Impact**: [How this affects the features]
+>
+> **Option 2: [Balanced approach - you fill this in]**
+> - **Pros**: ✅ [2-3 actual advantages]
+> - **Cons**: ❌ [2-3 actual trade-offs]
+> - **Technical Impact**: [How this affects the features]
+>
+> **Option 3: [Advanced approach - you fill this in]**
+> - **Pros**: ✅ [2-3 actual advantages]
+> - **Cons**: ❌ [2-3 actual trade-offs]
+> - **Technical Impact**: [How this affects the features]
+>
+> Would you like me to create working prototypes to compare these?
+
+**Track the response:**
+- If user wants prototypes → Go to Step 5B
+- If user picks an option → Go to Step 6 (set `ARCH_DECISION_MADE = true`)
+- If user skips → Go to Step 6 (set `ARCH_DECISION_MADE = false`)
+
+### Step 5B: Build Prototypes
 
 If user wants to prototype approaches:
 
-1. Build 2-3 prototype approaches in `/prototypes/epic-[id]-[approach-name]/`
-2. Each prototype should demonstrate the architectural difference
-3. **Add prototype header**:
+1. Create prototype directory using the epic ID from Step 1:
+   ```bash
+   mkdir -p prototypes/epic-${EPIC_ID}-${APPROACH_NAME}
    ```
-   // Prototype: Epic [epic-id] - [approach name]
-   // Created: [date]
-   // Purpose: Demonstrate [architectural aspect]
-   // Decision: [to be filled after testing]
+
+   **Example** (if epic ID is 5, approach is "websockets"):
+   ```bash
+   mkdir -p prototypes/epic-5-websockets
    ```
-4. After user tests, help them choose the winner
-5. Document the decision and rationale
 
-### Step 5C: If Approach Already Known
+2. Build 2-3 working prototypes demonstrating the architectural difference
 
-If user already knows the approach or skips prototyping:
+3. After user tests, ask which approach they prefer
 
-```
-Which architectural approach works best for this epic?
-```
+4. When user picks a winner → Go to Step 6 (set `ARCH_DECISION_MADE = true`)
 
-Then record their decision.
+### Step 5C: Skip Architecture (User Already Knows)
 
-### Step 6: Create Features and Complete Discovery
+If user says they already know the approach or don't need architectural decisions:
 
-Once features are defined and architectural decision is made (if needed):
+**Say to user:**
+> Got it. We'll skip architectural prototyping for this epic.
 
-**CRITICAL: You must EXECUTE commands using the Bash tool. Do NOT just display them as text.**
+Set `ARCH_DECISION_MADE = false` and proceed directly to Step 6.
 
-#### Step 6A: Create Features
-
-**CRITICAL:** You MUST pass the `--parent=<epic-id>` flag with the actual numeric epic ID. Without this, features won't appear under the epic in the backlog tree.
+---
 
-Use the Bash tool to create each feature. Replace `<EPIC_ID>` with the actual epic ID number:
+### Step 6: Create Features
 
-```javascript
-// CORRECT - uses actual numeric epic ID:
-jettypod work create feature "Live cursor tracking" "Track cursor positions in real-time" --parent=5
-
-// WRONG - missing parent flag (feature won't be under epic):
-jettypod work create feature "Live cursor tracking" "Track cursor positions in real-time"
-```
+**CRITICAL: Execute these commands with the Bash tool. Do NOT just display them.**
 
-For each feature, execute:
+**Before you start:** Confirm you have the epic ID from Step 1. If you're unsure, run:
 ```bash
-jettypod work create feature "<Title>" "<Description>" --parent=<EPIC_ID>
+jettypod backlog
 ```
 
-Display to user as you create each one:
-```
-Creating features...
-✅ Created Feature #123: [Feature 1]
-✅ Created Feature #456: [Feature 2]
-```
+#### Step 6A: Create Each Feature
 
-#### Step 6B: Record Architectural Decision (if applicable)
+For each feature the user agreed on, execute this command using the epic ID from Step 1:
 
-If an architectural decision was made, propose the rationale to the user:
+```bash
+jettypod work create feature "${FEATURE_TITLE}" "${FEATURE_DESCRIPTION}" --parent=${EPIC_ID}
+```
 
+**Example** (if epic ID is 5):
+```bash
+jettypod work create feature "Live cursor tracking" "Track cursor positions in real-time" --parent=5
 ```
-I'm going to record this architectural decision:
 
-Aspect: Architecture
-Decision: [architectural approach chosen]
-Rationale: [why this approach was selected]
+After each successful creation, tell the user:
+> ✅ Created Feature #[id from output]: [title]
 
-Does this rationale capture why you chose this approach? (You can edit it if needed)
-```
+#### Step 6B: Record Architectural Decision (Conditional)
 
-**WAIT for user to confirm or provide edited rationale.**
+**Check:** Did user select an architectural approach in Step 5A or 5B?
+- If YES (user picked Option 1/2/3 or chose after prototyping) → Continue below
+- If NO (user said "already know", skipped, declined, or Step 4 was answered "no") → Skip to Step 7
 
-**CRITICAL: After user confirms, use Bash tool to EXECUTE the epic-implement command:**
+If an architectural decision was made:
 
-```javascript
-// Use Bash tool to execute:
-jettypod work epic-implement [epic-id] \
-  --aspect="Architecture" \
-  --decision="[architectural approach chosen]" \
-  --rationale="[user's confirmed/edited rationale]"
-```
+**Say to user:**
+> I'm going to record this architectural decision:
+>
+> **Aspect:** Architecture
+> **Decision:** [the approach they chose]
+> **Rationale:** [why they chose it]
+>
+> Does this capture why you chose this approach? (You can edit it if needed)
 
-**DO NOT display this as example text. EXECUTE IT using the Bash tool.**
+**WAIT for user confirmation.**
 
-After execution succeeds, display:
+After user confirms, execute this command using the epic ID from Step 1 and the actual decision values:
 
-```
-✅ Architectural decision recorded
+```bash
+jettypod work epic-implement ${EPIC_ID} --aspect="${ASPECT}" --decision="${DECISION}" --rationale="${RATIONALE}"
 ```
 
-Then proceed to Step 7.
+**Example** (if epic ID is 5):
+```bash
+jettypod work epic-implement 5 --aspect="Architecture" --decision="WebSockets with Socket.io" --rationale="Chosen for bi-directional real-time communication"
+```
 
-### Step 7: Route to Next Planning Skill
+After success, tell the user:
+> ✅ Architectural decision recorded
 
-After features/chores are created (and architectural decision recorded if applicable), route to the appropriate planning skill.
+---
 
-#### Step 7A: Query Created Items
+### Step 7: Route to Next Planning Skill
 
-Query the database to find what was just created under this epic:
+#### Step 7A: List Created Items
 
+Run this command using the epic ID from Step 1:
 ```bash
-sqlite3 .jettypod/work.db "SELECT id, title, type FROM work_items WHERE parent_id = <EPIC_ID> ORDER BY id"
+jettypod work children ${EPIC_ID}
 ```
 
-#### Step 7B: Display and Recommend
+#### Step 7B: Recommend Next Item
 
-Display what was created and recommend which item to plan first:
+Based on the output, recommend which item to plan first.
 
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-🎯 Epic Planning Complete!
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Created under this epic:
-  ✨ Feature #[id]: [title]
-  ✨ Feature #[id]: [title]
-  🔧 Chore #[id]: [title]  (if any chores were created)
-
-💡 Recommendation: Start with [Feature/Chore] #[id] ([title])
-   [Reason - e.g., "It's foundational - other items may depend on it."]
-
-Plan this one now? [yes / pick different / done for now]
-```
+**Say to user:**
+> ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+> 🎯 Epic Planning Complete!
+> ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+>
+> Created under this epic:
+> [List the actual items from the children command output]
+>
+> 💡 Recommendation: Start with Feature #[actual id] ([actual title])
+>    [Your reasoning - e.g., "It's foundational - other features depend on it."]
+>
+> Plan this one now? [yes / pick different / done for now]
 
 **Recommendation logic:**
-- If features exist, recommend the first feature (features are typically foundational)
+- Recommend the first feature (features are typically foundational)
 - If only chores exist, recommend the first chore
-- Provide brief reasoning for the recommendation
+- Provide brief reasoning
 
 **WAIT for user response.**
 
@@ -268,7 +337,9 @@ Determine the skill to invoke based on item type:
 - **Feature** → invoke `feature-planning`
 - **Chore** → invoke `chore-planning`
 
-**IMMEDIATELY invoke the appropriate skill using the Skill tool:**
+**Before invoking, state the item ID clearly in your response** (e.g., "I'll start planning Feature #42" or "Let's plan Chore #15"). This ensures the child skill has the ID in context.
+
+**Then IMMEDIATELY invoke the appropriate skill using the Skill tool:**
 
 ```
 Use the Skill tool with skill: "feature-planning"