wiggum-cli 0.1.0

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

@@ -0,0 +1,59 @@
+#!/bin/bash
+# loop.sh - Simple Ralph iteration loop
+# Generated by ralph-cli for {{projectName}}
+# Usage: ./loop.sh [prompt-file] [max-iterations]
+
+set -e
+
+# 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
+    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")
+elif [ -f "$SCRIPT_DIR/../../ralph.config.js" ]; then
+    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")
+else
+    PROMPTS_DIR=".ralph/prompts"
+    DEFAULT_MODEL="sonnet"
+fi
+
+# Navigate to project root
+cd "$SCRIPT_DIR/../.."
+
+PROMPT_FILE="${1:-$PROMPTS_DIR/PROMPT.md}"
+MAX_ITERATIONS="${2:-0}"
+MODEL="${3:-$DEFAULT_MODEL}"
+ITERATION=0
+
+echo "Starting Ralph loop"
+echo "  Prompt: $PROMPT_FILE"
+echo "  Model: $MODEL"
+echo "  Max iterations: $MAX_ITERATIONS (0 = infinite)"
+echo "Press Ctrl+C to stop"
+echo ""
+
+# Check if prompt file exists
+if [ ! -f "$PROMPT_FILE" ]; then
+    echo "ERROR: Prompt file not found: $PROMPT_FILE"
+    exit 1
+fi
+
+while true; do
+    if [ $MAX_ITERATIONS -gt 0 ] && [ $ITERATION -ge $MAX_ITERATIONS ]; then
+        echo "Reached max iterations: $MAX_ITERATIONS"
+        break
+    fi
+
+    ITERATION=$((ITERATION + 1))
+    echo "======================== ITERATION $ITERATION ========================"
+
+    cat "$PROMPT_FILE" | claude -p --dangerously-skip-permissions --model "$MODEL"
+
+    echo ""
+    sleep 2
+done
+
+echo "Loop completed after $ITERATION iterations"

package/src/templates/scripts/ralph-monitor.sh.tmpl

