with one click
codex-skill-execute-ralph
// Use when the original skill 'execute-ralph' applies. Execute entire bd epic autonomously via subagent-per-task dispatch loop. Setup, dispatch subagent per task, end-of-epic review, branch completion.
// Use when the original skill 'execute-ralph' applies. Execute entire bd epic autonomously via subagent-per-task dispatch loop. Setup, dispatch subagent per task, end-of-epic review, branch completion.
[HINT] Download the complete skill directory including SKILL.md and all related files
| name | codex-skill-execute-ralph |
| description | Use when the original skill 'execute-ralph' applies. Execute entire bd epic autonomously via subagent-per-task dispatch loop. Setup, dispatch subagent per task, end-of-epic review, branch completion. |
flowchart TD
S([Start]) --> P0[Phase 0: Setup]
P0 --> P1[Phase 1: Get Next Task]
P1 --> P2[Phase 2: Dispatch Subagent]
P2 -->|criteria unmet| P1
P2 -->|Turn-Limit-Hit -> resume| P1
P2 -->|Critical/High -> create remediation task| P1
P2 -->|all criteria met| P3[Phase 3: End-of-Epic Review]
P3 -->|BOTH APPROVED| P4[Phase 4: Branch Completion]
P3 -->|non-approval| P1
P4 --> E([Done])
<skill_overview>
Execute a complete epic autonomously by dispatching one Agent subagent per task. Platform routing: If running in Claude Code (you see "You are Claude Code" in your system prompt), stop now and load the execute-ralph-cc skill instead -- it uses ScheduleWakeup for reliable autonomous looping in Claude Code. Continue with this skill only on other platforms (OpenCode, Gemini CLI, Kimi). Each subagent handles SRE refinement, TDD, test-runner, commit, and task closure in its own context. The main loop only tracks git log progress and epic criteria. End-of-epic: 3 specialized reviews (review-quality, security-scanner, test-effectiveness-analyst) in parallel, then dual final gate (autonomous-reviewer + review-implementation). Branch completion via finishing-a-development-branch.
</skill_overview>
<rigidity_level> STRICT - Follow the four-phase loop exactly. Epic requirements are immutable. Never ask the user for confirmation. </rigidity_level>
<quick_reference>
| Phase | Action | Outcome |
|---|---|---|
| 0. Setup | Triage, load epic, create branch, extract criteria | Ready |
| 1. Get Task | Claim ready / resume in-progress / auto-create | Task identified |
| 2. Dispatch Subagent | Agent tool runs task end-to-end, main checks git log | Task done or retried |
| 3. End-of-Epic Review | 3 specialized reviews + final gate (both must APPROVED) | Epic validated or remediation |
| 4. Branch Completion | finishing-a-development-branch | Epic closed |
</quick_reference>
The leading sentinel control block is the first consecutive non-empty group of sentinel-only lines in the response. Required shapes:
RALPH AUTOPILOT ACTIVE, followed by enough objective state to resume without asking the user:
RALPH AUTOPILOT COMPLETE or RALPH AUTOPILOT BLOCKED; terminal responses must not include RALPH AUTOPILOT ACTIVE.Use RALPH AUTOPILOT COMPLETE when the branch is complete and handoff is ready. Use RALPH AUTOPILOT BLOCKED when a critical blocker must reach the user.
Active sentinel text alone is not enough to trigger blocking. A Claude Code UserPromptExpansion for /xpowers:execute-ralph must first activate guarded stop-state for the current runtime session.
The guard only treats sentinels in the leading sentinel control block as control markers. Later quoted examples, logs, or code blocks are ignored.
For defensive compatibility, terminal sentinels still win if they appear in a malformed leading sentinel control block with RALPH AUTOPILOT ACTIVE, so stale active markers cannot trap the session.
The Claude Code Stop/SubagentStop guard can resume Ralph only when the exact active sentinel appears as the first non-empty line in an activated execute-ralph session. It does not bypass Claude Code permission prompts or session permission-mode settings. When a permission prompt appears, comply with Claude Code's permission flow; do not claim that Ralph can override it.
<when_to_use>
Use when: Epic is well-defined, user trusts autonomous execution, tasks are implementation work. Do NOT use when: Ambiguous requirements (use execute-plans), needs human oversight per task, exploratory work.
</when_to_use>
<the_process>
CRITICAL: TUI Dashboard Updates (If Supported)
If the update_ralph_state tool is available in your environment, you MUST continually use it to keep the live TUI dashboard updated:
logMessage field frequently to narrate your progress.phase: "done".If the tool is NOT available (e.g. running in Claude Code or OpenCode without the Pi extension), ignore this requirement and proceed with standard terminal logs.
bv --robot-triage || (tm ready && tm list)
Health gate: If dependency cycles or zero actionable items, alert user and stop.
bv --robot-next || tm show bd-EPIC
BRANCH_NAME=$(echo "[epic-title]" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr -cd 'a-z0-9-')
git checkout -b "feature/${BRANCH_NAME}"
Extract from epic: success criteria (immutable), anti-patterns (forbidden). Store in memory for loop.
bv --robot-next # Automated triage
A) In-progress task exists -- resume it (proceed to Phase 2).
B) Ready task exists -- claim it: tm update bd-N --status in_progress.
C) If no ready or in-progress tasks exist and epic success criteria are still unmet -- do not stop - create and execute the next task.
Refinement Step:
After task selection/creation, run SRE refinement to ensure the task design is robust:
Use Skill tool: xpowers:sre-task-refinement (prefer Opus 4.1 model)
tm create "Task: [criterion gap]" --type feature --priority 1 \
--design "## Goal\n[Close unmet criterion]\n## Success Criteria\n- [ ] Gap closed"
tm dep add bd-NEW bd-EPIC --type parent-child
tm update bd-NEW --status in_progress
Load full task context:
tm show bd-EPIC # epic requirements
tm show bd-N # task design
Before dispatching, record current HEAD:
PRE_SHA=$(git rev-parse HEAD)
Launch Agent tool using the canonical 'Dispatch Protocol' from subagent-driven-development.
Use the Subagent Prompt Template from subagent-driven-development skill, populating:
tm show bd-EPIC wrapped in <epic_contract> tags.tm show bd-N wrapped in <task_spec> tags.sre-task-refinement and TDD are mandated.After Agent returns, verify progress by status and SHA comparison:
POST_SHA=$(git rev-parse HEAD)
TASK_TYPE=$(tm show bd-N --json | jq -r .type)
STATUS=$(tm show bd-N --json | jq -r .status)
STATUS == "closed".POST_SHA != PRE_SHA.POST_SHA == PRE_SHA as long as status is closed.STATUS == "open" AND POST_SHA != PRE_SHA: Trigger Resume path. Return to Phase 1 and immediately re-dispatch the same task.STATUS != "closed" AND POST_SHA == PRE_SHA:
git checkout .), defer the task (tm update bd-N --status deferred), and return to Phase 1.STATUS == "closed" and POST_SHA == PRE_SHA for an implementation task (feature/bug/task/chore type), flag as hallucinated completion and STOP.Once verified, trigger the following review:
mcp_agents_agent_autonomous_reviewer()Remediation Path: If the review finds Critical or High issues:
tm create "Remediation: [Findings]" --parent bd-EPIC.Criteria check:
tm show bd-EPIC # re-read success criteria
Dispatch specialized reviews in parallel via Agent tool:
If any issues found, create remediation task and return to Phase 1 (max 2 consecutive Phase 3 re-entries; after 2 rounds with unresolved issues, STOP and wait for explicit user override).
Final gate -- dispatch in parallel:
Only close epic when BOTH final reviewers approve.
Mixed final reviewer outputs are non-approval. Do not close the epic unless both final reviewers return an approval verdict. Unknown or malformed verdict must create a remediation task and continue the loop.
Non-approval --> create remediation task, return to Phase 1 (max 50 overall no-progress remediation cycles across all phases).
Use Skill tool: xpowers:finishing-a-development-branch
Autonomous override: When the skill presents integration options, auto-select option 2 (Push and create Pull Request) without waiting for user input. Ralph is autonomous — do not present options or wait.
Present summary: tasks completed, commits made, review results, any flagged items.
MANDATORY: Run these verification commands and verify all pass before epic closure:
set -e # Exit on any failure
node --test tests/execute-ralph-contract.test.js
node --test tests/codex-*.test.js
node --test tests/*.test.js
node scripts/sync-codex-skills.js --check
If any verification fails, create remediation task and return to Phase 1.
In guarded environments, direct .git/hooks/pre-commit execution may be blocked by safety guardrails.
</the_process>
<common_rationalizations>
"The subagent said it's done, so I'll skip verification"
NO. Always verify via tm show --json status and SHA drift. Subagent claims are not proof.
"I'll just ask the user if the task is complete" NO. Ralph is autonomous. Never ask for confirmation. Use objective verification only.
"The test passed, so I don't need to check git log" NO. Implementation tasks MUST produce commits. Tests passing without SHA drift is a failure.
"I'll skip SRE refinement for simple tasks" NO. Every task requires refinement to catch edge cases before implementation.
</common_rationalizations>
<red_flags>
tm show --json status verification</red_flags>
Calls:
xpowers:sre-task-refinement -- mandatory per-task refinement after task selectionsubagent-driven-development -- canonical Dispatch Protocol for each taskxpowers:finishing-a-development-branch -- final branch completionCalled by:
Prerequisites: