minimal-agent 0.8.2 → 0.9.0

package/plugins/ralph-wiggum/commands/help.md

@@ -1,137 +0,0 @@
----
-description: "Explain Ralph Wiggum technique and available commands"
----
-
-# Ralph Wiggum Plugin Help
-
-Please explain the following to the user:
-
-## What is the Ralph Wiggum Technique?
-
-The Ralph Wiggum technique is an iterative development methodology based on continuous AI loops, pioneered by Geoffrey Huntley.
-
-**Core concept:**
-```bash
-while :; do
-  cat PROMPT.md | claude-code --continue
-done
-```
-
-The same prompt is fed to Claude repeatedly. The "self-referential" aspect comes from Claude seeing its own previous work in the files and git history, not from feeding output back as input.
-
-**Each iteration:**
-1. Claude receives the SAME prompt
-2. Works on the task, modifying files
-3. Tries to exit
-4. Stop hook intercepts and feeds the same prompt again
-5. Claude sees its previous work in the files
-6. Iteratively improves until completion
-
-The technique is described as "deterministically bad in an undeterministic world" - failures are predictable, enabling systematic improvement through prompt tuning.
-
-## Available Commands
-
-### /ralph-loop <PROMPT> [OPTIONS]
-
-Start a Ralph loop in your current session.
-
-**Usage:**
-```
-/ralph-loop "Refactor the cache layer" --max-iterations 20
-/ralph-loop "Add tests" --completion-promise "TESTS COMPLETE"
-```
-
-**Options:**
-- `--max-iterations <n>` - Max iterations before auto-stop (default: 50, hard cap: 200)
-- `--completion-promise <text>` - Custom phrase to signal completion (now fully active; default phrases DONE/COMPLETE/GOAL_COMPLETE also work)
-- `--verify "<CHECK>"` - Completion gate: ALL checks must pass after the promise tag before the loop truly exits. Repeatable. Supported CHECK types:
-  - `shell:<cmd>` — exit code 0 = pass (Windows: `cmd /c`, others: `bash -c`)
-  - `file_exists:<path>` — file must exist
-  - `file_contains:<file>:<regex>` — file content matches regex
-  - `test_count:<min>` — `bun test` pass count ≥ min
-
-**How it works:**
-1. Creates `.claude/.ralph-loop.local.md` state file
-2. You work on the task
-3. When you try to exit, stop hook intercepts
-4. Same prompt fed back
-5. You see your previous work
-6. Continues until promise detected or max iterations
-
----
-
-### /cancel-ralph
-
-Cancel an active Ralph loop (removes the loop state file).
-
-**Usage:**
-```
-/cancel-ralph
-```
-
-**How it works:**
-- Checks for active loop state file
-- Removes `.claude/.ralph-loop.local.md`
-- Reports cancellation with iteration count
-
----
-
-## Key Concepts
-
-### Completion Promises
-
-To signal completion, Claude outputs a `<promise>` tag:
-
-```
-<promise>TASK COMPLETE</promise>
-```
-
-The driver looks for this tag (or the custom `--completion-promise` phrase). This signals intent to complete — the loop then runs any `--verify` checks before truly exiting.
-
-**Escape hatches** (output these tags to exit early):
-- `<PROMISE>NEED_REPLAN</PROMISE>` — current approach is unworkable, replan with same goal
-- `<PROMISE>NEED_GOAL_REVISION</PROMISE>` — the goal itself is unreachable; loop stops cleanly for human review (distinct from NEED_REPLAN: that swaps approach, this flags the goal)
-
-**Lessons tagging**: wrap insights with `<learning>…</learning>` and the driver auto-archives them to `learnings.md` for reuse in subsequent iterations.
-
-### Self-Reference Mechanism
-
-The "loop" doesn't mean Claude talks to itself. It means:
-- Same prompt repeated
-- Claude's work persists in files
-- Each iteration sees previous attempts
-- Builds incrementally toward goal
-
-## Example
-
-### Interactive Bug Fix
-
-```
-/ralph-loop "Fix the token refresh logic in auth.ts. Output <promise>FIXED</promise> when all tests pass." --completion-promise "FIXED" --max-iterations 10
-```
-
-You'll see Ralph:
-- Attempt fixes
-- Run tests
-- See failures
-- Iterate on solution
-- In your current session
-
-## When to Use Ralph
-
-**Good for:**
-- Well-defined tasks with clear success criteria
-- Tasks requiring iteration and refinement
-- Iterative development with self-correction
-- Greenfield projects
-
-**Not good for:**
-- Tasks requiring human judgment or design decisions
-- One-shot operations
-- Tasks with unclear success criteria
-- Debugging production issues (use targeted debugging instead)
-
-## Learn More
-
-- Original technique: https://ghuntley.com/ralph/
-- Ralph Orchestrator: https://github.com/mikeyobrien/ralph-orchestrator

