Agent skill
ralph-preflight
Pre-flight check for Ralph TUI loops. Validates config, templates, prd.json, and environment before starting a loop. Run after /prd to verify everything is ready. Detects global CLAUDE.md conflicts, validates template variables, and provides launch commands.
Install this agent skill to your Project
npx add-skill https://github.com/AnsarUllahAnasZ360/cc-guide/tree/main/skills/ralph-preflight
SKILL.md
Ralph TUI Pre-Flight Check
Fast verification that everything is configured correctly before starting a Ralph loop. Run this after creating a PRD with /prd to validate and launch.
When to Use
- After running
/prdto create a prd.json - Before starting any Ralph loop
- When troubleshooting Ralph loop issues
- To verify template and config are in sync
Pre-Flight Phases
Execute these checks in order. Stop and report if critical issues are found.
Phase 1: Environment Check
1.1 Global CLAUDE.md Conflict Detection (CRITICAL)
Ralph loops can have global ~/.claude/CLAUDE.md override local project CLAUDE.md. Check and warn:
# Check if global CLAUDE.md exists
if [ -f ~/.claude/CLAUDE.md ]; then
echo "WARNING: Global CLAUDE.md exists at ~/.claude/CLAUDE.md"
echo "This may override your local CLAUDE.md during Ralph loops"
wc -l ~/.claude/CLAUDE.md
else
echo "OK: No global CLAUDE.md found"
fi
If global CLAUDE.md exists:
- Show its contents (first 20 lines)
- Ask user if they want to:
- A. Remove it temporarily (rename to CLAUDE.md.bak)
- B. Keep it (may cause issues)
- C. View full contents first
1.2 Ralph TUI Installation
which ralph-tui && ralph-tui --version
1.3 Required Tools
# Check tmux (required for persistent sessions)
which tmux && tmux -V
# Check git (required for worktrees)
git --version
1.4 Existing Ralph State Detection (CRITICAL)
Check if .ralph-tui/ has data from a previous run that could interfere:
# Check for existing state
if [ -d .ralph-tui ]; then
echo "Found existing .ralph-tui/ directory"
# Check for progress file with content
if [ -f .ralph-tui/progress.md ] && [ -s .ralph-tui/progress.md ]; then
echo "⚠ progress.md exists with content ($(wc -l < .ralph-tui/progress.md) lines)"
fi
# Check for iteration logs
if [ -d .ralph-tui/iterations ] && [ "$(ls -A .ralph-tui/iterations 2>/dev/null)" ]; then
echo "⚠ iterations/ has $(ls .ralph-tui/iterations | wc -l) log files"
fi
# Check for session state
if [ -f .ralph-tui/state.json ]; then
echo "⚠ state.json exists (previous session state)"
fi
# Check for lock file (Ralph might be running)
if [ -f .ralph-tui.lock ]; then
echo "⚠ .ralph-tui.lock exists - Ralph may be running!"
fi
else
echo "OK: No existing .ralph-tui/ state"
fi
If existing state is found, determine the situation:
AskUserQuestion: "Found existing Ralph state from a previous run. What's the situation?"
├── "Previous run is complete, clean up for new PRD"
│ → Clean .ralph-tui/iterations/, progress.md, state.json
│ → Keep config.toml and templates
├── "Previous run is still active (different PRD)"
│ → Create new worktree for this PRD
│ → Keep current directory untouched
├── "Save progress to branch first, then clean"
│ → Commit current progress
│ → Clean for new PRD
└── "Let me check the progress first"
│ → Show progress.md contents
│ → Show iteration count
│ → Re-ask after review
Cleanup commands (if user chooses to clean):
# Remove iteration logs
rm -rf .ralph-tui/iterations/*
# Clear progress file (keep file, clear content)
echo "" > .ralph-tui/progress.md
# Remove session state
rm -f .ralph-tui/state.json
rm -f .ralph-tui.lock
rm -f .ralph-tui-session.json
# Verify cleanup
ls -la .ralph-tui/
echo "Cleaned. Ready for new Ralph loop."
If previous run is still active:
# Check current branch
CURRENT_BRANCH=$(git branch --show-current)
echo "Current branch: $CURRENT_BRANCH"
# Suggest worktree for new PRD
REPO_NAME=$(basename $(git rev-parse --show-toplevel))
echo "Suggested worktree: ../${REPO_NAME}-[new-prd-name]"
Then proceed to Phase 7 for worktree setup.
Phase 2: Configuration Validation
2.1 Locate .ralph-tui/config.toml
# Check project config exists
if [ -f .ralph-tui/config.toml ]; then
echo "OK: Config found at .ralph-tui/config.toml"
else
echo "ERROR: No .ralph-tui/config.toml found"
echo "Run: ralph-tui setup"
fi
2.2 Validate Config Settings
Read config.toml and verify critical settings:
| Setting | Required Value | Check |
|---|---|---|
tracker |
"json" |
Must be json for prd.json execution |
agent |
"claude" |
Claude agent |
prompt_template |
Path exists | Template file must exist |
model |
"opus" or "sonnet" |
Valid model |
maxIterations |
> 0 | Reasonable iteration limit |
2.3 Show Template Source
ralph-tui template show | head -5
Verify it's loading from expected location (not default).
Phase 3: Template Validation
3.1 Locate prompt.hbs
Get template path from config.toml prompt_template setting and verify file exists:
# Extract template path from config
grep "prompt_template" .ralph-tui/config.toml
# Verify file exists
ls -la [extracted-path]
3.2 Template Variable Check
Read the prompt.hbs and verify it uses these required variables:
PRD Variables:
{{prdName}}- Project name{{prdDescription}}- Project overview{{prdCompletedCount}}/{{prdTotalCount}}- Progress{{currentIteration}}- Current iteration number (REQUIRED in header)
Task Variables:
{{taskId}}- Story ID (e.g., US-001){{taskTitle}}- Story title{{taskDescription}}- What and why (includes embedded tasks){{acceptanceCriteria}}- Auto-formatted checkbox list{{notes}}- Additional context{{dependsOn}}- Prerequisites
Context Variables:
{{codebasePatterns}}- Discovered patterns (optional)
DEPRECATED (should NOT be in template):
{{recentProgress}}- Agent reads.ralph-tui/progress.mddirectly as first action
3.3 Template Quality Check (Optimized v2)
Verify template includes all critical elements:
Structure Checks:
- Template does NOT include
{{recentProgress}}(agent reads file directly - this is redundant) - Template includes
{{currentIteration}}in header for tracking - Template has explicit "Context Files (Read These First)" section with:
- Path to
.ralph-tui/progress.md - Instruction to find
PRD.mdin same directory asprd.json
- Path to
Workflow Checks:
- Template includes 3-phase workflow: Context Gathering → Implementation → Documentation
- Phase 3 includes gibberish cleanup instructions (remove JSON fragments, malformed entries)
- Template defines verbose progress entry format with sections:
- "What was implemented" (detailed descriptions)
- "Files changed" (paths with descriptions)
- "Learnings" (patterns, gotchas, architecture insights)
- "Quality gate" (command output, test results)
Rules Checks:
- Template says "Be verbose and thorough - future iterations start with no memory"
- Template instructs to delete malformed entries (JSON fragments,
"type":"message", gibberish) - Completion signals (COMPLETE, BLOCKED, SKIP, EJECT)
- Loop awareness (starts fresh each iteration, must read progress.md)
Context References:
- Reference to CLAUDE.md for project commands/conventions
- Reference to progress.md for iteration context
- Reference to PRD.md for full project goals
3.4 Template Anti-Pattern Detection
Flag these issues if found:
| Issue | Problem | Fix |
|---|---|---|
{{recentProgress}} in template |
Redundant - agent reads file directly | Remove the section |
No {{currentIteration}} |
Can't track which iteration in logs | Add to header |
| No gibberish cleanup instruction | JSON fragments accumulate in progress.md | Add Phase 3 step 7 |
| Simple progress format | Future iterations lack context | Use verbose 4-section format |
| No "start with no memory" warning | Agent may not document thoroughly | Add to rules section |
Phase 4: PRD Validation
4.1 Discover prd.json
Search for prd.json files:
find . -name "prd.json" -not -path "*/node_modules/*" 2>/dev/null
If multiple found, ask user to select. If none found, report and exit.
4.2 Validate prd.json Structure
Read the prd.json and verify required fields:
{
"name": "required - kebab-case",
"description": "required - project context",
"branchName": "required - git branch name",
"userStories": [
{
"id": "required - e.g., US-001",
"title": "required - short title",
"description": "required - what and why",
"acceptanceCriteria": "required - array of strings",
"dependsOn": "optional - array of story IDs",
"notes": "optional - additional context",
"passes": "required - boolean, should be false initially"
}
]
}
4.3 Template Variable Mapping
Verify prd.json fields will map correctly to template:
| prd.json Field | Template Variable | Status |
|---|---|---|
name |
{{prdName}} |
Check |
description |
{{prdDescription}} |
Check |
userStories[].id |
{{taskId}} |
Check |
userStories[].title |
{{taskTitle}} |
Check |
userStories[].description |
{{taskDescription}} |
Check |
userStories[].acceptanceCriteria |
{{acceptanceCriteria}} |
Check |
userStories[].notes |
{{notes}} |
Check |
userStories[].dependsOn |
{{dependsOn}} |
Check |
4.4 Tasks in Description Check
Verify each story's description includes embedded tasks:
**Tasks:**
1. First task
2. Second task
WARNING: Tasks are NOT a separate field - they must be in the description.
4.5 Acceptance Criteria Format
Verify acceptanceCriteria is an array of strings (Ralph auto-converts to checkboxes).
Phase 5: Project Context Validation
5.1 Local CLAUDE.md Check
if [ -f CLAUDE.md ]; then
echo "OK: Local CLAUDE.md found"
# Check it has key sections
grep -l "Commands\|Development\|Project" CLAUDE.md
else
echo "WARNING: No local CLAUDE.md - Ralph will rely on global context"
fi
5.2 PRD.md Discovery
Check for human-readable PRD document:
find . -name "PRD.md" -o -name "prd.md" | head -5
If found, note the path for the prompt template enhancement.
5.3 Progress.md Path
Verify progress file path from config:
grep "progressFile" .ralph-tui/config.toml
# Default: .ralph-tui/progress.md
Phase 6: Pre-Launch Summary
6.1 Generate Report
Present a clear summary:
═══════════════════════════════════════════════════════════════════════════
Ralph TUI Pre-Flight Check Results
═══════════════════════════════════════════════════════════════════════════
Environment
├── Global CLAUDE.md: ✗ Not found (good) / ⚠ Found (may conflict)
├── Ralph TUI: ✓ v0.x.x installed
├── tmux: ✓ v3.x installed
├── git: ✓ v2.x installed
└── Existing State: ✓ Clean / ⚠ Previous run detected (action taken)
Existing State Details (if found)
├── progress.md: [X lines] / Empty
├── iterations/: [X files] / Empty
├── state.json: Found / Not found
└── Lock file: ⚠ Running / Not found
Configuration (.ralph-tui/config.toml)
├── Tracker: json ✓
├── Agent: claude ✓
├── Model: opus ✓
├── Max Iterations: 70 ✓
├── Template Path: .ralph-tui/templates/prompt.hbs ✓
└── PRD Path: [discovered path] ✓
Template (.ralph-tui/templates/prompt.hbs)
├── File exists: ✓
├── PRD variables: ✓
├── Task variables: ✓
├── Context variables: ✓
├── Workflow section: ✓
└── Completion signals: ✓
PRD (docs/prds/[name]/prd.json)
├── Name: [prd-name] ✓
├── Branch: [branch-name] ✓
├── Stories: [count] stories ✓
├── All have IDs: ✓
├── All have descriptions: ✓
├── All have acceptance criteria: ✓
└── Tasks embedded in descriptions: ✓
Project Context
├── Local CLAUDE.md: ✓ Found
├── PRD.md: ✓ Found at [path]
└── Progress tracking: .ralph-tui/progress.md (clean)
═══════════════════════════════════════════════════════════════════════════
6.2 Issues Found
If any issues were found, list them with severity:
Issues Found:
├── [CRITICAL] Global CLAUDE.md may override local context
├── [CRITICAL] Existing Ralph state - may confuse model with old progress
├── [CRITICAL] Lock file present - Ralph may already be running
├── [WARNING] Story US-003 missing tasks in description
└── [INFO] Model set to sonnet, opus recommended for complex work
Phase 7: Launch Options
7.1 Worktree vs Branch Question
AskUserQuestion: "How do you want to run this Ralph loop?"
├── "Branch only" - Create/switch to feature branch in current directory
├── "Worktree" - Create isolated worktree for parallel development
└── "Already set up" - Skip branch/worktree setup
7.2 Branch Setup (if selected)
# Determine base branch
git branch --show-current
# Create and checkout feature branch
git checkout -b [branchName-from-prd]
7.3 Worktree Setup (if selected)
# Get repo name and PRD name
REPO_NAME=$(basename $(git rev-parse --show-toplevel))
PRD_NAME=[name-from-prd]
# Create worktree
git worktree add ../${REPO_NAME}-${PRD_NAME} -b [branchName-from-prd]
# Show next steps
echo "Worktree created at: ../${REPO_NAME}-${PRD_NAME}"
echo "cd ../${REPO_NAME}-${PRD_NAME}"
7.4 Generate Launch Commands
Provide ready-to-copy commands:
═══════════════════════════════════════════════════════════════════════════
Launch Commands
═══════════════════════════════════════════════════════════════════════════
Option 1: Run in new tmux session (recommended)
───────────────────────────────────────────────────────────────────────────
tmux new-session -d -s ralph-[prd-name] "ralph-tui run --prd [prd-path]"
tmux attach-session -t ralph-[prd-name]
# Press 's' to start, then Ctrl+B D to detach
Option 2: Run directly (stays in foreground)
───────────────────────────────────────────────────────────────────────────
ralph-tui run --prd [prd-path]
Option 3: Run with verification (recommended first time)
───────────────────────────────────────────────────────────────────────────
ralph-tui run --prd [prd-path] --verify
Monitoring:
───────────────────────────────────────────────────────────────────────────
# Check progress
cat .ralph-tui/progress.md
# View iteration logs
ralph-tui logs
# Check session status
ralph-tui status
# Reattach to tmux
tmux attach-session -t ralph-[prd-name]
═══════════════════════════════════════════════════════════════════════════
Quick Reference
Template Variables from Ralph TUI
| Variable | Source | Description |
|---|---|---|
{{prdName}} |
prd.json name |
Project name |
{{prdDescription}} |
prd.json description |
Project context |
{{prdCompletedCount}} |
Calculated | Completed stories |
{{prdTotalCount}} |
Calculated | Total stories |
{{currentIteration}} |
Calculated | Current iteration number |
{{taskId}} |
userStories[].id |
Current story ID |
{{taskTitle}} |
userStories[].title |
Current story title |
{{taskDescription}} |
userStories[].description |
Story description (includes tasks) |
{{acceptanceCriteria}} |
userStories[].acceptanceCriteria |
Auto-formatted checkboxes |
{{notes}} |
userStories[].notes |
Additional context |
{{dependsOn}} |
userStories[].dependsOn |
Prerequisites |
{{codebasePatterns}} |
.ralph-tui/progress.md |
Discovered patterns |
DEPRECATED - Do NOT use:
| Variable | Reason |
|---|---|
{{recentProgress}} |
Redundant - agent reads .ralph-tui/progress.md directly as first action every iteration |
Common Issues
| Issue | Solution |
|---|---|
| Global CLAUDE.md overrides local | Rename ~/.claude/CLAUDE.md to .bak |
| Existing state from previous run | Clean iterations/, progress.md, state.json OR use worktree |
| Lock file present | Another Ralph may be running; check tmux sessions |
| Template not loading | Check prompt_template path in config.toml |
| Tasks not showing | Embed tasks in description field, not separate |
| acceptanceCriteria empty | Ensure it's an array of strings |
| Progress corrupted | Check .ralph-tui.lock, use ralph-tui resume |
| Model confused by old progress | Clean progress.md before starting new PRD |
| Gibberish/JSON in progress.md | Template should include cleanup instructions in Phase 3 |
| Duplicate progress entries | Ralph auto-appends + agent appends; use cleanup instructions |
Template uses {{recentProgress}} |
Remove it - agent reads file directly (redundant) |
Missing {{currentIteration}} |
Add to header for iteration tracking |
| Sparse progress notes | Use verbose 4-section format; add "no memory" warning |
Ralph TUI Commands
ralph-tui template show # Show current template
ralph-tui doctor # Diagnose issues
ralph-tui config show # Show merged config
ralph-tui status # Check session status
ralph-tui resume # Resume interrupted session
ralph-tui logs # View iteration logs
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
sprint-protocol
vercel-react-best-practices
React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.
agent-browser
Use Agent Browser CLI for headless browser automation and E2E testing. Invoke when user needs to automate browser tasks, run E2E tests, capture screenshots, interact with web pages, or perform web scraping tasks.
prd
Create self-verifying PRDs for autonomous execution. Interviews users to gather requirements, then generates structured prd.json with phased implementation and appropriate testing strategies. Supports 7 task categories with type-specific workflows. Use when user says "create a prd", "prd for", "plan a feature", "plan this", "write prd", or wants to plan any multi-step implementation work.
setup-claude
Interactive Claude Code repository setup and optimization. Configures the complete ecosystem - skills, commands, subagents, hooks, rules, MCPs, and plugins. Invoke with /setup-claude init or /setup-claude audit.
sprint-protocol
Didn't find tool you were looking for?