Supermango

Ralph loop engine with planner, coder, and reviewer for autonomous feature implementation.

How It Works

/ralph.planner (interactive)
         |
   Phase 1: product vision
   Phase 2: design
   Phase 3: tech stack
   Phase 4: risks & testing
   Phase 5: synthesis
         |
   draft brainstorm.md + spec.md
   review with user
   generate stories + tasks
   commit artifacts
         |
        done

%> pnpm loop (autonomous)
         |
   read state (spec, brainstorm, progress.json)
   find next story + task
   dispatch coder or reviewer
   update progress.json
   commit & end iteration
         |
   ↻ until all stories COMPLETE

1. /ralph.planner — Brainstorm with user, generate spec, stories, tasks, and progress.json
2. pnpm loop — Bash loop that pipes a prompt to claude per iteration (up to 100 iterations)
3. ralph.coder — TDD implementation, one task per iteration
4. ralph.reviewer — QA (live server), code quality, security, design review

Usage

# Step 1: Plan the feature interactively
/ralph.planner

# Step 2: Run autonomous implementation
pnpm loop

# Or run a single iteration (full output visible)
pnpm loop:once

Directory Structure

ralph-engine/
  ralph-loop.sh              # headless bash loop (up to 100 iterations)
  ralph-once.sh              # interactive single iteration
  ralph-prompt.md            # self-dispatching prompt with decision logic
  ralph-format.sh            # formats streaming JSON output

ralph-workspace/             # generated by planner, consumed by loop
  spec.md                    # feature spec (goals, non-goals, tech stack)
  brainstorm.md              # design rationale and architecture decisions
  progress.json              # global state (stories, tasks, statuses)
  known-issues.md            # tasks that exceeded retry caps
  logs/                      # iteration output logs
  001-{userstory}/
    story.md                 # user story description, acceptance criteria
    tasks.md                 # task breakdown
    log.md                   # coder/reviewer/QA detailed log (append-only)

.claude/skills/
  ralph.planner/             # interactive brainstorming PM (5 phases)
  ralph.coder/               # TDD implementation teammate
  ralph.reviewer/            # QA/review teammate (7 verification steps)

Prerequisites

Claude Code Skills

• superpowers — brainstorming, planning, execution workflows
• gstack — headless browser QA, CEO/eng plan reviews
• context7 — library documentation lookup
• frontend-design — production-grade UI generation

Architecture

Planner Flow (Interactive)

Phase 1: Product Vision

• Problem definition, affected surfaces (webapp, Slack, CLI, etc.)
• User stories per surface, concrete demo scenario, non-goals

Phase 2: Design

• Visual direction and interaction patterns per surface
• Interaction state matrix (loading, empty, error, success, partial)
• AI slop check — challenge generic patterns, push for specificity
• Edge cases per screen/interaction

Phase 3: Technical Foundation

• Tech stack per surface (verified via Context7 docs)
• Architecture and data model (cross-surface integration)
• Environment setup (API keys, OAuth, env vars, external services)

Phase 4: Risk & Test Strategy

• Risks with likelihood, impact, and mitigation
• Test strategy per surface (TDD, browser QA, integration)
• Acceptance criteria sharpening — every criterion must be objectively verifiable

Phase 5: Synthesis & Context

1. Draft brainstorm.md (design rationale from all phases)
2. Draft spec.md (goals, design, non-goals, tech, risks)
3. Section-by-section review with user
4. Write spec.md + brainstorm.md to disk
5. Generate story.md per user story
6. Generate tasks.md per user story (each task = one coder iteration)
7. Generate progress.json (all statuses start as pending)
8. Subagent spec review (TODOs, contradictions, vague criteria)
9. Update CLAUDE.md if new conventions emerged
10. Commit all artifacts to git

Loop Flow (Autonomous)

1. Read progress.json to find current work
2. Dispatch coder or reviewer based on task status
3. Coder: pre-flight checks, TDD (fail → implement → pass → commit), self-validate, write to log.md
4. Reviewer: 7 sequential steps — tests, lint/typecheck/build, live server QA, code quality, security, design, spec alignment
5. If issues: coder fixes, reviewer reviews again (max 5 rounds per task)
6. After all tasks pass: QA validates full story
7. Stuck tasks (5+ rounds) recorded in known-issues.md
8. Repeat until all stories complete

License

MIT