aiblueprint-cli 1.4.14 → 1.4.16

package/claude-code-config/skills/setup-ralph/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: setup-ralph
+description: Setup the Ralph autonomous AI coding loop - ships features while you sleep
+argument-hint: "<project-path> [-i/--interactive] [-f/--feature <name>]"
+---
+
+<objective>
+Set up the Ralph autonomous coding loop in any project. Ralph runs AI agents in a loop, picking tasks from a PRD, implementing one at a time, committing after each, and accumulating learnings until all tasks are complete.
+
+**This skill ONLY sets up Ralph - you run the commands yourself.**
+</objective>
+
+<quick_start>
+**Setup Ralph interactively (recommended):**
+```bash
+/setup-ralph -i
+```
+
+**Setup for specific feature:**
+```bash
+/setup-ralph -f 01-add-authentication
+```
+
+**What this does:**
+1. Creates `.claude/ralph/` structure in your project
+2. Runs setup script to create all Ralph files
+3. (If -i): Brainstorms PRD with you interactively
+4. Transforms PRD into user stories (prd.json)
+5. Shows you the command to run Ralph (you run it yourself)
+
+**After setup, you run:**
+```bash
+bun run .claude/ralph/ralph.sh -f <feature-name>
+```
+</quick_start>
+
+<critical_rule>
+🛑 NEVER run ralph.sh or any execution commands automatically
+🛑 NEVER execute the loop - only set up files and show instructions
+✅ ALWAYS let the user copy and run commands themselves
+✅ ALWAYS end by showing the exact command to run
+</critical_rule>
+
+<when_to_use>
+**Use this skill when:**
+- Starting a new feature that can be broken into small stories
+- Setting up Ralph in a new project
+- Creating a new feature PRD interactively
+
+**Don't use for:**
+- Simple single-file changes
+- Exploratory work without clear requirements
+- Major refactors without acceptance criteria
+</when_to_use>
+
+<parameters>
+| Flag | Description |
+|------|-------------|
+| `<project-path>` | Path to the project (defaults to current directory) |
+| `-i, --interactive` | Interactive mode: brainstorm PRD with AI assistance |
+| `-f, --feature <name>` | Feature folder name (e.g., `01-add-auth`) |
+
+**Examples:**
+```bash
+/setup-ralph /path/to/project -i              # Interactive PRD creation
+/setup-ralph . -f 01-add-auth                 # Setup for specific feature
+/setup-ralph -i -f 02-user-dashboard          # Interactive with specific name
+```
+</parameters>
+
+<state_variables>
+| Variable | Type | Description |
+|----------|------|-------------|
+| `{project_path}` | string | Absolute path to target project |
+| `{ralph_dir}` | string | Path to .claude/ralph in project |
+| `{feature_name}` | string | Feature folder name (e.g., `01-add-auth`) |
+| `{feature_dir}` | string | Path to task folder |
+| `{interactive_mode}` | boolean | Whether to brainstorm PRD interactively |
+| `{prd_content}` | string | PRD markdown content |
+| `{user_stories}` | array | User stories extracted from PRD |
+| `{branch_name}` | string | Git branch for the feature |
+</state_variables>
+
+<entry_point>
+Load `steps/step-00-init.md`
+</entry_point>
+
+<step_files>
+| Step | File | Purpose |
+|------|------|---------|
+| 00 | `step-00-init.md` | Parse flags, run setup script, create structure |
+| 01 | `step-01-interactive-prd.md` | Interactive PRD brainstorming and creation |
+| 02 | `step-02-create-stories.md` | Transform PRD into user stories (prd.json) |
+| 03 | `step-03-finish.md` | Show run command (user runs it themselves) |
+</step_files>
+
+<scripts>
+| Script | Purpose |
+|--------|---------|
+| `scripts/setup.sh` | Creates all Ralph files in the project |
+</scripts>
+
+<execution_rules>
+1. **Progressive Loading**: Load one step at a time
+2. **Script Execution**: Use scripts/setup.sh to create files atomically
+3. **Interactive Mode**: If -i flag, run brainstorming conversation
+4. **State Persistence**: Track progress in feature_dir/progress.txt
+5. **Resume Support**: Detect existing PRD.md and resume from there
+6. **NEVER RUN RALPH**: Only setup and show commands - user runs them
+</execution_rules>
+
+<success_criteria>
+✅ Ralph structure created at {project_path}/.claude/ralph
+✅ Feature folder created with PRD.md, prd.json, progress.txt
+✅ User stories properly formatted in prd.json
+✅ Clear run command provided to user (they run it themselves)
+</success_criteria>

