User's description
    |
    v
PHASE 0: Equip (wavybaby)
    |  - Detect project type and stack
    |  - Search skills.sh for relevant skills, install missing ones
    |  - Install missing MCP servers (Context7, Supabase, Sentry, etc.)
    |  - Set up project config (settings.local.json, CLAUDE.md)
    |  - Now the agent has the best tools for THIS specific project
    |
    v
PHASE 1: PRD Generation
    |  - Clarifying questions
    |  - Full PRD at .planning/specs/PRD.md
    |
    v
PHASE 2: GSD Project Bootstrap
    |  - PROJECT.md, ROADMAP.md, STATE.md, config.json
    |  - codebase/ docs (STACK, ARCHITECTURE, STRUCTURE, CONVENTIONS)
    |  - Phase directories with DISCOVERY.md per phase
    |
    v
PHASE 3: Plan Generation
    |  - Break each phase into {NN}-{NN}-PLAN.md files
    |  - Each plan: 1-4 hours, atomic, with verification steps
    |
    v
PHASE 4: Loop Configuration
    |  - .ralphrc tuned for GSD execution
    |  - PROMPT.md with GSD execution + CoVe verification logic
    |  - AGENT.md with build/test/lint commands
    |
    v
PHASE 5: Autonomous Execution
    - ralph --monitor
    - Each loop iteration: read STATE.md -> execute next plan (with CoVe on non-trivial code) -> write SUMMARY.md -> update STATE.md
    - Circuit breaker halts if stuck
    - Exits when all phases complete

undefined

**Auto-install recommendations based on stack:**

| Stack | Skills to Install |
|-------|------------------|
| React / Next.js | `npx skills add vercel-labs/agent-skills --skill vercel-react-best-practices --agent claude-code -y` |
| React Native / Expo | `npx skills add expo/skills --agent claude-code -y` |
| Supabase | `npx skills add supabase/agent-skills --agent claude-code -y` |
| Stripe payments | `npx skills add stripe/skills --agent claude-code -y` |
| Cloudflare | `npx skills add cloudflare/skills --agent claude-code -y` |
| Any web project | `npx skills add vercel-labs/agent-skills --skill web-design-guidelines --agent claude-code -y` |
| Security-critical | `npx skills add trailofbits/skills --agent claude-code -y` |

Install all relevant skills immediately — don't ask, just do it. The `-y` flag auto-confirms.

{
  "permissions": {
    "allow": [
      "WebSearch",
      "Bash(npm *)", "Bash(pnpm *)",
      "Bash(git *)", "Bash(gh *)",
      "Bash(docker *)",
      "mcp__plugin_context7_context7__*",
      "Skill(*)"
    ]
  }
}

{
  "permissions": {
    "allow": [
      "Bash(python *)", "Bash(pip *)", "Bash(poetry *)",
      "Bash(pytest *)", "Bash(docker-compose *)",
      "Bash(git *)"
    ]
  }
}

Equipped for: [project type]

Skills installed:
  - [skill 1] (from [repo])
  - [skill 2] (from [repo])

MCP servers configured:
  - [server 1]: [purpose]
  - [server 2]: [purpose]

Project config: settings.local.json [created/updated/already exists]

undefined

undefined

mkdir -p .planning/specs .planning/codebase .planning/phases

undefined

undefined

undefined

**Derivation rules:**
1. Infrastructure/setup is always Phase 1
2. Auth is Phase 2 (if applicable)
3. Each PRD Epic becomes one or more phases
4. PRD §5 Screen Map informs navigation phases
5. PRD §6 Non-Functional becomes a final polish phase
6. Every phase traces back to a PRD section

undefined

undefined

{
  "mode": "yolo",
  "depth": "comprehensive",
  "gates": {
    "confirm_project": false,
    "confirm_phases": false,
    "confirm_roadmap": false,
    "confirm_breakdown": false,
    "confirm_plan": false,
    "execute_next_plan": true,
    "issues_review": false,
    "confirm_transition": false
  },
  "safety": {
    "always_confirm_destructive": true,
    "always_confirm_external_services": true
  }
}

<plan>
  <phase>1</phase>
  <plan-number>01</plan-number>
  <type>execute</type>
  <name>[Descriptive name]</name>
</plan>

<objective>
[What this plan delivers and why, traced to PRD section]
</objective>

<context>
- PRD: .planning/specs/PRD.md
- Project: .planning/PROJECT.md
- Stack: .planning/codebase/STACK.md
</context>

<tasks>
  <task type="auto">
    <name>[Task name]</name>
    <files>[Files to create/modify]</files>
    <action>
      [Detailed implementation instructions]
    </action>
    <verify>
      - [ ] [Verification step]
      - [ ] [Verification step]
    </verify>
    <done>[Success indicator]</done>
  </task>

  <!-- More tasks -->
