{"id":49193656,"url":"https://github.com/zomars/ralph","last_synced_at":"2026-04-23T08:31:28.848Z","repository":{"id":341905947,"uuid":"1156540703","full_name":"zomars/ralph","owner":"zomars","description":"Ralph is a suite of autonomous agents that orchestrate Claude CLI for backlog-driven SDLC automation. Each agent acts as a specialized team member, picking up tasks from your backlog based on specific criteria.","archived":false,"fork":false,"pushed_at":"2026-03-18T22:31:42.000Z","size":520,"stargazers_count":26,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-19T11:45:28.271Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zomars.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-02-12T19:07:39.000Z","updated_at":"2026-03-19T06:08:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/zomars/ralph","commit_stats":null,"previous_names":["zomars/ralph"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/zomars/ralph","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zomars%2Fralph","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zomars%2Fralph/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zomars%2Fralph/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zomars%2Fralph/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zomars","download_url":"https://codeload.github.com/zomars/ralph/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zomars%2Fralph/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32173055,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-23T02:19:40.750Z","status":"ssl_error","status_checked_at":"2026-04-23T02:17:55.737Z","response_time":53,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5: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":[],"created_at":"2026-04-23T08:31:26.554Z","updated_at":"2026-04-23T08:31:28.835Z","avatar_url":"https://github.com/zomars.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ralph Agent Ecosystem\n\nRalph is a suite of autonomous agents that orchestrate Claude CLI for backlog-driven SDLC automation. Each agent acts as a specialized team member, picking up tasks from your backlog based on specific criteria.\n\n\u003cimg width=\"1920\" height=\"1080\" alt=\"image\" src=\"https://github.com/user-attachments/assets/48544de9-1619-4341-9d79-31cd5e960ff6\" /\u003e\n\n\n## Install\n\n```bash\ngit clone \u003crepo-url\u003e ralph\ncd ralph\nnpm link\n```\n\nThis installs the `ralph` command globally. Run it from any project directory.\n\nTo uninstall: `npm unlink -g ralph`\n\n## Configuration\n\n### Quick Start\n\n```bash\ncd your-project\nralph init          # Creates .ralphrc + .mcp.json from templates\n# Edit .ralphrc with your credentials\nralph config        # Verify configuration\n```\n\n### `.ralphrc`\n\nRalph loads `.ralphrc` from the current working directory. This file sets your backlog provider and credentials:\n\n**Jira Provider:**\n```zsh\nexport RALPH_PROVIDER=\"jira\"\nexport JIRA_EMAIL=\"you@example.com\"\nexport JIRA_API_TOKEN=\"your-token\"\nexport JIRA_BASE_URL=\"https://yourorg.atlassian.net\"\nexport RALPH_POLL_INTERVAL=5\n```\n\n**Linear Provider:**\n```zsh\nexport RALPH_PROVIDER=\"linear\"\nexport LINEAR_API_KEY=\"lin_api_...\"\nexport LINEAR_TEAM_KEY=\"ENG\"\nexport RALPH_POLL_INTERVAL=5\n```\n\n**GitHub Issues Provider:**\n```zsh\nexport RALPH_PROVIDER=\"github-issues\"\nexport GITHUB_REPO=\"owner/repo\"\nexport RALPH_POLL_INTERVAL=5\n# gh CLI handles auth via GITHUB_TOKEN or `gh auth login`\n```\n\n**GitHub Projects Provider:**\n```zsh\nexport RALPH_PROVIDER=\"github-projects\"\nexport GITHUB_REPO=\"owner/repo\"\nexport GITHUB_PROJECT_NUMBER=1\nexport RALPH_POLL_INTERVAL=5\n# gh CLI handles auth via GITHUB_TOKEN or `gh auth login`\n```\n\n**File Provider:**\n```zsh\nexport RALPH_PROVIDER=\"file\"\nexport RALPH_PRD_FILE=\"./prd.md\"  # Optional, defaults to ./prd.md\nexport RALPH_POLL_INTERVAL=5\n```\n\nAlternatively, set these as environment variables in your shell profile.\n\n## Commands\n\n```\nralph \u003ccommand\u003e [options]\n\nAgent commands (backlog-driven):\n  planner           Run the Planner agent\n  implementer       Run the Implementer agent\n  reviewer          Run the Reviewer agent\n  tester            Run the Tester agent\n  refactor          Run the Refactorer agent\n  documenter        Run the Documenter agent\n\nGitHub commands:\n  fixer             Respond to PR review feedback\n  merger            Auto-merge approved PRs\n\nAgent options:\n  --afk             Run in continuous poll loop (default)\n  --once            Run a single iteration, then exit\n\nDebugging:\n  debug \u003cagent\u003e [N] Tail a running agent's output (default: instance 1)\n    -f, --follow    Live tail (like tail -f)\n    -n, --lines N   Number of lines to show (default: 200)\n    --raw           Show raw JSON instead of rendered text\n\nUtility commands:\n  status            Show task counts and running instances for all agents\n  validate          Run routing validation (--matrix, --check-prompts, --check-loops, --check-all)\n  init              Create .ralphrc + .mcp.json in current directory\n  config            Show current configuration\n  version           Show version\n```\n\n### Agent Loops\n\nEach agent runs an infinite poll loop: check for work, invoke Claude, parse output, cooldown, repeat.\n\n**Backlog-gated agents** poll a provider (Jira/Linear/GitHub Issues/GitHub Projects/file) for matching tasks:\n\n| Command              | Role          | Trigger                                                  |\n| :------------------- | :------------ | :------------------------------------------------------- |\n| `ralph planner`      | Product Owner | Description empty/TODO, or label `needs-planning`        |\n| `ralph implementer`  | Developer     | Status \"To Do\"/\"In Progress\", description filled         |\n| `ralph reviewer`     | QA/Lead       | Status \"In Review\"                                       |\n| `ralph tester`       | QA Engineer   | Label `needs-tests`, not Done                            |\n| `ralph refactor`     | Architect     | Label `tech-debt`                                        |\n| `ralph documenter`   | Tech Writer   | Status \"Done\", not yet documented                        |\n\n**GitHub-gated agents** poll for PRs via `gh` CLI:\n\n| Command              | Role          | Trigger                                                  |\n| :------------------- | :------------ | :------------------------------------------------------- |\n| `ralph fixer`        | Developer     | Open PRs with unresolved review threads                  |\n| `ralph merger`       | Release Eng   | Approved PRs passing all checks                          |\n\n### Running a Full Team\n\n```bash\n# Run each agent in a separate terminal tab:\nralph planner        # Tab 1\nralph implementer    # Tab 2\nralph reviewer       # Tab 3\nralph tester         # Tab 4\nralph refactor       # Tab 5\nralph documenter     # Tab 6\nralph fixer          # Tab 7\nralph merger         # Tab 8\n```\n\n### Multi-Instance Support\n\nAgents claim numbered slots in `/tmp/ralph-{agent}/{n}`. Instance number determines which task to pick (instance 1 picks task 1, instance 2 picks task 2, etc.). Stale PIDs are auto-cleaned.\n\n```bash\n# Run two implementers in parallel (separate terminals):\nralph implementer    # Picks task #1\nralph implementer    # Picks task #2\n```\n\n### Debugging Running Agents\n\n```bash\nralph debug implementer         # Last 200 lines of rendered output\nralph debug implementer -f      # Live tail\nralph debug implementer 2 --raw # Raw JSON from instance 2\nralph status                    # Task counts + running instances overview\n```\n\n## Providers\n\nRalph abstracts the backlog system. Set `RALPH_PROVIDER` to switch providers.\n\n### Supported Providers\n\n- **jira** (default) — Jira Cloud via a bundled MCP server (`ralph-jira-mcp`)\n- **linear** — Linear via a bundled MCP server (`ralph-linear-mcp`)\n- **github-issues** — GitHub Issues with label-based statuses (`status:to-do`, etc.) via `gh` CLI\n- **github-projects** — GitHub Projects v2 with board column statuses via `gh` CLI + GraphQL\n- **file** — Local markdown file (prd.md)\n\n### Provider Architecture\n\nEach provider consists of 3 files:\n\n| File | Purpose |\n| :--- | :------ |\n| `lib/providers/\u003cname\u003e.sh` | Shell: `PROVIDER_ENV_VARS` array + `provider_check_tasks()` function |\n| `providers/\u003cname\u003e/instructions.md` | Claude system prompt overlay with tool mappings |\n| `providers/\u003cname\u003e/routing.json` | Queries and routing rules per agent |\n\n### File Provider\n\nThe file provider lets you use Ralph with a local markdown file instead of a cloud backlog system. Tasks are defined as H2 sections with metadata in HTML comments.\n\n**Task Format:**\n```markdown\n## USER-001: Feature Name\n\u003c!-- status: to-do --\u003e\n\u003c!-- labels: enhancement, needs-planning --\u003e\n\u003c!-- priority: high --\u003e\n\nDescription content here...\n\n### Acceptance Criteria\n- [ ] Item 1\n```\n\n**Supported Statuses:** `to-do`, `in-progress`, `in-review`, `done`\n\n**Standard Labels:** `needs-planning`, `needs-tests`, `tech-debt`, `ralph-blocked`, `ralph-failed`, `needs-input`, `documented`\n\n**Query Syntax:**\n- `status:to-do,in-progress` — status IN list\n- `!status:done` — status NOT in list\n- `label:needs-tests` — has label\n- `!label:tech-debt` — doesn't have label\n- `description:empty` — description is empty or contains TODO\n- `!description:empty` — description is not empty\n- `(condition OR condition)` — OR groups\n\n**Example:** See `examples/prd.md` for a complete template.\n\n### GitHub Issues Provider\n\nUses issue labels as statuses (`status:to-do`, `status:in-progress`, `status:in-review`, `status:done`). Agents interact via `gh` CLI — no MCP server needed.\n\nStatus changes are label swaps:\n```bash\ngh issue edit 123 --repo owner/repo --remove-label \"status:to-do\" --add-label \"status:in-progress\"\n```\n\n### GitHub Projects Provider\n\nUses GitHub Projects v2 board columns for statuses (`Todo`, `In Progress`, `In Review`, `Done`). Labels are still managed on the underlying issues. Agents use `gh api graphql` for status mutations and `gh issue edit` for labels/comments.\n\nRequires `GITHUB_PROJECT_NUMBER` in addition to `GITHUB_REPO`.\n\n### Adding a New Provider\n\n1. **`lib/providers/\u003cname\u003e.sh`** — Implement `PROVIDER_ENV_VARS` and `provider_check_tasks()`\n2. **`providers/\u003cname\u003e/instructions.md`** — Map generic workflow concepts to provider-specific tools\n3. **`providers/\u003cname\u003e/routing.json`** — Provider-specific queries per agent\n\nNo changes to core lib, bin wrappers, or base prompts needed.\n\n## Routing\n\nAll agent routing rules live in `providers/\u003cprovider\u003e/routing.json` — the single source of truth for queries.\n\n### Validating Routing\n\n```bash\nralph validate                  # Simulates ~168 ticket states, reports overlaps/gaps\nralph validate --matrix         # Full matrix — which agents match every simulated state\nralph validate --check-prompts  # Detect query drift between routing.json and prompts\nralph validate --check-loops    # Check self-loop risks\nralph validate --check-all      # Run all checks\n```\n\nWhen adding or modifying agent routing:\n1. Update `routing.json` (both `query` and `rules`)\n2. Update the corresponding `prompts/*.md` query to match\n3. Run `ralph validate --check-all` to verify\n\n## Labels\n\n| Label             | Purpose                                              |\n| :---------------- | :--------------------------------------------------- |\n| `needs-planning`  | Ticket needs (re-)planning by the Planner agent      |\n| `needs-tests`     | Ticket needs test coverage. Routed to Tester         |\n| `tech-debt`       | Code is functional but needs refactoring. Routed to Refactorer |\n| `ralph-blocked`   | Implementer hit a blocker it cannot resolve          |\n| `ralph-failed`    | Build or test failure during implementation          |\n| `needs-input`     | Planner needs human clarification on requirements    |\n| `documented`      | Documenter has updated docs for this ticket          |\n\n## Workflow\n\n```mermaid\nflowchart TD\n    NEW[\"🎫 New Ticket\u003cbr/\u003e\u003ci\u003eempty description\u003c/i\u003e\"] --\u003e PLANNER[\"🗺️ Planner\"]\n    PLANNER --\u003e|\"fills spec\"| TODO[\"📋 To Do\"]\n    PLANNER --\u003e|\"unclear requirements\"| BLOCKED_INPUT[\"⏸️ needs-input\u003cbr/\u003e\u003ci\u003ewaiting for human\u003c/i\u003e\"]\n\n    TODO --\u003e IMPL[\"⚡ Implementer\"]\n    IMPL --\u003e|\"code + evidence\"| IN_REVIEW[\"🔍 In Review\"]\n    IMPL --\u003e|\"dependency blocker\"| BLOCKED_DEP[\"⏸️ ralph-blocked\"]\n\n    IN_REVIEW --\u003e REVIEWER[\"👀 Reviewer\"]\n\n    REVIEWER --\u003e|\"✅ approve\"| READY[\"🏷️ ready-to-merge\"]\n    REVIEWER --\u003e|\"❌ reject\"| IN_PROGRESS[\"🔄 In Progress\"]\n    REVIEWER --\u003e|\"🧪 needs tests\"| TESTER[\"🧪 Tester\"]\n    REVIEWER --\u003e|\"🧹 tech debt\"| TECH[\"🏷️ tech-debt +\u003cbr/\u003eready-to-merge\"]\n\n    IN_PROGRESS --\u003e IMPL\n\n    TESTER --\u003e|\"test report +\u003cbr/\u003escreenshots\"| IN_REVIEW\n\n    TECH --\u003e MERGER2[\"🚀 Merger\"]\n    TECH --\u003e REFACTOR[\"♻️ Refactorer\"]\n    REFACTOR --\u003e|\"refactored\"| IN_REVIEW\n\n    READY --\u003e MERGER[\"🚀 Merger\"]\n    MERGER --\u003e|\"squash merge\"| DONE[\"✅ Done\"]\n    MERGER2 --\u003e|\"squash merge\"| DONE\n\n    DONE --\u003e DOCS[\"📝 Documenter\"]\n    DOCS --\u003e|\"adds documented label\"| FINAL[\"🏁 Done + documented\"]\n\n    PR_FEEDBACK[\"💬 PR Review Threads\"] --\u003e FIXER[\"🔧 Fixer\"]\n    FIXER --\u003e|\"pushes fixes\"| PR_FEEDBACK\n\n    style NEW fill:#e1f5fe\n    style FINAL fill:#c8e6c9\n    style BLOCKED_INPUT fill:#fff3e0\n    style BLOCKED_DEP fill:#fff3e0\n    style IN_REVIEW fill:#f3e5f5\n    style DONE fill:#c8e6c9\n```\n\n1.  **Planner** finds empty/TODO tickets (or `needs-planning`), adds specs, moves to **To Do**.\n2.  **Implementer** picks up **To Do**/**In Progress** (excludes `needs-tests`, `tech-debt`, `ralph-blocked`, `needs-planning`, `needs-input`; skips tasks blocked by unfinished dependencies), writes code, moves to **In Review** once verified with evidence.\n3.  **Reviewer** checks code in **In Review** (excludes `needs-planning`, `needs-tests`, `tech-debt`, `needs-input`, `ready-to-merge`):\n    - **Approve**: Adds `ready-to-merge` label to PR and ticket, stays **In Review** (Merger picks up).\n    - **Reject**: Moves back to **In Progress** (Implementer re-picks), optionally adds `ralph-failed`.\n    - **Needs Tests**: Adds `needs-tests`, moves to **To Do** (Tester picks up).\n    - **Tech Debt**: Adds `tech-debt` + `ready-to-merge` to PR, stays **In Review** (Merger merges; Refactorer picks up tech-debt later).\n4.  **Tester** picks up `needs-tests` (not Done), removes `needs-tests`, adds test evidence with screenshots, moves to **In Review**.\n5.  **Refactorer** picks up `tech-debt`, refactors, removes `tech-debt`, moves to **In Review**.\n6.  **Documenter** picks up **Done** items (excludes `tech-debt`, `documented`, `needs-input`), updates docs, adds `documented` label.\n7.  **Fixer** picks up open PRs with unresolved review threads, addresses feedback, pushes fixes.\n8.  **Merger** picks up PRs with `ready-to-merge` label + passing CI, squash-merges, transitions ticket to **Done**.\n\n## Project Structure\n\n```\nralph/\n├── bin/\n│   └── ralph                    # CLI entry point\n├── lib/\n│   ├── ralph-core.sh            # Shared functions\n│   ├── ralph-gated-loop.sh      # Backlog-gated poll loop\n│   ├── ralph-github-loop.sh     # GitHub-gated poll loop (fixer, merger)\n│   └── providers/\n│       ├── jira.sh              # Jira provider implementation\n│       ├── linear.sh            # Linear provider implementation\n│       ├── github-issues.sh     # GitHub Issues provider (label-based statuses)\n│       ├── github-projects.sh   # GitHub Projects v2 provider (board columns)\n│       ├── file.sh              # File provider implementation\n│       └── file-query.awk       # File query parser\n├── prompts/                     # Provider-agnostic workflow prompts\n│   ├── planner.md\n│   ├── implementer.md\n│   ├── reviewer.md\n│   ├── tester.md\n│   ├── refactor.md\n│   ├── documenter.md\n│   ├── fixer.md\n│   └── merger.md\n├── providers/\n│   ├── jira/\n│   │   ├── instructions.md      # Jira MCP tool mappings\n│   │   ├── routing.json         # Jira queries + validation rules\n│   │   └── mcp-server.mjs       # Bundled Jira MCP server\n│   ├── linear/\n│   │   ├── instructions.md      # Linear MCP tool mappings\n│   │   └── routing.json         # Linear queries + validation rules\n│   ├── github-issues/\n│   │   ├── instructions.md      # GitHub Issues gh CLI instructions\n│   │   └── routing.json         # GitHub Issues queries + validation rules\n│   ├── github-projects/\n│   │   ├── instructions.md      # GitHub Projects v2 GraphQL instructions\n│   │   └── routing.json         # GitHub Projects queries + validation rules\n│   └── file/\n│       ├── instructions.md      # File provider instructions\n│       └── routing.json         # File queries + validation rules\n├── examples/\n│   └── prd.md                   # Example PRD template for file provider\n├── package.json\n├── .ralphrc.example\n└── README.md\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzomars%2Fralph","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzomars%2Fralph","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzomars%2Fralph/lists"}