package/claude-code-config/skills/setup-ralph/scripts/setup.sh

@@ -0,0 +1,278 @@
+#!/bin/bash
+# Ralph Setup Script - Creates all Ralph files atomically
+# Usage: ./setup.sh <project-path> [feature-name]
+
+set -e
+
+PROJECT_PATH="${1:-.}"
+FEATURE_NAME="${2:-01-feature}"
+
+# Resolve absolute path
+PROJECT_PATH=$(cd "$PROJECT_PATH" && pwd)
+RALPH_DIR="$PROJECT_PATH/.claude/ralph"
+TASKS_DIR="$RALPH_DIR/tasks"
+FEATURE_DIR="$TASKS_DIR/$FEATURE_NAME"
+
+echo "🚀 Setting up Ralph in: $PROJECT_PATH"
+echo "📁 Feature: $FEATURE_NAME"
+
+# Create directory structure
+mkdir -p "$RALPH_DIR"
+mkdir -p "$FEATURE_DIR"
+
+# Create ralph.sh (main loop script)
+cat > "$RALPH_DIR/ralph.sh" << 'RALPH_SH'
+#!/bin/bash
+# Ralph - Autonomous AI Coding Loop
+# Usage: ./ralph.sh -f <feature-folder> [-n <max-iterations>]
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+MAX_ITERATIONS=10
+FEATURE_FOLDER=""
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    -f|--feature)
+      FEATURE_FOLDER="$2"
+      shift 2
+      ;;
+    -n|--max)
+      MAX_ITERATIONS="$2"
+      shift 2
+      ;;
+    *)
+      echo "Unknown option: $1"
+      echo "Usage: ./ralph.sh -f <feature-folder> [-n <max-iterations>]"
+      exit 1
+      ;;
+  esac
+done
+
+if [ -z "$FEATURE_FOLDER" ]; then
+  echo "❌ Error: Feature folder required"
+  echo "Usage: ./ralph.sh -f <feature-folder> [-n <max-iterations>]"
+  echo ""
+  echo "Available features:"
+  ls -1 "$SCRIPT_DIR/tasks/" 2>/dev/null || echo "  No features found. Create one first!"
+  exit 1
+fi
+
+TASK_DIR="$SCRIPT_DIR/tasks/$FEATURE_FOLDER"
+
+if [ ! -d "$TASK_DIR" ]; then
+  echo "❌ Error: Feature folder not found: $TASK_DIR"
+  echo ""
+  echo "Available features:"
+  ls -1 "$SCRIPT_DIR/tasks/" 2>/dev/null || echo "  No features found"
+  exit 1
+fi
+
+PRD_FILE="$TASK_DIR/prd.json"
+PROGRESS_FILE="$TASK_DIR/progress.txt"
+PROMPT_FILE="$SCRIPT_DIR/prompt.md"
+
+if [ ! -f "$PRD_FILE" ]; then
+  echo "❌ Error: prd.json not found in $TASK_DIR"
+  exit 1
+fi
+
+# Get story counts
+TOTAL_STORIES=$(jq '.userStories | length' "$PRD_FILE")
+COMPLETED=$(jq '[.userStories[] | select(.passes == true)] | length' "$PRD_FILE")
+
+echo "╔════════════════════════════════════════════════════════════╗"
+echo "║                    🤖 RALPH STARTING                       ║"
+echo "╠════════════════════════════════════════════════════════════╣"
+echo "║ Feature: $FEATURE_FOLDER"
+echo "║ Stories: $COMPLETED / $TOTAL_STORIES completed"
+echo "║ Max iterations: $MAX_ITERATIONS"
+echo "╚════════════════════════════════════════════════════════════╝"
+echo ""
+
+for ((i=1; i<=$MAX_ITERATIONS; i++)); do
+  # Refresh counts
+  COMPLETED=$(jq '[.userStories[] | select(.passes == true)] | length' "$PRD_FILE")
+  REMAINING=$((TOTAL_STORIES - COMPLETED))
+
+  echo ""
+  echo "═══════════════════════════════════════════════════════════════"
+  echo "📍 Iteration $i / $MAX_ITERATIONS | Completed: $COMPLETED / $TOTAL_STORIES | Remaining: $REMAINING"
+  echo "═══════════════════════════════════════════════════════════════"
+  echo ""
+
+  # Run Claude with the prompt
+  OUTPUT=$(claude -p --dangerously-skip-permissions \
+    "@$PRD_FILE @$PROGRESS_FILE @$PROMPT_FILE" 2>&1 \
+    | tee /dev/stderr) || true
+
+  # Check for completion signal
+  if echo "$OUTPUT" | grep -q "<promise>COMPLETE</promise>"; then
+    echo ""
+    echo "╔════════════════════════════════════════════════════════════╗"
+    echo "║                    ✅ RALPH COMPLETE                       ║"
+    echo "╠════════════════════════════════════════════════════════════╣"
+    echo "║ All $TOTAL_STORIES stories completed in $i iterations!"
+    echo "╚════════════════════════════════════════════════════════════╝"
+    exit 0
+  fi
+
+  sleep 2
+done
+
+echo ""
+echo "╔════════════════════════════════════════════════════════════╗"
+echo "║                    ⚠️  MAX ITERATIONS                       ║"
+echo "╠════════════════════════════════════════════════════════════╣"
+echo "║ Reached $MAX_ITERATIONS iterations. Run again to continue."
+echo "╚════════════════════════════════════════════════════════════╝"
+exit 1
+RALPH_SH
+
+chmod +x "$RALPH_DIR/ralph.sh"
+echo "✅ Created ralph.sh"
+
+# Create prompt.md (agent instructions)
+cat > "$RALPH_DIR/prompt.md" << 'PROMPT_MD'
+# Ralph Agent Instructions
+
+## Your Task
+
+You are an autonomous AI coding agent running in a loop. Each iteration, you implement ONE user story from the PRD.
+
+## Execution Sequence
+
+1. **Read Context**
+   - Read the PRD (prd.json) to understand all user stories
+   - Read progress.txt to see patterns and learnings from previous iterations
+   - Identify the **highest priority** story where `passes: false`
+
+2. **Check Git Branch**
+   - Verify you're on the correct branch (see `branchName` in prd.json)
+   - If not, checkout the branch: `git checkout <branchName>` or create it
+
+3. **Implement ONE Story**
+   - Focus on implementing ONLY the selected story
+   - Follow the acceptance criteria exactly
+   - Make minimal changes to achieve the goal
+
+4. **Verify Quality**
+   - Run typecheck (if applicable): `pnpm tsc --noEmit` or `npm run typecheck`
+   - Run tests (if applicable): `pnpm test` or `npm test`
+   - Fix any issues before proceeding
+
+5. **Commit Changes**
+   - Stage your changes: `git add .`
+   - Commit with format: `feat: [STORY-ID] - [Title]`
+   - Example: `feat: US-001 - Add login form validation`
+
+6. **Update PRD**
+   - Update prd.json to mark the story as `passes: true`
+   - Add any notes about the implementation
+
+7. **Log Learnings**
+   - Append to progress.txt with format:
+
+```
+## [Date] - [Story ID]: [Title]
+- What was implemented
+- Files changed
+- **Learnings:**
+  - Patterns discovered
+  - Gotchas encountered
+---
+```
+
+## Codebase Patterns
+
+Check the TOP of progress.txt for patterns discovered by previous iterations:
+- Follow existing patterns
+- Add new patterns when you discover them
+- Update patterns if they're outdated
+
+## Stop Condition
+
+**If ALL stories have `passes: true`**, output this exact text:
+
+<promise>COMPLETE</promise>
+
+This signals the loop to stop.
+
+## Critical Rules
+
+- 🛑 NEVER implement more than ONE story per iteration
+- 🛑 NEVER skip the verification step (typecheck/tests)
+- 🛑 NEVER commit if tests are failing
+- ✅ ALWAYS check progress.txt for patterns FIRST
+- ✅ ALWAYS update prd.json after implementing
+- ✅ ALWAYS append learnings to progress.txt
+PROMPT_MD
+
+echo "✅ Created prompt.md"
+
+# Create empty prd.json template
+cat > "$FEATURE_DIR/prd.json" << 'PRD_JSON'
+{
+  "branchName": "feat/FEATURE_NAME",
+  "userStories": []
+}
+PRD_JSON
+
+# Replace placeholder
+sed -i '' "s/FEATURE_NAME/${FEATURE_NAME}/g" "$FEATURE_DIR/prd.json" 2>/dev/null || \
+sed -i "s/FEATURE_NAME/${FEATURE_NAME}/g" "$FEATURE_DIR/prd.json"
+
+echo "✅ Created prd.json"
+
+# Create progress.txt template
+cat > "$FEATURE_DIR/progress.txt" << PROGRESS_TXT
+# Ralph Progress Log
+Started: $(date +%Y-%m-%d)
+Feature: $FEATURE_NAME
+
+## Codebase Patterns
+(Add discovered patterns here - Ralph will read these each iteration)
+
+---
+
+PROGRESS_TXT
+
+echo "✅ Created progress.txt"
+
+# Create empty PRD.md
+cat > "$FEATURE_DIR/PRD.md" << 'PRD_MD'
+# Feature: [Feature Name]
+
+## Vision
+[What this feature accomplishes]
+
+## Problem
+[What problem does this solve]
+
+## Solution
+[High-level approach]
+
+## User Stories
+[Will be converted to prd.json]
+
+## Technical Notes
+[Implementation details, constraints, dependencies]
+PRD_MD
+
+echo "✅ Created PRD.md"
+
+echo ""
+echo "╔════════════════════════════════════════════════════════════╗"
+echo "║                    ✅ RALPH SETUP COMPLETE                  ║"
+echo "╠════════════════════════════════════════════════════════════╣"
+echo "║ Structure created at: $RALPH_DIR"
+echo "║ Feature folder: $FEATURE_DIR"
+echo "╠════════════════════════════════════════════════════════════╣"
+echo "║ Next steps:"
+echo "║ 1. Edit PRD.md with your feature requirements"
+echo "║ 2. Run /ralph -i to brainstorm PRD interactively"
+echo "║ 3. Transform PRD to user stories in prd.json"
+echo "║ 4. Run: bun run $RALPH_DIR/ralph.sh -f $FEATURE_NAME"
+echo "╚════════════════════════════════════════════════════════════╝"

