Skip to content

Commit 31bf67e

Browse files
Ralph Agentclaude
Ralph Agent
and
claude
committed
✨ Restore Ralph automation scripts
Restore scripts needed for Ralph agent workflow: - scripts/ralph.sh (agent loop runner) - scripts/ralph/prompt.md (agent prompt template) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent d14657b commit 31bf67e

2 files changed

Lines changed: 249 additions & 0 deletions

File tree

‎scripts/ralph.sh‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
#!/bin/bash
2+
# Ralph Wiggum - Long-running AI agent loop
3+
# Usage: ./ralph.sh [--tool opencode|amp|claude] [max_iterations]
4+
5+
set -e
6+
7+
# Parse arguments
8+
TOOL="claude" # Default to claude
9+
MAX_ITERATIONS=10
10+
11+
while [[ $# -gt 0 ]]; do
12+
case $1 in
13+
--tool)
14+
TOOL="$2"
15+
shift 2
16+
;;
17+
--tool=*)
18+
TOOL="${1#*=}"
19+
shift
20+
;;
21+
*)
22+
# Assume it's max_iterations if it's a number
23+
if [[ "$1" =~ ^[0-9]+$ ]]; then
24+
MAX_ITERATIONS="$1"
25+
fi
26+
shift
27+
;;
28+
esac
29+
done
30+
31+
# Validate tool choice
32+
if [[ "$TOOL" != "opencode" && "$TOOL" != "amp" && "$TOOL" != "claude" ]]; then
33+
echo "Error: Invalid tool '$TOOL'. Must be 'opencode', 'amp' or 'claude'."
34+
exit 1
35+
fi
36+
37+
# Check for jq dependency
38+
if ! command -v jq >/dev/null 2>&1; then
39+
echo "Error: 'jq' is not installed but required by this script."
40+
echo "Please install it (e.g., 'brew install jq' or 'sudo apt-get install jq')."
41+
exit 1
42+
fi
43+
44+
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
45+
RALPH_DIR="$SCRIPT_DIR/ralph"
46+
PRD_FILE="$RALPH_DIR/prd.json"
47+
PROGRESS_FILE="$RALPH_DIR/progress.txt"
48+
ARCHIVE_DIR="$RALPH_DIR/archive"
49+
LAST_BRANCH_FILE="$RALPH_DIR/.last-branch"
50+
51+
# Archive previous run if branch changed
52+
if [ -f "$PRD_FILE" ] && [ -f "$LAST_BRANCH_FILE" ]; then
53+
CURRENT_BRANCH=$(jq -r '.branchName // empty' "$PRD_FILE" 2>/dev/null || echo "")
54+
LAST_BRANCH=$(cat "$LAST_BRANCH_FILE" 2>/dev/null || echo "")
55+
56+
if [ -n "$CURRENT_BRANCH" ] && [ -n "$LAST_BRANCH" ] && [ "$CURRENT_BRANCH" != "$LAST_BRANCH" ]; then
57+
# Archive the previous run
58+
DATE=$(date +%Y-%m-%d)
59+
# Strip "ralph/" prefix from branch name for folder
60+
FOLDER_NAME=$(echo "$LAST_BRANCH" | sed 's|^ralph/||')
61+
ARCHIVE_FOLDER="$ARCHIVE_DIR/$DATE-$FOLDER_NAME"
62+
63+
echo "Archiving previous run: $LAST_BRANCH"
64+
mkdir -p "$ARCHIVE_FOLDER"
65+
[ -f "$PRD_FILE" ] && cp "$PRD_FILE" "$ARCHIVE_FOLDER/"
66+
[ -f "$PROGRESS_FILE" ] && cp "$PROGRESS_FILE" "$ARCHIVE_FOLDER/"
67+
echo " Archived to: $ARCHIVE_FOLDER"
68+
69+
# Reset progress file for new run
70+
echo "# Ralph Progress Log" > "$PROGRESS_FILE"
71+
echo "Started: $(date)" >> "$PROGRESS_FILE"
72+
echo "---" >> "$PROGRESS_FILE"
73+
fi
74+
fi
75+
76+
# Track current branch
77+
if [ -f "$PRD_FILE" ]; then
78+
CURRENT_BRANCH=$(jq -r '.branchName // empty' "$PRD_FILE" 2>/dev/null || echo "")
79+
if [ -n "$CURRENT_BRANCH" ]; then
80+
echo "$CURRENT_BRANCH" > "$LAST_BRANCH_FILE"
81+
fi
82+
fi
83+
84+
# Initialize progress file if it doesn't exist
85+
if [ ! -f "$PROGRESS_FILE" ]; then
86+
echo "# Ralph Progress Log" > "$PROGRESS_FILE"
87+
echo "Started: $(date)" >> "$PROGRESS_FILE"
88+
echo "---" >> "$PROGRESS_FILE"
89+
fi
90+
91+
echo "Starting Ralph - Tool: $TOOL - Max iterations: $MAX_ITERATIONS"
92+
93+
for i in $(seq 1 $MAX_ITERATIONS); do
94+
echo ""
95+
echo "==============================================================="
96+
echo " Ralph Iteration $i of $MAX_ITERATIONS ($TOOL)"
97+
echo "==============================================================="
98+
99+
# Run the selected tool with the ralph prompt
100+
if [[ "$TOOL" == "opencode" ]]; then
101+
# opencode run: use prompt from prompt.md
102+
if [ -f "$RALPH_DIR/prompt.md" ]; then
103+
OUTPUT=$(opencode run "$(cat "$RALPH_DIR/prompt.md")" 2>&1 | tee /dev/stderr) || true
104+
else
105+
echo "Error: $RALPH_DIR/prompt.md not found. Create this file or use a different tool."
106+
echo "Example: ./ralph.sh --tool claude"
107+
exit 1
108+
fi
109+
elif [[ "$TOOL" == "amp" ]]; then
110+
if [ -f "$RALPH_DIR/prompt.md" ]; then
111+
OUTPUT=$(cat "$RALPH_DIR/prompt.md" | amp --dangerously-allow-all 2>&1 | tee /dev/stderr) || true
112+
else
113+
echo "Error: $RALPH_DIR/prompt.md not found. Create this file or use a different tool."
114+
exit 1
115+
fi
116+
else
117+
# Claude Code: use --dangerously-skip-permissions for autonomous operation, --print for output
118+
if [ -f "$RALPH_DIR/prompt.md" ]; then
119+
OUTPUT=$(claude --dangerously-skip-permissions --print < "$RALPH_DIR/prompt.md" 2>&1 | tee /dev/stderr) || true
120+
else
121+
echo "Error: $RALPH_DIR/prompt.md not found. Create this file or use a different tool."
122+
exit 1
123+
fi
124+
fi
125+
126+
# Check for completion signal
127+
if echo "$OUTPUT" | grep -q "<promise>COMPLETE</promise>"; then
128+
echo ""
129+
echo "Ralph completed all tasks!"
130+
echo "Completed at iteration $i of $MAX_ITERATIONS"
131+
exit 0
132+
fi
133+
134+
echo "Iteration $i complete. Continuing..."
135+
sleep 2
136+
done
137+
138+
echo ""
139+
echo "Ralph reached max iterations ($MAX_ITERATIONS) without completing all tasks."
140+
echo "Check $PROGRESS_FILE for status."
141+
exit 1