@@ -0,0 +1,244 @@
+#!/bin/bash
+# ralph-monitor.sh - Dashboard to monitor loop progress
+# Generated by ralph-cli for {{projectName}}
+# Usage: ./ralph-monitor.sh <feature-name>
+
+FEATURE="${1:?Usage: ./ralph-monitor.sh <feature-name>}"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Load config from ralph.config.js if available
+if [ -f "$SCRIPT_DIR/../ralph.config.js" ]; then
+    SPEC_DIR=$(node -e "console.log(require('$SCRIPT_DIR/../ralph.config.js').paths?.specs || '.ralph/specs')" 2>/dev/null || echo ".ralph/specs")
+elif [ -f "$SCRIPT_DIR/../../ralph.config.js" ]; then
+    SPEC_DIR=$(node -e "console.log(require('$SCRIPT_DIR/../../ralph.config.js').paths?.specs || '.ralph/specs')" 2>/dev/null || echo ".ralph/specs")
+else
+    SPEC_DIR=".ralph/specs"
+fi
+
+# Navigate to project root
+cd "$SCRIPT_DIR/../.."
+
+PLAN_FILE="$SPEC_DIR/${FEATURE}-implementation-plan.md"
+SPEC_FILE="$SPEC_DIR/${FEATURE}.md"
+APP_DIR="$(pwd)"
+STATUS_FILE="/tmp/ralph-loop-${FEATURE}.status"
+TOKENS_FILE="/tmp/ralph-loop-${FEATURE}.tokens"
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[0;33m'
+BLUE='\033[0;34m'
+MAGENTA='\033[0;35m'
+CYAN='\033[0;36m'
+BOLD='\033[1m'
+DIM='\033[2m'
+NC='\033[0m'
+
+# Terminal width
+TERM_WIDTH=$(tput cols 2>/dev/null || echo 80)
+
+# Truncate text
+truncate() {
+    local text="$1"
+    local max="$2"
+    if [ ${#text} -gt $max ]; then
+        echo "${text:0:$((max-3))}..."
+    else
+        echo "$text"
+    fi
+}
+
+# Clean task text
+clean_task() {
+    echo "$1" | sed 's/- \[\[complexity:.*\]\]//g' | sed 's/\[complexity:.*\]//g' | sed 's/  */ /g'
+}
+
+# Progress bar
+progress_bar() {
+    local percent=$1
+    local width=15
+    local filled=$((percent * width / 100))
+    local empty=$((width - filled))
+    printf "${GREEN}"
+    for ((i=0; i<filled; i++)); do printf "\xe2\x96\x88"; done
+    printf "${DIM}"
+    for ((i=0; i<empty; i++)); do printf "\xe2\x96\x91"; done
+    printf "${NC}"
+}
+
+# Detect current phase
+detect_phase() {
+    if pgrep -f "PROMPT_feature.md" > /dev/null 2>&1; then
+        echo "Planning"
+    elif pgrep -f "PROMPT_e2e.md" > /dev/null 2>&1; then
+        echo "E2E Testing"
+    elif pgrep -f "PROMPT_verify.md" > /dev/null 2>&1; then
+        echo "Verification"
+    elif pgrep -f "PROMPT_review.md" > /dev/null 2>&1; then
+        echo "PR Review"
+    elif pgrep -f "PROMPT.md" > /dev/null 2>&1; then
+        echo "Implementation"
+    elif pgrep -f "feature-loop.sh.*$FEATURE" > /dev/null 2>&1; then
+        echo "Running"
+    else
+        echo "Idle"
+    fi
+}
+
+# Get iteration info
+get_iteration_info() {
+    if [ -f "$STATUS_FILE" ]; then
+        cat "$STATUS_FILE"
+        return
+    fi
+    if pgrep -f "feature-loop.sh.*${FEATURE}" > /dev/null 2>&1; then
+        echo "-1|50|0"
+    else
+        echo "0|50|0"
+    fi
+}
+
+# Get token info
+get_token_info() {
+    if [ -f "$TOKENS_FILE" ]; then
+        cat "$TOKENS_FILE"
+    else
+        echo "0|0"
+    fi
+}
+
+# Format number
+format_number() {
+    local num=$1
+    if [ $num -ge 1000000 ]; then
+        printf "%.1fM" $(echo "scale=1; $num/1000000" | bc)
+    elif [ $num -ge 1000 ]; then
+        printf "%.1fK" $(echo "scale=1; $num/1000" | bc)
+    else
+        printf "%d" $num
+    fi
+}
+
+# Main loop
+while true; do
+    clear
+
+    TIMESTAMP=$(date '+%H:%M:%S')
+    ITER_INFO=$(get_iteration_info)
+    ITER_CURRENT=$(echo "$ITER_INFO" | cut -d'|' -f1)
+    ITER_MAX=$(echo "$ITER_INFO" | cut -d'|' -f2)
+    [[ "$ITER_CURRENT" =~ ^-?[0-9]+$ ]] || ITER_CURRENT=0
+    [[ "$ITER_MAX" =~ ^[0-9]+$ ]] || ITER_MAX=50
+
+    echo -e "${BOLD}================================================================${NC}"
+    printf "${BOLD}  ${CYAN}RALPH MONITOR${NC}: %-30s  ${DIM}%s${NC}\n" "$FEATURE" "$TIMESTAMP"
+    echo -e "${BOLD}================================================================${NC}"
+
+    # Check if plan exists
+    if [ ! -f "$PLAN_FILE" ]; then
+        echo ""
+        echo -e "  ${YELLOW}Waiting for implementation plan...${NC}"
+        echo -e "  ${DIM}$PLAN_FILE${NC}"
+        echo ""
+        sleep 10
+        continue
+    fi
+
+    # Count tasks
+    DONE_IMPL=$(grep "^- \[x\]" "$PLAN_FILE" 2>/dev/null | grep -v "E2E:" | wc -l | tr -d '[:space:]')
+    TODO_IMPL=$(grep "^- \[ \]" "$PLAN_FILE" 2>/dev/null | grep -v "E2E:" | wc -l | tr -d '[:space:]')
+    DONE_E2E=$(grep "^- \[x\].*E2E:" "$PLAN_FILE" 2>/dev/null | wc -l | tr -d '[:space:]')
+    TODO_E2E=$(grep "^- \[ \].*E2E:" "$PLAN_FILE" 2>/dev/null | wc -l | tr -d '[:space:]')
+    [[ "$DONE_IMPL" =~ ^[0-9]+$ ]] || DONE_IMPL=0
+    [[ "$TODO_IMPL" =~ ^[0-9]+$ ]] || TODO_IMPL=0
+    [[ "$DONE_E2E" =~ ^[0-9]+$ ]] || DONE_E2E=0
+    [[ "$TODO_E2E" =~ ^[0-9]+$ ]] || TODO_E2E=0
+
+    TOTAL_IMPL=$((DONE_IMPL + TODO_IMPL))
+    TOTAL_E2E=$((DONE_E2E + TODO_E2E))
+    DONE_ALL=$((DONE_IMPL + DONE_E2E))
+    TOTAL_ALL=$((TOTAL_IMPL + TOTAL_E2E))
+
+    [ $TOTAL_IMPL -gt 0 ] && PERCENT_IMPL=$((DONE_IMPL * 100 / TOTAL_IMPL)) || PERCENT_IMPL=0
+    [ $TOTAL_ALL -gt 0 ] && PERCENT_ALL=$((DONE_ALL * 100 / TOTAL_ALL)) || PERCENT_ALL=0
+
+    PHASE=$(detect_phase)
+    BRANCH=$(git branch --show-current 2>/dev/null || echo "-")
+
+    case "$PHASE" in
+        "Planning") PHASE_COLOR="${BLUE}" ;;
+        "Implementation") PHASE_COLOR="${YELLOW}" ;;
+        "E2E Testing") PHASE_COLOR="${CYAN}" ;;
+        "Verification") PHASE_COLOR="${MAGENTA}" ;;
+        "PR Review") PHASE_COLOR="${GREEN}" ;;
+        "Idle") PHASE_COLOR="${DIM}" ;;
+        *) PHASE_COLOR="${NC}" ;;
+    esac
+
+    TOKEN_INFO=$(get_token_info)
+    TOKEN_INPUT=$(echo "$TOKEN_INFO" | cut -d'|' -f1)
+    TOKEN_OUTPUT=$(echo "$TOKEN_INFO" | cut -d'|' -f2)
+    [[ "$TOKEN_INPUT" =~ ^[0-9]+$ ]] || TOKEN_INPUT=0
+    [[ "$TOKEN_OUTPUT" =~ ^[0-9]+$ ]] || TOKEN_OUTPUT=0
+    TOKEN_TOTAL=$((TOKEN_INPUT + TOKEN_OUTPUT))
+
+    if [ "$ITER_CURRENT" = "-1" ]; then
+        ITER_DISPLAY="?"
+    else
+        ITER_DISPLAY="$ITER_CURRENT"
+    fi
+
+    # Status
+    echo ""
+    printf "  Phase: ${PHASE_COLOR}${BOLD}%-14s${NC}" "$PHASE"
+    printf "  Iter: ${BOLD}%s${NC}/${DIM}%d${NC}" "$ITER_DISPLAY" "$ITER_MAX"
+    printf "  Branch: ${CYAN}%s${NC}\n" "$BRANCH"
+    printf "  Tokens: ${MAGENTA}$(format_number $TOKEN_TOTAL)${NC} ${DIM}(in:$(format_number $TOKEN_INPUT) out:$(format_number $TOKEN_OUTPUT))${NC}\n"
+
+    echo -e "${DIM}  ----------------------------------------------------------------${NC}"
+
+    # Progress
+    echo ""
+    printf "  ${BOLD}Implementation:${NC} $(progress_bar $PERCENT_IMPL) ${BOLD}%3d%%${NC}  " "$PERCENT_IMPL"
+    printf "${GREEN}Done: %d${NC} / ${YELLOW}Todo: %d${NC}\n" "$DONE_IMPL" "$TODO_IMPL"
+
+    if [ $TOTAL_E2E -gt 0 ]; then
+        [ $TOTAL_E2E -gt 0 ] && PERCENT_E2E=$((DONE_E2E * 100 / TOTAL_E2E)) || PERCENT_E2E=0
+        printf "  ${BOLD}E2E Tests:     ${NC} $(progress_bar $PERCENT_E2E) ${BOLD}%3d%%${NC}  " "$PERCENT_E2E"
+        printf "${GREEN}Done: %d${NC} / ${YELLOW}Todo: %d${NC}\n" "$DONE_E2E" "$TODO_E2E"
+    fi
+
+    printf "  ${DIM}--------------------------------------------${NC}\n"
+    printf "  ${BOLD}Overall:       ${NC} $(progress_bar $PERCENT_ALL) ${BOLD}%3d%%${NC}  " "$PERCENT_ALL"
+    printf "${GREEN}Done: %d${NC} / Total: %d\n" "$DONE_ALL" "$TOTAL_ALL"
+
+    # Current task
+    CURRENT_TASK=$(grep "^- \[ \]" "$PLAN_FILE" 2>/dev/null | grep -v "E2E:" | head -1 | sed 's/^- \[ \] //')
+    CURRENT_TASK=$(clean_task "$CURRENT_TASK")
+    if [ -n "$CURRENT_TASK" ]; then
+        echo ""
+        echo -e "  ${BOLD}NOW WORKING ON${NC}"
+        CURRENT_TASK=$(truncate "$CURRENT_TASK" $((TERM_WIDTH - 8)))
+        echo -e "  ${YELLOW}>${NC} ${BOLD}$CURRENT_TASK${NC}"
+    fi
+
+    # Recent commits
+    echo ""
+    echo -e "  ${BOLD}RECENT COMMITS${NC}"
+    COMMITS=$(git log --oneline -3 2>/dev/null)
+    if [ -n "$COMMITS" ]; then
+        while IFS= read -r commit; do
+            commit=$(truncate "$commit" $((TERM_WIDTH - 8)))
+            echo -e "  ${DIM}$commit${NC}"
+        done <<< "$COMMITS"
+    else
+        echo -e "  ${DIM}No commits yet${NC}"
+    fi
+
+    echo ""
+    echo -e "${DIM}  ----------------------------------------------------------------${NC}"
+    echo -e "  ${DIM}Refreshing every 10s - Press Ctrl+C to exit${NC}"
+
+    sleep 10
+done

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

