ralph

Ralph for Claude Code

This generated file is the Claude Code-facing runtime skill document. Claude Code slash commands should read this file directly; maintainers edit the source documents listed below instead.

Generated Runtime Composition

Source order:

• ../../docs/skill-core/ralph.md
• ../../docs/platforms/claude-code-ralph.md

The sections below are already composed for this platform. Do not ask the runtime model to load another platform's runtime document or invocation syntax.

Source: docs/skill-core/ralph.md

Ralph

Ralph is a mode-gated execution loop: it works until acceptance criteria are satisfied with fresh evidence, required review and cleanup gates are handled, and the final report is written. Ralph's main agent is the orchestrator: it owns .oh-no state, gate decisions, result intake, and FSM transitions while executor roles own default repository work-product mutation. Ralph owns execution mode selection or enforcement for ordinary implementation. Do not route concrete add/fix/refactor/implement requests directly to test-driven-development; Ralph invokes TDD internally when behavior-changing edits require it.

Do not use when requirements are still vague — use interview or ralplan first. Entering directly from interview, accept the path only if the spec's provisional Ralph mode is LIGHT; a non-LIGHT spec without a ralplan plan needs user re-confirmation before editing.

Invariants

E1. Copy the approved Direction Contract without reinterpretation before
    editing. If execution would change it, stop for explicit approval instead
    of silently rescoping. If the approved plan or an AC is itself wrong or
    infeasible as written, stop and route back to the user or `ralplan`
    (present options; never auto-invoke).
E2. An execution mode is recorded before any file change. Source priority:
    approved ralplan profile > explicit user instruction > interview LIGHT
    hint > Ralph-derived. Never de-escalate below an approved plan's mode
    without user approval.
E3. No source edit until a `Worktree decision` is recorded from the allowed
    table. A registered Git worktree is the direct-Ralph default; substitutes
    (`git clone`, `cp -R`, plain directories) are forbidden.
E4. Behavior-changing work requires RED evidence (fails against old behavior)
    before implementation and GREEN evidence before story completion; bug
    fixes need a reproduction; refactors need characterization; exceptions
    are recorded compactly.
E5. Every changed file and meaningful changed line traces to approved work;
    out-of-scope findings become residual risk or follow-ups, not diff growth.
E6. Parallel dispatch only for disjoint write scopes with no inter-dependency
    and clear ownership; create the whole eligible batch before waiting; a
    timeout or empty wait is never a final result.
E7. Review-then-verify: when a verifier trigger fires, the selected code-review
    stage completes before the single independent self-host verifier starts; on
    blocking findings, the verifier starts only after the single fix manifest is
    recorded. The verifier is never the maker and never a pair. The canonical
    `### Independent Verifier Trigger Predicate` alone selects it; mode, size,
    same authorship, reviewer presence, and imminent completion are non-triggers.
E8. Review topology is risk-gated with a one-round budget: exactly one review
    round. STANDARD and ordinary THOROUGH dispatch ONE full-role code-reviewer;
    only a named high-risk or diversity trigger selects the perspective-diverse
    pair. Accepted blocking findings get one executor-owned focused fix; the
    triggered independent verifier then audits the fixed revision as the safety
    net. A blocker unresolved after that goes to rescope or user direction.
E9. Mutation invalidates intersecting evidence except that the review verdict
    remains bound to its reviewed revision after the single post-review fix;
    the verifier owns freshness by binding to the mutated revision, and the
    caller owns it when no verifier trigger fires. Fresh revision-bound
    reviewer, verifier, and command evidence is REUSED as-is: imminent
    completion alone never justifies a rerun, a new test, or a fresh dispatch. A
    success status without the observable effect is missing evidence. Redact
    secrets/PII before writing evidence.
E10. Budget gates stop for rescope; a budget breach never authorizes
     automatic expansion.
E11. The run is invalid until every completion criterion is individually
     recorded in the session ledger; a silently omitted step is a named
     ledger gap, not a pass.
E12. Cleanup is trigger-gated after the behavior lock and BEFORE the single
     review round; rerun relevant verification whenever cleanup changes files;
     post-review cleanup is read-only (findings become residual risk or
     follow-ups).
E13. A direct-Ralph automatic worktree is not complete while work sits in the
     worktree: merge back with post-merge verification, or report the
     branch/PR handoff; on failure leave the worktree intact.
E14. Resume reconstructs state from artifacts, never working memory.
E15. Ralph is terminal: after the final report, no workflow skill is
     auto-invoked. Mid-loop skills (`test-driven-development`, `simplify`,
     `verification-before-completion`, `systematic-debugging`,
     `fusion-rescue`) are documented loop internals, not chaining events.
E17. The main agent is the orchestrator and sole owner of `.oh-no` state and
     FSM transitions. Repository work-product mutation, including
     REVIEW-to-EXECUTE focused fixes, dispatches `executor` by default; inline
     mutation is only a recorded LIGHT-tiny or dispatch-unavailable fallback.
     A fired review or audit trigger is exempt and never runs inline.
     Role result enums are caller gate inputs, never autonomous transitions.