Ralph Wiggum Full-Cycle Command

Execute complete feature development cycle: $ARGUMENTS

Phase 0-5 of Spec-Driven Workflow: Orchestrates Research → Specify → Plan → Work → Review in continuous loop

orchestrate this complex multi-phase workflow systematically. Manage iteration cycles, track progress across all phases, and ensure comprehensive quality at each stage.

Why This Matters

This workflow handles complete feature development from research to review. Poor orchestration leads to wasted cycles, incomplete phases, and features that fail quality gates. This orchestration task is critical for ensuring features are developed thoroughly and meet all requirements.

The Challenge

The manage continuous iteration across all workflow phases without getting stuck in loops. The challenge is knowing when to advance to next phase versus when to return for refinement, balancing persistence with efficiency. Success means feature completes all requirements, passes all quality gates, and doesn't exceed reasonable iteration limits.

Quick Start

# Full-cycle feature development
/ai-eng/ralph-wiggum "implement user authentication with JWT tokens"

# Start from existing specification
/ai-eng/ralph-wiggum "user authentication" --from-spec=specs/auth/spec.md

# Start from existing plan (skip research and specify)
/ai-eng/ralph-wiggum "user authentication" --from-plan=specs/auth/plan.md

# With checkpoints for manual review
/ai-eng/ralph-wiggum "user authentication" --checkpoint=all

# Resume interrupted build
/ai-eng/ralph-wiggum "user authentication" --resume

# Dry run to see execution plan
/ai-eng/ralph-wiggum "user authentication" --dry-run

How This Command Works

This command is a self-orchestrating prompt - when you invoke /ai-eng/ralph-wiggum, the AI reads these instructions and executes each phase directly within the conversation.

Execution Model:

NOT a CLI script - There is no external runner. The AI IS the executor.
Phase commands are internal - When instructions say "Execute /ai-eng/research", the AI follows that command's instructions directly (not spawning a subprocess).
Continuous flow - The AI proceeds through all phases autonomously unless checkpoints are set.

To run this command:

Claude Code: Type /ai-eng/ralph-wiggum "your feature description"
OpenCode: Type /ai-eng/ralph-wiggum "your feature description"

The AI will then follow all phases in this document from start to finish.

Options

Option	Type	Default	Description
`--max-cycles <n>`	number	5	Maximum full workflow cycles
`--max-phase-iterations <n>`	number	10	Max iterations per phase
`--checkpoint`	string	none	Pause points: `all`, `review`, or `none`
`--from-research <path>`	path	-	Start from existing research document
`--from-spec <path>`	path	-	Start from existing specification
`--from-plan <path>`	path	-	Start from existing plan
`--skip-research`	boolean	false	Skip research phase entirely
`--quality-gate <command>`	command	-	Custom quality gate command
`--completion-promise <text>`	string	(see below)	Custom completion criteria
`--show-progress`	boolean	true	Show detailed cycle progress
`--log-history <file>`	path	-	Log all iterations to JSON
`--verbose`	boolean	false	Enable verbose output
`--quiet`	boolean	false	Minimal output (milestones only)
`--dry-run`	boolean	false	Show plan without executing
`--resume`	boolean	false	Resume from last checkpoint
`--parallel`	boolean	false	Run phases in parallel where safe
`--refine-each-phase`	boolean	false	Re-invoke prompt-refinement at each phase (interactive mode)

Default Completion Promise:

"Feature is complete: all acceptance criteria met, quality gates passing, review approved, documentation updated"

Phase 0: Prompt Refinement (CRITICAL - Do First)

Load skills/prompt-refinement/SKILL.md and use phase: plan to transform your prompt into structured TCRO format (Task, Context, Requirements, Output). Ask clarifying questions if feature description, acceptance criteria, technical approach, or quality gates are unclear.

Store the refined output as $REFINED_CONTEXT - this will be used for ALL subsequent phases without re-invoking prompt-refinement.

Autonomous Execution Model

After Phase 0 completes:

Context is locked: The refined TCRO applies to ALL subsequent phases
No re-refinement: Do NOT invoke prompt-refinement again (unless --refine-each-phase is set)
Continuous execution: Proceed through phases without pausing for user input
Checkpoints are optional: Only pause if --checkpoint flag is explicitly set

This enables overnight/unattended execution as intended by the Ralph Wiggum pattern.

Phase 1: Git Setup

1.1 Create Feature Branch

Action: Create and checkout feature branch

git checkout -b feat/[feature-slug]

Feature Slug Generation:

Lowercase
Replace spaces with hyphens
Remove special characters
Max 50 characters

Example: "user authentication with JWT" → feat/user-authentication-jwt

Acceptance:

Branch created successfully
Branch starts from current branch
Branch name is valid Git reference

Phase 2: Main Cycle Loop

This is the core Ralph Wiggum pattern - continuous iteration until completion.

2.1 Cycle Start Check

Before starting each cycle, verify:

Max cycles not exceeded: If cycle > maxCycles, stop and report completion status
Checkpoint load (if --resume): Load from .ralph-wiggum/[feature]/checkpoint.json
Stuck detection: If 3 consecutive cycles without progress, alert user

Cycle Start Output:

🔄 Ralph Wiggum Cycle 1/5 for "user authentication"

2.2 Research Phase (if not skipped)

Goal: Gather context, patterns, and technical guidance

Context: Use $REFINED_CONTEXT from Phase 0. Do NOT re-invoke prompt-refinement unless --refine-each-phase is set.

Execute:

/ai-eng/research "$FEATURE_DESCRIPTION" \
  --ralph \
  --ralph-max-iterations $MAX_PHASE_ITERATIONS \
  --ralph-completion-promise "Research is comprehensive and complete" \
  --show-progress

If --from-research provided: Skip this phase, use existing document

Acceptance:

Research phase completes
Output: docs/research/[date]-[feature].md
Research report has high confidence (≥ 0.7)

Checkpoint (if --checkpoint=all): Pause and ask for approval before proceeding

→ CONTINUE: Immediately proceed to Phase 2.3 (Specify) without waiting for user input.

2.3 Specify Phase (if not skipped)

Goal: Create detailed specification with user stories and acceptance criteria

Context: Use $REFINED_CONTEXT from Phase 0. Do NOT re-invoke prompt-refinement unless --refine-each-phase is set.

Execute:

# If research was generated
/ai-eng/specify "$FEATURE_DESCRIPTION" \
  --from-research=$RESEARCH_OUTPUT \
  --ralph \
  --ralph-max-iterations $MAX_PHASE_ITERATIONS \
  --ralph-completion-promise "Specification is complete and ready for implementation" \
  --show-progress

# If starting from existing spec, skip

If --from-spec provided: Skip this phase, use existing document

Acceptance:

Specify phase completes
Output: specs/[feature]/spec.md
Spec has user stories with acceptance criteria
No [NEEDS CLARIFICATION] markers (or marked as resolved)

Checkpoint (if --checkpoint=all): Pause and ask for approval

→ CONTINUE: Immediately proceed to Phase 2.4 (Plan) without waiting for user input.

2.4 Plan Phase (if not skipped)

Goal: Create implementation plan with tasks and dependencies

Context: Use $REFINED_CONTEXT from Phase 0. Do NOT re-invoke prompt-refinement unless --refine-each-phase is set.

Execute:

# If spec was generated
/ai-eng/plan \
  --from-spec=$SPEC_OUTPUT \
  --ralph \
  --ralph-max-iterations $MAX_PHASE_ITERATIONS \
  --ralph-completion-promise "Plan is comprehensive and ready for execution" \
  --show-progress

# If starting from existing plan, skip

If --from-plan provided: Skip this phase, use existing document

Acceptance:

Plan phase completes
Output: specs/[feature]/plan.md
Plan has tasks with dependencies
Plan includes testing strategy

Checkpoint (if --checkpoint=all): Pause and ask for approval

→ CONTINUE: Immediately proceed to Phase 2.5 (Work) without waiting for user input.

2.5 Work Phase

Goal: Implement feature with TDD, quality gates, and iterative refinement