@@ -0,0 +1,57 @@
+# Specifications
+
+This folder contains feature specifications and their implementation plans.
+
+## Structure
+
+Each feature has:
+- `<feature>.md` - Specification document
+- `<feature>-implementation-plan.md` - Implementation tasks
+
+## Spec Template
+
+```markdown
+<!--
+Copyright (c) 2025 {{projectName}}. All rights reserved.
+SPDX-License-Identifier: Proprietary
+-->
+
+# Feature Name Specification
+
+**Status:** Planned | In Progress | Completed
+**Version:** 1.0
+**Last Updated:** YYYY-MM-DD
+
+## Purpose
+[One paragraph explaining why this feature exists]
+
+## User Stories
+- As a [user], I want [action] so that [benefit]
+
+## Requirements
+- [ ] Requirement 1
+- [ ] Requirement 2
+
+## Technical Notes
+- Uses: [existing patterns/components]
+- Location: [where code should live]
+
+## Visual Requirements
+(For UI features - delete if backend-only)
+- **Layout:** [Grid/Stack/Sidebar, responsive behavior]
+- **Components:** [shadcn components to use]
+- **Chart Types:** [If applicable]
+- **States:** [Empty, loading, error handling]
+- **Mobile:** [What changes on small screens]
+- **Reference:** [Similar page in app or shadcn docs]
+
+## Acceptance Criteria
+- [ ] Criteria 1
+- [ ] Criteria 2
+```
+
+## Active Specs
+
+| Spec | Status | Last Updated | Implementation Plan |
+|------|--------|--------------|---------------------|
+| (Your specs will appear here) | Planned | YYYY-MM-DD | - |

