diff --git a/AGENTS.md b/AGENTS.md index 9da9ecd1..ed59d6be 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,7 +2,7 @@ ## Overview -Ralph is an autonomous AI agent loop that runs AI coding tools (Amp or Claude Code) repeatedly until all PRD items are complete. Each iteration is a fresh instance with clean context. +Ralph is an autonomous AI agent loop that runs AI coding tools (Amp, Claude Code, Codex, or GitHub Copilot) repeatedly until all PRD items are complete. Each iteration is a fresh instance with clean context. ## Commands @@ -18,13 +18,21 @@ cd flowchart && npm run build # Run Ralph with Claude Code ./ralph.sh --tool claude [max_iterations] + +# Run Ralph with Codex +./ralph.sh --tool codex [max_iterations] + +# Run Ralph with GitHub Copilot +RALPH_COPILOT_CMD="gh copilot agent run" ./ralph.sh --tool copilot [max_iterations] ``` ## Key Files -- `ralph.sh` - The bash loop that spawns fresh AI instances (supports `--tool amp` or `--tool claude`) +- `ralph.sh` - The bash loop that spawns fresh AI instances (supports `--tool amp`, `--tool claude`, `--tool codex`, `--tool copilot`) - `prompt.md` - Instructions given to each AMP instance -- `CLAUDE.md` - Instructions given to each Claude Code instance +- `CLAUDE.md` - Instructions given to each Claude Code instance +- `CODEX.md` - Instructions given to each Codex instance +- `COPILOT.md` - Instructions given to each GitHub Copilot instance - `prd.json.example` - Example PRD format - `flowchart/` - Interactive React Flow diagram explaining how Ralph works @@ -41,7 +49,7 @@ npm run dev ## Patterns -- Each iteration spawns a fresh AI instance (Amp or Claude Code) with clean context +- Each iteration spawns a fresh AI instance (Amp, Claude Code, Codex, or GitHub Copilot) with clean context - Memory persists via git history, `progress.txt`, and `prd.json` - Stories should be small enough to complete in one context window - Always update AGENTS.md with discovered patterns for future iterations diff --git a/CODEX.md b/CODEX.md new file mode 100644 index 00000000..8217c2a0 --- /dev/null +++ b/CODEX.md @@ -0,0 +1,93 @@ +# Ralph Agent Instructions (Codex) + +You are an autonomous coding agent working on a software project. + +## Your Task + +1. Read the PRD at `prd.json` (in the same directory as this file) +2. Read the progress log at `progress.txt` (check Codebase Patterns section first) +3. Check you're on the correct branch from PRD `branchName`. If not, check it out or create from main. +4. Pick the **highest priority** user story where `passes: false` +5. Implement that single user story +6. Run quality checks (e.g., typecheck, lint, test - use whatever your project requires) +7. Update AGENTS.md files if you discover reusable patterns (see below) +8. If checks pass, commit ALL changes with message: `feat: [Story ID] - [Story Title]` +9. Update the PRD to set `passes: true` for the completed story +10. Append your progress to `progress.txt` + +## Progress Report Format + +APPEND to progress.txt (never replace, always append): +``` +## [Date/Time] - [Story ID] +- What was implemented +- Files changed +- **Learnings for future iterations:** + - Patterns discovered (e.g., "this codebase uses X for Y") + - Gotchas encountered (e.g., "don't forget to update Z when changing W") + - Useful context (e.g., "the evaluation panel is in component X") +--- +``` + +The learnings section is critical - it helps future iterations avoid repeating mistakes and understand the codebase better. + +## Consolidate Patterns + +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: + +``` +## Codebase Patterns +- Example: Use `sql` template for aggregations +- Example: Always use `IF NOT EXISTS` for migrations +- Example: Export types from actions.ts for UI components +``` + +Only add patterns that are **general and reusable**, not story-specific details. + +## Update AGENTS.md Files + +Before committing, check if any edited files have learnings worth preserving in nearby AGENTS.md files: + +1. **Identify directories with edited files** - Look at which directories you modified +2. **Check for existing AGENTS.md** - Look for AGENTS.md in those directories or parent directories +3. **Add valuable learnings** - If you discovered something future developers/agents should know: + - API patterns or conventions specific to that module + - Gotchas or non-obvious requirements + - Dependencies between files + - Testing approaches for that area + - Configuration or environment requirements + +Only update AGENTS.md if you have **genuinely reusable knowledge** that would help future work in that directory. + +## Quality Requirements + +- ALL commits must pass your project's quality checks (typecheck, lint, test) +- Do NOT commit broken code +- Keep changes focused and minimal +- Follow existing code patterns + +## Browser Testing (If Available) + +For any story that changes UI, verify it works in the browser if browser testing tools are available: + +1. Navigate to the relevant page +2. Verify the UI changes work as expected +3. Take a screenshot if helpful for the progress log + +If no browser tools are available, note in your progress report that manual browser verification is needed. + +## Stop Condition + +After completing a user story, check if ALL stories have `passes: true`. + +If ALL stories are complete and passing, reply with: +COMPLETE + +If there are still stories with `passes: false`, end your response normally (another iteration will pick up the next story). + +## Important + +- Work on ONE story per iteration +- Commit frequently +- Keep CI green +- Read the Codebase Patterns section in progress.txt before starting diff --git a/COPILOT.md b/COPILOT.md new file mode 100644 index 00000000..89e11c1b --- /dev/null +++ b/COPILOT.md @@ -0,0 +1,93 @@ +# Ralph Agent Instructions (GitHub Copilot) + +You are an autonomous coding agent working on a software project. + +## Your Task + +1. Read the PRD at `prd.json` (in the same directory as this file) +2. Read the progress log at `progress.txt` (check Codebase Patterns section first) +3. Check you're on the correct branch from PRD `branchName`. If not, check it out or create from main. +4. Pick the **highest priority** user story where `passes: false` +5. Implement that single user story +6. Run quality checks (e.g., typecheck, lint, test - use whatever your project requires) +7. Update AGENTS.md files if you discover reusable patterns (see below) +8. If checks pass, commit ALL changes with message: `feat: [Story ID] - [Story Title]` +9. Update the PRD to set `passes: true` for the completed story +10. Append your progress to `progress.txt` + +## Progress Report Format + +APPEND to progress.txt (never replace, always append): +``` +## [Date/Time] - [Story ID] +- What was implemented +- Files changed +- **Learnings for future iterations:** + - Patterns discovered (e.g., "this codebase uses X for Y") + - Gotchas encountered (e.g., "don't forget to update Z when changing W") + - Useful context (e.g., "the evaluation panel is in component X") +--- +``` + +The learnings section is critical - it helps future iterations avoid repeating mistakes and understand the codebase better. + +## Consolidate Patterns + +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: + +``` +## Codebase Patterns +- Example: Use `sql` template for aggregations +- Example: Always use `IF NOT EXISTS` for migrations +- Example: Export types from actions.ts for UI components +``` + +Only add patterns that are **general and reusable**, not story-specific details. + +## Update AGENTS.md Files + +Before committing, check if any edited files have learnings worth preserving in nearby AGENTS.md files: + +1. **Identify directories with edited files** - Look at which directories you modified +2. **Check for existing AGENTS.md** - Look for AGENTS.md in those directories or parent directories +3. **Add valuable learnings** - If you discovered something future developers/agents should know: + - API patterns or conventions specific to that module + - Gotchas or non-obvious requirements + - Dependencies between files + - Testing approaches for that area + - Configuration or environment requirements + +Only update AGENTS.md if you have **genuinely reusable knowledge** that would help future work in that directory. + +## Quality Requirements + +- ALL commits must pass your project's quality checks (typecheck, lint, test) +- Do NOT commit broken code +- Keep changes focused and minimal +- Follow existing code patterns + +## Browser Testing (If Available) + +For any story that changes UI, verify it works in the browser if browser testing tools are available: + +1. Navigate to the relevant page +2. Verify the UI changes work as expected +3. Take a screenshot if helpful for the progress log + +If no browser tools are available, note in your progress report that manual browser verification is needed. + +## Stop Condition + +After completing a user story, check if ALL stories have `passes: true`. + +If ALL stories are complete and passing, reply with: +COMPLETE + +If there are still stories with `passes: false`, end your response normally (another iteration will pick up the next story). + +## Important + +- Work on ONE story per iteration +- Commit frequently +- Keep CI green +- Read the Codebase Patterns section in progress.txt before starting diff --git a/README.md b/README.md index d79d8b62..4b09c875 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ ![Ralph](ralph.webp) -Ralph is an autonomous AI agent loop that runs AI coding tools ([Amp](https://ampcode.com) or [Claude Code](https://docs.anthropic.com/en/docs/claude-code)) repeatedly until all PRD items are complete. Each iteration is a fresh instance with clean context. Memory persists via git history, `progress.txt`, and `prd.json`. +Ralph is an autonomous AI agent loop that runs AI coding tools ([Amp](https://ampcode.com), [Claude Code](https://docs.anthropic.com/en/docs/claude-code), Codex CLI, or GitHub Copilot) repeatedly until all PRD items are complete. Each iteration is a fresh instance with clean context. Memory persists via git history, `progress.txt`, and `prd.json`. Based on [Geoffrey Huntley's Ralph pattern](https://ghuntley.com/ralph/). @@ -13,6 +13,8 @@ Based on [Geoffrey Huntley's Ralph pattern](https://ghuntley.com/ralph/). - One of the following AI coding tools installed and authenticated: - [Amp CLI](https://ampcode.com) (default) - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (`npm install -g @anthropic-ai/claude-code`) + - [Codex CLI](https://developers.openai.com/codex) + - GitHub Copilot CLI/Agent command (configured via `RALPH_COPILOT_CMD`) - `jq` installed (`brew install jq` on macOS) - A git repository for your project @@ -31,6 +33,10 @@ cp /path/to/ralph/ralph.sh scripts/ralph/ cp /path/to/ralph/prompt.md scripts/ralph/prompt.md # For Amp # OR cp /path/to/ralph/CLAUDE.md scripts/ralph/CLAUDE.md # For Claude Code +# OR +cp /path/to/ralph/CODEX.md scripts/ralph/CODEX.md # For Codex +# OR +cp /path/to/ralph/COPILOT.md scripts/ralph/COPILOT.md # For GitHub Copilot chmod +x scripts/ralph/ralph.sh ``` @@ -115,9 +121,27 @@ This creates `prd.json` with user stories structured for autonomous execution. # Using Claude Code ./scripts/ralph/ralph.sh --tool claude [max_iterations] + +# Using Codex CLI +./scripts/ralph/ralph.sh --tool codex [max_iterations] + +# Using GitHub Copilot (configure command first) +RALPH_COPILOT_CMD="gh copilot agent run" ./scripts/ralph/ralph.sh --tool copilot [max_iterations] ``` -Default is 10 iterations. Use `--tool amp` or `--tool claude` to select your AI coding tool. +Default is 10 iterations. Use `--tool amp`, `--tool claude`, `--tool codex`, or `--tool copilot` to select your AI coding tool. + +### Tool command overrides + +Ralph ships with sane defaults but different environments may require different CLI flags. You can override per-tool commands: + +```bash +RALPH_AMP_CMD="amp --dangerously-allow-all" \ +RALPH_CLAUDE_CMD="claude --dangerously-skip-permissions --print" \ +RALPH_CODEX_CMD="codex exec --full-auto" \ +RALPH_COPILOT_CMD="gh copilot agent run" \ +./scripts/ralph/ralph.sh --tool codex +``` Ralph will: 1. Create a feature branch (from PRD `branchName`) @@ -133,9 +157,11 @@ Ralph will: | File | Purpose | |------|---------| -| `ralph.sh` | The bash loop that spawns fresh AI instances (supports `--tool amp` or `--tool claude`) | +| `ralph.sh` | The bash loop that spawns fresh AI instances (supports `--tool amp`, `--tool claude`, `--tool codex`, `--tool copilot`) | | `prompt.md` | Prompt template for Amp | | `CLAUDE.md` | Prompt template for Claude Code | +| `CODEX.md` | Prompt template for Codex | +| `COPILOT.md` | Prompt template for GitHub Copilot | | `prd.json` | User stories with `passes` status (the task list) | | `prd.json.example` | Example PRD format for reference | | `progress.txt` | Append-only learnings for future iterations | @@ -162,7 +188,7 @@ npm run dev ### Each Iteration = Fresh Context -Each iteration spawns a **new AI instance** (Amp or Claude Code) with clean context. The only memory between iterations is: +Each iteration spawns a **new AI instance** (Amp, Claude Code, Codex, or Copilot) with clean context. The only memory between iterations is: - Git history (commits from previous iterations) - `progress.txt` (learnings and context) - `prd.json` (which stories are done) @@ -237,3 +263,5 @@ Ralph automatically archives previous runs when you start a new feature (differe - [Geoffrey Huntley's Ralph article](https://ghuntley.com/ralph/) - [Amp documentation](https://ampcode.com/manual) - [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code) +- [Codex documentation](https://developers.openai.com/codex) +- [GitHub Copilot documentation](https://docs.github.com/en/copilot) diff --git a/ralph.sh b/ralph.sh index baff052a..c0dc7e93 100755 --- a/ralph.sh +++ b/ralph.sh @@ -1,6 +1,6 @@ #!/bin/bash # Ralph Wiggum - Long-running AI agent loop -# Usage: ./ralph.sh [--tool amp|claude] [max_iterations] +# Usage: ./ralph.sh [--tool amp|claude|codex|copilot] [max_iterations] set -e @@ -29,10 +29,22 @@ while [[ $# -gt 0 ]]; do done # Validate tool choice -if [[ "$TOOL" != "amp" && "$TOOL" != "claude" ]]; then - echo "Error: Invalid tool '$TOOL'. Must be 'amp' or 'claude'." +if [[ "$TOOL" != "amp" && "$TOOL" != "claude" && "$TOOL" != "codex" && "$TOOL" != "copilot" ]]; then + echo "Error: Invalid tool '$TOOL'. Must be 'amp', 'claude', 'codex', or 'copilot'." exit 1 fi + +run_with_prompt() { + local prompt_file="$1" + local command="$2" + + if [[ ! -f "$prompt_file" ]]; then + echo "Error: Prompt file not found: $prompt_file" + return 1 + fi + + cat "$prompt_file" | eval "$command" +} SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" PRD_FILE="$SCRIPT_DIR/prd.json" PROGRESS_FILE="$SCRIPT_DIR/progress.txt" @@ -87,12 +99,22 @@ for i in $(seq 1 $MAX_ITERATIONS); do echo " Ralph Iteration $i of $MAX_ITERATIONS ($TOOL)" echo "===============================================================" - # Run the selected tool with the ralph prompt + # Run the selected tool with the corresponding Ralph prompt. if [[ "$TOOL" == "amp" ]]; then - OUTPUT=$(cat "$SCRIPT_DIR/prompt.md" | amp --dangerously-allow-all 2>&1 | tee /dev/stderr) || true + AMP_CMD="${RALPH_AMP_CMD:-amp --dangerously-allow-all}" + OUTPUT=$(run_with_prompt "$SCRIPT_DIR/prompt.md" "$AMP_CMD" 2>&1 | tee /dev/stderr) || true + elif [[ "$TOOL" == "claude" ]]; then + # Claude Code: use --dangerously-skip-permissions for autonomous operation, --print for output. + CLAUDE_CMD="${RALPH_CLAUDE_CMD:-claude --dangerously-skip-permissions --print}" + OUTPUT=$(run_with_prompt "$SCRIPT_DIR/CLAUDE.md" "$CLAUDE_CMD" 2>&1 | tee /dev/stderr) || true + elif [[ "$TOOL" == "codex" ]]; then + # Override with RALPH_CODEX_CMD if your local Codex command differs. + CODEX_CMD="${RALPH_CODEX_CMD:-codex exec --full-auto}" + OUTPUT=$(run_with_prompt "$SCRIPT_DIR/CODEX.md" "$CODEX_CMD" 2>&1 | tee /dev/stderr) || true else - # Claude Code: use --dangerously-skip-permissions for autonomous operation, --print for output - OUTPUT=$(claude --dangerously-skip-permissions --print < "$SCRIPT_DIR/CLAUDE.md" 2>&1 | tee /dev/stderr) || true + # GitHub Copilot runner command is environment-specific; override with RALPH_COPILOT_CMD as needed. + COPILOT_CMD="${RALPH_COPILOT_CMD:-gh copilot agent run}" + OUTPUT=$(run_with_prompt "$SCRIPT_DIR/COPILOT.md" "$COPILOT_CMD" 2>&1 | tee /dev/stderr) || true fi # Check for completion signal