Context: Use $REFINED_CONTEXT from Phase 0. Do NOT re-invoke prompt-refinement unless --refine-each-phase is set.

Execute:

/ai-eng/work $PLAN_OUTPUT \
  --ralph \
  --ralph-max-iterations $MAX_PHASE_ITERATIONS \
  --ralph-completion-promise "$COMPLETION_PROMISE" \
  --ralph-quality-gate="$QUALITY_GATE" \
  --ralph-show-progress \
  --show-progress

Quality Gates (default):

npm test && npm run lint && npm run build

Custom Quality Gate: If --quality-gate provided, use that command

Acceptance:

Checkpoint (if --checkpoint=all or --checkpoint=review): Pause and ask for approval

→ CONTINUE: Immediately proceed to Phase 2.6 (Review) without waiting for user input.

2.6 Review Phase

Goal: Comprehensive multi-perspective code review

Context: Use $REFINED_CONTEXT from Phase 0. Do NOT re-invoke prompt-refinement unless --refine-each-phase is set.

Execute:

/ai-eng/review . \
  --ralph \
  --ralph-max-iterations $MAX_PHASE_ITERATIONS \
  --ralph-completion-promise "Review is comprehensive and complete" \
  --show-progress

Acceptance:

Review phase completes
Output: code-review-report.json (or similar)
Review includes findings with severity levels (critical, major, minor)
All perspectives covered (security, performance, architecture, etc.)

Checkpoint (if --checkpoint=all or --checkpoint=review): Pause and ask for approval

→ CONTINUE: Immediately proceed to Phase 3 (Gap Analysis) without waiting for user input.

Phase 3: Gap Analysis

3.1 Analyze Review Findings

After review phase completes, analyze findings to determine next action:

Read the review report output from phase 2.6

Categorize findings:

Review Finding Type	Severity	Return To	Rationale
Missing requirements	Any	SPECIFY	Spec needs enhancement
Unclear acceptance criteria	Any	SPECIFY	Spec needs clarification
Architectural issues	Major/Critical	PLAN	Plan needs restructuring
Missing dependencies	Any	PLAN	Plan incomplete
Implementation bugs	Any	WORK	Code needs fixing
Test coverage gaps	Any	WORK	Tests need adding
Documentation gaps	Minor	WORK	Docs need updating
Security vulnerabilities	Critical	PLAN	May need architectural change
Security vulnerabilities	Major/Minor	WORK	Implementation fix
Performance issues	Critical	PLAN	May need architectural change
Performance issues	Major/Minor	WORK	Implementation optimization

3.2 Determine Completion Status

Check if completion criteria met:

Review Status: APPROVE (no critical or major findings)
Quality Gates: All pass
Spec Coverage: All acceptance criteria marked complete
Test Coverage: ≥ 80%
Documentation: Updated and complete

If ALL criteria met: Proceed to Phase 5 (Create PR)

If NOT all criteria met: Continue to next cycle (Phase 2.1)

3.3 Determine Return-To Phase

If continuing to next cycle, identify which phase to return to:

Based on gap analysis from 3.1:

SPECIFY gaps: Return to Phase 2.3
PLAN gaps: Return to Phase 2.4
WORK gaps: Return to Phase 2.5

Decision:

┌─────────────────────────────────────────┐
│ Gap Analysis: SPECIFY gaps found   │
└─────────────────────────────────────────┘
                 │
                 ▼
         Return to SPECIFY phase

Log decision for visibility:

📊 Gap Analysis:
  - 3 SPECIFY gaps found (missing requirements)
  - 0 PLAN gaps
  - 2 WORK gaps (test coverage)
  Decision: Return to SPECIFY phase

Phase 4: Checkpoint Management

4.1 Save Checkpoint (After Each Cycle)

Action: Save current build state to checkpoint file

Checkpoint File: .ralph-wiggum/[feature]/checkpoint.json

Checkpoint Structure:

