Agent skill
ralph-loop
Autonomous feature development loop. Executes complete 9-phase cycle (Interview -> Think Critically -> Plan -> Branch -> Implement -> Verify -> PR -> Merge -> Wrap-Up) with minimal human intervention. Triggers on "/ralph", "start autonomous loop", "run ralph loop".
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/other/ralph-loop-edumesones-azure-demo
SKILL.md
Ralph Loop - Autonomous Feature Development
Executes the complete Feature Development Cycle (9 phases) autonomously, only pausing for:
- Human input during Interview (if spec.md is incomplete)
- Think Critically: red flags or low confidence level
- Merge approval (PR review)
- 3 consecutive failures
Triggers
/ralph orchestrator [max_parallel]- Start multi-feature orchestration/ralph feature FEAT-XXX [max_iterations]- Single feature loop/ralph status- Check running loops/ralph stop- Stop all loops- "Start autonomous loop"
- "Run ralph on FEAT-XXX"
Architecture
RALPH LOOP ARCHITECTURE
ORCHESTRATOR (ralph-orchestrator.sh)
- Reads docs/features/_index.md for Pending features
- Creates git worktrees for isolation
- Launches feature loops in parallel (max N)
- Monitors for merge completion
- Cleans up worktrees after merge
|
+--> Worktree: ../project-FEAT-001-loop/
| --> ralph-feature.sh FEAT-001
|
+--> Worktree: ../project-FEAT-002-loop/
| --> ralph-feature.sh FEAT-002
|
+--> Worktree: ../project-FEAT-003-loop/
--> ralph-feature.sh FEAT-003
Feature Loop Phases
FEATURE LOOP - 9 PHASES
Iteration 1: INTERVIEW
- Read spec.md
- If Technical Decisions has TBD -> PAUSE for human input
- If complete -> emit INTERVIEW_COMPLETE
Iteration 2: THINK CRITICALLY (11-Step Protocol)
- Determine depth: full/medium/light/skip
- Execute analysis protocol -> analysis.md
- If red flags or low confidence -> PAUSE for review
- If safe -> emit ANALYSIS_COMPLETE
Iteration 3: PLAN
- Read spec.md + analysis.md (BOTH required)
- Generate design.md with architecture
- Generate tasks.md with ordered checklist
- emit PLAN_COMPLETE
Iteration 4: BRANCH
- git checkout -b feature/XXX-name
- emit BRANCH_COMPLETE
Iterations 5-N: IMPLEMENT
- Process 3 tasks per iteration
- Mark [in progress] -> implement -> mark [x] -> commit
- emit IMPLEMENT_PROGRESS until all done
- emit IMPLEMENT_COMPLETE when finished
Iteration N+1: VERIFY (if frontend changes)
- Run browser E2E tests
- emit VERIFY_COMPLETE
Iteration N+2: PR
- git push origin feature/XXX
- gh pr create
- emit PR_COMPLETE
Iteration N+3: MERGE
- Poll gh pr view for merge status
- emit MERGE_WAITING until approved
- emit MERGE_COMPLETE when merged
Iteration N+4: WRAP-UP
- Create context/wrap_up.md
- Document metrics and learnings
- emit WRAPUP_COMPLETE
- emit FEATURE_COMPLETE
Pause Conditions
The loop pauses (doesn't terminate) when:
-
Human Input Needed (return code 3)
- spec.md has TBD values that can't be auto-filled
- User must complete interview manually
-
Think Critically Requires Review (return code 3)
- Step 2: Assumption with Low confidence + High impact
- Step 9: Critical red flag identified
- Step 11: Overall confidence = "Low"
- User must review analysis.md and decide how to proceed
-
Waiting for External Action (return code 2)
- PR created, waiting for review approval
- Polls every 60 seconds
-
Too Many Failures (3 consecutive)
- Something is broken
- User must investigate and fix
Integration with Feature Cycle
Ralph Loop fully integrates with existing Feature Development Cycle (9 phases):
| Existing Command | Ralph Equivalent |
|---|---|
/interview FEAT-XXX |
Auto-executed if spec needs completion |
/think-critically FEAT-XXX |
Auto-executed with depth based on complexity |
/plan FEAT-XXX |
Auto-generated from spec + analysis |
/git "msg" |
Auto-commit after each task |
/git pr |
Auto-created after implementation |
/wrap-up FEAT-XXX |
Auto-generated after merge |
Usage Examples
# Start orchestrator for all pending features (max 3 parallel)
./ralph-orchestrator.sh 3
# Run single feature loop
./ralph-feature.sh FEAT-001-auth 15
# Check status
./ralph-orchestrator.sh --status
# Stop all loops
./ralph-orchestrator.sh --stop
Prerequisites
gitandgh(GitHub CLI) installed and authenticatedclaudeCLI availablepython3for JSON manipulation- Features defined in
docs/features/_index.md
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
Didn't find tool you were looking for?