package/claude-code-config/skills/setup-ralph/steps/step-00-init.md

@@ -0,0 +1,215 @@
+---
+name: step-00-init
+description: Parse flags, set up Ralph structure, detect existing PRD
+prev_step: null
+next_step: steps/step-01-interactive-prd.md
+---
+
+# Step 0: Initialize Ralph
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER skip the setup script - it creates files atomically
+- 🛑 NEVER run ralph.sh - only set up files and show commands
+- ✅ ALWAYS resolve project path to absolute path
+- ✅ ALWAYS check for existing Ralph structure before creating
+- ✅ ALWAYS let user run commands themselves
+- 📋 YOU ARE an initializer, not an executor
+- 💬 FOCUS on parsing flags and setting up structure only
+- 🚫 FORBIDDEN to create PRD content in this step
+- 🚫 FORBIDDEN to execute ralph.sh
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Parse all flags before taking any action
+- 💾 Run setup script to create file structure
+- 📖 Complete setup fully before next step
+- 🚫 FORBIDDEN to load next step until structure exists
+
+## CONTEXT BOUNDARIES:
+
+- User arguments are available in the skill invocation
+- No previous state exists (this is the first step)
+- Setup script will create all necessary files
+
+## YOUR TASK:
+
+Initialize Ralph by parsing flags, running the setup script, and preparing for PRD creation.
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. Parse User Arguments
+
+Extract from skill arguments:
+
+```yaml
+# DEFAULTS
+project_path: "."              # Current directory if not specified
+interactive_mode: false        # -i or --interactive
+setup_only: false              # --setup-only
+feature_name: null             # -f or --feature <name>
+```
+
+**Parsing Rules:**
+- First non-flag argument = project_path
+- `-i` or `--interactive` = interactive_mode: true
+- `--setup-only` = setup_only: true
+- `-f <name>` or `--feature <name>` = feature_name
+
+### 2. Validate Project Path
+
+```bash
+# Check project exists
+if [ ! -d "{project_path}" ]; then
+  echo "Error: Project path not found"
+  exit 1
+fi
+
+# Resolve to absolute path
+project_path=$(cd "{project_path}" && pwd)
+```
+
+### 3. Generate Feature Name (if not provided)
+
+If `{feature_name}` is null:
+- Use AskUserQuestion to get feature name
+- Generate kebab-case ID: `NN-feature-name`
+- NN = next available number (01, 02, 03...)
+
+**If interactive_mode = false and no feature_name:**
+```yaml
+questions:
+  - header: "Feature"
+    question: "What is the name of this feature? (will be used for folder name)"
+    options:
+      - label: "Let me type it"
+        description: "I'll provide a custom feature name"
+    multiSelect: false
+```
+
+### 4. Set State Variables
+
+```yaml
+{project_path}: "/absolute/path/to/project"
+{ralph_dir}: "{project_path}/.claude/ralph"
+{tasks_dir}: "{ralph_dir}/tasks"
+{feature_name}: "01-feature-name"
+{feature_dir}: "{tasks_dir}/{feature_name}"
+{interactive_mode}: true/false
+{setup_only}: true/false
+```
+
+### 5. Check for Existing Structure
+
+```bash
+# Check if Ralph already exists
+if [ -d "{ralph_dir}" ]; then
+  echo "✅ Ralph structure already exists"
+fi
+
+# Check if feature folder exists
+if [ -d "{feature_dir}" ]; then
+  echo "✅ Feature folder already exists"
+  # Check for existing PRD
+  if [ -f "{feature_dir}/PRD.md" ]; then
+    echo "📄 Found existing PRD.md"
+    {has_existing_prd} = true
+  fi
+  if [ -f "{feature_dir}/prd.json" ]; then
+    # Check if prd.json has stories
+    stories_count=$(jq '.userStories | length' "{feature_dir}/prd.json")
+    if [ "$stories_count" -gt 0 ]; then
+      echo "📋 Found $stories_count user stories in prd.json"
+      {has_user_stories} = true
+    fi
+  fi
+fi
+```
+
+### 6. Run Setup Script
+
+**Use Bash tool to run the setup script:**
+
+```bash
+# Make script executable and run it
+chmod +x /Users/melvynx/.claude/skills/setup-ralph/scripts/setup.sh
+/Users/melvynx/.claude/skills/setup-ralph/scripts/setup.sh "{project_path}" "{feature_name}"
+```
+
+The setup script creates:
+- `.claude/ralph/ralph.sh` (main loop)
+- `.claude/ralph/prompt.md` (agent instructions)
+- `.claude/ralph/tasks/{feature_name}/PRD.md` (empty template)
+- `.claude/ralph/tasks/{feature_name}/prd.json` (empty stories)
+- `.claude/ralph/tasks/{feature_name}/progress.txt` (learning log)
+
+### 7. Determine Next Step
+
+**Decision Tree:**
+
+```
+If {setup_only} = true:
+  → Show success message, END workflow
+
+If {has_user_stories} = true:
+  → Skip to step-03-finish.md (ready to run)
+
+If {has_existing_prd} = true AND content is not template:
+  → Skip to step-02-create-stories.md (transform PRD to stories)
+
+If {interactive_mode} = true:
+  → Load step-01-interactive-prd.md (brainstorm PRD)
+
+Else:
+  → Ask user what to do next
+```
+
+**If need to ask:**
+```yaml
+questions:
+  - header: "Next Step"
+    question: "Ralph is set up. What would you like to do next?"
+    options:
+      - label: "Create PRD interactively (Recommended)"
+        description: "Brainstorm and create PRD with AI assistance"
+      - label: "I'll write PRD manually"
+        description: "Edit PRD.md yourself, then run /setup-ralph again"
+      - label: "Transform existing PRD to stories"
+        description: "I already have a PRD, just create user stories"
+    multiSelect: false
+```
+
+---
+
+## SUCCESS METRICS:
+
+✅ Project path resolved to absolute path
+✅ Feature name generated or provided
+✅ Setup script executed successfully
+✅ All Ralph files created
+✅ State variables properly set
+✅ Next step determined
+
+## FAILURE MODES:
+
+❌ Project path doesn't exist
+❌ Setup script fails
+❌ Permission denied creating directories
+❌ Feature name contains invalid characters
+
+## INIT PROTOCOLS:
+
+- Always use absolute paths
+- Always run setup script (it's idempotent)
+- Never modify existing PRD.md if it has content
+- Use AskUserQuestion for any user decisions
+
+## NEXT STEP:
+
+Based on decision tree above, load the appropriate next step.
+
+<critical>
+Remember: This step ONLY sets up structure. PRD content is created in step-01.
+</critical>