package/src/templates/specs/_example.md.tmpl

@@ -0,0 +1,71 @@
+# Example Feature Specification
+
+**Status:** Planned
+**Version:** 1.0
+**Last Updated:** YYYY-MM-DD
+
+## Purpose
+
+This is an example specification to demonstrate the format. Replace this with your actual feature description explaining why this feature exists and what problem it solves.
+
+## User Stories
+
+- As a user, I want [action] so that [benefit]
+- As an admin, I want [action] so that [benefit]
+
+## Requirements
+
+### Functional Requirements
+- [ ] Requirement 1 - Description of what the system must do
+- [ ] Requirement 2 - Another functional requirement
+
+### Non-Functional Requirements
+- [ ] Performance: [target metrics]
+- [ ] Security: [security considerations]
+- [ ] Accessibility: [WCAG level]
+
+## Technical Notes
+
+- **Uses:** Existing patterns or components to leverage
+- **Location:** Where the code should live (e.g., `{{appDir}}/app/dashboard/`)
+- **Dependencies:** External libraries or APIs needed
+- **Database:** Schema changes required (if any)
+
+## Visual Requirements
+
+(For UI features - delete this section if backend-only)
+
+- **Layout:** Describe the layout structure and responsive behavior
+- **Components:** List the UI components needed (Button, Card, Table, etc.)
+- **Chart Types:** If applicable, specify chart types needed
+- **States:**
+  - Empty: What to show when there's no data
+  - Loading: Skeleton or spinner pattern
+  - Error: How to display errors
+- **Mobile:** How the layout adapts on small screens
+- **Reference:** Link to similar pages in the app or design references
+
+## API Endpoints
+
+(If applicable)
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/example` | Fetch example data |
+| POST | `/api/example` | Create new example |
+
+## Acceptance Criteria
+
+- [ ] Criteria 1 - Specific, testable condition
+- [ ] Criteria 2 - Another acceptance criterion
+- [ ] Criteria 3 - E2E testable scenario
+
+## Out of Scope
+
+- Feature X (planned for future iteration)
+- Integration Y (separate spec)
+
+## Open Questions
+
+- [ ] Question 1 - Decision needed
+- [ ] Question 2 - Clarification required

package/src/utils/config.ts

@@ -0,0 +1,221 @@
+/**
+ * Configuration Utilities
+ * Load and parse ralph.config.js files
+ */
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { logger } from './logger.js';
+
+/**
+ * Stack configuration in ralph.config.js
+ */
+export interface StackConfig {
+  framework: {
+    name: string;
+    version?: string;
+    variant?: string;
+  };
+  packageManager: string;
+  testing: {
+    unit: string;
+    e2e: string;
+  };
+  styling: string;
+}
+
+/**
+ * Commands configuration in ralph.config.js
+ */
+export interface CommandsConfig {
+  dev: string;
+  build: string;
+  test: string;
+  lint: string;
+  typecheck: string;
+}
+
+/**
+ * Paths configuration in ralph.config.js
+ */
+export interface PathsConfig {
+  root: string;
+  prompts: string;
+  guides: string;
+  specs: string;
+  scripts: string;
+  learnings: string;
+  agents: string;
+}
+
+/**
+ * Loop configuration in ralph.config.js
+ */
+export interface LoopConfig {
+  maxIterations: number;
+  maxE2eAttempts: number;
+  defaultModel: string;
+  planningModel: string;
+}
+
+/**
+ * Full ralph.config.js structure
+ */
+export interface RalphConfig {
+  name: string;
+  stack: StackConfig;
+  commands: CommandsConfig;
+  paths: PathsConfig;
+  loop: LoopConfig;
+}
+
+/**
+ * Default configuration values
+ */
+export const DEFAULT_CONFIG: RalphConfig = {
+  name: 'project',
+  stack: {
+    framework: {
+      name: 'unknown',
+      version: undefined,
+      variant: undefined,
+    },
+    packageManager: 'npm',
+    testing: {
+      unit: 'none',
+      e2e: 'none',
+    },
+    styling: 'css',
+  },
+  commands: {
+    dev: 'npm run dev',
+    build: 'npm run build',
+    test: 'npm test',
+    lint: 'npm run lint',
+    typecheck: 'npm run typecheck',
+  },
+  paths: {
+    root: '.ralph',
+    prompts: '.ralph/prompts',
+    guides: '.ralph/guides',
+    specs: '.ralph/specs',
+    scripts: '.ralph/scripts',
+    learnings: '.ralph/LEARNINGS.md',
+    agents: '.ralph/AGENTS.md',
+  },
+  loop: {
+    maxIterations: 10,
+    maxE2eAttempts: 5,
+    defaultModel: 'sonnet',
+    planningModel: 'opus',
+  },
+};
+
+/**
+ * Load ralph.config.js from a project directory
+ * Returns null if config file doesn't exist
+ */
+export async function loadConfig(projectRoot: string): Promise<RalphConfig | null> {
+  const configPath = join(projectRoot, 'ralph.config.js');
+
+  if (!existsSync(configPath)) {
+    return null;
+  }
+
+  try {
+    // Use dynamic import for ESM compatibility
+    // Add timestamp to bust module cache for fresh config
+    const configUrl = pathToFileURL(configPath).href + `?t=${Date.now()}`;
+    const configModule = await import(configUrl);
+    return (configModule.default || configModule) as RalphConfig;
+  } catch (error) {
+    logger.error(`Failed to load config from ${configPath}: ${error instanceof Error ? error.message : String(error)}`);
+    return null;
+  }
+}
+
+/**
+ * Load config with defaults merged in
+ */
+export async function loadConfigWithDefaults(projectRoot: string): Promise<RalphConfig> {
+  const config = await loadConfig(projectRoot);
+
+  if (!config) {
+    return DEFAULT_CONFIG;
+  }
+
+  // Deep merge with defaults
+  return {
+    name: config.name || DEFAULT_CONFIG.name,
+    stack: {
+      ...DEFAULT_CONFIG.stack,
+      ...config.stack,
+      framework: {
+        ...DEFAULT_CONFIG.stack.framework,
+        ...config.stack?.framework,
+      },
+      testing: {
+        ...DEFAULT_CONFIG.stack.testing,
+        ...config.stack?.testing,
+      },
+    },
+    commands: {
+      ...DEFAULT_CONFIG.commands,
+      ...config.commands,
+    },
+    paths: {
+      ...DEFAULT_CONFIG.paths,
+      ...config.paths,
+    },
+    loop: {
+      ...DEFAULT_CONFIG.loop,
+      ...config.loop,
+    },
+  };
+}
+
+/**
+ * Check if a ralph config exists in the project
+ */
+export function hasConfig(projectRoot: string): boolean {
+  const configPath = join(projectRoot, 'ralph.config.js');
+  return existsSync(configPath);
+}
+
+/**
+ * Get the ralph root directory from config or default
+ */
+export async function getRalphRoot(projectRoot: string): Promise<string> {
+  const config = await loadConfig(projectRoot);
+  return config?.paths?.root || '.ralph';
+}
+
+/**
+ * Get the specs directory from config or default
+ */
+export async function getSpecsDir(projectRoot: string): Promise<string> {
+  const config = await loadConfig(projectRoot);
+  return config?.paths?.specs || '.ralph/specs';
+}
+
+/**
+ * Get the scripts directory from config or default
+ */
+export async function getScriptsDir(projectRoot: string): Promise<string> {
+  const config = await loadConfig(projectRoot);
+  return config?.paths?.scripts || '.ralph/scripts';
+}
+
+/**
+ * Get loop settings with defaults
+ */
+export async function getLoopSettings(projectRoot: string): Promise<LoopConfig> {
+  const config = await loadConfig(projectRoot);
+  return {
+    maxIterations: config?.loop?.maxIterations || DEFAULT_CONFIG.loop.maxIterations,
+    maxE2eAttempts: config?.loop?.maxE2eAttempts || DEFAULT_CONFIG.loop.maxE2eAttempts,
+    defaultModel: config?.loop?.defaultModel || DEFAULT_CONFIG.loop.defaultModel,
+    planningModel: config?.loop?.planningModel || DEFAULT_CONFIG.loop.planningModel,
+  };
+}

package/src/utils/header.ts

@@ -0,0 +1,15 @@
+import cfonts from 'cfonts';
+
+/**
+ * Display the RALPH ASCII header in Simpson yellow
+ */
+export function displayHeader(): void {
+  cfonts.say('RALPH', {
+    font: 'block',
+    colors: ['#FED90F'],
+    letterSpacing: 1,
+    lineHeight: 1,
+    space: true,
+    maxLength: 0,
+  });
+}

package/src/utils/logger.ts

@@ -0,0 +1,28 @@
+import pc from 'picocolors';
+
+/**
+ * Logging utilities with colored output
+ */
+export const logger = {
+  info(message: string): void {
+    console.log(pc.blue('info'), message);
+  },
+
+  success(message: string): void {
+    console.log(pc.green('success'), message);
+  },
+
+  warn(message: string): void {
+    console.log(pc.yellow('warn'), message);
+  },
+
+  error(message: string): void {
+    console.log(pc.red('error'), message);
+  },
+
+  debug(message: string): void {
+    if (process.env.DEBUG) {
+      console.log(pc.gray('debug'), message);
+    }
+  },
+};