wiggum-cli 0.1.0

package/src/templates/prompts/PROMPT_feature.md.tmpl

@@ -0,0 +1,83 @@
+## Context
+Study @.ralph/AGENTS.md for commands and patterns.
+Study @.ralph/specs/README.md for spec structure.
+Study @.ralph/specs/$FEATURE.md for feature specification.
+{{#if frameworkVariant}}For detailed architecture, see @{{appDir}}/.claude/CLAUDE.md{{/if}}
+
+## Search
+- Use `mgrep "query"` to analyze existing codebase patterns
+- Use Context7 MCP to lookup library APIs and best practices
+
+## Phase: Planning
+1. Read the spec file: @.ralph/specs/$FEATURE.md
+2. Analyze codebase to identify what exists vs what's needed
+3. Create @.ralph/specs/$FEATURE-implementation-plan.md with tasks
+
+## Implementation Plan Format
+```markdown
+# $FEATURE Implementation Plan
+
+**Spec:** .ralph/specs/$FEATURE.md
+**Branch:** feat/$FEATURE
+**Status:** Planning | In Progress | PR Review | Completed
+
+## Tasks
+
+### Phase 1: Setup
+- [ ] Task 1 - [complexity: S/M/L]
+- [ ] Task 2
+
+### Phase 2: Core Implementation
+- [ ] Task 3
+- [ ] Task 4
+
+### Phase 3: Tests (Unit/Integration)
+- [ ] Write tests for [component]
+- [ ] Write tests for [feature]
+
+### Phase 4: Polish & Design
+- [ ] Run design checklist from @.ralph/guides/FRONTEND.md (if UI changes)
+- [ ] Verify responsive design (mobile/tablet/desktop)
+- [ ] Add loading/empty/error states
+- [ ] Verify hover/focus states on interactive elements
+{{#if styling}}- [ ] For charts: use ChartContainer pattern with tooltips + legends{{/if}}
+- [ ] Task N (additional polish)
+
+### Phase 5: E2E Testing
+Browser-based tests executed via Playwright MCP tools.
+
+- [ ] E2E: [Scenario name] - [brief description]
+  - **URL:** [starting URL, use {placeholders} for dynamic IDs]
+  - **Preconditions:** [setup requirements, e.g., "Survey must be published"]
+  - **Steps:**
+    1. [Action] -> [expected result]
+    2. [Action] -> [expected result]
+  - **Verify:** [final assertion text to check]
+  - **Database check:** [optional SQL query to verify data]
+
+Example E2E scenario:
+- [ ] E2E: Submit survey response - happy path
+  - **URL:** /survey/{surveyId}?utm_source=e2e_test
+  - **Preconditions:** Published survey with required questions
+  - **Steps:**
+    1. Navigate to survey URL -> Form displays with all questions
+    2. Fill required text field -> No validation error
+    3. Select rating 4 -> Button shows selected state
+    4. Click "Submit Survey" -> Loading state appears
+    5. Wait for "Thank You!" -> Success card displays
+  - **Verify:** "successfully submitted" text visible
+  - **Database check:** SELECT * FROM survey_responses WHERE survey_id = '{surveyId}'
+
+## Done
+- [x] Completed task - [commit hash]
+- [x] E2E: Scenario name - PASSED
+```
+
+## Rules
+- Plan only in this phase, do NOT implement
+- One task = one commit-sized unit of work
+- Every implementation task needs a corresponding test task
+- Use Supabase MCP to check existing schema
+- Use PostHog MCP to check existing analytics setup
+- For UI-heavy features (new pages, dashboards, analytics, marketing pages), reference @.ralph/guides/FRONTEND.md
+- Consider `/frontend-design` skill for features needing distinctive aesthetics

package/src/templates/prompts/PROMPT_review.md.tmpl

@@ -0,0 +1,167 @@
+## Context
+Study @.ralph/AGENTS.md for commands and patterns.
+Study @.ralph/specs/$FEATURE.md for feature specification.
+Study @.ralph/specs/$FEATURE-implementation-plan.md for completed tasks.
+
+## Learnings
+Read @.ralph/LEARNINGS.md for patterns from previous features.
+Capture any review feedback patterns for future iterations.
+
+## Task
+All implementation and E2E tasks are complete. Create PR and request review.
+
+### Step 1: Verify Ready State
+1. Check all tasks are complete in implementation plan (no `- [ ]` items)
+2. Verify tests pass: `cd {{appDir}} && {{testCommand}}`
+3. Verify build succeeds: `cd {{appDir}} && {{buildCommand}}`
+
+If any fail, fix before proceeding.
+
+### Step 2: Check Git Status
+```bash
+cd {{appDir}} && git status
+cd {{appDir}} && git log --oneline -5
+```
+
+Ensure:
+- On branch `feat/$FEATURE`
+- All changes are committed
+- Branch is pushed to remote
+
+If uncommitted changes exist:
+```bash
+git -C {{appDir}} add -A && git -C {{appDir}} commit -m "chore($FEATURE): final cleanup"
+git -C {{appDir}} push origin feat/$FEATURE
+```
+
+### Step 3: Create PR
+Check if PR already exists:
+```bash
+cd {{appDir}} && gh pr list --head feat/$FEATURE
+```
+
+If no PR exists, create one:
+```bash
+cd {{appDir}} && gh pr create --base main --head feat/$FEATURE \
+  --title "feat($FEATURE): [read description from spec]" \
+  --body "$(cat <<'EOF'
+## Summary
+[Read from spec Purpose section]
+
+## Changes
+[Read from implementation plan - list completed phases]
+
+## Testing
+- [x] Unit/integration tests: 97 passing
+- [x] E2E tests: All scenarios passed via Playwright MCP
+- [x] Build succeeds
+
+## E2E Test Results
+[Copy from implementation plan Phase 9]
+
+Generated with Claude Code
+EOF
+)"
+```
+
+### Step 4: Request Codex Review
+
+Run automated code review using Codex CLI:
+
+```bash
+# Check if Codex CLI is installed
+if ! command -v codex &> /dev/null; then
+    echo "WARNING: Codex CLI not installed. Manual review needed."
+    cd {{appDir}} && gh pr comment --body "Manual review requested - Codex CLI not available. Install: brew install openai/tap/codex"
+else
+    echo "Running Codex code review..."
+    # Get diff summary for context
+    DIFF_SUMMARY=$(cd {{appDir}} && git diff main --stat | head -50)
+
+    # Use codex exec for non-interactive review
+    echo "Code Review Request for $FEATURE feature.
+
+## Changed Files:
+$DIFF_SUMMARY
+
+## Review Checklist:
+- Code quality and patterns consistency
+- Test coverage adequacy
+- Potential bugs or edge cases
+- Security concerns (injection, XSS, etc.)
+- Performance implications
+- Error handling completeness
+
+Please review and respond with:
+- APPROVED if everything looks good
+- Or list specific issues that need to be fixed" | cd {{appDir}} && codex exec --full-auto -
+fi
+```
+
+**Handle review feedback:**
+- If Codex outputs "APPROVED" -> Proceed to Step 5 (rebase and merge)
+- If Codex lists issues:
+  1. Address each issue with code fixes
+  2. Commit: `git -C {{appDir}} add -A && git -C {{appDir}} commit -m "fix($FEATURE): address review feedback"`
+  3. Push: `git -C {{appDir}} push origin feat/$FEATURE`
+  4. Re-run the `codex review` command above
+- Max 3 review iterations before requiring manual intervention
+
+### Step 5: Rebase Before Merge (for Parallel Execution)
+Before merging, ensure branch is up-to-date with main:
+```bash
+cd {{appDir}} && git fetch origin main
+cd {{appDir}} && git rebase origin/main
+```
+
+If rebase has conflicts:
+1. Resolve conflicts in affected files
+2. `git add .` the resolved files
+3. `git rebase --continue`
+4. Re-run tests: `{{testCommand}} && {{buildCommand}}`
+
+Push rebased branch:
+```bash
+cd {{appDir}} && git push --force-with-lease origin feat/$FEATURE
+```
+
+### Step 6: Merge PR
+When Codex review is approved and branch is rebased:
+```bash
+cd {{appDir}} && gh pr merge --squash --delete-branch
+```
+
+### Step 7: Post-Merge Cleanup
+1. If using worktree, remove it:
+   ```bash
+   # Only if this feature used a worktree ({{appDir}}-$FEATURE directory exists)
+   git -C {{appDir}} worktree remove "../{{appDir}}-$FEATURE" 2>/dev/null || true
+   ```
+2. Checkout main and pull:
+   ```bash
+   git -C {{appDir}} checkout main && git -C {{appDir}} pull
+   ```
+
+Note: Spec status updates are handled in the Spec Verification phase before PR creation.
+
+## Rules
+- Do NOT merge without Codex approval
+- Address ALL review comments before merging
+- Use squash merge to keep history clean
+- If gh CLI fails, check authentication: `gh auth status`
+- Keep review conversation focused and professional
+
+## Troubleshooting
+- **gh: command not found** -> Install GitHub CLI: `brew install gh`
+- **gh auth error** -> Run: `gh auth login`
+- **PR already exists** -> Use: `gh pr view` to see status
+- **Codex CLI not installed** -> Install with: `brew install openai/tap/codex`, then `codex login`
+- **Rebase conflicts** -> Resolve carefully, re-run all tests after
+
+## Learning Capture
+If the review revealed patterns worth remembering, append to @.ralph/LEARNINGS.md:
+- Code quality feedback -> Add under "## Anti-Patterns" or "## Patterns"
+- Common review issues -> Add under "## Anti-Patterns"
+- Good practices identified -> Add under "## Patterns"
+
+Format: `- [YYYY-MM-DD] [$FEATURE] Brief description`

package/src/templates/prompts/PROMPT_verify.md.tmpl

@@ -0,0 +1,72 @@
+## Context
+Study @.ralph/specs/$FEATURE.md for original specification.
+Study @.ralph/specs/$FEATURE-implementation-plan.md for completed tasks.
+
+## Learnings
+Read @.ralph/LEARNINGS.md for verification patterns from previous features.
+
+## Task
+Verify that the implementation meets the spec requirements. Update spec files accordingly.
+
+### Step 1: Review Requirements
+Read @.ralph/specs/$FEATURE.md and for each requirement under "## Requirements":
+- Check if it was implemented (review implementation plan tasks)
+- Mark as `[x]` if complete
+- Leave as `[ ]` if not implemented, add note explaining why
+
+### Step 2: Review Acceptance Criteria
+For each item under "## Acceptance Criteria":
+- Verify against E2E test results in implementation plan
+- Mark as `[x]` if verified
+- Leave as `[ ]` with note if not met
+
+### Step 3: Update Spec Status
+Change `**Status:** Planned` (or `Draft`) to:
+- `**Status:** Completed` if all requirements met
+- `**Status:** Partial` if some requirements not met (with notes)
+
+Update `**Last Updated:**` to today's date.
+
+### Step 4: Update README.md
+Update @.ralph/specs/README.md Active Specs table:
+- Change status from "Planned" to "Completed" (or "Partial")
+- Update Last Updated date
+
+### Step 5: Document Gaps (if any)
+If any requirements were not fully met, add a section to the spec:
+
+```markdown
+## Implementation Notes
+- [Requirement X] - Deferred: [reason]
+- [Acceptance Criteria Y] - Partial: [explanation]
+```
+
+### Step 6: Commit Changes
+```bash
+git -C {{appDir}} add ../.ralph/specs/
+git -C {{appDir}} commit -m "docs($FEATURE): verify spec requirements complete"
+git -C {{appDir}} push origin feat/$FEATURE
+```
+
+## Verification Checklist
+Before marking complete, ensure:
+- [ ] All requirements in spec have been reviewed
+- [ ] All acceptance criteria have been reviewed
+- [ ] Spec status updated appropriately
+- [ ] README.md table updated
+- [ ] Any gaps documented with clear explanations
+- [ ] Changes committed and pushed
+
+## Rules
+- Be thorough - check every requirement and acceptance criterion
+- Be honest - don't mark incomplete items as complete
+- Document gaps clearly for future reference
+- If a requirement was intentionally deferred, explain why
+
+## Learning Capture
+If verification revealed patterns worth remembering, append to @.ralph/LEARNINGS.md:
+- Common gaps between spec and implementation -> Add under "## Anti-Patterns"
+- Useful spec writing patterns -> Add under "## Patterns"
+- Verification tips -> Add under "## Tool Usage"
+
+Format: `- [YYYY-MM-DD] [$FEATURE] Brief description`

package/src/templates/root/.gitignore.tmpl

@@ -0,0 +1,5 @@
+# Ralph working files
+*.log
+*.tmp
+
+# Don't ignore anything else - all ralph files should be committed

package/src/templates/root/LEARNINGS.md.tmpl

@@ -0,0 +1,24 @@
+# Learnings
+
+Accumulated knowledge from feature implementations. Reference before starting new tasks.
+
+## Patterns (What Works)
+
+<!-- Add successful patterns here -->
+- [YYYY-MM-DD] [feature] Pattern description
+
+## Anti-Patterns (What to Avoid)
+
+<!-- Add mistakes and issues to avoid -->
+- [YYYY-MM-DD] [feature] Anti-pattern description
+
+### E2E Pitfalls
+<!-- E2E testing specific issues -->
+
+## Tool Usage
+
+<!-- Tips for using MCP tools and CLI -->
+
+## Codebase Conventions
+
+<!-- Project-specific conventions discovered -->

package/src/templates/root/README.md.tmpl

@@ -0,0 +1,61 @@
+# .ralph - AI Development Configuration
+
+This directory contains configuration and guidance for AI-assisted development of **{{projectName}}**.
+
+## Structure
+
+```
+.ralph/
+|-- AGENTS.md          # Commands, patterns, and coding rules
+|-- LEARNINGS.md       # Accumulated knowledge from iterations
+|-- prompts/           # Task-specific prompts
+|   |-- PROMPT.md          # Main implementation prompt
+|   |-- PROMPT_feature.md  # Feature planning prompt
+|   |-- PROMPT_e2e.md      # E2E testing prompt
+|   |-- PROMPT_verify.md   # Verification prompt
+|   |-- PROMPT_review.md   # PR review prompt
+|-- guides/            # Reference documentation
+|   |-- FRONTEND.md        # UI/UX patterns and checklist
+|   |-- SECURITY.md        # Security review checklist
+|   |-- PERFORMANCE.md     # Performance patterns
+|-- specs/             # Feature specifications
+|   |-- README.md          # Spec template and index
+|   |-- _example.md        # Example specification
+|-- scripts/           # Automation scripts
+```
+
+## Usage
+
+### For Claude Code / AI Assistants
+
+Reference these files in your prompts:
+- `@.ralph/AGENTS.md` - Stack info, commands, coding rules
+- `@.ralph/prompts/PROMPT.md` - Implementation workflow
+- `@.ralph/guides/FRONTEND.md` - UI development guide
+
+### Feature Loop
+
+1. **Plan**: Use `PROMPT_feature.md` to create implementation plan
+2. **Implement**: Use `PROMPT.md` for iterative task completion
+3. **Test**: Use `PROMPT_e2e.md` for browser-based testing
+4. **Verify**: Use `PROMPT_verify.md` to verify spec requirements
+5. **Review**: Use `PROMPT_review.md` to create PR and get review
+
+### Specs
+
+Add new feature specs to `.ralph/specs/`:
+1. Copy `_example.md` as starting point
+2. Fill in requirements and acceptance criteria
+3. Use `PROMPT_feature.md` to create implementation plan
+
+## Detected Stack
+
+- **Framework:** {{framework}}{{#if frameworkVersion}} {{frameworkVersion}}{{/if}}{{#if frameworkVariant}} ({{frameworkVariant}}){{/if}}
+- **Package Manager:** {{packageManager}}
+- **Styling:** {{styling}}
+{{#if unitTest}}- **Unit Testing:** {{unitTest}}{{/if}}
+{{#if e2eTest}}- **E2E Testing:** {{e2eTest}}{{/if}}
+
+## Configuration
+
+See `ralph.config.js` in project root for full configuration.

package/src/templates/scripts/feature-loop.sh.tmpl

@@ -0,0 +1,267 @@
+#!/bin/bash
+# feature-loop.sh - Full feature workflow: branch -> implement -> E2E test -> PR -> review -> merge
+# Generated by ralph-cli for {{projectName}}
+# Usage: ./feature-loop.sh <feature-name> [max-iterations] [max-e2e-attempts] [--worktree] [--resume] [--model MODEL]
+#
+# Options:
+#   --worktree       Use git worktree for isolation (enables parallel execution)
+#   --resume         Resume an interrupted loop (reuses existing branch/worktree)
+#   --model MODEL    Claude model to use (e.g., opus, sonnet, claude-sonnet-4-5-20250514)
+
+set -e
+set -o pipefail
+
+# Get script directory
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Load config from ralph.config.js if available
+if [ -f "$SCRIPT_DIR/../ralph.config.js" ]; then
+    RALPH_ROOT=$(node -e "console.log(require('$SCRIPT_DIR/../ralph.config.js').paths?.root || '.ralph')" 2>/dev/null || echo ".ralph")
+    SPEC_DIR=$(node -e "console.log(require('$SCRIPT_DIR/../ralph.config.js').paths?.specs || '.ralph/specs')" 2>/dev/null || echo ".ralph/specs")
+    PROMPTS_DIR=$(node -e "console.log(require('$SCRIPT_DIR/../ralph.config.js').paths?.prompts || '.ralph/prompts')" 2>/dev/null || echo ".ralph/prompts")
+    DEFAULT_MODEL=$(node -e "console.log(require('$SCRIPT_DIR/../ralph.config.js').loop?.defaultModel || 'sonnet')" 2>/dev/null || echo "sonnet")
+    PLANNING_MODEL=$(node -e "console.log(require('$SCRIPT_DIR/../ralph.config.js').loop?.planningModel || 'opus')" 2>/dev/null || echo "opus")
+    DEFAULT_MAX_ITERATIONS=$(node -e "console.log(require('$SCRIPT_DIR/../ralph.config.js').loop?.maxIterations || 10)" 2>/dev/null || echo "10")
+    DEFAULT_MAX_E2E=$(node -e "console.log(require('$SCRIPT_DIR/../ralph.config.js').loop?.maxE2eAttempts || 5)" 2>/dev/null || echo "5")
+elif [ -f "$SCRIPT_DIR/../../ralph.config.js" ]; then
+    RALPH_ROOT=$(node -e "console.log(require('$SCRIPT_DIR/../../ralph.config.js').paths?.root || '.ralph')" 2>/dev/null || echo ".ralph")
+    SPEC_DIR=$(node -e "console.log(require('$SCRIPT_DIR/../../ralph.config.js').paths?.specs || '.ralph/specs')" 2>/dev/null || echo ".ralph/specs")
+    PROMPTS_DIR=$(node -e "console.log(require('$SCRIPT_DIR/../../ralph.config.js').paths?.prompts || '.ralph/prompts')" 2>/dev/null || echo ".ralph/prompts")
+    DEFAULT_MODEL=$(node -e "console.log(require('$SCRIPT_DIR/../../ralph.config.js').loop?.defaultModel || 'sonnet')" 2>/dev/null || echo "sonnet")
+    PLANNING_MODEL=$(node -e "console.log(require('$SCRIPT_DIR/../../ralph.config.js').loop?.planningModel || 'opus')" 2>/dev/null || echo "opus")
+    DEFAULT_MAX_ITERATIONS=$(node -e "console.log(require('$SCRIPT_DIR/../../ralph.config.js').loop?.maxIterations || 10)" 2>/dev/null || echo "10")
+    DEFAULT_MAX_E2E=$(node -e "console.log(require('$SCRIPT_DIR/../../ralph.config.js').loop?.maxE2eAttempts || 5)" 2>/dev/null || echo "5")
+else
+    # Default paths
+    RALPH_ROOT=".ralph"
+    SPEC_DIR=".ralph/specs"
+    PROMPTS_DIR=".ralph/prompts"
+    DEFAULT_MODEL="sonnet"
+    PLANNING_MODEL="opus"
+    DEFAULT_MAX_ITERATIONS="10"
+    DEFAULT_MAX_E2E="5"
+fi
+
+# Navigate to project root (parent of .ralph)
+cd "$SCRIPT_DIR/../.."
+
+# Parse arguments
+USE_WORKTREE=false
+RESUME=false
+MODEL=""
+POSITIONAL=()
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --worktree)
+            USE_WORKTREE=true
+            shift
+            ;;
+        --resume)
+            RESUME=true
+            shift
+            ;;
+        --model)
+            MODEL="$2"
+            shift 2
+            ;;
+        *)
+            POSITIONAL+=("$1")
+            shift
+            ;;
+    esac
+done
+set -- "${POSITIONAL[@]}"
+
+# Build claude commands
+CLAUDE_CMD_OPUS="claude -p --dangerously-skip-permissions --model ${PLANNING_MODEL}"
+CLAUDE_CMD_IMPL="claude -p --dangerously-skip-permissions --model ${MODEL:-$DEFAULT_MODEL}"
+
+# Token tracking
+TOKENS_FILE="/tmp/ralph-loop-${1}.tokens"
+CLAUDE_OUTPUT="/tmp/ralph-loop-${1}.output"
+
+# Initialize token tracking
+init_tokens() {
+    echo "0|0" > "$TOKENS_FILE"
+}
+
+# Parse and accumulate tokens
+parse_and_accumulate_tokens() {
+    local output_file="$1"
+    local input_tokens=$({ grep -oE "input[^0-9]*([0-9,]+)" "$output_file" 2>/dev/null || true; } | { grep -oE "[0-9,]+" || true; } | tr -d ',' | tail -1)
+    local output_tokens=$({ grep -oE "output[^0-9]*([0-9,]+)" "$output_file" 2>/dev/null || true; } | { grep -oE "[0-9,]+" || true; } | tr -d ',' | tail -1)
+
+    input_tokens=${input_tokens:-0}
+    output_tokens=${output_tokens:-0}
+
+    if [ -f "$TOKENS_FILE" ]; then
+        local current=$(cat "$TOKENS_FILE")
+        local current_input=$(echo "$current" | cut -d'|' -f1)
+        local current_output=$(echo "$current" | cut -d'|' -f2)
+        [[ "$current_input" =~ ^[0-9]+$ ]] || current_input=0
+        [[ "$current_output" =~ ^[0-9]+$ ]] || current_output=0
+    else
+        current_input=0
+        current_output=0
+    fi
+
+    local new_input=$((current_input + input_tokens))
+    local new_output=$((current_output + output_tokens))
+    echo "${new_input}|${new_output}" > "$TOKENS_FILE"
+}
+
+# Initialize tokens
+init_tokens
+
+FEATURE="${1:?Usage: ./feature-loop.sh <feature-name> [max-iterations] [max-e2e-attempts] [--worktree] [--resume] [--model MODEL]}"
+MAX_ITERATIONS="${2:-$DEFAULT_MAX_ITERATIONS}"
+MAX_E2E_ATTEMPTS="${3:-$DEFAULT_MAX_E2E}"
+ITERATION=0
+
+# Paths
+SPEC_FILE="$SPEC_DIR/${FEATURE}.md"
+PLAN_FILE="$SPEC_DIR/${FEATURE}-implementation-plan.md"
+BRANCH="feat/${FEATURE}"
+APP_DIR="$(pwd)"
+
+echo "=========================================="
+echo "Ralph Loop: $FEATURE"
+echo "Spec: $SPEC_FILE"
+echo "Plan: $PLAN_FILE"
+echo "Branch: $BRANCH"
+echo "App dir: $APP_DIR"
+echo "Worktree mode: $USE_WORKTREE"
+echo "Resume mode: $RESUME"
+echo "Model (planning): $PLANNING_MODEL"
+echo "Model (impl): ${MODEL:-$DEFAULT_MODEL}"
+echo "Max iterations: $MAX_ITERATIONS"
+echo "Max E2E attempts: $MAX_E2E_ATTEMPTS"
+echo "=========================================="
+
+# Phase 1: Validate spec exists
+if [ ! -f "$SPEC_FILE" ]; then
+    echo "ERROR: Spec file not found: $SPEC_FILE"
+    echo "Create the spec first: ralph new $FEATURE"
+    exit 1
+fi
+
+# Phase 2: Create branch if not exists
+CURRENT_BRANCH=$(git branch --show-current)
+if [ "$CURRENT_BRANCH" != "$BRANCH" ]; then
+    if git rev-parse --verify "$BRANCH" >/dev/null 2>&1; then
+        if [ "$RESUME" = true ]; then
+            echo "Resuming on existing branch: $BRANCH"
+            git checkout "$BRANCH"
+        else
+            echo "Creating/switching to branch: $BRANCH"
+            git checkout -B "$BRANCH" main 2>/dev/null || git checkout -B "$BRANCH" master
+        fi
+    else
+        echo "Creating branch: $BRANCH"
+        git checkout -b "$BRANCH" main 2>/dev/null || git checkout -b "$BRANCH" master
+    fi
+else
+    echo "Already on branch: $BRANCH"
+fi
+
+# Create output file for monitoring
+touch "$CLAUDE_OUTPUT"
+
+# Phase 3: Planning (if no implementation plan exists)
+if [ ! -f "$PLAN_FILE" ]; then
+    echo "======================== PLANNING PHASE ========================"
+    export FEATURE APP_DIR SPEC_DIR PROMPTS_DIR
+    cat "$PROMPTS_DIR/PROMPT_feature.md" | envsubst | $CLAUDE_CMD_OPUS 2>&1 | tee "$CLAUDE_OUTPUT" || {
+        echo "ERROR: Planning phase failed"
+        exit 1
+    }
+    parse_and_accumulate_tokens "$CLAUDE_OUTPUT"
+fi
+
+# Phase 4: Implementation loop
+echo "======================== IMPLEMENTATION PHASE ========================"
+while true; do
+    if [ $ITERATION -ge $MAX_ITERATIONS ]; then
+        echo "Reached max iterations: $MAX_ITERATIONS"
+        exit 1
+    fi
+
+    ITERATION=$((ITERATION + 1))
+    echo "$ITERATION|$MAX_ITERATIONS|$(date +%s)" > "/tmp/ralph-loop-${FEATURE}.status"
+    echo "------------------------ Iteration $ITERATION ------------------------"
+
+    # Check if implementation tasks are done
+    PENDING_IMPL=$({ grep "^- \[ \]" "$PLAN_FILE" 2>/dev/null || true; } | { grep -v "E2E:" || true; } | wc -l | tr -d ' ')
+    if [ "$PENDING_IMPL" -eq 0 ]; then
+        echo "All implementation tasks completed!"
+        break
+    fi
+
+    echo "Pending implementation tasks: $PENDING_IMPL"
+    export FEATURE APP_DIR SPEC_DIR PROMPTS_DIR
+    cat "$PROMPTS_DIR/PROMPT.md" | envsubst | $CLAUDE_CMD_IMPL 2>&1 | tee "$CLAUDE_OUTPUT" || true
+    parse_and_accumulate_tokens "$CLAUDE_OUTPUT"
+
+    sleep 2
+done
+
+# Phase 5: E2E Testing
+echo "======================== E2E TESTING PHASE ========================"
+E2E_TOTAL=$({ grep "^- \[.\].*E2E:" "$PLAN_FILE" 2>/dev/null || true; } | wc -l | tr -d ' ')
+if [ "$E2E_TOTAL" -eq 0 ]; then
+    echo "No E2E scenarios defined, skipping E2E phase."
+else
+    E2E_ATTEMPT=0
+    while [ $E2E_ATTEMPT -lt $MAX_E2E_ATTEMPTS ]; do
+        E2E_ATTEMPT=$((E2E_ATTEMPT + 1))
+        echo "------------------------ E2E Attempt $E2E_ATTEMPT of $MAX_E2E_ATTEMPTS ------------------------"
+
+        export FEATURE APP_DIR SPEC_DIR PROMPTS_DIR
+        cat "$PROMPTS_DIR/PROMPT_e2e.md" | envsubst | $CLAUDE_CMD_IMPL 2>&1 | tee "$CLAUDE_OUTPUT" || true
+        parse_and_accumulate_tokens "$CLAUDE_OUTPUT"
+
+        # Check if all E2E tests passed
+        E2E_FAILED=$({ grep "^- \[ \].*E2E:.*FAILED" "$PLAN_FILE" 2>/dev/null || true; } | wc -l | tr -d ' ')
+        E2E_PENDING=$({ grep "^- \[ \].*E2E:" "$PLAN_FILE" 2>/dev/null || true; } | { grep -v "FAILED" || true; } | wc -l | tr -d ' ')
+
+        if [ "$E2E_FAILED" -eq 0 ] && [ "$E2E_PENDING" -eq 0 ]; then
+            echo "All E2E tests passed!"
+            break
+        fi
+
+        if [ $E2E_ATTEMPT -lt $MAX_E2E_ATTEMPTS ]; then
+            echo "E2E tests have failures. Running fix iteration..."
+            cat "$PROMPTS_DIR/PROMPT.md" | envsubst | $CLAUDE_CMD_IMPL 2>&1 | tee "$CLAUDE_OUTPUT" || true
+            parse_and_accumulate_tokens "$CLAUDE_OUTPUT"
+        fi
+    done
+fi
+
+# Phase 6: Spec Verification
+echo "======================== SPEC VERIFICATION PHASE ========================"
+export FEATURE APP_DIR SPEC_DIR PROMPTS_DIR
+cat "$PROMPTS_DIR/PROMPT_verify.md" | envsubst | $CLAUDE_CMD_OPUS 2>&1 | tee "$CLAUDE_OUTPUT" || true
+parse_and_accumulate_tokens "$CLAUDE_OUTPUT"
+
+# Phase 7: PR and Review
+echo "======================== PR & REVIEW PHASE ========================"
+export FEATURE APP_DIR SPEC_DIR PROMPTS_DIR
+cat "$PROMPTS_DIR/PROMPT_review.md" | envsubst | $CLAUDE_CMD_OPUS 2>&1 | tee "$CLAUDE_OUTPUT" || true
+parse_and_accumulate_tokens "$CLAUDE_OUTPUT"
+
+# Cleanup temp files
+rm -f "/tmp/ralph-loop-${FEATURE}.status" 2>/dev/null || true
+rm -f "/tmp/ralph-loop-${FEATURE}.output" 2>/dev/null || true
+
+# Print final token usage
+if [ -f "/tmp/ralph-loop-${FEATURE}.tokens" ]; then
+    echo ""
+    echo "=========================================="
+    echo "Final Token Usage:"
+    cat "/tmp/ralph-loop-${FEATURE}.tokens" | awk -F'|' '{printf "  Input: %s tokens\n  Output: %s tokens\n  Total: %s tokens\n", $1, $2, $1+$2}'
+    echo "=========================================="
+fi
+
+echo "=========================================="
+echo "Ralph loop completed: $FEATURE"
+echo "=========================================="