{
  "feature": "user-authentication",
  "feature_slug": "user-authentication",
  "branch": "feat/user-authentication",
  "cycle": 2,
  "max_cycles": 5,
  "current_phase": "WORK",
  "completed_phases": ["RESEARCH", "SPECIFY", "PLAN"],
  "refined_context": {
    "task": "Specific, actionable task statement",
    "context": "Broader system, goals, constraints from CLAUDE.md",
    "requirements": ["Must-have requirement 1", "Must-have requirement 2"],
    "output": "What should be delivered (working code, tests, docs, PR)"
  },
  "artifacts": {
    "research": "docs/research/2026-01-05-user-authentication.md",
    "spec": "specs/user-authentication/spec.md",
    "plan": "specs/user-authentication/plan.md"
  },
  "token_usage": {
    "total": 45230,
    "this_cycle": 12450,
    "by_phase": {
      "research": 8450,
      "specify": 5230,
      "plan": 12100,
      "work": 19450
    }
  },
  "last_review": {
    "status": "CHANGES_REQUESTED",
    "findings_count": 8,
    "critical": 2,
    "major": 5,
    "minor": 1
  },
  "checkpoint_time": "2026-01-05T14:23:45Z",
  "gap_analysis": {
    "return_to_phase": "WORK",
    "reason": "2 test coverage gaps identified"
  }
}

Git Ignore:

Auto-add .ralph-wiggum/ to .gitignore
This prevents checkpoints from being committed

Acceptance:

Checkpoint saved successfully
.ralph-wiggum/ added to .gitignore (if not already present)

4.2 Load Checkpoint (If `--resume`)

Action: Load checkpoint and continue from last state

Validate checkpoint:

Check file exists
Validate JSON structure
Verify branch matches checkpoint.branch

Resume Process:

Switch to checkpointed branch: git checkout <branch>
Load artifacts from checkpoint.artifacts
Set cycle number to checkpoint.cycle
Set current phase to checkpoint.current_phase
Restore token usage from checkpoint.token_usage
Display resume summary

Resume Output:

✅ Checkpoint found: Cycle 2, WORK phase in progress
🔄 Resuming from cycle 2, phase 4 (WORK)
📋 Last gap analysis: Return to WORK phase
💰 Token usage: 45,230 total

Acceptance:

Checkpoint loaded successfully
State restored correctly
Build continues from appropriate phase

Phase 5: Pull Request Creation

5.1 Create Draft PR

Action: Create draft pull request with comprehensive summary

Execute:

gh pr create \
  --title "[Feature] $FEATURE_DESCRIPTION" \
  --body "$PR_BODY" \
  --draft

PR Body Template:

## Summary
$FEATURE_SUMMARY

## Cycle History
- Cycle 1: Research + Specify + Plan + Work (32,400 tokens)
  - Research: Complete (confidence: 0.9)
  - Specify: Complete (5 user stories, 23 AC)
  - Plan: Complete (12 tasks, 8 hours)
  - Work: 8/12 tasks complete
  - Review: CHANGES_REQUESTED (8 findings)
  - Gap Analysis: Return to WORK phase

- Cycle 2: Work refinement (12,450 tokens)
  - Work: 12/12 tasks complete
  - Review: APPROVE
  - Gap Analysis: None

## Changes
- [Bullet list of major changes]
- [New files added]
- [Existing files modified]

## Testing
- [x] Unit tests added (N tests)
- [x] Integration tests pass
- [x] Security scans pass (no vulnerabilities)
- [x] Lint passing
- [x] Type checking passing

## Quality Gates
- Lint: ✅ Passing
- Types: ✅ Passing
- Tests: ✅ 20/20 passing (100%)
- Test Coverage: ✅ 80%
- Security: ✅ No vulnerabilities
- Build: ✅ Passing

## Artifacts
- Specification: specs/[feature]/spec.md
- Plan: specs/[feature]/plan.md
- Research: docs/research/[date]-[feature].md
- Review: code-review-report.json
- Checkpoint: .ralph-wiggum/[feature]/checkpoint.json

## Completion Status
✅ Feature complete: All acceptance criteria met, quality gates passing, review approved

Acceptance:

Progress Output

Default Display (balanced verbosity)

After each phase:

🔄 Ralph Wiggum Cycle 2/5 for "user authentication"

