{"id":51066654,"url":"https://github.com/iyaki/specralph","last_synced_at":"2026-06-23T07:01:14.557Z","repository":{"id":341333933,"uuid":"1169611078","full_name":"iyaki/specralph","owner":"iyaki","description":"Spec-driven AI coding automation CLI. Workflow runner for Claude Code, OpenCode, Cursor, and other agent CLIs.","archived":false,"fork":false,"pushed_at":"2026-06-19T15:32:47.000Z","size":587,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-19T16:16:02.023Z","etag":null,"topics":["agentic","ai","ai-agents","ai-developer-tools","automation","cli","code-generation","developer-tools","devtools","go","harness-engineering","llm","loop-engineering","prompt-engineering","ralph-loop","ralph-wiggum","software-development","spec-driven-development"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iyaki.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-28T23:56:43.000Z","updated_at":"2026-06-19T15:33:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/iyaki/specralph","commit_stats":null,"previous_names":["iyaki/ralph","iyaki/ralphex","iyaki/specralph"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/iyaki/specralph","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iyaki%2Fspecralph","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iyaki%2Fspecralph/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iyaki%2Fspecralph/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iyaki%2Fspecralph/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iyaki","download_url":"https://codeload.github.com/iyaki/specralph/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iyaki%2Fspecralph/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34678931,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-23T02:00:07.161Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic","ai","ai-agents","ai-developer-tools","automation","cli","code-generation","developer-tools","devtools","go","harness-engineering","llm","loop-engineering","prompt-engineering","ralph-loop","ralph-wiggum","software-development","spec-driven-development"],"created_at":"2026-06-23T07:01:13.763Z","updated_at":"2026-06-23T07:01:14.543Z","avatar_url":"https://github.com/iyaki.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SpecRalph - Spec-Driven Ralph-Wiggum Agentic AI Loops\n\n[![GitHub Release](https://img.shields.io/github/v/release/iyaki/specralph)](https://github.com/iyaki/specralph/releases)\n[![Build Status](https://img.shields.io/github/actions/workflow/status/iyaki/specralph/quality.yml)](https://github.com/iyaki/specralph/actions)\n[![License](https://img.shields.io/github/license/iyaki/specralph)](LICENSE)\n\nSpecRalph (formerly Ralphex) is a **spec-driven AI coding automation CLI** for developers. It orchestrates iterative development loops with external agent CLIs like **Claude Code, OpenCode, Cursor, and Oh My Pi**. Built with **Go** for **cross-platform** support (Linux, macOS, Windows), SpecRalph implements the [Ralph Wiggum methodology](https://ghuntley.com/ralph/) for **AI-assisted software development**: define specs, generate implementation plans, and execute automated coding loops until completion.\n\nSpecRalph wraps a supported agent CLI in a repeatable loop: resolve a prompt, run the agent, and repeat until the agent emits `\u003cpromise\u003eCOMPLETE\u003c/promise\u003e` or max iterations is reached. Each pass works against the updated repository, which makes it a good fit for specs, implementation plans, and repository-local prompts.\n\n\u003e [!NOTE]\n\u003e The repository is `iyaki/specralph`, but the CLI command remains `ralph`.\n\n\u003e [!IMPORTANT]\n\u003e SpecRalph does not bundle an agent runtime. Install and authenticate a supported agent CLI separately, then make sure its binary is available on your `PATH`.\n\n## Table of Contents\n\n- [What is Specralph?](#what-is-specralph)\n- [Why Specralph](#why-specralph)\n- [Supported Agents](#supported-agents)\n- [Install](#install)\n- [Quick Start](#quick-start)\n- [Command Model](#command-model)\n- [Creating Custom Prompts](#creating-custom-prompts)\n- [Prompt Resolution](#prompt-resolution)\n- [Configuration](#configuration)\n- [Completion Signal](#completion-signal)\n- [Workflow](#workflow)\n- [Spec Creator Skill](#spec-creator-skill)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Why Specralph\n\n- Runs a repeatable prompt loop until the agent signals completion or max iterations is reached.\n- Supports built-in `build` and `plan` prompts plus inline, stdin, and file-based prompts.\n- Applies predictable precedence across flags, environment variables, config files, and prompt front matter.\n- Keeps repository-specific prompts and local overrides easy to manage.\n- Fits the Ralph Wiggum style of specs-first development.\n\n## Why Spec-Driven?\n\nSpec-driven development reduces ambiguity and keeps AI agents focused on concrete requirements.\n\n## Supported Agents\n\n| Agent | Binary |\n| --- | --- |\n| Claude Code | `claude` |\n| OpenCode | `opencode` |\n| Cursor | `cursor` |\n| Oh My Pi | `omp` |\n\n**Codex, Copilot, Gemini, and more agents, coming soon**\n\n`model` and `agent-mode` are forwarded when the selected agent CLI supports them.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eAdding support for new agents\u003c/strong\u003e\u003c/summary\u003e\n\n### Adding Support for New Agents\n\nAgent support Pull Requests are always welcomed. To add or update agent integrations, follow the workflow in [`CONTRIBUTING.md` (\"Adding Support for a New Agent\")](CONTRIBUTING.md#adding-support-for-a-new-agent):\n\n1. `agent-spec-creation` for spec definition\n2. `agent-implementation` for TDD-based code changes\n\n\u003c/details\u003e\n\n## Install\n\nRequirements:\n\n- A supported agent CLI in `PATH`\n- Go `1.25` if you are building from source\n\nPrebuilt binaries are published on [GitHub Releases](https://github.com/iyaki/specralph/releases). The latest release page is https://github.com/iyaki/specralph/releases/latest.\n\n## Quick Install (Recommended)\n\n### One-line install (Linux/macOS)\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/iyaki/specralph/main/scripts/install.sh | bash\n```\n\n### Manual download\n\n1. Visit [GitHub Releases](https://github.com/iyaki/specralph/releases/latest)\n2. Download the binary for your platform\n3. Move to your PATH:\n   ```bash\n   chmod +x ralph\n   sudo mv ralph /usr/local/bin/\n   ```\n\n### Devcontainer feature:\n\n`ghcr.io/iyaki/devcontainer-features/ralph:1`\n\n### Build from source\n\n\n```bash\n# Clone the repository and then:\nmake build\n./bin/ralph --help\n./bin/ralph version\n```\n\nInstall system-wide after building:\n\n```bash\nmake install\n```\n\nFor a reproducible local environment, open the repository with the included dev container in `.devcontainer/devcontainer.json`.\n\n## Quick Start\n\nIf you are already doing spec-driven development:\n\n```bash\n# Create a starter config\nralph init\n\n# Generate or refresh the implementation plan for a scope\nralph plan authentication\n\n# Run the default build loop\nralph\n\n# Run the same default loop through the explicit entrypoint and prompt name\nralph run build\n\n# Use a different agent for one run\nralph --agent claude --model claude-sonnet-4 build\n```\n\nCommon prompt entrypoints:\n\n```bash\n# Inline prompt text\nralph --prompt \"Review the repository and summarize the highest-risk area\"\n\n# Prompt from stdin\nprintf 'Prompt from stdin' | ralph -\n\n# Prompt from a file with an explicit prompt name\nralph --prompt-file ./prompts/review.md review\n\n# Per-run child agent environment override\nralph --env HTTP_PROXY=http://127.0.0.1:8080 build\n```\n\n## Command Model\n\n| Command | Behavior |\n| --- | --- |\n| `ralph` | Equivalent to `ralph run build` |\n| `ralph run \u003cprompt\u003e [scope]` | Explicit loop entrypoint |\n| `ralph \u003cprompt\u003e [scope]` | Alias to `ralph run \u003cprompt\u003e [scope]` when `\u003cprompt\u003e` is not a subcommand |\n| `ralph prompts list` | List all available built-in and custom prompts |\n| `ralph prompts show \u003cname\u003e` | Display full content of a specific prompt |\n| `ralph init` | Generate a starter config file |\n| `ralph run init` | Run a prompt named `init` |\n| `ralph version` | Print the version number |\n\nUseful examples:\n\n```bash\n# Built-in planning prompt\nralph plan payment-service\n\n# List available prompts\nralph prompts list\n\n# View the full build prompt\nralph prompts show build\n\n# View the full plan prompt\nralph prompts show plan\n\n# Explicit run command\nralph run build\n\n# Inline prompt text\nralph --prompt \"Review the repository and summarize the highest-risk area\"\n\n# Prompt from stdin\nprintf 'Prompt from stdin' | ralph -\n\n# Prompt from a file with an explicit prompt name\nralph --prompt-file ./prompts/review.md review\n\n# Per-run child agent environment override\nralph --env HTTP_PROXY=http://127.0.0.1:8080 build\n# Check Ralph version\nralph version\n```\n\n### `ralph init`\n\n`ralph init` currently writes a starter config with repository-friendly defaults. It requires an interactive terminal, writes to `./ralph.toml` by default, and fails if the target already exists unless `--force` is set.\n\n```bash\nralph init\nralph init --output ./team/ralph.toml\nralph init --force\n```\n\nThe generated starter config disables logging by default (log file is empty). Users can enable logging during the interactive questionnaire by providing a log file path. The default prompts directory is set to `.ralph/prompts` so prompt files can live inside the repository.\n\n### `ralph prompts`\n\nThe `prompts` command helps you discover and inspect built-in and custom prompts.\n\n```bash\n# List all available prompts\nralph prompts list\n\n# View the full content of the build prompt\nralph prompts show build\n\n# View the full content of the plan prompt\nralph prompts show plan\n\n# View a custom prompt file\nralph prompts show review\n```\n\nThe `prompts list` subcommand displays:\n- Built-in Prompts: `build` and `plan` with brief descriptions\n- Custom Prompts: Any prompt files found in the configured prompts directory with their file paths\n\nThis command is useful when you want to:\n- Inspect built-in prompts to understand what instructions Specralph sends to the agent\n- Review custom prompts before using them\n- Discover available prompts in your repository\n- Debug prompt content without actually running the agent loop\n\nThe full prompt content is displayed exactly as it would be sent to the agent (with frontmatter stripped for custom prompts), making it easy to verify your prompt configuration or understand the default behavior.\n\n## Creating Custom Prompts\n\nWhen writing custom prompts (inline via `--prompt` or in prompt files), always include the completion signal so Specralph knows when the agent is done.\n\n**Inline prompt example:**\n```bash\nralph --prompt \"Review the authentication module and suggest improvements. When done, output: \u003cpromise\u003eCOMPLETE\u003c/promise\u003e\"\n```\n\n**Prompt file example (`prompts/review.md`):**\n```markdown\nReview the authentication module and identify security issues.\nWrite tests to cover edge cases.\nWhen everything is done, output: \u003cpromise\u003eCOMPLETE\u003c/promise\u003e\n```\n\nYou can also use the placeholder `\u003cCOMPLETION_SIGNAL\u003e` — Specralph automatically replaces it with `\u003cpromise\u003eCOMPLETE\u003c/promise\u003e` at runtime:\n```markdown\nImplement feature X.\nWrite tests for Y.\nWhen everything is done, output: \u003cCOMPLETION_SIGNAL\u003e\n```\n\nFor full details on prompt resolution order and front matter, see [Prompt Resolution](#prompt-resolution).\n\n ## Prompt Resolution\n\nPrompt content is resolved in this order:\n\nFor `model` and `agent-mode`, effective precedence is:\n\n```text\nflags \u003e environment variables \u003e prompt front matter \u003e [prompt-overrides.\u003cprompt\u003e] \u003e global config\n```\n\n## Configuration\n\nSpecralph resolves settings with this precedence:\n\n```text\nflags \u003e environment variables \u003e config file \u003e defaults\n```\n\n### Config Files and Local Overlays\n\nBase config selection happens in this order:\n\n1. `--config \u003cpath\u003e`\n2. `RALPH_CONFIG`\n3. `./ralph.toml` in the current directory\n\nIf a base config file is selected, a sibling `ralph-local.toml` is merged over it before environment variables and flags are applied. This lets you commit shared defaults in `ralph.toml` and keep machine-specific overrides untracked in `ralph-local.toml`.\n\nFor example, `--config ./team/ralph.toml` loads `./team/ralph-local.toml` if it exists. It does not look for `./ralph-local.toml` in the current working directory.\n\n`[env]` entries and `[prompt-overrides.\u003cprompt\u003e]` entries merge by key across `ralph.toml` and `ralph-local.toml`. Parse errors in either file stop the run before the agent starts.\n\n\u003e [!TIP]\n\u003e Keep shared team defaults in `ralph.toml`, add `ralph-local.toml` to `.gitignore`, and use the local file for personal overrides and secrets.\n\nExample `ralph.toml`:\n\n```toml\nagent = \"opencode\"\nmodel = \"gpt-5\"\nmax-iterations = 30\n\nspecs-dir = \"specs\"\nspecs-index-file = \"README.md\"\nimplementation-plan-name = \"IMPLEMENTATION_PLAN.md\"\nprompts-dir = \".ralph/prompts\"\n\nno-log = false\nlog-file = \"./ralph.log\"\n\n[prompt-overrides.plan]\nagent-mode = \"planner\"\n\n[env]\nHTTP_PROXY = \"http://127.0.0.1:8080\"\n```\n\n### Environment Variables\n\n| Variable | Purpose |\n| --- | --- |\n| `RALPH_CONFIG` | Select the base config file path |\n| `RALPH_MAX_ITERATIONS` | Override `max-iterations` |\n| `RALPH_SPECS_DIR` | Override `specs-dir` |\n| `RALPH_SPECS_INDEX_FILE` | Override `specs-index-file` |\n| `RALPH_IMPLEMENTATION_PLAN_NAME` | Override `implementation-plan-name` |\n| `RALPH_CUSTOM_PROMPT` | Provide inline prompt text, similar to `--prompt` |\n| `RALPH_LOG_FILE` | Override the log file path |\n| `RALPH_LOG_ENABLED` | Boolean: `1` or `true` enables logging, `0` or `false` disables it |\n| `RALPH_LOG_APPEND` | Boolean: `1` or `true` appends, `0` or `false` truncates on start |\n| `RALPH_PROMPTS_DIR` | Override `prompts-dir` |\n| `RALPH_AGENT` | Select the agent: `opencode`, `claude`, or `cursor` |\n| `RALPH_MODEL` | Override `model` |\n| `RALPH_AGENT_MODE` | Override `agent-mode` |\n\nIf `prompts-dir` is unset everywhere, the runtime default is `$HOME/.ralph`. The starter config written by `ralph init` pins `prompts-dir` to `.ralph/prompts` so prompt files live in the repository.\n\n### Child Agent Environment\n\nSpecralph's own `RALPH_*` settings are separate from the environment passed to the child agent. Use `[env]` in config for shared values and repeatable `--env KEY=VALUE` flags for per-run overrides.\n\nChild agent environment precedence is:\n\n```text\ninherited environment \u003c [env] in config \u003c repeated --env flags\n```\n\nLater `--env` flags win for the same key. Each flag entry must use `KEY=VALUE`, and keys must match `[A-Za-z_][A-Za-z0-9_]*`.\n\n### Logging\n\nWith no config file, logging is disabled by default. When logging is enabled and no explicit path is configured, the effective default log file is `./ralph.log` in the current working directory.\n\nLogs mirror stdout and are written with `0600` permissions. Each run starts with a header that includes a timestamp plus git branch and commit metadata; unresolved git values are recorded as `N/A`.\n\n```bash\n# Enable logs for one run even if config disables them\nralph --no-log=false --log-file ./ralph.log build\n\n# Start from an empty log file\nralph --no-log=false --log-file ./ralph.log --log-truncate build\n\n# Same behavior through environment variables\nRALPH_LOG_ENABLED=1 RALPH_LOG_APPEND=0 ralph build\n```\n\n## Completion Signal\n\nRalph detects task completion by searching for the following XML-like tag in agent output:\n\n```xml\n\u003cpromise\u003eCOMPLETE\u003c/promise\u003e\n```\n\nThe built-in `build` and `plan` prompts use the placeholder `\u003cCOMPLETION_SIGNAL\u003e`, which Ralph automatically replaces with `\u003cpromise\u003eCOMPLETE\u003c/promise\u003e` at runtime before sending the prompt to the agent.\n\nWhen creating custom prompts (inline via `--prompt` or in prompt files), you can either:\n\n1. Use the placeholder `\u003cCOMPLETION_SIGNAL\u003e` — Ralph will replace it for you:\n   ```markdown\n   Implement feature X.\n   Write tests for Y.\n   When everything is done, output: \u003cCOMPLETION_SIGNAL\u003e\n   ```\n\n2. Or directly include the actual signal:\n   ```markdown\n   Implement feature X.\n   Write tests for Y.\n   When everything is done, output: \u003cpromise\u003eCOMPLETE\u003c/promise\u003e\n   ```\n\nThe tag is case-sensitive and must appear exactly as shown. Ralph will stop after detecting the first occurrence.\n\n\u003e [!TIP]\n\u003e For technical details on the completion signal mechanism, see [specs/prompts.md#completion-signal](specs/prompts.md#completion-signal).\n\u003e [!CAUTION]\n\u003e Prompt text and agent output are written to stdout and, when logging is enabled, to the configured log file. Treat prompt files, config overrides, and logs as sensitive.\n\n## Workflow\n\nSpecralph is designed around a specs-first loop inspired by Geoffrey Huntley's [Ralph methodology](https://ghuntley.com/ralph/).\n\nTypical flow:\n\n1. Define or refine requirements in `specs/`.\n2. Run `ralph plan \u003cscope\u003e` to generate or update `IMPLEMENTATION_PLAN.md`.\n3. Run `ralph` or `ralph build` to implement the next task.\n4. Repeat until the agent returns the completion signal.\n\nThe built-in prompts use a `\u003cCOMPLETION_SIGNAL\u003e` placeholder, which Specralph replaces with `\u003cpromise\u003eCOMPLETE\u003c/promise\u003e` before sending the prompt to the agent.\n\n## Spec Creator Skill\n\nThis repo includes the `spec-creator` [skill](https://agentskills.io/home) (see [.agents/skills/spec-creator/SKILL.md](.agents/skills/spec-creator/SKILL.md)) for the first phase of Geoffrey Huntley's Ralph Wiggum methodology.\n\nTo install it using Vercel's skills CLI, run:\n\n```sh\nnpx skills add https://github.com/iyaki/specralph/ --skill spec-creator\n```\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for:\n\n- Development setup and prerequisites\n- Specs-first workflow guidelines\n- Testing and quality gates\n- How to add support for new agents\n\n## License\n\n[MIT License](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiyaki%2Fspecralph","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fiyaki%2Fspecralph","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiyaki%2Fspecralph/lists"}