package/plugins/ralph-wiggum/commands/ralph-loop.md

@@ -1,85 +0,0 @@
----
-description: "Start Ralph Wiggum loop in current session"
-argument-hint: "PROMPT [--max-iterations N] [--completion-promise TEXT] [--verify \"CHECK\" ...]"
-allowed-tools: ["Bash(${CLAUDE_PLUGIN_ROOT}/scripts/setup-ralph-loop.sh:*)"]
-hide-from-slash-command-tool: "true"
----
-
-# Ralph Loop Command
-
-<!--
-  minimal-agent 注意：以下 ```! ``` 块是 Claude Code 专有的 shell-on-command
-  语法，minimal-agent **不会执行**它。GoalState 的初始化（goal.md / phase.md
-  / completion.md 等）由本插件的 plugin.ts 在进循环前自动完成，
-  不需要 setup 脚本。该块保留在这里只是为了与原版 Claude Code 兼容。
--->
-
-Execute the setup script to initialize the Ralph loop:
-
-```!
-"${CLAUDE_PLUGIN_ROOT}/scripts/setup-ralph-loop.sh" $ARGUMENTS
-```
-
-Please work on the task. When you try to exit, the Ralph loop will feed the SAME PROMPT back to you for the next iteration. You'll see your previous work in files and git history, allowing you to iterate and improve.
-
-CRITICAL RULE: If a completion promise is set, you may ONLY output it when the statement is completely and unequivocally TRUE. Do not output false promises to escape the loop, even if you think you're stuck or should exit for other reasons. The loop is designed to continue until genuine completion.
-
----
-
-## 本插件管理的状态文件
-
-`.minimal-agent-ralph-wiggum/` 目录下的所有文件（goal.md / phase.md / completion.md /
-progress.md / learnings.md / decisions.md）**由本插件自动创建并维护**，你不需要主动
-读写它们。每轮迭代开始时，插件会把当前目标、阶段、最近进度、关键决策、教训自动拼接到
-你的 prompt 头部（freshContext），你**专注按头部信息行动**即可。
-
-## 阶段工作流
-
-循环会自动管理阶段转换（PLAN → BUILD → VERIFY → HEAL → DONE），但你应主动配合当前阶段：
-
-- **PLAN 阶段**：分析任务、拆解步骤、识别风险
-- **BUILD 阶段**：按计划实现代码，每次聚焦一个子任务
-- **VERIFY 阶段**：运行测试、检查输出、验证功能
-- **HEAL 阶段**：定位问题根因、修复 bug、避免回归
-
-## 完成哨兵
-
-当且仅当任务真正完成时，输出（驱动进入验证门）：
-```
-<promise>DONE</promise>
-```
-也可使用 `--completion-promise` 指定的自定义短语，驱动同样认可。
-
-如果发现**当前方案**根本不可行，需要换方案重新规划（目标不变）：
-```
-<PROMISE>NEED_REPLAN</PROMISE>
-```
-
-如果**目标本身**有问题、无法用任何方案达成，需要人工修订目标时（独立逃生门，循环干净停止）：
-```
-<PROMISE>NEED_GOAL_REVISION</PROMISE>
-```
-> 区别：NEED_REPLAN = 换方案（目标不变）；NEED_GOAL_REVISION = 目标本身有问题，请人工介入。
-
-## 验证门 --verify
-
-命中完成哨兵后，驱动会运行所有 `--verify` CHECK，**全部通过才真正退出**，否则回 BUILD 继续。
-可重复多次，支持 4 种 CHECK 类型：
-
-- `shell:<命令>` —— 退出码 0 = 通过（Windows 走 `cmd /c`，其余 `bash -c`）
-- `file_exists:<路径>` —— 文件存在
-- `file_contains:<文件>:<正则>` —— 文件内容匹配正则
-- `test_count:<最小数>` —— 跑 `bun test`，统计到的通过数 ≥ 最小数
-
-示例：
-```
-/ralph-loop "实现并测试缓存层" --verify "shell:bun test" --verify "file_exists:src/cache.ts"
-```
-
-## 踩坑记录
-
-如果在工作中发现任何值得记录的教训（坑、陷阱、最佳实践），用 `<learning>…</learning>` 标记：
-```
-<learning>直接写文件前必须先 Read，否则 Edit 会报错</learning>
-```
-驱动每轮自动把 learning 存档到 `.minimal-agent-ralph-wiggum/learnings.md`，后续迭代会自动读入上下文复用。