📊 Phase Status:
  ✅ Research: Complete (confidence: 0.9)
  ✅ Specify: Complete (5 user stories, 23 acceptance criteria)
  ✅ Plan: Complete (12 tasks, 8 hours estimated)
  🔄 Work: In Progress (8/12 tasks complete)
  ⏳ Review: Pending

📈 Quality Gates:
  ✅ Lint: Passing
  ✅ Types: Passing
  🔄 Tests: 15/20 passing (75%)
  ⏳ Build: Not run
  ⏳ Security: Not run

📋 Acceptance Criteria: 18/23 complete (78%)
🧪 Test Coverage: 72% (target: 80%)
💰 Token Usage: 45,230 total (this cycle: 12,450)
⏱️ Elapsed: 23m 45s

Verbose Display

Adds per-phase iteration details:

📝 Phase Details:
  Research: 3 iterations, 8,450 tokens
  Specify: 2 iterations, 5,230 tokens
  Plan: 4 iterations, 12,100 tokens
  Work: 6 iterations (ongoing), 19,450 tokens

Quiet Display

Minimal output:

🔄 Cycle 2/5 | Work 8/12 | AC 78% | Tests 75%

Safety Measures

Max Cycles Limit

Enforcement: Stop execution when cycle > maxCycles

Behavior:

If max cycles reached without completion:
- Display completion summary
- List remaining gaps
- Suggest manual intervention
- Exit with clear status

Stuck Detection

Trigger: No progress in 3 consecutive cycles

Definition of "Progress":

Completion status didn't improve
Same phase failing repeatedly
Same quality gate results

Action on Stuck Detection:

Alert user with detailed analysis
Save checkpoint with stuck state
Offer to pause for manual intervention
Continue if --continue-on-stuck flag set

Token Usage Tracking

Display: Always show cumulative and per-cycle token usage

No Enforcement: Track only, users manage their own API budgets

Output:

💰 Token Usage: 45,230 total (this cycle: 12,450)
   Research: 8,450 (3 iterations)
   Specify: 5,230 (2 iterations)
   Plan: 12,100 (4 iterations)
   Work: 19,450 (6 iterations)

Optional Checkpoints

Checkpoint Interaction (if `--checkpoint` is set)

After each phase (or after review if --checkpoint=review):

🔶 Checkpoint reached: [PHASE_NAME] phase complete

📊 Phase Summary:
  Status: Complete
  Artifacts Generated: [list]
  Token Usage: [N tokens]

  [Phase-specific findings/results]

🤔 Action Required:
  [Analysis and recommendation]

Options:
  [1] Continue to next phase
  [2] Return to [EARLIER PHASE]
  [3] Review phase findings
  [4] Modify artifacts
  [5] Abort build

Enter choice (1-5): _

User Response Handling:

1: Proceed to next phase
2: Set current_phase to specified earlier phase, continue
3: Display detailed findings, prompt again
4: Open editor for user to modify artifacts, then continue
5: Stop build, save final checkpoint

Dry Run Mode

Purpose: Show execution plan without actually running phases

Output:

🔍 DRY RUN: Plan for "$FEATURE_DESCRIPTION"

## Workflow Phases:
1. RESEARCH (3 iterations estimated)
   - Command: /ai-eng/research --ralph --max-phase-iterations 5
   - Output: docs/research/[date]-[feature].md

2. SPECIFY (2 iterations estimated)
   - Command: /ai-eng/specify --from-research=... --ralph --max-phase-iterations 3
   - Output: specs/[feature]/spec.md

3. PLAN (4 iterations estimated)
   - Command: /ai-eng/plan --from-spec=... --ralph --max-phase-iterations 4
   - Output: specs/[feature]/plan.md

4. WORK (6 iterations estimated)
   - Command: /ai-eng/work specs/[feature]/plan.md --ralph --max-phase-iterations 8
   - Quality gate: npm test && npm run lint
   - Output: Implementation + tests

5. REVIEW (3 iterations estimated)
   - Command: /ai-eng/review . --ralph --max-phase-iterations 3
   - Output: code-review-report.json

