Development Loop - The Outer Loop for Ralph
Overview
A complete development workflow that wraps Ralph with planning, review, and feedback cycles. Think of it as an "outer loop" that ensures quality through iterative refinement.
┌─────────────────────────────────────────────────────────────┐ │ DEVELOPMENT LOOP │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────────────────┐ │ │ │BRAINSTORM│───▶│ PLAN │───▶│ RALPH IMPLEMENT │ │ │ │ │ │(superthink) │ (inner loop) │ │ │ └──────────┘ └──────────┘ └──────────┬───────────┘ │ │ │ │ │ ▼ │ │ ┌──────────┐ ┌──────────┐ ┌──────────────────────┐ │ │ │ APPROVED │◀───│ REVIEW │◀───│ 5-AGENT REVIEW │ │ │ │ (exit) │ │(decision)│ │ │ │ │ └──────────┘ └────┬─────┘ └──────────────────────┘ │ │ │ needs work │ │ ▼ │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ FEEDBACK LOOP │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ │ │ FEEDBACK │───▶│ RALPH │───▶│ REVIEW │──┐ │ │ │ │ │ PLAN │ │ FIX │ │ │ │ │ │ │ │ └──────────┘ └──────────┘ └──────────┘ │ │ │ │ │ ▲ │ │ │ │ │ └────────── needs more work ─────────────┘ │ │ │ └──────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────┘
The Phases
Phase 1: BRAINSTORM
Goal: Understand what to build through collaborative dialogue.
- •Invoke
workers-do:brainstormingskill - •Ask questions one at a time
- •Explore approaches and trade-offs
- •Output: Design document in
docs/plans/
Exit criteria: User approves the design
Phase 2: PLAN (Superthink)
Goal: Create TDD beads issues with extended thinking.
Use extended thinking to:
- •Break design into implementable modules
- •For each module, create beads issue chain:
- •
RED: [Module] tests(tdd-red label) - •
GREEN: Implement [Module](tdd-green label, blocked by RED) - •
REFACTOR: Clean up [Module](tdd-refactor label, blocked by GREEN)
- •
- •Set up cross-module dependencies
- •Prioritize order of work
Output: Beads issues with full dependency graph
Exit criteria: Issue plan reviewed and approved
Phase 3: IMPLEMENT (Ralph Loop)
Goal: Autonomous implementation following TDD.
Start Ralph loop with prompt:
Work through beads issues in dependency order. For each issue: 1. Claim it (bd update --status=in_progress) 2. Follow TDD: write test (RED), implement (GREEN), refactor 3. Close it (bd close) 4. Move to next ready issue (bd ready) Continue until all issues are closed. Output <promise>IMPLEMENTATION COMPLETE</promise> when done.
Exit criteria: All beads issues closed, tests passing
Phase 4: REVIEW (5-Agent)
Goal: Comprehensive quality check.
Launch 5 parallel review agents:
- •General code review
- •Architectural review
- •TypeScript review
- •Product/vision review
- •TDD/beads compliance review
Output: Synthesized review with findings
Decision point:
- •APPROVED → Exit loop, work is done
- •NEEDS WORK → Continue to Phase 5
Phase 5: FEEDBACK PLAN (Superthink)
Goal: Convert review feedback into actionable issues.
Use extended thinking to:
- •Analyze each review finding
- •Create beads issues for fixes:
- •
FIX: [Finding description]with appropriate labels
- •
- •Set priorities based on severity
- •Add dependencies if fixes depend on each other
Output: New beads issues for fixes
Phase 6: FIX (Ralph Loop)
Goal: Address review findings.
Start Ralph loop with prompt:
Work through fix issues from code review. For each issue: 1. Claim it 2. Implement the fix following TDD 3. Verify tests pass 4. Close it Output <promise>FIXES COMPLETE</promise> when all fix issues closed.
Phase 7: FINAL REVIEW
Goal: Verify fixes and decide if done.
Run 5-agent review again, focused on:
- •Were the findings addressed?
- •Any new issues introduced?
- •Overall quality assessment
Decision:
- •APPROVED → Exit, publish/merge
- •NEEDS MORE WORK → Loop back to Phase 5
State Management
The loop tracks state in .claude/dev-loop.local.md:
--- phase: IMPLEMENT # Current phase iteration: 1 # Which review cycle started_at: "2024-01-01T00:00:00Z" design_doc: "docs/plans/2024-01-01-feature-design.md" initial_issues: ["workers-xxx", "workers-yyy"] fix_issues: [] review_findings: [] --- Original task description here...
Commands
/dev-loop "task description"
Start a new development loop.
/dev-loop-status
Show current phase and progress.
/dev-loop-advance
Manually advance to next phase (for human checkpoints).
/dev-loop-cancel
Cancel the loop and clean up.
Human Checkpoints
The loop pauses for human approval at:
- •After BRAINSTORM - Approve design before planning
- •After PLAN - Review issues before implementation
- •After REVIEW - Decide: approved or needs work
- •After FINAL REVIEW - Final approval or more iteration
Extended Thinking Integration
Phases 2 and 5 use "superthink" - extended thinking mode for:
- •Deep analysis of requirements
- •Comprehensive issue breakdown
- •Thorough dependency mapping
- •Quality feedback analysis
Enable with: thinking: extended in prompts or model configuration.
Example Usage
# Start the loop /dev-loop "Add user authentication with JWT tokens, SSO support, and session management" # Loop will: # 1. Brainstorm with you about auth requirements # 2. Create TDD issues for auth module # 3. Ralph-loop implement the auth system # 4. 5-agent review the implementation # 5. Create fix issues from feedback # 6. Ralph-loop the fixes # 7. Final review → approve or iterate
Key Principles
- •Quality over speed - Multiple review cycles ensure quality
- •TDD throughout - Every implementation follows RED-GREEN-REFACTOR
- •Tracked work - All work captured in beads issues
- •Human oversight - Key decisions require human approval
- •Autonomous execution - Ralph handles implementation phases
- •Comprehensive review - 5 specialized perspectives catch issues
When to Use
Good for:
- •Significant features (multi-day work)
- •Complex implementations
- •High-quality requirements
- •Work that needs documentation
Not good for:
- •Quick fixes (use simple TDD)
- •Exploratory work (use just brainstorming)
- •Urgent hotfixes (skip the loop)