{"id":49366279,"url":"https://github.com/merllinsbeard/speckit-ralph","last_synced_at":"2026-04-27T19:34:43.782Z","repository":{"id":333021109,"uuid":"1135959541","full_name":"merllinsbeard/speckit-ralph","owner":"merllinsbeard","description":"Ralph Wiggum Loop - Iterative execution engine for SPEC-KIT workflows with Claude Code and Codex","archived":false,"fork":false,"pushed_at":"2026-01-17T07:21:57.000Z","size":58,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-01-17T10:21:33.636Z","etag":null,"topics":["ai","ai-coding","automation","claude-code","codex","iterative-development","ralph","ralph-wiggum","spec-driven","spec-kit"],"latest_commit_sha":null,"homepage":null,"language":"Shell","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/merllinsbeard.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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":null,"dco":null,"cla":null}},"created_at":"2026-01-16T20:55:05.000Z","updated_at":"2026-01-17T08:00:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/merllinsbeard/speckit-ralph","commit_stats":null,"previous_names":["merllinsbeard/speckit-ralph"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/merllinsbeard/speckit-ralph","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/merllinsbeard%2Fspeckit-ralph","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/merllinsbeard%2Fspeckit-ralph/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/merllinsbeard%2Fspeckit-ralph/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/merllinsbeard%2Fspeckit-ralph/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/merllinsbeard","download_url":"https://codeload.github.com/merllinsbeard/speckit-ralph/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/merllinsbeard%2Fspeckit-ralph/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32352398,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-27T17:12:42.749Z","status":"ssl_error","status_checked_at":"2026-04-27T17:12:41.658Z","response_time":128,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["ai","ai-coding","automation","claude-code","codex","iterative-development","ralph","ralph-wiggum","spec-driven","spec-kit"],"created_at":"2026-04-27T19:34:43.083Z","updated_at":"2026-04-27T19:34:43.768Z","avatar_url":"https://github.com/merllinsbeard.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🔄 speckit-ralph\n\n### _Iterative execution engine for SPEC-KIT._\n\n**Automate the Ralph Wiggum Loop for Spec-Driven Development workflows.**\n\n---\n\n## Table of Contents\n\n- [🤔 What is speckit-ralph?](#-what-is-speckit-ralph)\n- [⚡ Quick Start](#-quick-start)\n- [📽️ How It Works](#️-how-it-works)\n- [🤖 Supported AI Agents](#-supported-ai-agents)\n- [🔧 CLI Reference](#-cli-reference)\n- [🛡️ Guardrails (Signs)](#️-guardrails-signs)\n- [📊 Activity Logging](#-activity-logging)\n- [⚙️ Environment Variables](#️-environment-variables)\n- [🔍 Troubleshooting](#-troubleshooting)\n- [📖 Learn More](#-learn-more)\n- [📄 License](#-license)\n\n## 🤔 What is speckit-ralph?\n\n[SPEC-KIT](https://github.com/github/spec-kit) is GitHub's official toolkit for **Spec-Driven Development** — a structured approach where specifications become executable, directly generating working implementations.\n\nWhile SPEC-KIT's `/speckit.implement` runs tasks once, **speckit-ralph automates the iterative loop**:\n\n1. Reads tasks from `specs/\u003cbranch\u003e/tasks.md`\n2. Feeds them to your AI agent (Claude Code or Codex)\n3. Runs multiple iterations until completion\n4. Tracks progress, learns from failures, applies guardrails\n\n**Think of it as:** SPEC-KIT defines the \"what\" and \"how\", Ralph executes the \"do\" repeatedly until done.\n\n## ⚡ Quick Start\n\n### Prerequisites\n\n1. **SPEC-KIT installed and initialized** in your project\n2. **Spec workflow complete**: `spec.md`, `plan.md`, `tasks.md` exist in `specs/\u003cbranch\u003e/`\n3. **Feature branch** matching your spec directory (e.g., `feature/auth` → `specs/feature/auth/`)\n\n### Installation\n\n```bash\nuv tool install speckit-ralph --from git+https://github.com/merllinsbeard/speckit-ralph.git\n```\n\n### Usage\n\n```bash\n# 1. Checkout your feature branch\ngit checkout feature/my-feature\n\n# 2. Initialize Ralph (creates .speckit-ralph/ directory)\nspeckit-ralph init\n\n# 3. Run the loop\nspeckit-ralph once --agent claude      # Single iteration (review each step)\nspeckit-ralph loop 10 --agent claude   # Multiple iterations (AFK mode)\n```\n\n### Optional: Inspect the prompt\n\n```bash\n# See what Ralph will send to the AI agent\nspeckit-ralph build-prompt\n\n# Save to file for review\nspeckit-ralph build-prompt --output prompt.md\n```\n\n### New to SPEC-KIT?\n\nIf you haven't set up SPEC-KIT yet:\n\n```bash\n# Install SPEC-KIT\nuv tool install specify-cli --from git+https://github.com/github/spec-kit.git\n\n# Initialize in your project\nspecify init . --here --ai claude\n\n# Create spec workflow (in Claude Code)\n/speckit.specify    # Create specifications\n/speckit.plan       # Create implementation plan\n/speckit.tasks      # Generate task breakdown\n\n# Then install and run Ralph\nuv tool install speckit-ralph --from git+https://github.com/merllinsbeard/speckit-ralph.git\nspeckit-ralph init\nspeckit-ralph loop 10 --agent claude\n```\n\n## 📽️ How It Works\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                    SPEC-KIT Phase                           │\n│                   (Human-Guided)                            │\n├─────────────────────────────────────────────────────────────┤\n│  /speckit.specify  →  specs/\u003cbranch\u003e/spec.md               │\n│  /speckit.plan     →  specs/\u003cbranch\u003e/plan.md               │\n│  /speckit.tasks    →  specs/\u003cbranch\u003e/tasks.md              │\n└─────────────────────────────────────────────────────────────┘\n                            ↓\n┌─────────────────────────────────────────────────────────────┐\n│                    Ralph Phase                              │\n│                  (Automated Loop)                           │\n├─────────────────────────────────────────────────────────────┤\n│  speckit-ralph loop 10 --agent claude                       │\n│    ├─ AI reads tasks.md, spec.md, plan.md                  │\n│    ├─ AI implements one task per iteration                 │\n│    ├─ AI sees previous work via git history (self-ref)     │\n│    └─ Loop continues until:                                │\n│        ├─ All tasks complete                               │\n│        ├─ \u003cpromise\u003eCOMPLETE\u003c/promise\u003e detected             │\n│        └─ Max iterations reached                           │\n└─────────────────────────────────────────────────────────────┘\n```\n\n## 🤖 Supported AI Agents\n\n| Agent                                        | CLI        | Status |\n| -------------------------------------------- | ---------- | ------ |\n| [Claude Code](https://claude.ai/download)    | `claude`   | ✅     |\n| [Codex CLI](https://github.com/openai/codex) | `codex`    | ✅     |\n| [Droid](https://github.com/droidcli/droid)   | `droid`    | ✅     |\n| [OpenCode](https://opencode.ai)              | `opencode` | ✅     |\n\n## 🔧 CLI Reference\n\n### Commands\n\n| Command                         | Description                         |\n| ------------------------------- | ----------------------------------- |\n| `speckit-ralph once`            | Run a single iteration              |\n| `speckit-ralph loop \u003cN\u003e`        | Run N iterations                    |\n| `speckit-ralph init`            | Initialize .speckit-ralph directory |\n| `speckit-ralph show-guardrails` | Display guardrails                  |\n| `speckit-ralph show-activity`   | Display activity log                |\n| `speckit-ralph show-errors`     | Display errors log                  |\n| `speckit-ralph build-prompt`    | Generate prompt for inspection      |\n| `speckit-ralph scripts-path`    | Print bundled scripts path          |\n\n### Options\n\n| Option                   | Commands                                                  | Description                                                    |\n| ------------------------ | --------------------------------------------------------- | -------------------------------------------------------------- |\n| `--agent`, `-a`          | `once`, `loop`                                            | **Required.** Agent: `claude`, `codex`, `droid`, or `opencode` |\n| `--keep-artifacts`, `-k` | `once`, `loop`                                            | Keep temp files for debugging                                  |\n| `--promise`, `-p`        | `once`, `loop`                                            | Completion promise string                                      |\n| `--detach`, `-d`         | `loop`                                                    | Run in background                                              |\n| `--sleep`, `-s`          | `loop`                                                    | Seconds between iterations                                     |\n| `--spec`, `-S`           | `once`, `loop`, `build-prompt`                            | Spec directory path (overrides branch detection)               |\n| `--root`, `-r`           | `init`, `show-activity`, `show-errors`, `show-guardrails` | Project root directory                                         |\n| `--lines`, `-n`          | `show-activity`, `show-errors`                            | Number of lines to show (default: 50)                          |\n| `--output`, `-o`         | `build-prompt`                                            | Output file path                                               |\n\n### Examples\n\n```bash\n# Single iteration with Claude\nspeckit-ralph once --agent claude\n\n# Single iteration with Codex\nspeckit-ralph once --agent codex\n\n# 10 iterations with Claude, keep artifacts\nspeckit-ralph loop 10 --agent claude --keep-artifacts\n\n# Run Codex in background\nspeckit-ralph loop 20 --agent codex --detach\n\n# Custom sleep between iterations\nspeckit-ralph loop 10 --agent claude --sleep 5\n\n# Multi-spec: explicitly specify which spec to use\nspeckit-ralph loop 5 --agent claude --spec specs/feature/auth\nspeckit-ralph once --agent codex --spec specs/feature/payments\n```\n\n### Multi-Spec Projects\n\nBy default, Ralph detects which spec to use based on your current git branch name (e.g., `feature/auth` maps to `specs/feature/auth/`).\n\nFor projects with multiple specs, you can explicitly specify which spec to use:\n\n```bash\n# Override branch detection with --spec\nspeckit-ralph loop 10 --agent claude --spec specs/feature/auth\n\n# Use relative path from repo root\nspeckit-ralph once --agent codex --spec specs/feature/payments\n\n# Or absolute path\nspeckit-ralph loop 5 --agent claude --spec /path/to/my-project/specs/feature/checkout\n```\n\n**When to use `--spec`:**\n\n- Working on a different spec than your current branch\n- Running multiple loops in parallel for different specs\n- Testing a spec from a non-feature branch (e.g., `main`)\n\n## 🛡️ Guardrails (Signs)\n\nGuardrails are **signs** — lessons learned from failures that prevent recurring mistakes. They are stored in `.speckit-ralph/guardrails.md` and injected into each iteration's prompt.\n\nEdit `.speckit-ralph/guardrails.md` directly to add new signs.\n\n### Sign Format\n\n```markdown\n### Sign: [Name]\n\n- **Trigger**: When this applies\n- **Instruction**: What to do instead\n- **Added after**: Why it was added\n```\n\n### Types of Signs\n\n| Type             | Purpose                          |\n| ---------------- | -------------------------------- |\n| **Preventive**   | Stop problems before they happen |\n| **Corrective**   | Fix recurring mistakes           |\n| **Process**      | Enforce good practices           |\n| **Architecture** | Guide design decisions           |\n\n## 📊 Activity Logging\n\nRalph automatically logs all activity to `.speckit-ralph/activity.log`:\n\n- Loop start/end events\n- Iteration start/end with duration\n- Errors and failures\n- Git HEAD changes per iteration\n\nRun summaries are stored in `.speckit-ralph/runs/` with:\n\n- CLI used (claude or codex)\n- Duration\n- Status (success or error)\n- Git commits made\n\n## ⚙️ Environment Variables\n\n| Variable                  | Default                   | Description                          |\n| ------------------------- | ------------------------- | ------------------------------------ |\n| `RALPH_AGENT`             | `claude`                  | Agent: `claude` or `codex`           |\n| `RALPH_PROMISE`           | `COMPLETE`                | Completion promise string            |\n| `RALPH_SLEEP_SECONDS`     | `2` (claude), `1` (codex) | Seconds between iterations           |\n| `RALPH_ARTIFACT_DIR`      | (temp)                    | Directory for artifacts              |\n| `RALPH_SKIP_BRANCH_CHECK` | `0`                       | Skip feature branch validation       |\n| `RALPH_SPEC_DIR`          | (auto)                    | Override spec directory (multi-spec) |\n| `CODEX_SANDBOX`           | `workspace-write`         | Codex sandbox mode                   |\n| `CODEX_APPROVAL_POLICY`   | `never`                   | Codex approval policy                |\n\n## 🔍 Troubleshooting\n\n### SPEC-KIT not initialized\n\n```\nERROR: SPEC-KIT not initialized in this project.\n```\n\n**Solution:** Ralph requires SPEC-KIT to be set up first. Run these commands:\n\n```bash\n# 1. Install SPEC-KIT\nuv tool install specify-cli --from git+https://github.com/github/spec-kit.git\n\n# 2. Initialize SPEC-KIT in your project\nspecify init . --here --ai claude\n\n# 3. Create your spec in Claude Code\n/speckit.specify\n/speckit.plan\n/speckit.tasks\n\n# 4. Now Ralph can run\nspeckit-ralph init\nspeckit-ralph loop 10\n```\n\n### plan.md not found\n\n```\nERROR: plan.md not found at specs/\u003cbranch\u003e/plan.md\n```\n\n**Solution:** Complete the SPEC-KIT workflow:\n\n```bash\n/speckit.specify    # Create spec.md\n/speckit.plan       # Create plan.md\n/speckit.tasks      # Create tasks.md\nspeckit-ralph loop 10   # Now Ralph can run\n```\n\n### Tasks not recognized\n\n**Solution:** Ensure `tasks.md` follows SPEC-KIT format:\n\n```markdown\n## User Story 1: [Title]\n\n- [ ] Task 1 description\n- [ ] Task 2 description\n\n## User Story 2: [Title]\n\n- [ ] Task 3 description\n```\n\n## 📖 Learn More\n\n- **[SPEC-KIT](https://github.com/github/spec-kit)** — GitHub's official Spec-Driven Development toolkit\n- **[Spec-Driven Methodology](https://github.com/github/spec-kit/blob/main/spec-driven.md)** — Complete methodology guide\n- **[Ralph Wiggum Technique](https://ghuntley.com/ralph/)** — Original methodology\n- **[11 Tips for Better Ralph Wiggums](https://www.aihero.dev/11-tips-for-better-ralph-wiggums)** — Best practices\n\n## 📄 License\n\nThis project is licensed under the terms of the MIT open source license. See [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmerllinsbeard%2Fspeckit-ralph","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmerllinsbeard%2Fspeckit-ralph","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmerllinsbeard%2Fspeckit-ralph/lists"}