‎scripts/ralph/prompt.md‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
# Ralph Agent Instructions
2+
3+
You are an autonomous coding agent working on a software project.
4+
5+
## Your Task
6+
7+
1. Read the PRD at `prd.json` (in the same directory as this file)
8+
2. Read the progress log at `progress.txt` (check Codebase Patterns section first)
9+
3. Check you're on the correct branch from PRD `branchName`. If not, check it out or create from main.
10+
4. Pick the **highest priority** user story where `passes: false`
11+
5. Implement that single user story
12+
6. Run quality checks (e.g., typecheck, lint, test - use whatever your project requires)
13+
7. Update AGENTS.md files if you discover reusable patterns (see below)
14+
8. If checks pass, commit ALL changes with message: `feat: [Story ID] - [Story Title]`
15+
9. Update the PRD to set `passes: true` for the completed story
16+
10. Append your progress to `progress.txt`
17+
18+
## Progress Report Format
19+
20+
APPEND to progress.txt (never replace, always append):
21+
```
22+
## [Date/Time] - [Story ID]
23+
Session: https://opencode.ai/sessions/[SESSION_ID]
24+
- What was implemented
25+
- Files changed
26+
- **Learnings for future iterations:**
27+
- Patterns discovered (e.g., "this codebase uses X for Y")
28+
- Gotchas encountered (e.g., "don't forget to update Z when changing W")
29+
- Useful context (e.g., "the evaluation panel is in component X")
30+
---
31+
```
32+
33+
Find your current Session ID by running `opencode session list` (it should be the first one). Include the session URL so future iterations can reference previous work if needed.
34+
35+
The learnings section is critical - it helps future iterations avoid repeating mistakes and understand the codebase better.
36+
37+
## Consolidate Patterns
38+
39+
If you discover a **reusable pattern** that future iterations should know, add it to the `## Codebase Patterns` section at the TOP of progress.txt (create it if it doesn't exist). This section should consolidate the most important learnings:
40+
41+
```
42+
## Codebase Patterns
43+
- Example: Use `sql<number>` template for aggregations
44+
- Example: Always use `IF NOT EXISTS` for migrations
45+
- Example: Export types from actions.ts for UI components
46+
```
47+
48+
Only add patterns that are **general and reusable**, not story-specific details.
49+
50+
## Update AGENTS.md Files
51+
52+
Before committing, check if any edited files have learnings worth preserving in nearby AGENTS.md files:
53+
54+
1. **Identify directories with edited files** - Look at which directories you modified
55+
2. **Check for existing AGENTS.md** - Look for AGENTS.md in those directories or parent directories
56+
3. **Add valuable learnings** - If you discovered something future developers/agents should know:
57+
- API patterns or conventions specific to that module
58+
- Gotchas or non-obvious requirements
59+
- Dependencies between files
60+
- Testing approaches for that area
61+
- Configuration or environment requirements
62+
63+
**Examples of good AGENTS.md additions:**
64+
- "When modifying X, also update Y to keep them in sync"
65+
- "This module uses pattern Z for all API calls"
66+
- "Tests require the dev server running on PORT 3000"
67+
- "Field names must match the template exactly"
68+
69+
**Do NOT add:**
70+
- Story-specific implementation details
71+
- Temporary debugging notes
72+
- Information already in progress.txt
73+
74+
Only update AGENTS.md if you have **genuinely reusable knowledge** that would help future work in that directory.
75+
76+
## Quality Requirements
77+
78+
- ALL commits must pass your project's quality checks (typecheck, lint, test)
79+
- Do NOT commit broken code
80+
- Keep changes focused and minimal
81+
- Follow existing code patterns
82+
83+
## Browser Testing (Required for Frontend Stories)
84+
85+
For any story that changes UI, you MUST verify it works in the browser:
86+
87+
1. Use available browser verification tools.
88+
2. Navigate to the relevant page.
89+
3. Verify the UI changes work as expected.
90+
4. Take a screenshot if helpful for the progress log.
91+
92+
A frontend story is NOT complete until browser verification passes.
93+
94+
## Stop Condition
95+
96+
After completing a user story, check if ALL stories have `passes: true`.
97+
98+
If ALL stories are complete and passing, reply with:
99+
<promise>COMPLETE</promise>
100+
101+
If there are still stories with `passes: false`, end your response normally (another iteration will pick up the next story).
102+
103+
## Important
104+
105+
- Work on ONE story per iteration
106+
- Commit frequently
107+
- Keep CI green
108+
- Read the Codebase Patterns section in progress.txt before starting

0 commit comments

Comments
 (0)