package/plugins/ralph-wiggum/hooks/hooks.json

@@ -1,15 +0,0 @@
-{
-  "description": "Ralph Wiggum plugin stop hook for self-referential loops",
-  "hooks": {
-    "Stop": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/stop-hook.sh"
-          }
-        ]
-      }
-    ]
-  }
-}

package/plugins/ralph-wiggum/hooks/stop-hook.sh

@@ -1,191 +0,0 @@
-#!/bin/bash
-
-# Ralph Wiggum Stop Hook
-# Prevents session exit when a ralph-loop is active
-# Feeds Claude's output back as input to continue the loop
-#
-# NOTE (minimal-agent):
-#   This hook is the original Claude Code contract — kept here so the plugin
-#   stays portable to upstream. In minimal-agent the loop is driven natively
-#   by src/plugins/pluginRunner.ts; this hook is consulted as an *advisory*
-#   signal (block → inject reason into next iteration; pass / errors → no
-#   effect on loop termination). The loop's real exit conditions are:
-#     - <promise>DONE</promise> sentinel + verification pass
-#     - --max-iterations reached
-#     - user abort / NEED_REPLAN
-#   On Windows minimal-agent skips this hook entirely (bash unavailable).
-#   The .minimal-agent/ralph-loop.local.md state file referenced below is
-#   NOT created by minimal-agent — GoalState writes goal.md/phase.md/etc
-#   instead, so this hook simply exits 0 in minimal-agent runs.
-
-set -euo pipefail
-
-# Read hook input from stdin (advanced stop hook API)
-HOOK_INPUT=$(cat)
-
-# Check if ralph-loop is active
-RALPH_STATE_FILE=".minimal-agent/ralph-loop.local.md"
-
-if [[ ! -f "$RALPH_STATE_FILE" ]]; then
-  # No active loop - allow exit
-  exit 0
-fi
-
-# Parse markdown frontmatter (YAML between ---) and extract values
-FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$RALPH_STATE_FILE")
-ITERATION=$(echo "$FRONTMATTER" | grep '^iteration:' | sed 's/iteration: *//')
-MAX_ITERATIONS=$(echo "$FRONTMATTER" | grep '^max_iterations:' | sed 's/max_iterations: *//')
-# Extract completion_promise and strip surrounding quotes if present
-COMPLETION_PROMISE=$(echo "$FRONTMATTER" | grep '^completion_promise:' | sed 's/completion_promise: *//' | sed 's/^"\(.*\)"$/\1/')
-
-# Validate numeric fields before arithmetic operations
-if [[ ! "$ITERATION" =~ ^[0-9]+$ ]]; then
-  echo "⚠️  Ralph loop: State file corrupted" >&2
-  echo "   File: $RALPH_STATE_FILE" >&2
-  echo "   Problem: 'iteration' field is not a valid number (got: '$ITERATION')" >&2
-  echo "" >&2
-  echo "   This usually means the state file was manually edited or corrupted." >&2
-  echo "   Ralph loop is stopping. Run /ralph-loop again to start fresh." >&2
-  rm "$RALPH_STATE_FILE"
-  exit 0
-fi
-
-if [[ ! "$MAX_ITERATIONS" =~ ^[0-9]+$ ]]; then
-  echo "⚠️  Ralph loop: State file corrupted" >&2
-  echo "   File: $RALPH_STATE_FILE" >&2
-  echo "   Problem: 'max_iterations' field is not a valid number (got: '$MAX_ITERATIONS')" >&2
-  echo "" >&2
-  echo "   This usually means the state file was manually edited or corrupted." >&2
-  echo "   Ralph loop is stopping. Run /ralph-loop again to start fresh." >&2
-  rm "$RALPH_STATE_FILE"
-  exit 0
-fi
-
-# Check if max iterations reached
-if [[ $MAX_ITERATIONS -gt 0 ]] && [[ $ITERATION -ge $MAX_ITERATIONS ]]; then
-  echo "🛑 Ralph loop: Max iterations ($MAX_ITERATIONS) reached."
-  rm "$RALPH_STATE_FILE"
-  exit 0
-fi
-
-# Get transcript path from hook input
-TRANSCRIPT_PATH=$(echo "$HOOK_INPUT" | jq -r '.transcript_path')
-
-if [[ ! -f "$TRANSCRIPT_PATH" ]]; then
-  echo "⚠️  Ralph loop: Transcript file not found" >&2
-  echo "   Expected: $TRANSCRIPT_PATH" >&2
-  echo "   This is unusual and may indicate a Claude Code internal issue." >&2
-  echo "   Ralph loop is stopping." >&2
-  rm "$RALPH_STATE_FILE"
-  exit 0
-fi
-
-# Read last assistant message from transcript (JSONL format - one JSON per line)
-# First check if there are any assistant messages
-if ! grep -q '"role":"assistant"' "$TRANSCRIPT_PATH"; then
-  echo "⚠️  Ralph loop: No assistant messages found in transcript" >&2
-  echo "   Transcript: $TRANSCRIPT_PATH" >&2
-  echo "   This is unusual and may indicate a transcript format issue" >&2
-  echo "   Ralph loop is stopping." >&2
-  rm "$RALPH_STATE_FILE"
-  exit 0
-fi
-
-# Extract last assistant message with explicit error handling
-LAST_LINE=$(grep '"role":"assistant"' "$TRANSCRIPT_PATH" | tail -1)
-if [[ -z "$LAST_LINE" ]]; then
-  echo "⚠️  Ralph loop: Failed to extract last assistant message" >&2
-  echo "   Ralph loop is stopping." >&2
-  rm "$RALPH_STATE_FILE"
-  exit 0
-fi
-
-# Parse JSON with error handling
-LAST_OUTPUT=$(echo "$LAST_LINE" | jq -r '
-  .message.content |
-  map(select(.type == "text")) |
-  map(.text) |
-  join("\n")
-' 2>&1)
-
-# Check if jq succeeded
-if [[ $? -ne 0 ]]; then
-  echo "⚠️  Ralph loop: Failed to parse assistant message JSON" >&2
-  echo "   Error: $LAST_OUTPUT" >&2
-  echo "   This may indicate a transcript format issue" >&2
-  echo "   Ralph loop is stopping." >&2
-  rm "$RALPH_STATE_FILE"
-  exit 0
-fi
-
-if [[ -z "$LAST_OUTPUT" ]]; then
-  echo "⚠️  Ralph loop: Assistant message contained no text content" >&2
-  echo "   Ralph loop is stopping." >&2
-  rm "$RALPH_STATE_FILE"
-  exit 0
-fi
-
-# Check for completion promise (only if set)
-if [[ "$COMPLETION_PROMISE" != "null" ]] && [[ -n "$COMPLETION_PROMISE" ]]; then
-  # Extract text from <promise> tags using Perl for multiline support
-  # -0777 slurps entire input, s flag makes . match newlines
-  # .*? is non-greedy (takes FIRST tag), whitespace normalized
-  PROMISE_TEXT=$(echo "$LAST_OUTPUT" | perl -0777 -pe 's/.*?<promise>(.*?)<\/promise>.*/$1/s; s/^\s+|\s+$//g; s/\s+/ /g' 2>/dev/null || echo "")
-
-  # Use = for literal string comparison (not pattern matching)
-  # == in [[ ]] does glob pattern matching which breaks with *, ?, [ characters
-  if [[ -n "$PROMISE_TEXT" ]] && [[ "$PROMISE_TEXT" = "$COMPLETION_PROMISE" ]]; then
-    echo "✅ Ralph loop: Detected <promise>$COMPLETION_PROMISE</promise>"
-    rm "$RALPH_STATE_FILE"
-    exit 0
-  fi
-fi
-
-# Not complete - continue loop with SAME PROMPT
-NEXT_ITERATION=$((ITERATION + 1))
-
-# Extract prompt (everything after the closing ---)
-# Skip first --- line, skip until second --- line, then print everything after
-# Use i>=2 instead of i==2 to handle --- in prompt content
-PROMPT_TEXT=$(awk '/^---$/{i++; next} i>=2' "$RALPH_STATE_FILE")
-
-if [[ -z "$PROMPT_TEXT" ]]; then
-  echo "⚠️  Ralph loop: State file corrupted or incomplete" >&2
-  echo "   File: $RALPH_STATE_FILE" >&2
-  echo "   Problem: No prompt text found" >&2
-  echo "" >&2
-  echo "   This usually means:" >&2
-  echo "     • State file was manually edited" >&2
-  echo "     • File was corrupted during writing" >&2
-  echo "" >&2
-  echo "   Ralph loop is stopping. Run /ralph-loop again to start fresh." >&2
-  rm "$RALPH_STATE_FILE"
-  exit 0
-fi
-
-# Update iteration in frontmatter (portable across macOS and Linux)
-# Create temp file, then atomically replace
-TEMP_FILE="${RALPH_STATE_FILE}.tmp.$$"
-sed "s/^iteration: .*/iteration: $NEXT_ITERATION/" "$RALPH_STATE_FILE" > "$TEMP_FILE"
-mv "$TEMP_FILE" "$RALPH_STATE_FILE"
-
-# Build system message with iteration count and completion promise info
-if [[ "$COMPLETION_PROMISE" != "null" ]] && [[ -n "$COMPLETION_PROMISE" ]]; then
-  SYSTEM_MSG="🔄 Ralph iteration $NEXT_ITERATION | To stop: output <promise>$COMPLETION_PROMISE</promise> (ONLY when statement is TRUE - do not lie to exit!)"
-else
-  SYSTEM_MSG="🔄 Ralph iteration $NEXT_ITERATION | No completion promise set - loop runs infinitely"
-fi
-
-# Output JSON to block the stop and feed prompt back
-# The "reason" field contains the prompt that will be sent back to Claude
-jq -n \
-  --arg prompt "$PROMPT_TEXT" \
-  --arg msg "$SYSTEM_MSG" \
-  '{
-    "decision": "block",
-    "reason": $prompt,
-    "systemMessage": $msg
-  }'
-
-# Exit 0 for successful hook execution
-exit 0