Ralph Loop support in Specify CLI by Rubiss · Pull Request #1489 · github/spec-kit

Rubiss · 2026-01-20T02:34:00Z

No description provided.

Copilot

Pull request overview

This pull request adds autonomous implementation support to the Specify CLI through a new "Ralph Loop" command. The feature enables controlled iteration through task execution using GitHub Copilot CLI with fresh agent contexts per iteration.

Changes:

Adds new specify ralph CLI command with configurable iteration limits and AI model selection
Implements cross-platform loop orchestrators (PowerShell and Bash scripts)
Creates progress tracking with iteration history and codebase pattern discovery
Adds comprehensive documentation including spec, plan, research, and task breakdowns

Reviewed changes

Copilot reviewed 48 out of 49 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/specify_cli/init.py	Adds ralph command with prerequisite validation, script detection, and invocation
scripts/powershell/ralph-loop.ps1	PowerShell orchestrator for Windows with iteration management and Copilot CLI integration
scripts/bash/ralph-loop.sh	Bash orchestrator for Unix/Linux with parallel functionality to PowerShell version
specs/001-ralph-loop-implement/*.md	Complete specification documents (spec, plan, tasks, research, contracts, checklists)
.github/agents/speckit.ralph.agent.md	Agent profile defining work unit scope and execution constraints
templates and other support files	Templates, configuration updates, and agent context files

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-01-20T02:36:33Z

src/specify_cli/__init__.py

+            if models_list:
+                console.print("[green]Available models:[/green]")
+                for m in models_list:
+                    default_marker = " [yellow](default)[/yellow]" if m == "claude-sonnet-4.5" else ""


The default model name "claude-sonnet-4.5" appears to be hardcoded, but this model version may not exist. Based on typical Claude versioning, this should likely be "claude-sonnet-3.5" or verify that version 4.5 actually exists in the Copilot CLI.

Copilot · 2026-01-20T02:36:34Z

scripts/powershell/ralph-loop.ps1

+            Write-Host "--- Copilot Agent Output ---" -ForegroundColor DarkCyan
+            $outputLines = @()
+            # Use speckit.ralph agent - it already knows to complete one work unit
+            & copilot --agent speckit.ralph -p $prompt --model $Model --allow-all-tools -s 2>&1 | ForEach-Object {


The scripts reference agent "speckit.ralph" but the specification documents repeatedly reference "speckit.implement" as the agent profile to use. This inconsistency needs to be resolved - either both scripts and documentation should use "speckit.ralph" or both should use "speckit.implement".

Copilot · 2026-01-20T02:36:34Z

scripts/bash/ralph-loop.sh

+    while IFS= read -r line; do
+        echo "$line"
+        output_lines+=("$line")
+    done < <(copilot --agent speckit.ralph -p "$prompt" --model "$model" --allow-all-tools -s 2>&1) || exit_code=$?


The scripts reference agent "speckit.ralph" but the specification documents repeatedly reference "speckit.implement" as the agent profile to use. This inconsistency needs to be resolved - either both scripts and documentation should use "speckit.ralph" or both should use "speckit.implement".

Previously, specify ralph would select the first feature folder found alphabetically (e.g., 001-* over 002-*), ignoring which branch the user was on. Now it: 1. First tries to match the current branch name to a feature folder 2. Falls back to the last folder alphabetically (highest feature number) This ensures working on branch 002-foo uses specs/002-foo/tasks.md instead of incorrectly picking specs/001-bar/tasks.md.

Copilot

Pull request overview

Copilot reviewed 49 out of 50 changed files in this pull request and generated 13 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-01-27T04:21:25Z

scripts/powershell/ralph-loop.ps1

+    $prompt = "Iteration $Iteration - Complete one work unit from tasks.md"
+
+    # Only show debug info when verbose
+    if ($Verbose) {
+        Write-Host "DEBUG: Prompt = $prompt" -ForegroundColor Magenta
+        Write-Host "DEBUG: WorkDir = $WorkDir" -ForegroundColor Magenta
+    }
+
+    try {
+        # Change to working directory so copilot finds the correct agents
+        $originalDir = Get-Location
+        if ($WorkDir -and (Test-Path $WorkDir)) {
+            Push-Location $WorkDir
+            if ($Verbose) {
+                Write-Host "DEBUG: Changed to $WorkDir" -ForegroundColor Magenta
+            }
+        }
+
+        # Refresh PATH to ensure pwsh is available (copilot CLI requires PowerShell 7+)
+        $env:Path = [System.Environment]::GetEnvironmentVariable("Path", "Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path", "User")
+
+        try {
+            # Always stream copilot output in real-time so user can see what the agent is doing
+            Write-Host ""
+            Write-Host "--- Copilot Agent Output ---" -ForegroundColor DarkCyan
+            $outputLines = @()
+            # Use speckit.ralph agent - it already knows to complete one work unit
+            & copilot --agent speckit.ralph -p $prompt --model $Model --allow-all-tools -s 2>&1 | ForEach-Object {


The prompt variable on line 188 is directly interpolated into the command on line 215 without sanitization. If the iteration number or any other variable used to construct the prompt contains shell metacharacters, this could lead to command injection. While the iteration number is controlled (integer), consider using proper command escaping or parameterization to prevent any future issues if the prompt construction changes.

Copilot · 2026-01-27T04:21:25Z

scripts/powershell/ralph-loop.ps1

+    # Simple prompt - the speckit.ralph agent already knows to complete one work unit
+    $prompt = "Iteration $Iteration - Complete one work unit from tasks.md"


The comment on line 188 references "speckit.ralph agent" and mentions it "already knows to complete one work unit", but this relies on an external agent definition. If the agent definition is missing or misconfigured, the behavior may not match expectations. Consider adding validation to check if the agent file exists before proceeding, or document this dependency more explicitly in the function docstring.

Copilot · 2026-01-27T04:21:26Z

specs/001-ralph-loop-implement/quickstart.md

+
+| File | Purpose |
+|------|---------|
+| `specs/{feature}/progress.txt` | Detailed log of each iteration |


Inconsistency: The quickstart.md file references progress.txt (line 130) but the actual implementation creates progress.md. This should be updated to match the implementation.

Copilot · 2026-01-27T04:21:26Z

.github/agents/copilot-instructions.md

+- Python 3.11+ (Specify CLI) + PowerShell 6+ and Bash (scripts) + Typer, Rich (existing CLI deps); `copilot` CLI (standalone GitHub Copilot CLI) (001-ralph-loop-implement)
+- Markdown files (tasks.md, progress.txt) - no database (001-ralph-loop-implement)
+
+- Python 3.11+ (Specify CLI) + PowerShell 5.1/7+ and Bash (scripts) + Typer, Rich (existing CLI deps); `gh copilot` CLI (external) (001-ralph-loop-implement)


The copilot-instructions.md file has duplicate and conflicting technology stack entries. Lines 6-7 mention "copilot CLI (standalone GitHub Copilot CLI)" while lines 9 says "gh copilot CLI (external)". These entries contradict each other - it should be one or the other, not both. Based on the implementation, it should only reference the standalone copilot CLI.

Copilot · 2026-01-27T04:21:26Z

.github/agents/copilot-instructions.md

+- 001-ralph-loop-implement: Added Python 3.11+ (Specify CLI) + PowerShell 6+ and Bash (scripts) + Typer, Rich (existing CLI deps); `copilot` CLI (standalone GitHub Copilot CLI)
+
+- 001-ralph-loop-implement: Added Python 3.11+ (Specify CLI) + PowerShell 5.1/7+ and Bash (scripts) + Typer, Rich (existing CLI deps); `gh copilot` CLI (external)


Lines 27-29 show duplicate "Recent Changes" entries with conflicting information. One mentions "PowerShell 6+" and "copilot CLI (standalone)", the other mentions "PowerShell 5.1/7+" and "gh copilot CLI (external)". This duplication suggests the agent context was updated multiple times without removing old entries. Clean up to show only the correct, current entry.

Copilot · 2026-01-27T04:21:27Z

CHANGELOG.md

+  - Supports `--max-iterations` (default: 10) and `--model` (default: claude-sonnet-4.5) options
+  - Verbose mode with `-v` flag for detailed output
+  - Warns about uncommitted changes before starting
+  - Creates progress.txt log with iteration history and codebase patterns


The CHANGELOG.md references progress.txt on line 22, but the implementation creates progress.md. This should be corrected to progress.md for consistency.

Copilot · 2026-01-27T04:21:27Z

src/specify_cli/__init__.py

+            console.print(tracker.render())
+            console.print()
+            console.print("[red]Error:[/red] GitHub Copilot CLI not found.")
+            console.print("[dim]Install from: https://docs.github.com/copilot/using-github-copilot/using-github-copilot-chat-in-your-ide[/dim]")


The error message on line 1363 provides an installation link that points to the GitHub Copilot IDE documentation, but this is for the standalone CLI tool. The correct installation documentation link should point to the GitHub Copilot CLI documentation, not the IDE integration docs. The npm install command on line 1364 is correct, but the docs link is misleading.

Copilot · 2026-01-27T04:21:28Z

scripts/powershell/ralph-loop.ps1

+            Write-Host "--- Copilot Agent Output ---" -ForegroundColor DarkCyan
+            $outputLines = @()
+            # Use speckit.ralph agent - it already knows to complete one work unit
+            & copilot --agent speckit.ralph -p $prompt --model $Model --allow-all-tools -s 2>&1 | ForEach-Object {


The --allow-all-tools flag on line 215 grants the copilot agent permission to execute any tool without confirmation. While this is necessary for autonomous operation, it poses a security risk if the agent is compromised or if malicious prompts are injected. Consider documenting this security tradeoff in the function comments and potentially adding a warning message on first use, or offering a more restricted mode for untrusted environments.

Copilot · 2026-01-27T04:21:28Z

src/specify_cli/__init__.py

+    npm_path = os.path.expandvars(r"%APPDATA%\npm\copilot.cmd")
+    if os.path.exists(npm_path):
+        copilot_path = npm_path


The Windows-specific npm path check on line 1250 uses r-string formatting with Windows path separators but there's no OS check before attempting this. If this code runs on Linux/macOS, it will try to check a non-existent Windows path. Consider adding a platform check: if platform.system() == 'Windows': before the Windows-specific path logic.

Copilot · 2026-01-27T04:21:28Z

specs/001-ralph-loop-implement/data-model.md

+
+## File Formats
+
+### progress.txt


There's an inconsistency in file naming throughout the codebase. The implementation in both ralph-loop.ps1 (line 88) and ralph-loop.sh (line 85) creates progress.md, but the data model documentation (data-model.md lines 47, 80, 86) refers to progress.txt. The .gitignore also references progress.txt. All references should be consistent. Based on the actual implementation, it should be progress.md everywhere.

Rubiss added 2 commits January 18, 2026 11:59

plan: Planning completed

a4a8269

task: Tasking completed

4f70286

Copilot AI review requested due to automatic review settings January 20, 2026 02:34

Rubiss mentioned this pull request Jan 20, 2026

Ralph in Specify CLI #1490

Open

Copilot started reviewing on behalf of Rubiss January 20, 2026 02:34 View session

Copilot AI reviewed Jan 20, 2026

View reviewed changes

implement: ralph-loop support in specify cli

16d825a

Rubiss force-pushed the 001-ralph-loop-implement branch from 7635c4b to 16d825a Compare January 23, 2026 18:16

Copilot AI review requested due to automatic review settings January 27, 2026 04:17

Copilot started reviewing on behalf of Rubiss January 27, 2026 04:17 View session

Copilot AI reviewed Jan 27, 2026

View reviewed changes

		# Simple prompt - the speckit.ralph agent already knows to complete one work unit
		$prompt = "Iteration $Iteration - Complete one work unit from tasks.md"

		- 001-ralph-loop-implement: Added Python 3.11+ (Specify CLI) + PowerShell 6+ and Bash (scripts) + Typer, Rich (existing CLI deps); `copilot` CLI (standalone GitHub Copilot CLI)

		- 001-ralph-loop-implement: Added Python 3.11+ (Specify CLI) + PowerShell 5.1/7+ and Bash (scripts) + Typer, Rich (existing CLI deps); `gh copilot` CLI (external)

Conversation

Rubiss commented Jan 20, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant