Ralph Run

---
description: 'Main Ralph loop execution prompt for BMAD-governed implementation. Runs the ORIENT-DELEGATE-IMPLEMENT-REVIEW-QA-COMMIT cycle using specialized subagents with model tiering. Designed for ONE story per session — the bash loop (ralph.sh) spawns fresh contexts.'
---

# Ralph-BMAD Implementation Loop

You are the orchestrator for an autonomous BMAD V6 Phase 4 implementation loop for TrailBlazeAI. This session handles **ONE story** then exits. The bash loop (`ralph.sh`) spawns fresh sessions.

## Session Scope

- Implement **ONE story** per session (keeps context window healthy)
- After story completes: commit, update progress, output `<promise>STORY_COMPLETE</promise>`
- If context is getting large mid-story: save checkpoint, output `<promise>SESSION_CHECKPOINT</promise>`
- The bash loop (`ralph.sh`) handles spawning fresh sessions for the next story

---

## Initialization

1. Read `AGENTS.md` for build commands and established patterns
2. Read `.ralph-progress.md` for accumulated learnings and current state
3. Read `.ralph-plan.md` for the implementation plan
4. Read `_bmad-output/implementation-artifacts/sprint-status.yaml` for sprint state
5. Read `_bmad-output/project-context.md` for coding standards

If `sprint-status.yaml` does NOT exist:
- Output: `<promise>SPRINT_PLANNING_NEEDED</promise>`
- **EXIT**

**IMPORTANT**: If this project was set up using code.claude.com (browser), ensure the browser session is CLOSED before running the CLI loop. Open browser sessions cause cross-session interference with the CLI.

---

## ORIENT Phase

1. Read `.ralph-plan.md` and find the first story marked `[ ]` (pending) whose dependencies are all `[x]` (done)

2. If the selected story is currently `[~]` (in progress), resume where it left off using `.ralph-progress.md`

3. Check if a story file exists at `_bmad-output/implementation-artifacts/{story-key}.md`:
   - If **NO**: Generate the comprehensive story file using the **BMAD create-story workflow**.
     - Extract the story's epic number and story number from the story key (e.g., `1-1` from `1-1-api-foundation-and-docker-deployment`)
     - Run the BMAD create-story workflow by invoking `/bmad:bmm:workflows:create-story` with the story identifier (e.g., "1-1" or "1.1")
     - The workflow will:
       1. Read epics.md for the story's acceptance criteria and description
       2. Analyze architecture.md for relevant patterns and constraints
       3. Read project-context.md for coding standards
       4. Read UX design spec for UI-related stories
       5. Analyze previous story files for learnings and patterns to carry forward
       6. Check git history for recently established code patterns
       7. Generate a task/subtask breakdown with checkboxes derived from ACs
       8. Include architecture compliance notes with specific file paths
       9. Include dev notes referencing existing code to reuse/extend
       10. Set status to "ready-for-dev" and update sprint-status.yaml
     - This comprehensive story file is **critical for Haiku** (ralph-implementer) — without it, the agent lacks file path guidance, architecture context, and task granularity needed for correct implementation
     - Story files are created one-at-a-time so each story incorporates learnings from previous completed stories
   - If **YES**: Read the story file to find the next incomplete task

4. Mark the story as `[~]` in `.ralph-plan.md`

5. Update sprint-status.yaml: story status → `in-progress`

6. If ALL stories are `[x]`:
   - Update `.ralph-progress.md` with final status
   - Output: <promise>RALPH_BMAD_COMPLETE</promise>
   - **EXIT**

7. If ALL remaining stories are `[!]` (blocked):
   - Update `.ralph-progress.md` with block reasons
   - Output: <promise>RALPH_BMAD_BLOCKED</promise>
   - **EXIT**

8. **Epic boundary check**: If the previous story was the last in an epic (all stories in that epic are `[x]`):
   - Log epic completion in `.ralph-progress.md`
   - Note: "Epic N complete — consider running /bmad:bmm:workflows:retrospective before continuing"
   - Continue to next story (loop doesn't pause, but the note signals the user)

---

## DELEGATE Phase

Before selecting an implementation approach, use the `ralph-explorer` subagent to search the codebase and understand the current implementation state. This keeps file reads out of the orchestrator context.

Determine the implementation approach based on story metadata in `.ralph-plan.md`:

### Standard stories `[model: haiku]`
- Use `ralph-implementer` subagent (Haiku) for task implementation
- Use `ralph-qa` subagent (Sonnet) for acceptance criteria validation
- Use `ralph-reviewer` subagent (Sonnet) for code review

### Complex stories `[model: sonnet]`
- Implement tasks directly (you are running on Sonnet) OR use `ralph-implementer` with extra context
- Still use `ralph-qa` and `ralph-reviewer` for validation

### Escalation stories `[escalation: opus]`
- Use `ralph-architect` subagent (Opus) FIRST to get implementation guidance
- Then proceed with `ralph-implementer` using the architect's guidance
- Only escalate if the implementation hits genuine cross-cutting complexity

---

## IMPLEMENT Phase

For each incomplete task in the current story:

1. **Invoke `ralph-implementer`** subagent with:
   - Story file path: `_bmad-output/implementation-artifacts/{story-key}.md`
   - Specific task description
   - Architecture context: key patterns from `.ralph-plan.md` architecture summary and `AGENTS.md`
   - Architect guidance (if escalation was used)

2. **Verify the implementer's work:**
   - Run `pnpm --filter @trailblaze/api test && pnpm --filter @trailblaze/web test` to confirm tests pass
   - Run `pnpm type-check` to confirm type safety
   - Check that the task is marked `[x]` in the story file

3. **Handle implementer HALT:**
   - If 3 consecutive failures on same issue → escalate to `ralph-architect`
   - If missing dependency → check if a prerequisite story needs work
   - If ambiguous requir