| name | developer-ralph |
| description | Launch the Ralph loop runner for a single work item; iterate until quality gates pass, iteration budget is exhausted, or the loop is detected as wedged. |
| library | true |
| phase | developer-loop |
| surface | unattended |
| purpose | Implement one work item to green gates inside its worktree, iterating until the budget is exhausted or the loop wedges. |
| composition | {"skills":[],"tools":["git","node"],"mcps":[],"guards":["event-log","cost-guard","stall-watchdog","scratch-strip"]} |
| runtime | {"sdk":"claude","strategy":"fixed","model":"claude-sonnet-4-6","loopStrategy":"ralph"} |
| fanout | {"drivingArtifact":"work-items","isolation":"worktree","concurrencyCap":1,"perItemGate":"item-declared"} |
| brainAccess | advisory |
| interactivity | Fully autonomous; never blocks on the operator. |
| allowed-tools | ["Read","Write","Edit","MultiEdit","Bash","Grep","Glob"] |
| disallowed-tools | ["NotebookEdit","WebFetch","WebSearch","Task","Agent"] |
| budgets | {} |
Developer — Ralph
Single responsibility
Drive a single work item to completion via the Ralph loop pattern (ADR 002). Thin wrapper: prepare loop input artifacts (PROMPT.md, AGENT.md, fix_plan.md), invoke loops/ralph/runner.ts.
Brain-read policy
The dev-loop does NOT query the forge brain (Brains 1+2; ADR 010). The planner already encoded every relevant pattern/antipattern/convention into the WI spec — the work item is the single source of intent; a forge-brain read here is wasted cost and a source-of-truth split.
You may consult the project brain (Brain 3 — brain/profile.md + brain/themes/ in the worktree) for supplemental project context when the WI is thin on a project convention. Advisory, not mandatory (ADR 010 amendment 2026-05-26).
Inputs / Outputs
Inputs:
<worktree>/.forge/work-items/WI-<n>.md — the work-item spec.loops/ralph/PROMPT.md.tmpl + loops/ralph/AGENT.md.tmpl — templates.- The worktree itself.
Outputs:
- Commits in the worktree (one per AC where possible).
<worktree>/AGENT.md — final institutional memory (updated each iteration).<worktree>/fix_plan.md — checklist showing remaining work if loop didn't complete.- Iteration events to the event log.
Status frontmatter is owned by the orchestrator. Do not edit WI-<n>.md — the orchestrator writes status: complete | failed after run() returns.
Event-log entries to emit
ralph.start — event_type: 'log', loop initiated.- per-iteration
event_type: 'iteration' — number, cost, duration, files touched.
ralph.uncommitted-work-swept — ; the autocommit safety net fired (G1: the agent's commit-discipline gap, made visible for reflectors).