## Estimated Completion:
- Max cycles: 5
- Total iterations: 18
- Estimated tokens: ~75,000
- Estimated time: ~2 hours

Proceed with execution? (y/n)

Completion Report

When build completes successfully (all criteria met or max cycles reached):

## Build Complete

**Feature**: $FEATURE_DESCRIPTION
**Status**: ✅ COMPLETE / ⚠️ INCOMPLETE (max cycles reached)

**Final Summary**:
- Total cycles: N
- Total tokens: N
- Total time: N
- Phases completed: Research, Specify, Plan, Work, Review

**Acceptance Criteria**: M / N complete (X%)
**Quality Gates**: All passing
**Review Status**: APPROVE / CHANGES_REQUESTED

**Artifacts Generated**:
- docs/research/[date]-[feature].md
- specs/[feature]/spec.md
- specs/[feature]/plan.md
- [Implementation files]
- code-review-report.json
- .ralph-wiggum/[feature]/checkpoint.json

**Pull Request**:
- Draft PR created: https://github.com/user/repo/pull/N
- Ready for review

**Next Steps**:
- Review draft PR
- Merge when ready
- Delete feature branch after merge

Integration with Existing Commands

This command orchestrates existing ai-eng-system commands:

Research Phase

/ai-eng/research "$FEATURE" --ralph --ralph-max-iterations $MAX

Specify Phase

/ai-eng/specify "$FEATURE" --from-research=$RESEARCH_OUTPUT --ralph --ralph-max-iterations $MAX

Plan Phase

/ai-eng/plan --from-spec=$SPEC_OUTPUT --ralph --ralph-max-iterations $MAX

Work Phase

/ai-eng/work $PLAN_OUTPUT --ralph --ralph-max-iterations $MAX --ralph-quality-gate="$QUALITY_GATE"

Review Phase

/ai-eng/review . --ralph --ralph-max-iterations $MAX

Best Practices & Troubleshooting

See docs/ralph-wiggum-guide.md for comprehensive guidance on:

Best practices for effective builds
When to use Ralph Wiggum (ideal vs. non-ideal scenarios)
Troubleshooting common issues (stuck loops, token usage, quality gates, resume failures, etc.)

Success Criteria

Successful build achieves:

✅ All phases executed sequentially or with appropriate returns
✅ Gap analysis correctly determines return-to phase
✅ Checkpoints saved and can be loaded
✅ Progress displayed at appropriate verbosity
✅ Safety limits enforced (max cycles, stuck detection)
✅ Token usage tracked and displayed
✅ Draft PR created with comprehensive summary
✅ Build report generated with all artifacts and metrics

/ralph-wiggum

Ralph Wiggum Full-Cycle Command

Why This Matters

The Challenge

Quick Start

How This Command Works

Options

Phase 0: Prompt Refinement (CRITICAL - Do First)

Autonomous Execution Model

Phase 1: Git Setup

1.1 Create Feature Branch

Phase 2: Main Cycle Loop

2.1 Cycle Start Check

2.2 Research Phase (if not skipped)

2.3 Specify Phase (if not skipped)

2.4 Plan Phase (if not skipped)

2.5 Work Phase

2.6 Review Phase

Phase 3: Gap Analysis

3.1 Analyze Review Findings

3.2 Determine Completion Status

3.3 Determine Return-To Phase

Phase 4: Checkpoint Management

4.1 Save Checkpoint (After Each Cycle)

4.2 Load Checkpoint (If --resume)

Phase 5: Pull Request Creation

5.1 Create Draft PR

Progress Output

Default Display (balanced verbosity)

Verbose Display

Quiet Display

Safety Measures

Max Cycles Limit

Stuck Detection

Token Usage Tracking

Optional Checkpoints

Checkpoint Interaction (if --checkpoint is set)

Dry Run Mode

Completion Report

Integration with Existing Commands

Research Phase

Specify Phase

Plan Phase

Work Phase

Review Phase

Best Practices & Troubleshooting

Success Criteria

4.2 Load Checkpoint (If `--resume`)

Checkpoint Interaction (if `--checkpoint` is set)