ralph-tool 1.0.0

package/helpers/output_formatting.jq

@@ -0,0 +1,294 @@
+# Output formatting filter for ralph loop
+# This file contains the jq filter for formatting Claude's JSON stream output
+
+# Color escape codes
+def esc(s): "\u001b[" + s + "m";
+def reset:  if $COLOR==1 then esc("0")    else "" end;
+def bold:   if $COLOR==1 then esc("1")    else "" end;
+def cyan:   if $COLOR==1 then esc("36")   else "" end;
+def yellow: if $COLOR==1 then esc("33")   else "" end;
+def green:  if $COLOR==1 then esc("32")   else "" end;
+def red:    if $COLOR==1 then esc("31")   else "" end;
+def mag:    if $COLOR==1 then esc("35")   else "" end;
+def dim:    if $COLOR==1 then esc("2")    else "" end;
+def blue:   if $COLOR==1 then esc("34")   else "" end;
+
+def hr: "────────────────────────────────────────────────────────────\n";
+
+# Extract file path from tool input
+def extract_file_path(input):
+  if input.file_path? then input.file_path
+  elif input.target_file? then input.target_file
+  elif input.file? then input.file
+  elif input.path? then input.path
+  else null
+  end;
+
+# Check if command is ralph status
+def is_ralph_status_cmd(cmd):
+  (cmd | test("ralph\\s+status"));
+
+# Extract minimal tool info for display (main agent)
+def tool_info_minimal(input; name):
+  if input.command? then
+    (input.command|tostring) as $cmd
+    | if is_ralph_status_cmd($cmd) then
+        "BASH: " + $cmd
+      else
+        ($cmd | split("\n")) as $lines
+        | if ($lines | length) > 4 then
+            (($lines[0:4] | join("\n")) + "\n...")
+          else
+            $cmd
+          end
+        | "BASH: " + .
+      end
+  else
+    (extract_file_path(input) // "") as $file
+    | if $file != null and $file != "" then
+        name + " " + $file
+      else
+        name
+      end
+  end;
+
+# Extract tool info for subagents (more detailed)
+def tool_info_subagent(input; name):
+  if input.command? then
+    (input.command|tostring) as $cmd
+    | if is_ralph_status_cmd($cmd) then
+        "BASH: " + $cmd
+      else
+        ($cmd | split("\n")) as $lines
+        | if ($lines | length) > 4 then
+            (($lines[0:4] | join("\n")) + "\n...")
+          else
+            $cmd
+          end
+        | "BASH: " + .
+      end
+  else
+    (extract_file_path(input) // "") as $file
+    | if $file != null and $file != "" then
+        name + " → " + $file
+      elif input.pattern? then
+        name + " → pattern: " + (input.pattern|tostring)
+      elif input.query? then
+        name + " → query: " + (input.query|tostring)
+      elif input.glob_pattern? then
+        name + " → glob: " + (input.glob_pattern|tostring)
+      else
+        name
+      end
+  end;
+
+# Extract parent_tool_use_id from various possible locations
+def get_parent_id:
+  if .parent_tool_use_id? and (.parent_tool_use_id != "") then
+    .parent_tool_use_id
+  elif .event?.parent_tool_use_id? and (.event.parent_tool_use_id != "") then
+    .event.parent_tool_use_id
+  elif .event?.content_block?.parent_tool_use_id? and (.event.content_block.parent_tool_use_id != "") then
+    .event.content_block.parent_tool_use_id
+  elif .message?.parent_tool_use_id? and (.message.parent_tool_use_id != "") then
+    .message.parent_tool_use_id
+  else
+    null
+  end;
+
+# Check if this is a subagent task
+def is_subagent: (get_parent_id != null);
+
+# Get subagent number from mapping
+def get_subagent_num:
+  if is_subagent and ($SUBAGENT_MAP | type == "object") then
+    get_parent_id as $id
+    | if $id and $SUBAGENT_MAP[$id] then
+        $SUBAGENT_MAP[$id]
+      else
+        null
+      end
+  else
+    null
+  end;
+
+# Subagent name list
+def subagent_names:
+  ["BOB", "BEN", "TIBO", "ALONSO", "JULIAN", "JULIA", "MELISSA", "TALIA", "CENK", "VIKRAM", "ANKIT", "JULIETTE", "ANICA", "CHUBS", "STILGARD", "GERARD"];
+
+# Get short ID suffix from parent_tool_use_id
+def get_short_id:
+  get_parent_id as $id
+  | if $id and ($id | length) > 4 then
+      $id[-4:]
+    elif $id then
+      $id
+    else
+      null
+    end;
+
+# Get deterministic name from parent_tool_use_id
+def get_subagent_name:
+  get_parent_id as $id
+  | if $id then
+      ($id | explode | add) as $hash
+      | subagent_names[$hash % (subagent_names | length)]
+    else
+      null
+    end;
+
+# Format subagent label
+def subagent_label:
+  if is_subagent then
+    get_subagent_num as $num
+    | if $num then
+        blue + bold + "[SUBAGENT #\($num)] " + reset
+      else
+        get_subagent_name as $name
+        | get_short_id as $short
+        | if $name and $short then
+            blue + bold + "[\($name) @\($short)] " + reset
+          elif $name then
+            blue + bold + "[\($name)] " + reset
+          elif $short then
+            blue + bold + "[SUBAGENT @\($short)] " + reset
+          else
+            blue + bold + "[SUBAGENT] " + reset
+          end
+      end
+  else
+    ""
+  end;
+
+# Format tool result content
+def format_tool_result(content; is_ralph_status):
+  if content | type == "string" then
+    if is_ralph_status then
+      (content | split("\n") | .[0:4] | join("\n"))
+    else
+      (content | split("\n") | .[0]) as $first
+      | if ($first|length) > 100 then
+          $first[0:100] + "..."
+        else
+          $first
+        end
+    end
+  else
+    "[OK]"
+  end;
+
+# Format duration from milliseconds
+def format_duration(ms):
+  if ms == null or ms == 0 then
+    "0s"
+  else
+    (ms / 1000 | floor) as $total_secs
+    | ($total_secs / 3600 | floor) as $hours
+    | (($total_secs % 3600) / 60 | floor) as $minutes
+    | ($total_secs % 60) as $seconds
+    | (if $hours > 0 then "\($hours)h " else "" end) +
+      (if $minutes > 0 then "\($minutes)m " else "" end) +
+      "\($seconds)s"
+  end;
+
+# Format cost to 2 decimal places
+def format_cost(cost):
+  if cost == null then
+    "$0.00"
+  else
+    (cost * 100 | round / 100) as $rounded
+    | ($rounded | tostring) as $str
+    | if ($str | contains(".")) then
+        ($str | split(".")) as $parts
+        | "$" + $parts[0] + "." + (($parts[1] // "") | .[0:2] | if length < 2 then . + ("0" * (2 - length)) else . end)
+      else
+        "$" + $str + ".00"
+      end
+  end;
+
+# Main filter
+try
+  if .type=="system" and .subtype=="init" then
+    bold + cyan + "[MODEL] " + reset + bold + (.model // "unknown") + reset + "\n"
+
+  elif .type=="stream_event"
+    and .event.type=="content_block_start"
+    and .event.content_block.type=="text"
+    and .event.index == 0 then
+    "\n" + dim + ">>>    " + reset
+
+  elif .type=="stream_event"
+    and .event.type=="content_block_start"
+    and .event.content_block.type=="tool_use" then
+    subagent_label +
+    mag + bold + "TOOL: " + reset + mag +
+    (if (is_subagent) then
+      tool_info_subagent(.event.content_block.input; .event.content_block.name)
+    else
+      tool_info_minimal(.event.content_block.input; .event.content_block.name)
+    end) +
+    reset + "\n"
+
+  elif .type=="assistant"
+    and (.message | type == "object")
+    and (.message.content | type == "array")
+    and (.message.content[]?.type=="tool_use") then
+    subagent_label +
+    (.message.content[]
+      | select(.type=="tool_use")
+      | if (.input.command? != null) then
+          yellow + bold + "BASH: " + reset + yellow +
+          (.input.command|tostring) + reset + "\n"
+        elif (is_subagent) then
+          yellow + bold + "TOOL: " + reset + yellow +
+          tool_info_subagent(.input; .name) + reset + "\n"
+        elif (.input.file_path? or .input.target_file? or .input.file?) then
+          yellow + bold + "TOOL: " + reset + yellow +
+          tool_info_minimal(.input; .name) + reset + "\n"
+        else empty end)
+
+  elif .type=="user"
+    and (.message | type == "object")
+    and (.message.content | type == "array")
+    and (.message.content[0]?.type=="tool_result") then
+    (if (is_subagent) then
+      empty
+    else
+      (.message.content[0].content | type == "string" and test("╔|╗|╚|╝|║|═|Feature:|Task:|Status:")) as $is_ralph_status
+      | cyan + bold + "RESULT:" + reset +
+      (if $is_ralph_status then
+        "\n" + format_tool_result(.message.content[0].content; $is_ralph_status)
+      elif (.message.content[0].content | type == "string") then
+        " " + format_tool_result(.message.content[0].content; false)
+      else
+        " [OK]"
+      end) + "\n"
+    end)
+
+  elif .type=="stream_event"
+    and .event.type=="content_block_delta"
+    and .event.delta.type=="text_delta"
+    and .event.index == 0 then
+    .event.delta.text | gsub("\n"; "\n       ")
+
+  elif .type=="stream_event"
+    and .event.type=="content_block_stop"
+    and .event.index == 0 then
+    "\n\n"
+
+  elif .type=="stream_event" and .event.type=="message_stop" then
+    empty
+
+  elif .type=="result" then
+    hr +
+    green + bold + "[COMPLETE] ITERATION COMPLETED" + reset + "\n" +
+    "  Turns:    \(.num_turns)  |  Duration:  \(format_duration(.duration_ms))  |  Cost:  \(format_cost(.total_cost_usd))\n" +
+    dim +
+    "  Tokens:   in=\(.usage.input_tokens)  out=\(.usage.output_tokens)  cache_read=\(.usage.cache_read_input_tokens)  cache_write=\(.usage.cache_creation_input_tokens)\n" +
+    reset +
+    hr
+
+  else
+    empty
+  end
+catch empty

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "ralph-tool",
+  "version": "1.0.0",
+  "description": "AI-powered task automation CLI for software development",
+  "main": "bin/ralph.js",
+  "bin": {
+    "ralph": "./bin/ralph.js"
+  },
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js"
+  },
+  "keywords": [
+    "ai",
+    "automation",
+    "claude",
+    "claude-code",
+    "cli",
+    "task-runner",
+    "developer-tools",
+    "code-generation",
+    "orchestration"
+  ],
+  "author": "Thibault Knobloch",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Thibault-Knobloch/ralph-tool.git"
+  },
+  "homepage": "https://github.com/Thibault-Knobloch/ralph-tool#readme",
+  "bugs": {
+    "url": "https://github.com/Thibault-Knobloch/ralph-tool/issues"
+  },
+  "dependencies": {
+    "commander": "^12.0.0",
+    "chalk": "^4.1.2"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "bin/",
+    "scripts/",
+    "helpers/",
+    "templates/",
+    "Dockerfile",
+    "docker-compose.yaml"
+  ]
+}

package/scripts/check_feature_completion.sh

@@ -0,0 +1,116 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Ralph Auto Feature Completion Check
+# Called automatically after each loop iteration
+# Environment: RALPH_HOME, PROJECT_RALPH_DIR
+
+RALPH_NAME="${1:-RALPH}"
+
+RALPH_HOME="${RALPH_HOME:?RALPH_HOME not set}"
+PROJECT_RALPH_DIR="${PROJECT_RALPH_DIR:?PROJECT_RALPH_DIR not set}"
+
+PRD_FILE="${PROJECT_RALPH_DIR}/tasks/prd.json"
+PROGRESS_FILE="${PROJECT_RALPH_DIR}/tasks/progress.txt"
+PROGRESS_ARCHIVE_DIR="${PROJECT_RALPH_DIR}/logs/progress"
+
+# Verify PRD file exists
+if [[ ! -f "$PRD_FILE" ]]; then
+    exit 0
+fi
+
+# Check if multi-feature format
+IS_MULTI_FEATURE=$(jq 'has("features")' "$PRD_FILE" 2>/dev/null)
+if [[ "$IS_MULTI_FEATURE" != "true" ]]; then
+    exit 0
+fi
+
+# Find current feature (first incomplete one)
+CURRENT_FEATURE=$(jq -r '.features[] | select(.feature_completed == false) | .id' "$PRD_FILE" 2>/dev/null | head -1)
+
+if [[ -z "$CURRENT_FEATURE" ]]; then
+    exit 0
+fi
+
+# Check if all tasks in current feature are completed
+ALL_TASKS_DONE=$(jq --arg id "$CURRENT_FEATURE" '
+    .features[] | select(.id == $id) |
+    (.tasks | length > 0) and (.tasks | all(.completed == true))
+' "$PRD_FILE" 2>/dev/null)
+
+if [[ "$ALL_TASKS_DONE" != "true" ]]; then
+    exit 0
+fi
+
+# Check if feature is already marked complete
+FEATURE_ALREADY_COMPLETE=$(jq --arg id "$CURRENT_FEATURE" '
+    .features[] | select(.id == $id) | .feature_completed
+' "$PRD_FILE" 2>/dev/null)
+
+if [[ "$FEATURE_ALREADY_COMPLETE" == "true" ]]; then
+    exit 0
+fi
+
+# === All tasks done, feature not yet marked complete - proceed ===
+
+# Get feature name for archive filename
+FEATURE_NAME=$(jq -r --arg id "$CURRENT_FEATURE" '.features[] | select(.id == $id) | .name' "$PRD_FILE" 2>/dev/null)
+FEATURE_NAME_KEBAB=$(echo "$FEATURE_NAME" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr -cd '[:alnum:]-')
+
+echo ""
+echo "═══════════════════════════════════════════════════════════════"
+echo "  AUTO-COMPLETING FEATURE: $FEATURE_NAME"
+echo "═══════════════════════════════════════════════════════════════"
+echo ""
+
+# Step 1: Update prd.json - set feature_completed: true
+echo "[1/4] Marking feature as completed in prd.json..."
+jq --arg id "$CURRENT_FEATURE" '(.features[] | select(.id == $id) | .feature_completed) = true' "$PRD_FILE" > "${PRD_FILE}.tmp"
+mv "${PRD_FILE}.tmp" "$PRD_FILE"
+echo "  ✓ Feature $CURRENT_FEATURE marked as completed"
+
+# Step 2: Git operations
+if [[ "${RALPH_LOCAL:-}" == "1" ]]; then
+    echo "[2/4] Committing changes locally (--local mode, skipping branch/push/PR)..."
+    git add -A -- ':!.ralph'
+    git commit -m "RALPH: ${FEATURE_NAME}" || echo "  ⓘ Nothing to commit"
+    echo "  ✓ Changes committed on current branch"
+else
+    echo "[2/4] Creating git branch and PR for feature..."
+    "${RALPH_HOME}/scripts/git_feature_complete.sh" "$FEATURE_NAME" "$FEATURE_NAME_KEBAB" "$RALPH_NAME" "$PROGRESS_FILE"
+fi
+
+# Step 3: Archive progress.txt
+echo "[3/4] Archiving progress.txt..."
+mkdir -p "$PROGRESS_ARCHIVE_DIR"
+
+if [[ -f "$PROGRESS_FILE" && -s "$PROGRESS_FILE" ]]; then
+    TIMESTAMP=$(date +%Y%m%d_%H%M%S)
+    ARCHIVE_FILE="${PROGRESS_ARCHIVE_DIR}/${FEATURE_NAME_KEBAB}-progress-${TIMESTAMP}.txt"
+    cp "$PROGRESS_FILE" "$ARCHIVE_FILE"
+    echo "  ✓ Archived to: $ARCHIVE_FILE"
+else
+    echo "  ⓘ No progress.txt to archive (empty or missing)"
+fi
+
+# Step 4: Clear progress.txt for next feature
+echo "[4/4] Clearing progress.txt for next feature..."
+: > "$PROGRESS_FILE"
+echo "  ✓ progress.txt cleared"
+
+echo ""
+echo "═══════════════════════════════════════════════════════════════"
+echo "  FEATURE '$FEATURE_NAME' AUTO-COMPLETED"
+echo "═══════════════════════════════════════════════════════════════"
+
+# Check if there's a next feature
+NEXT_FEATURE=$(jq -r '.features[] | select(.feature_completed == false) | .name' "$PRD_FILE" 2>/dev/null | head -1)
+if [[ -n "$NEXT_FEATURE" ]]; then
+    echo "  Next feature: $NEXT_FEATURE"
+    echo ""
+    exit 0
+else
+    echo "  🎉 ALL FEATURES COMPLETED!"
+    echo ""
+    exit 99
+fi

package/scripts/cleanup.sh

@@ -0,0 +1,179 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Ralph Cleanup - Archive Completed Features
+# Environment: RALPH_HOME, PROJECT_RALPH_DIR
+
+RALPH_HOME="${RALPH_HOME:?RALPH_HOME not set}"
+PROJECT_RALPH_DIR="${PROJECT_RALPH_DIR:?PROJECT_RALPH_DIR not set}"
+
+TASKS_DIR="${PROJECT_RALPH_DIR}/tasks"
+NEW_TASKS_DIR="${TASKS_DIR}/1_new_tasks"
+DONE_TASKS_DIR="${TASKS_DIR}/2_done_tasks"
+PROGRESS_DIR="${PROJECT_RALPH_DIR}/logs/progress"
+PRD_FILE="${TASKS_DIR}/prd.json"
+
+FEATURE_ARG="${1:-}"
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+LIGHT_BLUE='\033[1;36m'
+NC='\033[0m'
+
+echo ""
+echo -e "${LIGHT_BLUE}Ralph Cleanup - Archive Completed Features${NC}"
+echo ""
+
+# 1. Clear iteration logs
+echo "[1/4] Clearing iteration logs..."
+"${RALPH_HOME}/scripts/clear.sh" > /dev/null 2>&1 || true
+echo -e "  ${GREEN}✓${NC} Logs cleared"
+
+# 2. Parse prd.json and find completed features
+echo "[2/4] Finding completed features..."
+
+if [[ ! -f "$PRD_FILE" ]]; then
+    echo -e "${RED}Error: prd.json not found${NC}"
+    exit 1
+fi
+
+# Get completed features as JSON array
+COMPLETED_FEATURES=$(jq '[.features[] | select(.feature_completed == true)]' "$PRD_FILE")
+COMPLETED_COUNT=$(echo "$COMPLETED_FEATURES" | jq 'length')
+
+if [[ "$COMPLETED_COUNT" -eq 0 ]]; then
+    echo -e "${YELLOW}No completed features to cleanup${NC}"
+    exit 0
+fi
+
+# If feature arg provided, filter to just that feature
+if [[ -n "$FEATURE_ARG" ]]; then
+    ARG_LOWER=$(echo "$FEATURE_ARG" | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
+
+    MATCHED_FEATURE=$(echo "$COMPLETED_FEATURES" | jq --arg arg "$ARG_LOWER" '
+        [.[] | select(
+            (.name | ascii_downcase | gsub(" "; "-")) == $arg or
+            (.name | ascii_downcase | gsub(" "; "-") | contains($arg)) or
+            (.id | ascii_downcase) == $arg
+        )] | .[0] // empty
+    ')
+
+    if [[ -z "$MATCHED_FEATURE" || "$MATCHED_FEATURE" == "null" ]]; then
+        echo -e "${RED}Feature '${FEATURE_ARG}' not found in completed features${NC}"
+        echo "Completed features:"
+        echo "$COMPLETED_FEATURES" | jq -r '.[].name' | sed 's/^/  - /'
+        exit 1
+    fi
+
+    COMPLETED_FEATURES="[$MATCHED_FEATURE]"
+    COMPLETED_COUNT=1
+fi
+
+echo -e "  ${GREEN}✓${NC} Found ${COMPLETED_COUNT} completed feature(s)"
+
+# Helper: Convert feature name to slug
+to_slug() {
+    echo "$1" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | sed 's/[^a-z0-9-]//g'
+}
+
+# Helper: Convert slug to camelCase
+to_camel_case() {
+    echo "$1" | awk -F'-' '{
+        for(i=1; i<=NF; i++) {
+            if(i==1) printf "%s", $i
+            else printf "%s", toupper(substr($i,1,1)) substr($i,2)
+        }
+    }'
+}
+
+# 3. Process each feature
+echo "[3/4] Archiving features..."
+CLEANED_FEATURES=()
+CLEANED_IDS=()
+
+for i in $(seq 0 $((COMPLETED_COUNT - 1))); do
+    FEATURE=$(echo "$COMPLETED_FEATURES" | jq ".[$i]")
+    FEATURE_NAME=$(echo "$FEATURE" | jq -r '.name')
+    FEATURE_ID=$(echo "$FEATURE" | jq -r '.id')
+    SPEC_FILE=$(echo "$FEATURE" | jq -r '.tasks[0].specFile // empty')
+
+    SLUG=$(to_slug "$FEATURE_NAME")
+    CAMEL_CASE=$(to_camel_case "$SLUG")
+
+    echo "  Processing: ${FEATURE_NAME}"
+
+    # Create done folder
+    DONE_FOLDER="${DONE_TASKS_DIR}/${CAMEL_CASE}"
+    mkdir -p "$DONE_FOLDER"
+
+    # Move spec file
+    SPEC_MOVED=false
+
+    if [[ -n "$SPEC_FILE" ]]; then
+        SPEC_PATH="${PROJECT_RALPH_DIR}/../${SPEC_FILE}"
+        if [[ -f "$SPEC_PATH" ]]; then
+            mv "$SPEC_PATH" "$DONE_FOLDER/"
+            SPEC_MOVED=true
+        fi
+    fi
+
+    if [[ "$SPEC_MOVED" == false ]]; then
+        FOUND_SPEC=$(find "$NEW_TASKS_DIR" -maxdepth 1 -name "*${SLUG}*" -type f 2>/dev/null | head -1)
+        if [[ -n "$FOUND_SPEC" && -f "$FOUND_SPEC" ]]; then
+            mv "$FOUND_SPEC" "$DONE_FOLDER/"
+            SPEC_MOVED=true
+        fi
+    fi
+
+    if [[ "$SPEC_MOVED" == true ]]; then
+        echo -e "    ${GREEN}✓${NC} Moved spec file"
+    else
+        echo -e "    ${YELLOW}⚠${NC} Spec file not found"
+    fi
+
+    # Move progress file(s)
+    if [[ -d "$PROGRESS_DIR" ]]; then
+        PROGRESS_MOVED=false
+        while IFS= read -r -d '' pfile; do
+            if [[ -f "$pfile" ]]; then
+                mv "$pfile" "$DONE_FOLDER/"
+                PROGRESS_MOVED=true
+            fi
+        done < <(find "$PROGRESS_DIR" -maxdepth 1 -name "*${SLUG}*" -type f -print0 2>/dev/null)
+
+        if [[ "$PROGRESS_MOVED" == true ]]; then
+            echo -e "    ${GREEN}✓${NC} Moved progress file(s)"
+        else
+            echo -e "    ${YELLOW}⚠${NC} No progress files found"
+        fi
+    else
+        echo -e "    ${YELLOW}⚠${NC} Progress directory not found"
+    fi
+
+    CLEANED_FEATURES+=("$CAMEL_CASE")
+    CLEANED_IDS+=("$FEATURE_ID")
+done
+
+# 4. Update prd.json - remove cleaned features
+echo "[4/4] Updating prd.json..."
+
+if [[ -n "$FEATURE_ARG" ]]; then
+    FEATURE_ID=$(echo "$COMPLETED_FEATURES" | jq -r '.[0].id')
+    jq --arg id "$FEATURE_ID" '.features = [.features[] | select(.id != $id)]' "$PRD_FILE" > "${PRD_FILE}.tmp"
+else
+    jq '.features = [.features[] | select(.feature_completed != true)]' "$PRD_FILE" > "${PRD_FILE}.tmp"
+fi
+
+mv "${PRD_FILE}.tmp" "$PRD_FILE"
+echo -e "  ${GREEN}✓${NC} prd.json updated"
+
+# Summary
+echo ""
+echo -e "${GREEN}Cleanup complete!${NC}"
+echo "Archived ${#CLEANED_FEATURES[@]} feature(s):"
+for f in "${CLEANED_FEATURES[@]}"; do
+    echo "  - 2_done_tasks/${f}/"
+done
+echo ""

package/scripts/clear.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Ralph Clear - Delete all log files (keeps progress folder)
+# Environment: PROJECT_RALPH_DIR
+
+PROJECT_RALPH_DIR="${PROJECT_RALPH_DIR:?PROJECT_RALPH_DIR not set}"
+LOG_DIR="${PROJECT_RALPH_DIR}/logs"
+
+# Color support (only if TTY)
+if [[ -t 1 ]]; then
+  GREEN="\033[32m"
+  YELLOW="\033[33m"
+  RESET="\033[0m"
+else
+  GREEN=""
+  YELLOW=""
+  RESET=""
+fi
+
+# Check if logs directory exists
+if [[ ! -d "$LOG_DIR" ]]; then
+    echo "Logs directory not found: $LOG_DIR"
+    exit 0
+fi
+
+# Count files to be deleted (excluding progress directory)
+FILE_COUNT=$(find "$LOG_DIR" -maxdepth 1 -type f | wc -l | tr -d ' ')
+
+if [[ "$FILE_COUNT" -eq 0 ]]; then
+    echo -e "${YELLOW}No log files to clear.${RESET}"
+    exit 0
+fi
+
+# Delete all files in logs directory (but not subdirectories like progress)
+find "$LOG_DIR" -maxdepth 1 -type f -delete
+
+echo -e "${GREEN}Cleared ${FILE_COUNT} log files.${RESET}"