From 2671eca1dee42ba3b647590b5bd6c39b1a0295ef Mon Sep 17 00:00:00 2001 From: Jeff Tian Date: Mon, 2 Feb 2026 18:14:37 +0800 Subject: [PATCH 1/4] feat: add GitHub Copilot support to Ralph agent --- AGENTS.md | 9 ++++++--- README.md | 13 +++++++++---- ralph.sh | 9 ++++++--- 3 files changed, 21 insertions(+), 10 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 9da9ecd1..73d276eb 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, or GitHub Copilot) repeatedly until all PRD items are complete. Each iteration is a fresh instance with clean context. ## Commands @@ -18,11 +18,14 @@ cd flowchart && npm run build # Run Ralph with Claude Code ./ralph.sh --tool claude [max_iterations] + +# Run Ralph with GitHub Copilot +./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`, or `--tool copilot`) - `prompt.md` - Instructions given to each AMP instance - `CLAUDE.md` - Instructions given to each Claude Code instance - `prd.json.example` - Example PRD format @@ -41,7 +44,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, 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/README.md b/README.md index d79d8b62..2729ad12 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), or [GitHub Copilot](https://github.com/features/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,7 @@ 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`) + - [GitHub Copilot CLI](https://github.com/features/copilot) (`gh extension install github/gh-copilot`) - `jq` installed (`brew install jq` on macOS) - A git repository for your project @@ -115,9 +116,12 @@ This creates `prd.json` with user stories structured for autonomous execution. # Using Claude Code ./scripts/ralph/ralph.sh --tool claude [max_iterations] + +# Using GitHub Copilot +./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`, or `--tool copilot` to select your AI coding tool. Ralph will: 1. Create a feature branch (from PRD `branchName`) @@ -133,7 +137,7 @@ 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`, or `--tool copilot`) | | `prompt.md` | Prompt template for Amp | | `CLAUDE.md` | Prompt template for Claude Code | | `prd.json` | User stories with `passes` status (the task list) | @@ -162,7 +166,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, or GitHub 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 +241,4 @@ 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) +- [GitHub Copilot documentation](https://docs.github.com/en/copilot) diff --git a/ralph.sh b/ralph.sh index baff052a..2e9af304 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|copilot] [max_iterations] set -e @@ -29,8 +29,8 @@ 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" != "copilot" ]]; then + echo "Error: Invalid tool '$TOOL'. Must be 'amp', 'claude', or 'copilot'." exit 1 fi SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" @@ -90,6 +90,9 @@ for i in $(seq 1 $MAX_ITERATIONS); do # Run the selected tool with the ralph prompt if [[ "$TOOL" == "amp" ]]; then OUTPUT=$(cat "$SCRIPT_DIR/prompt.md" | amp --dangerously-allow-all 2>&1 | tee /dev/stderr) || true + elif [[ "$TOOL" == "copilot" ]]; then + PROMPT_CONTENT=$(cat "$SCRIPT_DIR/prompt.md" | sed "s|Read the PRD at \`prd.json\` (in the same directory as this file)|Read the PRD at \`$PRD_FILE\`|" | sed "s|Read the progress log at \`progress.txt\`|Read the progress log at \`$PROGRESS_FILE\`|" | sed "s|APPEND to progress.txt|APPEND to $PROGRESS_FILE|") + OUTPUT=$(copilot -i "$PROMPT_CONTENT" --yolo --no-ask-user 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 From b889b14035581a1551b336b9551523d772133c7d Mon Sep 17 00:00:00 2001 From: Jeff Tian Date: Mon, 2 Feb 2026 18:21:50 +0800 Subject: [PATCH 2/4] feat: add instructions for GitHub Copilot in new COPILOT.md file and update AGENTS.md --- AGENTS.md | 3 +- COPILOT.md | 104 +++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 9 +++-- 3 files changed, 112 insertions(+), 4 deletions(-) create mode 100644 COPILOT.md diff --git a/AGENTS.md b/AGENTS.md index 73d276eb..0dc84c95 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -27,7 +27,8 @@ cd flowchart && npm run build - `ralph.sh` - The bash loop that spawns fresh AI instances (supports `--tool amp`, `--tool claude`, or `--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 +- `COPILOT.md` - Instructions given to each GitHub Copilot instance - `prd.json.example` - Example PRD format - `flowchart/` - Interactive React Flow diagram explaining how Ralph works diff --git a/COPILOT.md b/COPILOT.md new file mode 100644 index 00000000..39c83ae9 --- /dev/null +++ b/COPILOT.md @@ -0,0 +1,104 @@ +# Ralph Agent Instructions + +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 + +**Examples of good AGENTS.md additions:** +- "When modifying X, also update Y to keep them in sync" +- "This module uses pattern Z for all API calls" +- "Tests require the dev server running on PORT 3000" +- "Field names must match the template exactly" + +**Do NOT add:** +- Story-specific implementation details +- Temporary debugging notes +- Information already in progress.txt + +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 you have browser testing tools configured (e.g., via MCP): + +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 2729ad12..edb7426d 100644 --- a/README.md +++ b/README.md @@ -29,9 +29,11 @@ mkdir -p scripts/ralph cp /path/to/ralph/ralph.sh scripts/ralph/ # Copy the prompt template for your AI tool of choice: -cp /path/to/ralph/prompt.md scripts/ralph/prompt.md # For Amp +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 +cp /path/to/ralph/CLAUDE.md scripts/ralph/CLAUDE.md # For Claude Code +# OR +cp /path/to/ralph/COPILOT.md scripts/ralph/COPILOT.md # For GitHub Copilot chmod +x scripts/ralph/ralph.sh ``` @@ -140,6 +142,7 @@ Ralph will: | `ralph.sh` | The bash loop that spawns fresh AI instances (supports `--tool amp`, `--tool claude`, or `--tool copilot`) | | `prompt.md` | Prompt template for Amp | | `CLAUDE.md` | Prompt template for Claude Code | +| `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 | @@ -227,7 +230,7 @@ git log --oneline -10 ## Customizing the Prompt -After copying `prompt.md` (for Amp) or `CLAUDE.md` (for Claude Code) to your project, customize it for your project: +After copying `prompt.md` (for Amp), `CLAUDE.md` (for Claude Code), or `COPILOT.md` (for GitHub Copilot) to your project, customize it for your project: - Add project-specific quality check commands - Include codebase conventions - Add common gotchas for your stack From cb38b896c1ac618da0799eaff8003c86c5caa442 Mon Sep 17 00:00:00 2001 From: Jeff Tian Date: Mon, 2 Feb 2026 18:35:48 +0800 Subject: [PATCH 3/4] fix: update GitHub Copilot CLI installation instructions in README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index edb7426d..87e162a0 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ 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`) - - [GitHub Copilot CLI](https://github.com/features/copilot) (`gh extension install github/gh-copilot`) + - [GitHub Copilot CLI](https://github.com/features/copilot) (bundled with VS Code Copilot Chat extension, not `gh copilot`) - `jq` installed (`brew install jq` on macOS) - A git repository for your project From 3ccfea9ec5a25c9947584b33d07a08967776f9d1 Mon Sep 17 00:00:00 2001 From: Jeff Tian Date: Mon, 2 Feb 2026 18:48:06 +0800 Subject: [PATCH 4/4] refactor: consolidate GitHub Copilot instructions and remove COPILOT.md --- AGENTS.md | 3 +- COPILOT.md | 104 ----------------------------------------------------- README.md | 11 +++--- 3 files changed, 5 insertions(+), 113 deletions(-) delete mode 100644 COPILOT.md diff --git a/AGENTS.md b/AGENTS.md index 0dc84c95..78ca9698 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -26,9 +26,8 @@ cd flowchart && npm run build ## Key Files - `ralph.sh` - The bash loop that spawns fresh AI instances (supports `--tool amp`, `--tool claude`, or `--tool copilot`) -- `prompt.md` - Instructions given to each AMP instance +- `prompt.md` - Instructions given to each Amp and GitHub Copilot instance - `CLAUDE.md` - Instructions given to each Claude Code 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 diff --git a/COPILOT.md b/COPILOT.md deleted file mode 100644 index 39c83ae9..00000000 --- a/COPILOT.md +++ /dev/null @@ -1,104 +0,0 @@ -# Ralph Agent Instructions - -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 - -**Examples of good AGENTS.md additions:** -- "When modifying X, also update Y to keep them in sync" -- "This module uses pattern Z for all API calls" -- "Tests require the dev server running on PORT 3000" -- "Field names must match the template exactly" - -**Do NOT add:** -- Story-specific implementation details -- Temporary debugging notes -- Information already in progress.txt - -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 you have browser testing tools configured (e.g., via MCP): - -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 87e162a0..b86cb789 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ 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`) - - [GitHub Copilot CLI](https://github.com/features/copilot) (bundled with VS Code Copilot Chat extension, not `gh copilot`) + - [GitHub Copilot CLI](https://docs.github.com/en/copilot) - Requires VS Code with [Copilot Chat extension](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot-chat) installed; the CLI binary is bundled at `~/.vscode/extensions/github.copilot-chat-*/copilotCli/copilot` (note: this is different from the `gh copilot` extension) - `jq` installed (`brew install jq` on macOS) - A git repository for your project @@ -29,11 +29,9 @@ mkdir -p scripts/ralph cp /path/to/ralph/ralph.sh scripts/ralph/ # Copy the prompt template for your AI tool of choice: -cp /path/to/ralph/prompt.md scripts/ralph/prompt.md # For Amp +cp /path/to/ralph/prompt.md scripts/ralph/prompt.md # For Amp and GitHub Copilot # OR cp /path/to/ralph/CLAUDE.md scripts/ralph/CLAUDE.md # For Claude Code -# OR -cp /path/to/ralph/COPILOT.md scripts/ralph/COPILOT.md # For GitHub Copilot chmod +x scripts/ralph/ralph.sh ``` @@ -140,9 +138,8 @@ Ralph will: | File | Purpose | |------|---------| | `ralph.sh` | The bash loop that spawns fresh AI instances (supports `--tool amp`, `--tool claude`, or `--tool copilot`) | -| `prompt.md` | Prompt template for Amp | +| `prompt.md` | Prompt template for Amp and GitHub Copilot | | `CLAUDE.md` | Prompt template for Claude Code | -| `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 | @@ -230,7 +227,7 @@ git log --oneline -10 ## Customizing the Prompt -After copying `prompt.md` (for Amp), `CLAUDE.md` (for Claude Code), or `COPILOT.md` (for GitHub Copilot) to your project, customize it for your project: +After copying `prompt.md` (for Amp and GitHub Copilot) or `CLAUDE.md` (for Claude Code) to your project, customize it for your project: - Add project-specific quality check commands - Include codebase conventions - Add common gotchas for your stack