aiblueprint-cli 1.4.14 → 1.4.16

package/claude-code-config/skills/setup-ralph/steps/step-01-interactive-prd.md

@@ -0,0 +1,366 @@
+---
+name: step-01-interactive-prd
+description: Collaborative PRD brainstorming with parallel exploration (APEX-style)
+prev_step: steps/step-00-init.md
+next_step: steps/step-02-create-stories.md
+---
+
+# Step 1: Interactive PRD Creation
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input - you're a FACILITATOR
+- 🛑 NEVER be too technical - focus on WHAT and WHY, not HOW
+- 🛑 NEVER write final PRD without user approval
+- 🛑 NEVER run ralph.sh - only create PRD files
+- ✅ ALWAYS brainstorm collaboratively - ask, listen, refine
+- ✅ ALWAYS use parallel exploration to understand codebase context
+- ✅ ALWAYS let user validate each section before continuing
+- 📋 YOU ARE A FACILITATOR and BRAINSTORMING PARTNER
+- 💬 FOCUS on understanding the vision, not implementation details
+- 🚫 FORBIDDEN to skip brainstorming phases
+- 🚫 FORBIDDEN to proceed without user confirmation at each phase
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Start with open discovery - understand the vision
+- 💾 Build PRD incrementally with user approval at each section
+- 📖 Use parallel agents to gather context (like APEX analyze phase)
+- 🚫 FORBIDDEN to load next step until PRD is saved and approved
+
+## CONTEXT BOUNDARIES:
+
+**Available from step-00:**
+- `{project_path}` - Absolute path to project
+- `{ralph_dir}` - Path to .claude/ralph
+- `{feature_name}` - Feature folder name (e.g., `01-add-auth`)
+- `{feature_dir}` - Path to feature folder
+
+## YOUR TASK:
+
+Collaboratively brainstorm with the user to create a comprehensive PRD, using parallel exploration to understand the codebase context.
+
+---
+
+## EXECUTION SEQUENCE:
+
+### Phase 1: Discovery & Vision
+
+**Start with a warm welcome:**
+
+```
+🚀 Let's brainstorm your feature: {feature_name}
+
+I'm here as your brainstorming partner. We'll explore your ideas together
+and create a PRD that captures exactly what you want to build.
+
+This is about WHAT you want, not HOW to build it.
+```
+
+**Use AskUserQuestion for initial discovery:**
+
+```yaml
+questions:
+  - header: "Vision"
+    question: "In one sentence, what's the core idea of this feature?"
+    options:
+      - label: "Let me describe it"
+        description: "I'll explain my vision"
+    multiSelect: false
+```
+
+**After user responds, ask follow-up questions conversationally:**
+
+1. **"What problem does this solve?"** - Pain point, who experiences it
+2. **"What does success look like?"** - Ideal outcome when it's done
+3. **"Who benefits most?"** - Primary users/personas
+
+**After gathering vision, offer A/P/C menu:**
+
+```yaml
+questions:
+  - header: "Vision"
+    question: "We've captured your vision. What's next?"
+    options:
+      - label: "Continue to exploration (Recommended)"
+        description: "Let me explore your codebase to understand context"
+      - label: "Refine vision more"
+        description: "I want to add or change something"
+      - label: "Advanced: Brainstorming techniques"
+        description: "Use specific brainstorming methods"
+    multiSelect: false
+```
+
+### Phase 2: Parallel Exploration (APEX-Style)
+
+**Launch parallel exploration agents to understand context:**
+
+```
+📡 Exploring your codebase to understand context...
+```
+
+**CRITICAL: Launch ALL agents in a SINGLE message for parallel execution.**
+
+**Agent 1: Codebase Exploration** (`explore-codebase`)
+```
+Find existing code related to: {user's feature description}
+
+Report:
+1. Files that contain related functionality
+2. Existing patterns used for similar features
+3. How similar features are currently structured
+4. What infrastructure already exists
+
+Report ONLY what exists - no planning.
+```
+
+**Agent 2: Documentation Research** (`explore-docs`)
+```
+Research documentation for libraries that might be relevant to: {user's feature description}
+
+Find:
+1. How relevant libraries/frameworks work
+2. Common patterns from official docs
+```
+
+**After exploration completes, synthesize findings:**
+
+```
+🔍 Context Discovery Complete
+
+**Related code found:**
+- {list key files and what they do}
+
+**Existing patterns:**
+- {list patterns you can follow}
+
+**Infrastructure available:**
+- {list utilities and helpers}
+```
+
+### Phase 3: Scope Definition
+
+**Help user define clear scope:**
+
+```yaml
+questions:
+  - header: "Scope"
+    question: "How big should this feature be for the first version?"
+    options:
+      - label: "Minimal MVP (Recommended)"
+        description: "Just the core functionality - can iterate later"
+      - label: "Full feature"
+        description: "Complete implementation with all edge cases"
+      - label: "Let's discuss"
+        description: "Help me figure out the right scope"
+    multiSelect: false
+```
+
+**If "Let's discuss":**
+Use the 3-question MVP test:
+1. "What's the ONE thing this must do to be useful?"
+2. "What can we add in version 2?"
+3. "What's explicitly NOT part of this?"
+
+### Phase 4: Feature Brainstorming
+
+**Brainstorm the key capabilities:**
+
+```yaml
+questions:
+  - header: "Features"
+    question: "What are the 3-5 key things this feature should do?"
+    options:
+      - label: "Let me list them"
+        description: "I'll describe the main capabilities"
+    multiSelect: false
+```
+
+**After user lists features, reflect back:**
+
+```
+📝 Key Features Identified:
+
+1. {Feature 1} - {brief description}
+2. {Feature 2} - {brief description}
+3. {Feature 3} - {brief description}
+```
+
+**Then offer refinement:**
+
+```yaml
+questions:
+  - header: "Features"
+    question: "Does this capture what you want?"
+    options:
+      - label: "Yes, continue (Recommended)"
+        description: "Move to organizing into phases"
+      - label: "Add more features"
+        description: "I want to add something"
+      - label: "Remove or change"
+        description: "Some of these need adjustment"
+    multiSelect: false
+```
+
+### Phase 5: Phase Planning
+
+**Help organize features into phases:**
+
+```
+💡 Let's organize these into phases for Ralph:
+
+**Phase 1 (Foundation):** What must work first?
+**Phase 2 (Core):** Main functionality
+**Phase 3 (Polish):** Nice-to-haves
+```
+
+**Guide the splitting:**
+- Each phase should have 3-8 stories
+- Each story = 5-30 minutes of work
+- Stories must be independently committable
+
+**Story Writing Guidelines:**
+```
+✅ Good story: "Add email validation to signup form"
+❌ Too big: "Build entire auth system"
+❌ Too small: "Add import statement"
+
+Each story should:
+- Be completable by one developer
+- Not depend on future stories
+- Deliver measurable value
+- Be independently testable
+```
+
+### Phase 6: Draft PRD
+
+**Generate PRD draft based on all brainstorming:**
+
+```markdown
+# Feature: {Feature Name}
+
+## Vision
+{1 paragraph from Phase 1 - in user's words}
+
+## Problem
+{Pain point and who experiences it}
+
+## Solution
+{High-level approach - WHAT not HOW}
+
+## Success Criteria
+- {What success looks like - from user}
+
+## Key Features
+- {Feature 1}
+- {Feature 2}
+- {Feature 3}
+
+## Phases
+
+### Phase 1: Foundation
+- [ ] {Story 1 - small, atomic}
+- [ ] {Story 2}
+
+### Phase 2: Core Functionality
+- [ ] {Story 3}
+- [ ] {Story 4}
+
+### Phase 3: Polish
+- [ ] {Story 5}
+
+## Out of Scope
+- {What we're NOT doing - from Phase 3}
+
+## Context from Codebase
+- Key files: {from exploration}
+- Patterns to follow: {from exploration}
+```
+
+**Note: Keep it non-technical. Focus on WHAT, not HOW.**
+
+### Phase 7: Review & Finalize
+
+**Present PRD for review:**
+
+```yaml
+questions:
+  - header: "PRD Review"
+    question: "Here's the PRD. How does it look?"
+    options:
+      - label: "Looks great, save it (Recommended)"
+        description: "Save PRD and create user stories"
+      - label: "Make changes"
+        description: "I want to adjust something"
+      - label: "Start over"
+        description: "Let's brainstorm from scratch"
+    multiSelect: false
+```
+
+**If "Make changes":** Ask what to change, update, present again.
+
+### Phase 8: Save PRD
+
+**Save to `{feature_dir}/PRD.md`:**
+
+```
+✅ PRD saved to: {feature_dir}/PRD.md
+
+Ready to transform this into user stories for Ralph!
+```
+
+---
+
+## BRAINSTORMING TECHNIQUES (If user selects "Advanced")
+
+Offer these techniques:
+
+1. **What If Scenarios** - "What if users could X? What if Y didn't exist?"
+2. **Reversal** - "What would make this feature fail completely?"
+3. **First Principles** - "What's the fundamental problem we're solving?"
+4. **Six Thinking Hats** - Facts, Emotions, Cautions, Benefits, Creativity, Process
+5. **SCAMPER** - Substitute, Combine, Adapt, Modify, Put to other uses, Eliminate, Reverse
+
+---
+
+## SUCCESS METRICS:
+
+✅ Vision clearly captured in user's words
+✅ Codebase context explored with parallel agents
+✅ Scope defined (MVP vs full)
+✅ Features brainstormed collaboratively
+✅ Phases organized logically
+✅ PRD drafted and approved by user
+✅ User validated at each phase (not auto-generated)
+
+## FAILURE MODES:
+
+❌ Generating PRD without user input (CRITICAL)
+❌ Being too technical (focus on WHAT not HOW)
+❌ Skipping exploration phase
+❌ Not offering A/P/C menus at each phase
+❌ Making assumptions without asking
+❌ Creating huge stories (each should be 5-30 min)
+❌ Running ralph.sh (user runs it themselves!)
+
+## FACILITATOR PROTOCOLS:
+
+- Ask, don't assume
+- Reflect back what you heard
+- Use user's language, not technical jargon
+- Offer choices, don't dictate
+- Build incrementally with validation
+- Keep energy collaborative, not transactional
+
+## NEXT STEP:
+
+After PRD is saved and approved, load `./step-02-create-stories.md`
+
+<critical>
+Remember: You are a FACILITATOR. The PRD should be in the USER'S words,
+capturing THEIR vision. Your job is to ask good questions, explore context,
+and organize their ideas - not to generate content they haven't validated.
+
+The goal is the BEST possible PRD and BEST possible task split.
+Small, well-defined stories are KEY to Ralph working effectively.
+</critical>