</tasks>

<verification>
  - [ ] All files created/modified as specified
  - [ ] Tests pass
  - [ ] No TypeScript/lint errors
  - [ ] Acceptance criteria from PRD met
</verification>

<success_criteria>
[Definition of done for this plan]
</success_criteria>

which ralph-loop 2>/dev/null || which ralph 2>/dev/null

git clone https://github.com/frankbria/ralph-claude-code.git /tmp/ralph-claude-code
cd /tmp/ralph-claude-code && ./install.sh

PROJECT_NAME="$ARGUMENTS"
PROJECT_TYPE="[detected]"
MAX_CALLS_PER_HOUR=100
CLAUDE_TIMEOUT_MINUTES=20
CLAUDE_OUTPUT_FORMAT="json"
ALLOWED_TOOLS="Write,Read,Edit,Bash(git *),Bash(npm *),Bash(npx *),Skill(gsd:*)"
SESSION_CONTINUITY=true
SESSION_EXPIRY_HOURS=24
TASK_SOURCES="local"
CB_NO_PROGRESS_THRESHOLD=3
CB_SAME_ERROR_THRESHOLD=5
CB_OUTPUT_DECLINE_THRESHOLD=70

undefined

Is current phase's DISCOVERY.md missing?
  YES → Run research: read PRD, explore codebase, write DISCOVERY.md
        Use Context7 to look up docs for any unfamiliar tech.
  NO  ↓

Are there ungenerated plans for current phase?
  YES → Generate next {NN}-{NN}-PLAN.md from DISCOVERY.md + PRD
  NO  ↓

Is there an unexecuted plan in current phase?
  YES → Execute it (see "Execute a Plan" below)
  NO  ↓

Are all plans in current phase complete?
  YES → Complete phase: update ROADMAP.md, advance STATE.md to next phase
  NO  → Something is wrong. Set STATUS: BLOCKED.

Are all phases complete?
  YES → Run verification gate. If passing, set EXIT_SIGNAL: true
  NO  → Continue to next phase (loop back to top)

undefined

undefined

undefined

echo -e "\n# Ralph loop state\n.ralph/logs/\n.ralph/status.json\n.ralph/progress.json\n.ralph/.call_count\n.ralph/.last_reset\n.ralph/.exit_signals\n.ralph/.response_analysis\n.ralph/.circuit_breaker_state\n.ralph/.claude_session_id\n.ralph/.ralph_session\n.ralph/.ralph_session_history" >> .gitignore

Steve setup complete.

EQUIPPED:
  Skills:         [list installed skills]
  MCP servers:    [list configured servers]
  Config:         settings.local.json

PROJECT:
  PRD:            .planning/specs/PRD.md        (review before running)
  Project:        .planning/PROJECT.md          (derived from PRD)
  Roadmap:        .planning/ROADMAP.md          (phases derived from PRD)
  State:          .planning/STATE.md            (tracks progress)
  Phase 1 Plans:  .planning/phases/01-*/        (ready to execute)

LOOP:
  Config:         .ralphrc                      (rate limits, timeouts)
  Prompt:         .ralph/PROMPT.md              (GSD + CoVe execution logic)
  Build/test:     .ralph/AGENT.md               (edit if auto-detect wrong)

To run:
  ralph --monitor      # Recommended: loop + dashboard in tmux
  ralph                # Loop only

The loop will:
  1. Execute Phase 1 plans sequentially (with CoVe on non-trivial code)
  2. Write SUMMARY.md after each plan
  3. Use Context7 for library docs (no hallucinated APIs)
  4. Generate Phase 2 plans just-in-time
  5. Continue through all phases
  6. Run final verification gate
  7. Exit when milestone is complete

To check progress:
  cat .planning/STATE.md
  ralph-monitor

Loop iteration N:
  1. Read .planning/STATE.md
  2. Identify: Phase X, Plan Y
  3. If DISCOVERY.md missing → research phase (use Context7) → write DISCOVERY.md → done
  4. If plans not generated → generate plans from DISCOVERY + PRD → done
  5. Read .planning/phases/{X}-{name}/{XX}-{YY}-PLAN.md
  6. Execute all tasks in plan
     - Non-trivial code → CoVe 4-stage verification
     - Library usage → Context7 doc lookup
  7. Run verification checks
  8. Write {XX}-{YY}-SUMMARY.md
  9. Update STATE.md (plan Y+1, metrics)
  10. If last plan in phase → update ROADMAP.md, advance to Phase X+1
  11. If last phase → verification gate → EXIT_SIGNAL: true
  12. Output RALPH_STATUS block