brainstorm-to-ralph

Brainstorm to Ralph

You are orchestrating a complete development workflow. This skill takes an initial idea through brainstorming, planning, execution, and submission to ralph-o-matic for iterative refinement.

Arguments

Parse the following from the user's command:

• IDEA: The feature or task description (required)
• --max-iterations N: Max ralph loop iterations (default: 50)
• --priority LEVEL: Job priority - high, normal, low (default: normal)
• --open-ended: Use polish prompt without exit criteria
• --local: Use local repo directory (skip clone). Auto-detected when server is localhost.

Workflow Overview

Phase 1: Brainstorm (INTERACTIVE) ────► Design document
                                              │
Phase 2: Plan (AUTOMATIC) ────────────► Phase documents
                                              │
Phase 3: Execute (PARALLEL) ──────────► Implementation
                                              │
Phase 4: Ship (AUTOMATIC) ────────────► Ralph job submitted

---

Phase 1: Brainstorm (INTERACTIVE)

Announce: "Starting brainstorming session for: {IDEA}"

REQUIRED: Invoke superpowers:brainstorming with the IDEA.

This phase is interactive. You will:

1. Explore the current project context
2. Ask clarifying questions one at a time
3. Propose 2-3 approaches with trade-offs
4. Present the design in sections, validating each

Output: docs/plans/YYYY-MM-DD-{topic}-design.md

On completion:

• Commit the design document
• Announce: "Design complete. Moving to planning phase."
• Proceed to Phase 2

---

Phase 2: Plan (AUTOMATIC)

Announce: "Creating implementation plan from design..."

REQUIRED: Invoke superpowers:writing-plans to create detailed phase documents.

Using the design document from Phase 1, create:

• docs/plans/YYYY-MM-DD-{topic}-design-phase-1.md
• docs/plans/YYYY-MM-DD-{topic}-design-phase-2.md
• docs/plans/YYYY-MM-DD-{topic}-design-phase-3.md
• (etc., as many phases as needed)

Each phase document must follow the writing-plans format:

• Clear task breakdown with exact file paths
• TDD approach (tests before implementation)
• Step-by-step instructions
• Commit points

On completion:

• Commit all phase documents
• Announce: "Planning complete. {N} phases created. Starting parallel execution..."
• Proceed to Phase 3

---

Phase 3: Execute (PARALLEL)

Announce: "Launching parallel execution agents..."

REQUIRED: Use superpowers:dispatching-parallel-agents to execute phase documents concurrently.

Agent Configuration

Spawn one agent per phase document. Each agent receives:

You are executing an implementation plan for a specific phase.

**Phase Document:** docs/plans/YYYY-MM-DD-{topic}-design-phase-{N}.md

**REQUIRED:** Invoke `superpowers:executing-plans` with this phase document.

**Task Tracking:**

Each phase document contains numbered tasks. Work through them in order:
1. Read the phase document to understand the full scope
2. For each task, implement it following TDD (tests first, then implementation)
3. Run tests after each task to verify correctness
4. Commit after each task completion

If a task depends on work from another phase that isn't complete yet,
skip it and move to the next independent task. Return to blocked tasks
after the dependency is available.

**Commit Strategy:**
- Commit after each task completion
- Use conventional commit messages
- Reference the phase and task in commit messages, e.g.: "feat(phase-1): create users table"

Execution Flow

1. Dispatch agents for all phases simultaneously
2. Phases with dependencies on earlier phases will skip blocked tasks and return to them
3. Wait for all agents to complete
4. If any agent fails, review its output and either fix manually or re-run

Handling Failures

If an agent fails:

1. Review the error in agent output
2. Either:
   • Fix manually and commit the fix
   • Re-run the agent for that specific phase

On completion:

• Run full test suite to verify implementation
• Announce: "Implementation complete. All {N} phases done. Preparing for ralph submission..."
• Proceed to Phase 4

---

Phase 4: Ship (AUTOMATIC)

Announce: "Running pre-flight checks and shipping to ralph-o-matic..."

Pre-flight Checks

Run these checks before submission:

# 1. Working tree clean
if [ -n "$(git status --porcelain)" ]; then
    echo "✗ Uncommitted changes detected"
    git status --short
    # Commit remaining changes
    git add -A
    git commit -m "chore: final implementation cleanup"
fi
echo "✓ Working tree clean"

# 2. Branch pushed to origin
BRANCH=$(git branch --show-current)
if ! git ls-remote --exit-code origin "$BRANCH" &>/dev/null; then
    echo "Pushing branch to origin..."
    git push -u origin "$BRANCH"
fi
echo "✓ Branch '$BRANCH' pushed to origin"

# 3. Tests exist
TEST_COUNT=$(find . -name "*_test.go" -o -name "test_*.py" -o -name "*.test.ts" | wc -l | tr -d ' ')
if [ "$TEST_COUNT" -eq 0 ]; then
    echo "✗ No tests found - ralph needs tests to verify completion"
    exit 1
fi
echo "✓ Tests found ($TEST_COUNT test files)"

# 4. Server reachable
if ! ralph-o-matic status &>/dev/null; then
    echo "✗ Cannot reach ralph-o-matic server"
    exit 1
fi
echo "✓ Server reachable"