package/claude-code-config/skills/setup-ralph/steps/step-02-create-stories.md

@@ -0,0 +1,273 @@
+---
+name: step-02-create-stories
+description: Transform PRD into user stories (prd.json)
+prev_step: steps/step-01-interactive-prd.md
+next_step: steps/step-03-finish.md
+---
+
+# Step 2: Create User Stories
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER create stories without reading PRD.md first
+- 🛑 NEVER make stories too large - each must fit in ONE iteration
+- 🛑 NEVER run ralph.sh - only create prd.json, user runs commands
+- ✅ ALWAYS include acceptance criteria for each story
+- ✅ ALWAYS set correct priority order (1 = first to implement)
+- 📋 YOU ARE a story writer, not an implementer
+- 💬 FOCUS on breaking down PRD into atomic stories
+- 🚫 FORBIDDEN to proceed without user confirmation
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Read PRD.md completely before writing stories
+- 💾 Save prd.json after user approval
+- 📖 Each story must have clear acceptance criteria
+- 🚫 FORBIDDEN to load next step until prd.json is saved
+
+## CONTEXT BOUNDARIES:
+
+**Available from previous steps:**
+- `{project_path}` - Absolute path to project
+- `{ralph_dir}` - Path to .claude/ralph
+- `{feature_name}` - Feature folder name
+- `{feature_dir}` - Path to feature folder
+- PRD.md exists in `{feature_dir}`
+
+## YOUR TASK:
+
+Transform the PRD into a prd.json file with properly structured user stories that Ralph can execute.
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. Read PRD.md
+
+```bash
+Read: {feature_dir}/PRD.md
+```
+
+Extract:
+- Feature name and description
+- All user stories/tasks
+- Acceptance criteria
+- Technical notes
+
+### 2. Generate Branch Name
+
+Create a branch name from the feature:
+- Format: `feat/{feature-name}`
+- Example: `feat/01-add-auth` or `feat/user-dashboard`
+
+### 3. Transform Stories to JSON
+
+**For each story in the PRD, create a JSON object:**
+
+```json
+{
+  "id": "US-001",
+  "title": "Short descriptive title",
+  "acceptanceCriteria": [
+    "Specific criterion 1",
+    "Specific criterion 2",
+    "TypeScript compiles",
+    "Tests pass"
+  ],
+  "priority": 1,
+  "passes": false,
+  "notes": "Any context Claude needs"
+}
+```
+
+**Story Sizing Rules:**
+
+✅ **Good Story Size:**
+- Can be implemented in 5-30 minutes
+- Changes 1-5 files
+- Has clear start and end
+- Independent (can be committed alone)
+
+❌ **Story Too Large - Split It:**
+- "Build entire auth system" → Split into 10+ stories
+- "Add user dashboard" → Split into individual widgets
+- "Refactor module" → Split by function/component
+
+❌ **Story Too Small - Combine:**
+- "Add import statement" → Combine with the story that uses it
+- "Fix typo" → Combine with related story
+
+### 4. Structure prd.json
+
+```json
+{
+  "branchName": "feat/{feature-name}",
+  "userStories": [
+    {
+      "id": "US-001",
+      "title": "Add FeatureType enum value",
+      "acceptanceCriteria": [
+        "FEATURE_TYPE added to enum in schema",
+        "TypeScript compiles without errors"
+      ],
+      "priority": 1,
+      "passes": false,
+      "notes": "First step - add the type before using it"
+    },
+    {
+      "id": "US-002",
+      "title": "Create feature handler skeleton",
+      "acceptanceCriteria": [
+        "New handler file created following existing patterns",
+        "Basic structure in place",
+        "TypeScript compiles"
+      ],
+      "priority": 2,
+      "passes": false,
+      "notes": "Follow pattern from existing handlers"
+    }
+    // ... more stories
+  ]
+}
+```
+
+### 5. Priority Guidelines
+
+**Priority determines execution order (1 = first):**
+
+1. **Foundation** (Priority 1-5)
+   - Schema changes
+   - Type definitions
+   - Base interfaces
+
+2. **Core Logic** (Priority 6-15)
+   - Business logic
+   - Main functionality
+   - API endpoints
+
+3. **UI Components** (Priority 16-25)
+   - Display components
+   - Forms
+   - Interactions
+
+4. **Integration** (Priority 26-35)
+   - Connect pieces
+   - Error handling
+   - Edge cases
+
+5. **Polish** (Priority 36+)
+   - Tests
+   - Documentation
+   - Cleanup
+
+### 6. Present Stories for Review
+
+Show all stories to user:
+
+```
+📋 User Stories for {feature_name}
+
+Branch: {branchName}
+Total stories: {count}
+
+| ID | Priority | Title |
+|----|----------|-------|
+| US-001 | 1 | Add FeatureType enum value |
+| US-002 | 2 | Create feature handler skeleton |
+| ... | ... | ... |
+
+[Show full JSON for review]
+```
+
+**Use AskUserQuestion:**
+```yaml
+questions:
+  - header: "Stories"
+    question: "Do these user stories look correct? Any changes needed?"
+    options:
+      - label: "Looks good, save them (Recommended)"
+        description: "Save prd.json and get run instructions"
+      - label: "Adjust stories"
+        description: "I want to add, remove, or modify some stories"
+      - label: "Re-read PRD"
+        description: "Let me update PRD.md first, then try again"
+    multiSelect: false
+```
+
+### 7. Iterate if Needed
+
+If user wants changes:
+- Ask what to change
+- Add/remove/modify stories
+- Adjust priorities
+- Present again
+
+### 8. Save prd.json
+
+Once approved, save to `{feature_dir}/prd.json`:
+
+```bash
+# Use Write tool
+Write to: {feature_dir}/prd.json
+Content: [JSON with proper formatting]
+```
+
+**Also update progress.txt with key files:**
+
+```bash
+# Append to progress.txt
+Edit: {feature_dir}/progress.txt
+
+Append:
+## Key Files
+- {list of files that will be modified}
+- {based on PRD technical design}
+```
+
+---
+
+## STORY QUALITY CHECKLIST:
+
+Before saving, verify each story:
+
+✅ **Atomic** - One clear thing to implement
+✅ **Independent** - Can be committed alone
+✅ **Testable** - Clear acceptance criteria
+✅ **Prioritized** - Dependencies come first
+✅ **Sized Right** - 5-30 minutes of work
+✅ **Has Context** - Notes explain what Claude needs to know
+
+## SUCCESS METRICS:
+
+✅ PRD.md read completely
+✅ All stories extracted and structured
+✅ Priorities set correctly (dependencies first)
+✅ Each story has acceptance criteria
+✅ User approved the stories
+✅ prd.json saved correctly
+✅ progress.txt updated with key files
+
+## FAILURE MODES:
+
+❌ Stories too large (will fail to complete in one iteration)
+❌ Missing acceptance criteria
+❌ Wrong priority order (dependency after dependent)
+❌ No TypeScript/test criteria in stories
+❌ Skipped user approval
+
+## STORY CREATION PROTOCOLS:
+
+- Always include "TypeScript compiles" in acceptance criteria
+- Always include "Tests pass" if project has tests
+- Use consistent ID format: US-001, US-002, etc.
+- Notes should explain patterns to follow
+- Group related stories with consecutive priorities
+
+## NEXT STEP:
+
+After prd.json is saved, load `./step-03-finish.md` to show run instructions.
+
+<critical>
+Remember: Story size is CRITICAL. Each story must be completable in one Ralph iteration.
+If in doubt, split into smaller stories. More small stories > fewer large stories.
+</critical>