Ralph Run the autonomous loop to execute features from directory. Usage Process Run the loop script in background mode: Use to prevent timeout. After starting, tell the user to check progress with . What It Does 1. Shows dependency graph, finds next available project 2. Creates git worktree at 3. For each iteration: - Picks first story where - Implements it, runs quality checks - Commits: - Updates JSON, syncs back to main repo 4. When all stories pass, outputs Dependencies Ralph reads from each PRD and enforces ordering: Projects with incomplete dependencies are blocked. Ralph picks the firs…

\\n'\n done\n\n choice=$(claude -p \"Pick ONE project to work on next. Reply with just the project name, nothing else.\n\nReady projects:\n$project_info\" 2>/dev/null | tr -d '[:space:]')\n\n # Validate choice is in ready list\n for proj in \"${ready_projects[@]}\"; do\n if [ \"$proj\" = \"$choice\" ]; then\n echo \"$choice\"\n return 0\n fi\n done\n\n # Fallback to first if invalid response\n echo \"${ready_projects[0]}\"\n return 0\n fi\n}\n\n# Show dependency graph\nshow_dependency_graph() {\n echo \"Dependency Graph:\"\n echo \"─────────────────\"\n for json_file in $(ls \"$PRDS_DIR\"/*.json 2>/dev/null | sort); do\n [ -f \"$json_file\" ] || continue\n local name=$(basename \"$json_file\" .json)\n local deps=$(jq -r '.dependsOn // [] | join(\", \")' \"$json_file\")\n local status=\"pending\"\n\n if is_project_complete \"$json_file\"; then\n status=\"✓ complete\"\n elif are_dependencies_complete \"$json_file\"; then\n status=\"ready\"\n else\n status=\"blocked\"\n fi\n\n if [ -n \"$deps\" ]; then\n echo \" $name [$status] → depends on: $deps\"\n else\n echo \" $name [$status] → (no dependencies)\"\n fi\n done\n echo \"\"\n}\n\necho \"Using PRD directory: $PRDS_DIR\"\n\n# Show dependency graph\nshow_dependency_graph\n\n# Find project to work on\nPROJECT=$(find_next_project) || exit 1\nPRD_FILE=\"$PRDS_DIR/$PROJECT.json\"\nBRANCH_NAME=$(jq -r '.branchName' \"$PRD_FILE\")\n\necho \"Project: $PROJECT\"\necho \"Branch: $BRANCH_NAME\"\necho \"Max iterations: $MAX_ITERATIONS\"\n\n# Setup worktree\nWORKTREE_PATH=\"$MAIN_REPO/../$REPO_NAME-$PROJECT\"\n\nif [ ! -d \"$WORKTREE_PATH\" ]; then\n echo \"Creating worktree at $WORKTREE_PATH...\"\n\n # Create branch if it doesn't exist\n if ! git show-ref --verify --quiet \"refs/heads/$BRANCH_NAME\"; then\n git branch \"$BRANCH_NAME\" main\n fi\n\n git worktree add \"$WORKTREE_PATH\" \"$BRANCH_NAME\"\nelse\n echo \"Using existing worktree at $WORKTREE_PATH\"\nfi\n\n# Copy PRD to worktree (as prd.json for the agent to find)\ncp \"$PRD_FILE\" \"$WORKTREE_PATH/prd.json\"\n\n# Set status to in_progress\njq '.status = \"in_progress\"' \"$WORKTREE_PATH/prd.json\" > \"$WORKTREE_PATH/prd.json.tmp\" && mv \"$WORKTREE_PATH/prd.json.tmp\" \"$WORKTREE_PATH/prd.json\"\ncp \"$WORKTREE_PATH/prd.json\" \"$PRD_FILE\"\n\n# Use progress file in worktree (each project has its own)\nWORKTREE_PROGRESS=\"$WORKTREE_PATH/.ralph-progress.txt\"\nif [ ! -f \"$WORKTREE_PROGRESS\" ]; then\n echo \"# Ralph Progress Log\" > \"$WORKTREE_PROGRESS\"\n echo \"Started: $(date)\" >> \"$WORKTREE_PROGRESS\"\n echo \"Project: $PROJECT\" >> \"$WORKTREE_PROGRESS\"\n echo \"Branch: $BRANCH_NAME\" >> \"$WORKTREE_PROGRESS\"\n echo \"---\" >> \"$WORKTREE_PROGRESS\"\nfi\n\n# Main loop - keeps going until all PRDs are complete\nwhile true; do\n echo \"\"\n echo \"Starting Ralph in worktree: $WORKTREE_PATH\"\n echo \"═══════════════════════════════════════════════════════\"\n\n cd \"$WORKTREE_PATH\"\n\n for i in $(seq 1 $MAX_ITERATIONS); do\n echo \"\"\n echo \"═══════════════════════════════════════════════════════\"\n echo \" Ralph Iteration $i of $MAX_ITERATIONS\"\n echo \" Project: $PROJECT\"\n echo \"═══════════════════════════════════════════════════════\"\n\n # Run claude with the ralph prompt\n OUTPUT=$(claude --dangerously-skip-permissions -p \"$(cat \"$SCRIPT_DIR/references/prompt.md\")\" 2>&1 | tee /dev/stderr) || true\n\n # Sync prd.json back to main repo\n if [ -f \"$WORKTREE_PATH/prd.json\" ]; then\n cp \"$WORKTREE_PATH/prd.json\" \"$PRD_FILE\"\n fi\n\n # Check for completion signal\n if echo \"$OUTPUT\" | grep -q \"\u003cpromise>COMPLETE\u003c/promise>\"; then\n echo \"\"\n echo \"═══════════════════════════════════════════════════════\"\n echo \" Ralph completed all tasks for $PROJECT!\"\n echo \" Completed at iteration $i of $MAX_ITERATIONS\"\n echo \"═══════════════════════════════════════════════════════\"\n echo \"\"\n\n # Push and create PR\n echo \"Pushing branch and creating PR...\"\n git push -u origin \"$BRANCH_NAME\"\n\n # Generate PR body from PRD\n PR_TITLE=$(jq -r '.title // .projectName' \"$WORKTREE_PATH/prd.json\")\n PR_BODY=$(cat \u003c\u003cEOF\n## Summary\n$(jq -r '.description // \"Automated implementation by Ralph.\"' \"$WORKTREE_PATH/prd.json\")\n\n## Stories Completed\n$(jq -r '.userStories[] | \"- [x] \\(.title)\"' \"$WORKTREE_PATH/prd.json\")\n\n---\n🤖 Generated by Ralph\nEOF\n)\n\n gh pr create --title \"$PR_TITLE\" --body \"$PR_BODY\" || echo \"PR may already exist\"\n\n echo \"\"\n break # Exit inner loop, continue to next PRD\n fi\n\n echo \"Iteration $i complete. Continuing...\"\n sleep 2\n done\n\n # Check if we hit max iterations without completing\n if ! echo \"$OUTPUT\" | grep -q \"\u003cpromise>COMPLETE\u003c/promise>\"; then\n echo \"\"\n echo \"Ralph reached max iterations ($MAX_ITERATIONS) without completing.\"\n echo \"Project: $PROJECT\"\n echo \"Worktree: $WORKTREE_PATH\"\n echo \"Check $WORKTREE_PATH/.ralph-progress.txt for status.\"\n exit 1\n fi\n\n # Go back to main repo to find next project\n cd \"$MAIN_REPO\"\n\n echo \"\"\n echo \"Looking for next PRD...\"\n echo \"\"\n\n # Show updated dependency graph\n show_dependency_graph\n\n # Find next project\n PROJECT=$(find_next_project) || {\n echo \"\"\n echo \"═══════════════════════════════════════════════════════\"\n echo \" All PRDs complete! 🎉\"\n echo \"═══════════════════════════════════════════════════════\"\n exit 0\n }\n\n # Setup for next project\n PRD_FILE=\"$PRDS_DIR/$PROJECT.json\"\n BRANCH_NAME=$(jq -r '.branchName' \"$PRD_FILE\")\n\n echo \"Next project: $PROJECT\"\n echo \"Branch: $BRANCH_NAME\"\n\n # Setup worktree for next project\n WORKTREE_PATH=\"$MAIN_REPO/../$REPO_NAME-$PROJECT\"\n\n if [ ! -d \"$WORKTREE_PATH\" ]; then\n echo \"Creating worktree at $WORKTREE_PATH...\"\n\n if ! git show-ref --verify --quiet \"refs/heads/$BRANCH_NAME\"; then\n git branch \"$BRANCH_NAME\" main\n fi\n\n git worktree add \"$WORKTREE_PATH\" \"$BRANCH_NAME\"\n else\n echo \"Using existing worktree at $WORKTREE_PATH\"\n fi\n\n # Copy PRD to worktree\n cp \"$PRD_FILE\" \"$WORKTREE_PATH/prd.json\"\n\n # Set status to in_progress\n jq '.status = \"in_progress\"' \"$WORKTREE_PATH/prd.json\" > \"$WORKTREE_PATH/prd.json.tmp\" && mv \"$WORKTREE_PATH/prd.json.tmp\" \"$WORKTREE_PATH/prd.json\"\n cp \"$WORKTREE_PATH/prd.json\" \"$PRD_FILE\"\n\n # Initialize progress file if needed\n WORKTREE_PROGRESS=\"$WORKTREE_PATH/.ralph-progress.txt\"\n if [ ! -f \"$WORKTREE_PROGRESS\" ]; then\n echo \"# Ralph Progress Log\" > \"$WORKTREE_PROGRESS\"\n echo \"Started: $(date)\" >> \"$WORKTREE_PROGRESS\"\n echo \"Project: $PROJECT\" >> \"$WORKTREE_PROGRESS\"\n echo \"Branch: $BRANCH_NAME\" >> \"$WORKTREE_PROGRESS\"\n echo \"---\" >> \"$WORKTREE_PROGRESS\"\n fi\n\n sleep 2\ndone\n","content_type":"application/x-sh; charset=utf-8","language":"bash","size":11817,"content_sha256":"f576548c3ac7e25095ffd51706056b300c72a0421f011417cd0ccf572fb69452"},{"filename":"references/prompt.md","content":"# Ralph Agent Instructions\n\nYou are an autonomous coding agent working in a git worktree on a feature branch.\n\n## Your Task\n\n1. Read the PRD at `prd.json` (worktree root)\n2. Read the progress log at `.ralph-progress.txt` (check Codebase Patterns section first)\n3. You're already on the correct branch in this worktree\n4. Pick the **highest priority** user story where `passes: false`\n5. Implement that single user story\n6. Run quality checks (e.g., typecheck, lint, test - use whatever your project requires)\n7. Update AGENTS.md files if you discover reusable patterns (see below)\n8. If checks pass, commit ALL changes with message: `feat: [Story ID] - [Story Title]`\n9. Update the PRD to set `passes: true` for the completed story\n10. Append your progress to `.ralph-progress.txt`\n\n## Progress Report Format\n\nAPPEND to progress.txt (never replace, always append):\n```\n## [Date/Time] - [Story ID]\n- What was implemented\n- Files changed\n- **Learnings for future iterations:**\n - Patterns discovered (e.g., \"this codebase uses X for Y\")\n - Gotchas encountered (e.g., \"don't forget to update Z when changing W\")\n - Useful context (e.g., \"the evaluation panel is in component X\")\n---\n```\n\nThe learnings section is critical - it helps future iterations avoid repeating mistakes and understand the codebase better.\n\n## Consolidate Patterns\n\nIf you discover a **reusable pattern** that future iterations should know, add it to the `## Codebase Patterns` section at the TOP of `.ralph-progress.txt` (create it if it doesn't exist). This section should consolidate the most important learnings:\n\n```\n## Codebase Patterns\n- Example: Use `sql\u003cnumber>` template for aggregations\n- Example: Always use `IF NOT EXISTS` for migrations\n- Example: Export types from actions.ts for UI components\n```\n\nOnly add patterns that are **general and reusable**, not story-specific details.\n\n## Update AGENTS.md Files\n\nBefore committing, check if any edited files have learnings worth preserving in nearby AGENTS.md files:\n\n1. **Identify directories with edited files** - Look at which directories you modified\n2. **Check for existing AGENTS.md** - Look for AGENTS.md in those directories or parent directories\n3. **Add valuable learnings** - If you discovered something future developers/agents should know:\n - API patterns or conventions specific to that module\n - Gotchas or non-obvious requirements\n - Dependencies between files\n - Testing approaches for that area\n - Configuration or environment requirements\n\n**Examples of good AGENTS.md additions:**\n- \"When modifying X, also update Y to keep them in sync\"\n- \"This module uses pattern Z for all API calls\"\n- \"Tests require the dev server running on PORT 3000\"\n- \"Field names must match the template exactly\"\n\n**Do NOT add:**\n- Story-specific implementation details\n- Temporary debugging notes\n- Information already in progress.txt\n\nOnly update AGENTS.md if you have **genuinely reusable knowledge** that would help future work in that directory.\n\n## Quality Requirements\n\n- ALL commits must pass your project's quality checks (typecheck, lint, test)\n- Do NOT commit broken code\n- Keep changes focused and minimal\n- Follow existing code patterns\n\n## Stop Condition\n\nAfter completing a user story, check if ALL stories have `passes: true`.\n\nIf ALL stories are complete and passing:\n1. Update prd.json: set `status: \"done\"` and `completedAt` to current ISO timestamp\n2. Reply with: `\u003cpromise>COMPLETE\u003c/promise>`\n\nIf there are still stories with `passes: false`, end your response normally (another iteration will pick up the next story).\n\n## Important\n\n- Work on ONE story per iteration\n- Commit frequently\n- Keep CI green\n- Read the Codebase Patterns section in `.ralph-progress.txt` before starting\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":3741,"content_sha256":"2efdb831a595cda88a41cab820950c1bc39ac1cc251eaaaed05628921b844e0e"}],"content_json":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"text":"Ralph","type":"text"}]},{"type":"paragraph","content":[{"text":"Run the autonomous loop to execute features from ","type":"text"},{"text":"prds/","type":"text","marks":[{"type":"code_inline"}]},{"text":" directory.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Usage","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"/ralph # Run next available project (respects dependencies)\n/ralph 25 # Run with 25 iterations\n/ralph auth-flow # Run specific project","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Process","type":"text"}]},{"type":"paragraph","content":[{"text":"Run the loop script in background mode:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"~/.claude/skills/ralph/ralph.sh [iterations] [project-name]","type":"text"}]},{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"run_in_background: true","type":"text","marks":[{"type":"code_inline"}]},{"text":" to prevent timeout. After starting, tell the user to check progress with ","type":"text"},{"text":"tail -f \u003cworktree>/.ralph-progress.txt","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"What It Does","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Shows dependency graph, finds next available project","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Creates git worktree at ","type":"text"},{"text":"../{repo}-{feature}/","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"For each iteration:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Picks first story where ","type":"text"},{"text":"passes: false","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Implements it, runs quality checks","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Commits: ","type":"text"},{"text":"feat: [id] - [title]","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Updates JSON, syncs back to main repo","type":"text"}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"When all stories pass, outputs ","type":"text"},{"text":"\u003cpromise>COMPLETE\u003c/promise>","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Dependencies","type":"text"}]},{"type":"paragraph","content":[{"text":"Ralph reads ","type":"text"},{"text":"dependsOn","type":"text","marks":[{"type":"code_inline"}]},{"text":" from each PRD and enforces ordering:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"json"},"content":[{"text":"{\n \"projectName\": \"Dashboard\",\n \"dependsOn\": [\"auth-flow\", \"user-profile\"]\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"Projects with incomplete dependencies are blocked. Ralph picks the first ready project alphabetically.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Prerequisites","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"At least one ","type":"text"},{"text":".json","type":"text","marks":[{"type":"code_inline"}]},{"text":" PRD file in ","type":"text"},{"text":".claude/plans/","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"plans/","type":"text","marks":[{"type":"code_inline"}]},{"text":", or ","type":"text"},{"text":"prds/","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Use plan mode to create a plan, then run ","type":"text"},{"text":"/ralph-json-create-issues","type":"text","marks":[{"type":"code_inline"}]},{"text":" to convert it","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Notes","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Run multiple Ralphs in parallel on independent projects (separate terminals)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Each works in its own worktree, no conflicts","type":"text"}]}]}]},{"type":"hr","attrs":{"markup":"---"}}]},"metadata":{"date":"2026-06-05","name":"ralph-json-start-loop","author":"@skillopedia","source":{"stars":62,"repo_name":"agent-skills","origin_url":"https://github.com/richtabor/agent-skills/blob/HEAD/skills/ralph-json-start-loop/SKILL.md","repo_owner":"richtabor","body_sha256":"84fabe3d707d8fa0a8a3c29c1397110bf6d0b5db0649a92000140efd6e32d774","cluster_key":"374508bf0afa367f1365d786157f319e87f21e4be535200ab7e943130a03d2ea","clean_bundle":{"format":"clean-skill-bundle-v1","source":"richtabor/agent-skills/skills/ralph-json-start-loop/SKILL.md","attachments":[{"id":"a4d4a811-7878-5e1a-a071-85ddbf65e6c2","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/a4d4a811-7878-5e1a-a071-85ddbf65e6c2/attachment.sh","path":"ralph.sh","size":11817,"sha256":"f576548c3ac7e25095ffd51706056b300c72a0421f011417cd0ccf572fb69452","contentType":"application/x-sh; charset=utf-8"},{"id":"0ea39c2e-95c0-5e5a-b0e4-9765f8283ee0","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/0ea39c2e-95c0-5e5a-b0e4-9765f8283ee0/attachment.md","path":"references/prompt.md","size":3741,"sha256":"2efdb831a595cda88a41cab820950c1bc39ac1cc251eaaaed05628921b844e0e","contentType":"text/markdown; charset=utf-8"}],"bundle_sha256":"c26e9c42ae4953391961bf57265833b0d4efeb5eccf60bceaa8389c0b6e76c59","attachment_count":2,"text_attachments":2,"attachment_storage":"skillopedia-attachments-v1","binary_attachments":0,"excluded_attachments":[]},"cluster_size":1,"skill_md_path":"skills/ralph-json-start-loop/SKILL.md","import_metadata":{"date":"2026-06-05","author":"@skillopedia","version":"v1","category":"software-engineering","category_label":"Engineering"},"exact_dupes_collapsed_into_this":0},"version":"v1","category":"software-engineering","import_tag":"clean-skills-v1","description":"Runs the Ralph autonomous loop. Executes stories from prds/*.json using git worktrees.","argument-hint":"[iterations] [project-name]","disable-model-invocation":true}},"renderedAt":1782979740900}

Ralph Run the autonomous loop to execute features from directory. Usage Process Run the loop script in background mode: Use to prevent timeout. After starting, tell the user to check progress with . What It Does 1. Shows dependency graph, finds next available project 2. Creates git worktree at 3. For each iteration: - Picks first story where - Implements it, runs quality checks - Commits: - Updates JSON, syncs back to main repo 4. When all stories pass, outputs Dependencies Ralph reads from each PRD and enforces ordering: Projects with incomplete dependencies are blocked. Ralph picks the firs…