# 5. Branch not already in queue
SERVER=$(ralph-o-matic config | grep '^server:' | awk '{print $2}')
EXISTING=$(curl -sf "$SERVER/api/jobs?status=queued,running,paused" | jq -r ".jobs[] | select(.branch == \"$BRANCH\") | .id" 2>/dev/null | head -1)
if [ -n "$EXISTING" ]; then
    echo "✗ Branch already in queue as job #$EXISTING"
    exit 1
fi
echo "✓ Branch not in queue"

Local Server Detection

After pre-flight checks pass, determine whether the ralph server is local.

How to detect: Read the configured server URL from ralph-o-matic config. If it contains localhost or 127.0.0.1, the server is local.

If --local was passed: Use local mode without asking.

If server is local and --local was NOT passed: Ask the user with AskUserQuestion:

Option	Description
Use local repo (Recommended)	Ralph works directly in your checkout — no clone, faster startup, changes pushed after each pass. Don't edit these files while ralph is running.
Clone as usual	Ralph clones into its own workspace. Slower but your working tree stays untouched.

If the user chooses local repo: Get the repo root with git rev-parse --show-toplevel. Store this as LOCAL_DIR for use in the submit step.

If server is NOT local: Skip this — remote servers can't access local paths.

Generate Ralph Prompt

Based on the --open-ended flag, generate the appropriate prompt:

Standard prompt (bounded):

You are refining code to meet a specification. The user is unavailable — do the work without asking for input.

Spec: docs/plans/YYYY-MM-DD-{topic}-design.md
Progress: docs/plans/{BRANCH}-ralph-status.md

Steps:
1. Read the spec and progress file to understand current state
2. Search the codebase before assuming anything is missing — do not reimplement existing code
3. Pick the single highest-impact remaining task
4. Implement it, keeping the change focused and testable
5. Run tests — if they fail, fix before moving on
6. Update the progress file: mark completed items, add discovered work, note what's next
7. Commit and push

The code may have been drafted by another agent. Do not trust it. Verify against the spec.

When all spec requirements are satisfied and tests pass, output:
<promise>FINIT</promise>

Otherwise, output:
<promise>CLOSER</promise>

Output exactly one tag, then stop.

Open-ended prompt (unbounded):

You are improving this codebase toward production quality. The user is unavailable — do the work without asking for input.

Progress: docs/plans/{BRANCH}-ralph-status.md

Steps:
1. Read the progress file to understand what's been done and what remains
2. Search the codebase before assuming anything is missing
3. Pick the single highest-impact improvement
4. Implement it, keeping the change focused and testable
5. Run tests — if they fail, fix before moving on
6. Update the progress file: mark completed items, add discovered work, note what's next
7. Commit and push

Do not output a <promise> tag. Continue improving until stopped.

Submit to Ralph-o-matic

# Write prompt to RALPH.md
cat > RALPH.md << 'EOF'
{GENERATED_PROMPT}
EOF

git add RALPH.md
git commit -m "chore: add ralph review prompt"
git push

# Submit job
# If LOCAL_DIR is set, pass --working-dir to use the local repo directly
ralph-o-matic submit \
    --priority {PRIORITY} \
    --max-iterations {MAX_ITERATIONS} \
    ${LOCAL_DIR:+--working-dir "$LOCAL_DIR"}

Report Success

Shipped to Ralph-o-matic!

  Job ID:         #{JOB_ID}
  Branch:         {BRANCH}
  Priority:       {PRIORITY}
  Max Iterations: {MAX_ITERATIONS}
  Mode:           {LOCAL_DIR ? "local repo (direct)" : "cloned workspace"}

  Dashboard:      {SERVER_URL}/jobs/{JOB_ID}

  Monitor: ralph-o-matic logs {JOB_ID} --follow

If local mode was used, add:

  Note: Ralph is working directly in {LOCAL_DIR}.
        Changes are pushed to the remote after each pass.
        Avoid editing files in this repo until the job completes.

---

Error Handling

Server Unreachable

If ralph-o-matic server is unreachable during pre-flight:

Cannot reach ralph-o-matic server

The implementation is complete and ready for ralph. Options:

1. Start the server locally:
   ralph-o-matic-server

2. Point to a different server:
   ralph-o-matic config set server http://new-server:9090

3. Create PR manually instead:
   git push -u origin $(git branch --show-current)
   gh pr create

Tests Failing

If tests are failing before submission:

Tests failing - ralph needs passing tests as baseline

{N} tests failing. Fix these before submitting to ralph:

  FAIL  src/auth/login.test.ts
    ✗ should validate credentials
    ✗ should create session

Ralph uses test results to measure progress. Submit when tests pass.

No Tests Found

No tests found

Ralph needs tests to verify completion. The implementation includes code but no tests.

Add tests for the new functionality before submitting:
  - Unit tests for new functions
  - Integration tests for API endpoints
  - E2E tests for critical flows

---

Recovery

If the workflow fails partway through, you can resume:

Resume from Phase 2 (Planning)

If brainstorming completed but planning failed:

/brainstorm-to-ralph resume --from-design docs/plans/YYYY-MM-DD-{topic}-design.md

Resume from Phase 3 (Execution)

If planning completed but execution failed:

/brainstorm-to-ralph resume --from-plans "docs/plans/YYYY-MM-DD-{topic}-design-phase-*.md"

Resume from Phase 4 (Ship)

If execution completed but shipping failed:

ralph-o-matic submit --priority normal --max-iterations 50