All notable changes to the Ralph Loop extension will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
- Select dependency-ready work across Setup, Foundational, user-story, and final phases, including tasks without story labels. Keep each iteration within one story or one non-story phase and allow validated partial commits in fallback prompts.
- Stop both orchestrators after three consecutive iterations without validated completed work, independently of agent exit codes. Count unsuccessful subject repairs, retain immediate validation failures, and accept completion with follow-up task additions as progress.
- Report remaining tasks and available blocker context when the no-progress circuit breaker stops a run.
- Recognize task IDs wrapped in Markdown emphasis (
- [x] **T1. …**,__T1__,*T1*) in both orchestrators. Since 1.4.2 such a completed task yielded no ID, and a fully completed iteration was rejected asfailed-iteration-advanced-head(#59).
- Added official OpenCode CLI support in both orchestrators, with non-interactive fresh iterations, model and prompt forwarding, streamed output, and the existing failure handling (#3).
- Fixed the Bash failure counter exiting on the first failed agent call under
set -e, allowing the three-consecutive-failure circuit breaker and failure summary to run. - Required
speckit.ralph.runto dispatch the orchestrator and verify fresh startup output before reporting success, with explicit in-app/native terminal fallbacks, a bounded startup check, and actionable failed or unverified launch results (#29).
- Accepted valid task-expansion iterations that complete existing tasks while adding follow-up unchecked tasks, and kept add-only task churn rejected (#49).
- Reconciled the iterate command's partial-progress instructions with the orchestrator's commit validation: a validated task subset is now committed as a coordinated work unit each iteration, so a multi-task user story can span several iterations without terminating the loop as
FAILED(#50).
- Accepted coordinated state-only commits when an iteration intentionally completes review or analysis tasks, while continuing to reject bookkeeping commits that do not advance task state.
- Added configurable nested Ralph commit policy with legacy and conventional styles, optional scope selection, inferred issue suffixes, runtime subject enforcement, and matching Bash and PowerShell coverage.
- Amended the constitution to v2.1.0 to allow a narrow pre-acceptance retry for subject-only
commit-subject-invaliddefects from explicitly configured commit policy, while keeping broader cleanup, recovery, and history-rewrite behavior forbidden.
- Allowed Ralph to rerun after clean human-authored spec or task refinements by limiting coordinated commit-shape validation to commits created within the current iteration (#39).
- Reduced fresh-install payloads by excluding repository-only tests, community and security documents, and root Git metadata files; package-local attributes retain required LF checkouts for shell scripts and the canonical memory template. Removed the redundant
ralph-config.template.ymlwhile retainingralph-config.ymlas the manifest's canonical configuration source. - Expanded the contributing guide with the
mainpull request target, changelog requirements, cross-platform test commands, release ownership, and repository-specific review guidance; CI no longer retains obsoletemasterbranch triggers.
- Added a packaged canonical
templates/ralph-memory.mdand cross-platform create-new initialization with aggregate, byte-preserving validation for malformed feature memory. - Added read-only coordinated-commit and bookkeeping-only validation for work-unit history.
- Fresh iterations now read compact
ralph-memory.mdbefore tasks and design artifacts;progress.mdis append-only audit history and only optional recent context. - Completed work now persists task state, durable memory, and audit before one substantive commit. Failed or no-work attempts retain useful memory/audit changes without advancing
HEAD. - Completion now requires zero tasks, the exact terminal handoff, valid coordinated history, and an empty repository-wide
git status --short --untracked-files=all; dirty or inconsistent states stop immediately without repair or another agent iteration.
- Corrected the required Spec Kit version to
>=0.8.5so installs enforce the Copilot skills-mode integration metadata required by Ralph's dispatch logic. - Updated compatibility documentation and direct archive install examples for the
v1.2.1release.
- Official Claude Code support via a dedicated
claudeinvocation path (--dangerously-skip-permissions) in both Bash and PowerShell orchestrators (#8) - Regression coverage for Claude CLI detection and the Claude iteration codepath
- Documented
claudeas a supportedagent_clivalue and marked it as an optional tool requirement
- PowerShell Copilot dispatch now reads Spec Kit's nested
integration_settings.copilotsettings, so skills-mode repositories invoke/speckit-ralph-iterateinstead of the dottedspeckit.ralph.iterateagent. - Agent CLI detection now works on bash 3.2 (the default on macOS); the previous
${var,,}lowercasing failed withbad substitution, causing everyagent_clito be reported as unsupported - Claude iterations now pass the
speckit.ralph.iteratecommand text in the prompt instead of--agent speckit.ralph.iterate; Claude Code has no registered agent to select, so the old invocation always failed - Completion signal is now recognized only when
<promise>COMPLETE</promise>stands alone on a line, so agents mentioning the token in prose (e.g. "no<promise>COMPLETE</promise>") no longer terminate the loop prematurely
- Hardened
speckit.ralph.runso free-form launcher text likeImplement US1is warned about and ignored, preventing the host agent from implementing tasks inline instead of launching the Ralph loop (#18).
- Install-time Ralph config placement now targets
.specify/extensions/ralph/ralph-config.yml, matching the path loaded by the orchestrator scripts.
- Official Codex CLI support via a dedicated
codex execinvocation path in both Bash and PowerShell orchestrators - Regression coverage for agent CLI detection and Codex prompt assembly
- Documented supported
agent_clivalues and marked Copilot/Codex tool requirements as alternative optional agent CLIs
- Updated repository references from
Rubiss/spec-kit-ralphtoRubiss-Projects/spec-kit-ralphafter the repository transfer - Updated the README installation example to point at the
v1.0.2release archive
- Two-workflow release pipeline:
release.yml(workflow_dispatch) creates a version-bump PR, andrelease-publish.ymlcreates the tag and GitHub Release when the PR merges — respects branch protection without elevated tokens .github/workflows/tests.yml— CI workflow running bash tests on Ubuntu and PowerShell tests on Windows for PRs and pushes to main- Regression test suites: 25 bash tests (
tests/regression/bash/) and 26 PowerShell tests (tests/regression/powershell/)
get_incomplete_task_countinralph-loop.shreturning"0 0"instead of"0"when no incomplete tasks exist —grep -coutputs"0"with exit code 1, then|| echo 0duplicated it (#1)- Hardcoded
model: Claude Haiku 4.5 (copilot)inrun.mdfrontmatter preventing use with non-Copilot CLIs or setups without Haiku access (#1)
extension.yml— schema v1.0 manifest declaring 2 commands, 1 hook, 1 config template, and tool requirements (copilot, git)
speckit.ralph.run— thin launcher that validates prerequisites, resolves configuration, and launches the platform-appropriate orchestrator script in a visible terminalspeckit.ralph.iterate— single-iteration agent command that completes one work unit fromtasks.md, commits, and updatesprogress.md
ralph-loop.ps1— PowerShell orchestrator for Windows with real-time agent output streamingralph-loop.sh— Bash orchestrator for macOS/Linux with real-time agent output streaming- 5-layer configuration precedence: extension defaults → project config → local config → environment variables → CLI parameters
- 3-consecutive-failure circuit breaker
- Graceful Ctrl+C / SIGINT handling (exit code 130)
- Summary block on all 4 termination paths (completed, interrupted, failed, iteration limit)
- Cross-iteration progress tracking via
progress.md
ralph-config.template.yml— config template withmodel,max_iterations, andagent_clisettings- Environment variable overrides:
SPECKIT_RALPH_MODEL,SPECKIT_RALPH_MAX_ITERATIONS,SPECKIT_RALPH_AGENT_CLI
after_taskshook for optional post-task-generation loop start
README.mdwith installation, usage (agent command + direct script), configuration reference, loop architecture diagram, and extension structureCONTRIBUTING.mdwith PR guidelinesLICENSE(MIT)CODEOWNERS— auto-request review from@Rubiss.extensionignore— excludes.github/,.specify/,.vscode/, andspecs/from extension packaging.gitignorefor local config and build artifacts
- Full spec-kit design artifacts under
specs/001-port-ralph-extension/: spec, plan, research, data model, quickstart, tasks, requirements checklist, and contracts (command schemas, config schema, extension manifest)