{
  "schemaVersion": "1.0",
  "item": {
    "slug": "ralph-loops",
    "name": "Ralph Loops",
    "source": "tencent",
    "type": "skill",
    "category": "AI 智能",
    "sourceUrl": "https://clawhub.ai/qlifebot-coder/ralph-loops",
    "canonicalUrl": "https://clawhub.ai/qlifebot-coder/ralph-loops",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/ralph-loops",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=ralph-loops",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "SETUP.md",
      "SKILL.md",
      "dashboard/lib/cost-calculator.mjs",
      "dashboard/lib/loop-detector.mjs",
      "dashboard/lib/ralph-reader.mjs",
      "dashboard/lib/transcript-reader.mjs"
    ],
    "primaryDoc": "SKILL.md",
    "quickSetup": [
      "Download the package from Yavira.",
      "Extract the archive and review SKILL.md first.",
      "Import or place the package into your OpenClaw setup."
    ],
    "agentAssist": {
      "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
      "steps": [
        "Download the package from Yavira.",
        "Extract it into a folder your agent can access.",
        "Paste one of the prompts below and point your agent at the extracted folder."
      ],
      "prompts": [
        {
          "label": "New install",
          "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete."
        },
        {
          "label": "Upgrade existing",
          "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-30T16:55:25.780Z",
      "expiresAt": "2026-05-07T16:55:25.780Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
        "contentDisposition": "attachment; filename=\"network-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/ralph-loops"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    },
    "downloadPageUrl": "https://openagent3.xyz/downloads/ralph-loops",
    "agentPageUrl": "https://openagent3.xyz/skills/ralph-loops/agent",
    "manifestUrl": "https://openagent3.xyz/skills/ralph-loops/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/ralph-loops/agent.md"
  },
  "agentAssist": {
    "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
    "steps": [
      "Download the package from Yavira.",
      "Extract it into a folder your agent can access.",
      "Paste one of the prompts below and point your agent at the extracted folder."
    ],
    "prompts": [
      {
        "label": "New install",
        "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete."
      },
      {
        "label": "Upgrade existing",
        "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "Ralph Loops Skill",
        "body": "First time? Read SETUP.md first to install dependencies and verify your setup.\n\nAutonomous AI agent loops for iterative development. Based on Geoffrey Huntley's Ralph Wiggum technique, as documented by Clayton Farr.\n\nScript: skills/ralph-loops/scripts/ralph-loop.mjs\nDashboard: skills/ralph-loops/dashboard/ (run with node server.mjs)\nTemplates: skills/ralph-loops/templates/\nArchive: ~/clawd/logs/ralph-archive/"
      },
      {
        "title": "Claude Code Version Compatibility",
        "body": "Claude Code 2.1.29 has a critical bug that spawns orphaned sub-agents consuming 99% CPU. Iterations fail with \"exit code null\" on first run.\n\nFix: Downgrade to 2.1.25:\n\nnpm install -g @anthropic-ai/claude-code@2.1.25\n\nVerify:\n\nclaude --version  # Should show 2.1.25\n\nThis was discovered 2026-02-01. Check if newer versions fix the issue before upgrading."
      },
      {
        "title": "⚠️ Don't Block the Conversation!",
        "body": "When running a Ralph loop, don't monitor it synchronously. The loop runs as a separate Claude CLI process — you can keep chatting.\n\n❌ Wrong (blocks conversation):\n\nStart loop → sleep 60 → poll → sleep 60 → poll → ... (6 minutes of silence)\n\n✅ Right (stays responsive):\n\nStart loop → \"It's running, I'll check periodically\" → keep chatting → check on heartbeats\n\nHow to monitor without blocking:\n\nStart the loop with node ralph-loop.mjs ... (runs in background)\nTell human: \"Loop running. I'll check progress periodically or you can ask.\"\nCheck via process poll <sessionId> when asked or during heartbeats\nUse the dashboard at http://localhost:3939 for real-time visibility\n\nThe loop is autonomous — that's the whole point. Don't babysit it at the cost of ignoring your human."
      },
      {
        "title": "Trigger Phrases",
        "body": "When human says:\n\nPhraseAction\"Interview me about system X\"Start Phase 1 requirements interview\"Start planning system X\"Run ./loop.sh plan (needs specs first)\"Start building system X\"Run ./loop.sh build (needs plan first)\"Ralph loop over X\"ASK which phase (see below)"
      },
      {
        "title": "When Human Says \"Ralph Loop\" — Clarify the Phase!",
        "body": "Don't assume which phase. Ask:\n\n\"Which type of Ralph loop are we doing?\n1️⃣ Interview — I'll ask you questions to build specs (Phase 1)\n2️⃣ Planning — I'll iterate on an implementation plan (Phase 2)\n3️⃣ Building — I'll implement from a plan, one task per iteration (Phase 3)\n4️⃣ Generic — Simple iterative refinement on a single topic\"\n\nThen proceed based on their answer:\n\nChoiceActionInterviewUse templates/requirements-interview.md protocolPlanningNeed specs first → run planning loop with PROMPT_plan.mdBuildingNeed plan first → run build loop with PROMPT_build.mdGenericCreate prompt file, run ralph-loop.mjs directly"
      },
      {
        "title": "Generic Ralph Loop Flow (Phase 4)",
        "body": "For simple iterative refinement (not full system builds):\n\nClarify the task — What exactly should be improved/refined?\nCreate a prompt file — Save to /tmp/ralph-prompt-<task>.md\nSet completion criteria — What signals \"done\"?\nRun the loop:\nnode skills/ralph-loops/scripts/ralph-loop.mjs \\\n  --prompt \"/tmp/ralph-prompt-<task>.md\" \\\n  --model opus \\\n  --max 10 \\\n  --done \"RALPH_DONE\"\n\n\nOr spawn as sub-agent for long-running tasks"
      },
      {
        "title": "Core Philosophy",
        "body": "\"Human roles shift from 'telling the agent what to do' to 'engineering conditions where good outcomes emerge naturally through iteration.\"\n— Clayton Farr\n\nThree principles drive everything:\n\nContext is scarce — With ~176K usable tokens from a 200K window, keep each iteration lean\nPlans are disposable — A drifting plan is cheaper to regenerate than salvage\nBackpressure beats direction — Engineer environments where wrong outputs get rejected automatically"
      },
      {
        "title": "Three-Phase Workflow",
        "body": "┌─────────────────────────────────────────────────────────────────────┐\n│  Phase 1: REQUIREMENTS                                              │\n│  Human + LLM conversation → JTBD → Topics → specs/*.md              │\n├─────────────────────────────────────────────────────────────────────┤\n│  Phase 2: PLANNING                                                  │\n│  Gap analysis (specs vs code) → IMPLEMENTATION_PLAN.md              │\n├─────────────────────────────────────────────────────────────────────┤\n│  Phase 3: BUILDING                                                  │\n│  One task per iteration → fresh context → backpressure → commit     │\n└─────────────────────────────────────────────────────────────────────┘"
      },
      {
        "title": "Phase 1: Requirements (Talk to Human)",
        "body": "Goal: Understand what to build BEFORE building it.\n\nThis is the most important phase. Use structured conversation to:\n\nIdentify Jobs to Be Done (JTBD)\n\nWhat user need or outcome are we solving?\nNot features — outcomes\n\n\n\nBreak JTBD into Topics of Concern\n\nEach topic = one distinct aspect/component\nUse the \"one sentence without 'and'\" test\n✓ \"The color extraction system analyzes images to identify dominant colors\"\n✗ \"The user system handles authentication, profiles, and billing\" → 3 topics\n\n\n\nCreate Specs for Each Topic\n\nOne markdown file per topic in specs/\nCapture requirements, acceptance criteria, edge cases\n\nTemplate: templates/requirements-interview.md"
      },
      {
        "title": "Phase 2: Planning (Gap Analysis)",
        "body": "Goal: Create a prioritized task list without implementing anything.\n\nUses PROMPT_plan.md in the loop:\n\nStudy all specs\nStudy existing codebase\nCompare specs vs code (gap analysis)\nGenerate IMPLEMENTATION_PLAN.md with prioritized tasks\nNO implementation — planning only\n\nUsually completes in 1-2 iterations."
      },
      {
        "title": "Phase 3: Building (One Task Per Iteration)",
        "body": "Goal: Implement tasks one at a time with fresh context.\n\nUses PROMPT_build.md in the loop:\n\nRead IMPLEMENTATION_PLAN.md\nPick the most important task\nInvestigate codebase (don't assume not implemented)\nImplement\nRun validation (backpressure)\nUpdate plan, commit\nExit → fresh context → next iteration\n\nKey insight: One task per iteration keeps context lean. The agent stays in the \"smart zone\" instead of accumulating cruft.\n\nWhy fresh context matters:\n\nNo accumulated mistakes — Each iteration starts clean; previous errors don't compound\nFull context budget — 200K tokens for THIS task, not shared with finished work\nReduced hallucination — Shorter contexts = more grounded responses\nNatural checkpoints — Each commit is a save point; easy to revert single iterations"
      },
      {
        "title": "File Structure",
        "body": "project/\n├── loop.sh                    # Ralph loop script\n├── PROMPT_plan.md             # Planning mode instructions\n├── PROMPT_build.md            # Building mode instructions  \n├── AGENTS.md                  # Operational guide (~60 lines max)\n├── IMPLEMENTATION_PLAN.md     # Prioritized task list (generated)\n└── specs/                     # Requirement specs\n    ├── topic-a.md\n    ├── topic-b.md\n    └── ..."
      },
      {
        "title": "File Purposes",
        "body": "FilePurposeWho Createsspecs/*.mdSource of truth for requirementsHuman + Phase 1PROMPT_plan.mdInstructions for planning modeCopy from templatePROMPT_build.mdInstructions for building modeCopy from templateAGENTS.mdBuild/test/lint commandsHuman + RalphIMPLEMENTATION_PLAN.mdTask list with prioritiesRalph (Phase 2)"
      },
      {
        "title": "Project Organization (Systems)",
        "body": "For Clawdbot systems, each Ralph project lives in <workspace>/systems/<name>/:\n\nsystems/\n├── health-tracker/           # Example system\n│   ├── specs/\n│   │   ├── daily-tracking.md\n│   │   └── test-scheduling.md\n│   ├── PROMPT_plan.md\n│   ├── PROMPT_build.md\n│   ├── AGENTS.md\n│   ├── IMPLEMENTATION_PLAN.md  # ← exists = past Phase 1\n│   └── src/\n└── activity-planner/\n    ├── specs/                  # ← empty = still in Phase 1\n    └── ..."
      },
      {
        "title": "Phase Detection (Auto)",
        "body": "Detect current phase by checking what files exist:\n\nWhat ExistsCurrent PhaseNext ActionNothing / empty specs/Phase 1: RequirementsRun requirements interviewspecs/*.md but no IMPLEMENTATION_PLAN.mdReady for Phase 2Run ./loop.sh planspecs/*.md + IMPLEMENTATION_PLAN.mdPhase 2 or 3Review plan, run ./loop.sh buildPlan shows all tasks completeDoneArchive or iterate\n\nQuick check:\n\n# What phase are we in?\n[ -z \"$(ls specs/ 2>/dev/null)\" ] && echo \"Phase 1: Need specs\" && exit\n[ ! -f IMPLEMENTATION_PLAN.md ] && echo \"Phase 2: Need plan\" && exit\necho \"Phase 3: Ready to build (or done)\""
      },
      {
        "title": "JTBD Breakdown",
        "body": "The hierarchy matters:\n\nJTBD (Job to Be Done)\n└── Topic of Concern (1 per spec file)\n    └── Tasks (many per topic, in IMPLEMENTATION_PLAN.md)\n\nExample:\n\nJTBD: \"Help designers create mood boards\"\nTopics:\n\nImage collection → specs/image-collection.md\nColor extraction → specs/color-extraction.md\nLayout system → specs/layout-system.md\nSharing → specs/sharing.md\n\n\nTasks: Each spec generates multiple implementation tasks"
      },
      {
        "title": "Topic Scope Test",
        "body": "Can you describe the topic in one sentence without \"and\"?\n\nIf you need \"and\" or \"also\", it's probably multiple topics. Split it.\n\nWhen to split:\n\nMultiple verbs in the description → separate topics\nDifferent user personas involved → separate topics\nCould be implemented by different teams → separate topics\nHas its own failure modes → probably its own topic\n\nExample split:\n\n❌ \"User management handles registration, authentication, profiles, and permissions\"\n\n✅ Split into:\n   - \"Registration creates new user accounts from email/password\"\n   - \"Authentication verifies user identity via login flow\"  \n   - \"Profiles let users view and edit their information\"\n   - \"Permissions control what actions users can perform\"\n\nCounter-example (don't split):\n\n✅ Keep together:\n   \"Color extraction analyzes images and returns dominant color palettes\"\n   \n   Why: \"analyzes\" and \"returns\" are steps in one operation, not separate concerns."
      },
      {
        "title": "Backpressure Mechanisms",
        "body": "Autonomous loops converge when wrong outputs get rejected. Three layers:"
      },
      {
        "title": "1. Downstream Gates (Hard)",
        "body": "Tests, type-checking, linting, build validation. Deterministic.\n\n# In AGENTS.md\n## Validation\n- Tests: `npm test`\n- Typecheck: `npm run typecheck`\n- Lint: `npm run lint`"
      },
      {
        "title": "2. Upstream Steering (Soft)",
        "body": "Existing code patterns guide the agent. It discovers conventions through exploration."
      },
      {
        "title": "3. LLM-as-Judge (Subjective)",
        "body": "For subjective criteria (tone, UX, aesthetics), use another LLM call with binary pass/fail.\n\nStart with hard gates. Add LLM-as-judge for subjective criteria only after mechanical backpressure works."
      },
      {
        "title": "Prompt Structure",
        "body": "Geoffrey's prompts follow a numbered pattern:\n\nSectionPurpose0a-0dOrient: Study specs, source, current plan1-4Main instructions: What to do this iteration999+Guardrails: Invariants (higher number = more critical)"
      },
      {
        "title": "The Numbered Guardrails Pattern",
        "body": "Guardrails use escalating numbers (99999, 999999, 9999999...) to signal priority:\n\n99999. Important: Capture the why in documentation.\n\n999999. Important: Single sources of truth, no migrations.\n\n9999999. Create git tags after successful builds.\n\n99999999. Add logging if needed to debug.\n\n999999999. Keep IMPLEMENTATION_PLAN.md current.\n\nWhy this works:\n\nVisual prominence — Large numbers stand out, harder to skip\nImplicit priority — More 9s = more critical (like DEFCON levels in reverse)\nNo collisions — Sparse numbering lets you insert new rules without renumbering\nMnemonic — Claude treats these as invariants, not suggestions\n\nThe \"Important:\" prefix is deliberate — it triggers Claude's attention."
      },
      {
        "title": "Key Language Patterns",
        "body": "Use Geoffrey's specific phrasing — it matters:\n\n\"study\" (not \"read\" or \"look at\")\n\"don't assume not implemented\" (critical!)\n\"using parallel subagents\" / \"up to N subagents\"\n\"only 1 subagent for build/tests\" (backpressure control)\n\"Ultrathink\" (deep reasoning trigger)\n\"capture the why\"\n\"keep it up to date\"\n\"resolve them or document them\""
      },
      {
        "title": "1. Set Up Project Structure",
        "body": "mkdir -p myproject/specs\ncd myproject\ngit init  # Ralph expects git for commits\n\n# Copy templates\ncp .//templates/PROMPT_plan.md .\ncp .//templates/PROMPT_build.md .\ncp .//templates/AGENTS.md .\ncp .//templates/loop.sh .\nchmod +x loop.sh"
      },
      {
        "title": "2. Customize Templates (Required!)",
        "body": "PROMPT_plan.md — Replace [PROJECT_GOAL] with your actual goal:\n\n# Before:\nULTIMATE GOAL: We want to achieve [PROJECT_GOAL].\n\n# After:\nULTIMATE GOAL: We want to achieve a fully functional mood board app with image upload and color extraction.\n\nPROMPT_build.md — Adjust source paths if not using src/:\n\n# Before:\n0c. For reference, the application source code is in `src/*`.\n\n# After:\n0c. For reference, the application source code is in `lib/*`.\n\nAGENTS.md — Update build/test/lint commands for your stack."
      },
      {
        "title": "3. Phase 1: Requirements Gathering (Don't Skip!)",
        "body": "This phase happens WITH the human. Use the interview template:\n\ncat .//templates/requirements-interview.md\n\nThe workflow:\n\nDiscuss the JTBD (Job to Be Done) — outcomes, not features\nBreak into Topics of Concern (each passes the \"one sentence\" test)\nWrite a spec file for each topic: specs/topic-name.md\nHuman reviews and approves specs\n\nExample output:\n\nspecs/\n├── image-collection.md\n├── color-extraction.md\n├── layout-system.md\n└── sharing.md"
      },
      {
        "title": "4. Phase 2: Planning",
        "body": "./loop.sh plan\n\nWait for IMPLEMENTATION_PLAN.md to be generated (usually 1-2 iterations). Review it — this is your task list."
      },
      {
        "title": "5. Phase 3: Building",
        "body": "./loop.sh build 20  # Max 20 iterations\n\nWatch it work. Add backpressure (tests, lints) as patterns emerge. Check commits for progress."
      },
      {
        "title": "Loop Script Options",
        "body": "./loop.sh              # Build mode, unlimited\n./loop.sh 20           # Build mode, max 20 iterations\n./loop.sh plan         # Plan mode, unlimited\n./loop.sh plan 5       # Plan mode, max 5 iterations\n\nOr use the Node.js wrapper for more control:\n\nnode skills/ralph-loops/scripts/ralph-loop.mjs \\\n  --prompt \"./PROMPT_build.md\" \\\n  --model opus \\\n  --max 20 \\\n  --done \"RALPH_DONE\""
      },
      {
        "title": "When to Regenerate the Plan",
        "body": "Plans drift. Regenerate when:\n\nRalph is going off track (implementing wrong things)\nPlan feels stale or doesn't match current state\nToo much clutter from completed items\nYou've made significant spec changes\nYou're confused about what's actually done\n\nJust switch back to planning mode:\n\n./loop.sh plan\n\nRegeneration cost is one Planning loop. Cheap compared to Ralph going in circles."
      },
      {
        "title": "Safety",
        "body": "Ralph requires --dangerously-skip-permissions to run autonomously. This bypasses Claude's permission system entirely.\n\nPhilosophy: \"It's not if it gets popped, it's when. And what is the blast radius?\"\n\nProtections:\n\nRun in isolated environments (Docker, VM)\nOnly the API keys needed for the task\nNo access to private data beyond requirements\nRestrict network connectivity where possible\nEscape hatches: Ctrl+C stops the loop; git reset --hard reverts uncommitted changes"
      },
      {
        "title": "Cost Expectations",
        "body": "Task TypeModelIterationsEst. CostGenerate planOpus1-2$0.50-1.00Implement simple featureOpus3-5$1.00-2.00Implement complex featureOpus10-20$3.00-8.00Full project buildoutOpus50+$15-50+\n\nTip: Use Sonnet for simpler tasks where plan is clear. Use Opus for planning and complex reasoning."
      },
      {
        "title": "Real-World Results",
        "body": "From Geoffrey Huntley:\n\n6 repos generated overnight at YC hackathon\n$50k contract completed for $297 in API costs\nCreated entire programming language over 3 months"
      },
      {
        "title": "Advanced: Running as Sub-Agent",
        "body": "For long loops, spawn as sub-agent so main session stays responsive:\n\nsessions_spawn({\n  task: `cd /path/to/project && ./loop.sh build 20\n         \nSummarize what was implemented when done.`,\n  label: \"ralph-build\",\n  model: \"opus\"\n})\n\nCheck progress:\n\nsessions_list({ kinds: [\"spawn\"] })\nsessions_history({ label: \"ralph-build\", limit: 5 })"
      },
      {
        "title": "Ralph keeps implementing the same thing",
        "body": "Plan is stale → regenerate with ./loop.sh plan\nBackpressure missing → add tests that catch duplicates"
      },
      {
        "title": "Ralph goes in circles",
        "body": "Add more specific guardrails to prompts\nCheck if specs are ambiguous\nRegenerate plan"
      },
      {
        "title": "Context getting bloated",
        "body": "Ensure one task per iteration (check prompt)\nKeep AGENTS.md under 60 lines\nMove status/progress to IMPLEMENTATION_PLAN.md, not AGENTS.md"
      },
      {
        "title": "Tests not running",
        "body": "Check AGENTS.md has correct validation commands\nEnsure backpressure section in prompt references AGENTS.md"
      },
      {
        "title": "Projects Without Git",
        "body": "The loop script expects git for commits and pushes. For projects without version control:\n\nOption 1: Initialize git anyway (recommended)\n\ngit init\ngit add -A\ngit commit -m \"Initial commit before Ralph\"\n\nOption 2: Modify the prompts\n\nRemove git-related guardrails from PROMPT_build.md\nRemove the git push section from loop.sh\nUse file backups instead: add cp -r src/ backups/iteration-$ITERATION/ to loop.sh\n\nOption 3: Use tarball snapshots\n\n# Add to loop.sh before each iteration:\ntar -czf \"snapshots/pre-iteration-$ITERATION.tar.gz\" src/"
      },
      {
        "title": "Very Large Codebases",
        "body": "For codebases with 100K+ lines:\n\nReduce subagent parallelism: Change \"up to 500 parallel Sonnet subagents\" to \"up to 50\" in prompts\nScope narrowly: Use focused specs that target specific directories\nAdd path restrictions: In AGENTS.md, note which directories are in-scope\nConsider workspace splitting: Treat large modules as separate Ralph projects"
      },
      {
        "title": "When Claude CLI Isn't Available",
        "body": "The methodology works with any Claude interface:\n\nClaude API directly:\n\n# Replace loop.sh with API calls using curl or a script\ncurl https://api.anthropic.com/v1/messages \\\n  -H \"x-api-key: $ANTHROPIC_API_KEY\" \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\": \"claude-sonnet-4-20250514\", \"max_tokens\": 8192, \"messages\": [...]}'\n\nAlternative agents:\n\nAider: aider --opus --auto-commits\nContinue.dev: Use with Claude API key\nCursor: Composer mode with PROMPT files as context\n\nThe key principles (one task per iteration, fresh context, backpressure) apply regardless of tooling."
      },
      {
        "title": "Non-Node.js Projects",
        "body": "Adapt AGENTS.md for your stack:\n\nStackBuildTestLintPythonpip install -e .pytestruff .Gogo build ./...go test ./...golangci-lint runRustcargo buildcargo testcargo clippyRubybundle installrspecrubocop\n\nAlso update path references in prompts (src/* → your source directory)."
      },
      {
        "title": "Learn More",
        "body": "Geoffrey Huntley: https://ghuntley.com/ralph/\nClayton Farr's Playbook: https://github.com/ClaytonFarr/ralph-playbook\nGeoffrey's Fork: https://github.com/ghuntley/how-to-ralph-wiggum"
      },
      {
        "title": "Credits",
        "body": "Built by Johnathan & Q — a human-AI dyad.\n\nTwitter: @spacepixel\nClawdHub: clawhub.ai/skills/ralph-loops"
      }
    ],
    "body": "Ralph Loops Skill\n\nFirst time? Read SETUP.md first to install dependencies and verify your setup.\n\nAutonomous AI agent loops for iterative development. Based on Geoffrey Huntley's Ralph Wiggum technique, as documented by Clayton Farr.\n\nScript: skills/ralph-loops/scripts/ralph-loop.mjs Dashboard: skills/ralph-loops/dashboard/ (run with node server.mjs) Templates: skills/ralph-loops/templates/ Archive: ~/clawd/logs/ralph-archive/\n\n⚠️ Known Issues\nClaude Code Version Compatibility\n\nClaude Code 2.1.29 has a critical bug that spawns orphaned sub-agents consuming 99% CPU. Iterations fail with \"exit code null\" on first run.\n\nFix: Downgrade to 2.1.25:\n\nnpm install -g @anthropic-ai/claude-code@2.1.25\n\n\nVerify:\n\nclaude --version  # Should show 2.1.25\n\n\nThis was discovered 2026-02-01. Check if newer versions fix the issue before upgrading.\n\n⚠️ Don't Block the Conversation!\n\nWhen running a Ralph loop, don't monitor it synchronously. The loop runs as a separate Claude CLI process — you can keep chatting.\n\n❌ Wrong (blocks conversation):\n\nStart loop → sleep 60 → poll → sleep 60 → poll → ... (6 minutes of silence)\n\n\n✅ Right (stays responsive):\n\nStart loop → \"It's running, I'll check periodically\" → keep chatting → check on heartbeats\n\n\nHow to monitor without blocking:\n\nStart the loop with node ralph-loop.mjs ... (runs in background)\nTell human: \"Loop running. I'll check progress periodically or you can ask.\"\nCheck via process poll <sessionId> when asked or during heartbeats\nUse the dashboard at http://localhost:3939 for real-time visibility\n\nThe loop is autonomous — that's the whole point. Don't babysit it at the cost of ignoring your human.\n\nTrigger Phrases\n\nWhen human says:\n\nPhrase\tAction\n\"Interview me about system X\"\tStart Phase 1 requirements interview\n\"Start planning system X\"\tRun ./loop.sh plan (needs specs first)\n\"Start building system X\"\tRun ./loop.sh build (needs plan first)\n\"Ralph loop over X\"\tASK which phase (see below)\nWhen Human Says \"Ralph Loop\" — Clarify the Phase!\n\nDon't assume which phase. Ask:\n\n\"Which type of Ralph loop are we doing?\n\n1️⃣ Interview — I'll ask you questions to build specs (Phase 1) 2️⃣ Planning — I'll iterate on an implementation plan (Phase 2)\n3️⃣ Building — I'll implement from a plan, one task per iteration (Phase 3) 4️⃣ Generic — Simple iterative refinement on a single topic\"\n\nThen proceed based on their answer:\n\nChoice\tAction\nInterview\tUse templates/requirements-interview.md protocol\nPlanning\tNeed specs first → run planning loop with PROMPT_plan.md\nBuilding\tNeed plan first → run build loop with PROMPT_build.md\nGeneric\tCreate prompt file, run ralph-loop.mjs directly\nGeneric Ralph Loop Flow (Phase 4)\n\nFor simple iterative refinement (not full system builds):\n\nClarify the task — What exactly should be improved/refined?\nCreate a prompt file — Save to /tmp/ralph-prompt-<task>.md\nSet completion criteria — What signals \"done\"?\nRun the loop:\nnode skills/ralph-loops/scripts/ralph-loop.mjs \\\n  --prompt \"/tmp/ralph-prompt-<task>.md\" \\\n  --model opus \\\n  --max 10 \\\n  --done \"RALPH_DONE\"\n\nOr spawn as sub-agent for long-running tasks\nCore Philosophy\n\n\"Human roles shift from 'telling the agent what to do' to 'engineering conditions where good outcomes emerge naturally through iteration.\" — Clayton Farr\n\nThree principles drive everything:\n\nContext is scarce — With ~176K usable tokens from a 200K window, keep each iteration lean\nPlans are disposable — A drifting plan is cheaper to regenerate than salvage\nBackpressure beats direction — Engineer environments where wrong outputs get rejected automatically\nThree-Phase Workflow\n┌─────────────────────────────────────────────────────────────────────┐\n│  Phase 1: REQUIREMENTS                                              │\n│  Human + LLM conversation → JTBD → Topics → specs/*.md              │\n├─────────────────────────────────────────────────────────────────────┤\n│  Phase 2: PLANNING                                                  │\n│  Gap analysis (specs vs code) → IMPLEMENTATION_PLAN.md              │\n├─────────────────────────────────────────────────────────────────────┤\n│  Phase 3: BUILDING                                                  │\n│  One task per iteration → fresh context → backpressure → commit     │\n└─────────────────────────────────────────────────────────────────────┘\n\nPhase 1: Requirements (Talk to Human)\n\nGoal: Understand what to build BEFORE building it.\n\nThis is the most important phase. Use structured conversation to:\n\nIdentify Jobs to Be Done (JTBD)\n\nWhat user need or outcome are we solving?\nNot features — outcomes\n\nBreak JTBD into Topics of Concern\n\nEach topic = one distinct aspect/component\nUse the \"one sentence without 'and'\" test\n✓ \"The color extraction system analyzes images to identify dominant colors\"\n✗ \"The user system handles authentication, profiles, and billing\" → 3 topics\n\nCreate Specs for Each Topic\n\nOne markdown file per topic in specs/\nCapture requirements, acceptance criteria, edge cases\n\nTemplate: templates/requirements-interview.md\n\nPhase 2: Planning (Gap Analysis)\n\nGoal: Create a prioritized task list without implementing anything.\n\nUses PROMPT_plan.md in the loop:\n\nStudy all specs\nStudy existing codebase\nCompare specs vs code (gap analysis)\nGenerate IMPLEMENTATION_PLAN.md with prioritized tasks\nNO implementation — planning only\n\nUsually completes in 1-2 iterations.\n\nPhase 3: Building (One Task Per Iteration)\n\nGoal: Implement tasks one at a time with fresh context.\n\nUses PROMPT_build.md in the loop:\n\nRead IMPLEMENTATION_PLAN.md\nPick the most important task\nInvestigate codebase (don't assume not implemented)\nImplement\nRun validation (backpressure)\nUpdate plan, commit\nExit → fresh context → next iteration\n\nKey insight: One task per iteration keeps context lean. The agent stays in the \"smart zone\" instead of accumulating cruft.\n\nWhy fresh context matters:\n\nNo accumulated mistakes — Each iteration starts clean; previous errors don't compound\nFull context budget — 200K tokens for THIS task, not shared with finished work\nReduced hallucination — Shorter contexts = more grounded responses\nNatural checkpoints — Each commit is a save point; easy to revert single iterations\nFile Structure\nproject/\n├── loop.sh                    # Ralph loop script\n├── PROMPT_plan.md             # Planning mode instructions\n├── PROMPT_build.md            # Building mode instructions  \n├── AGENTS.md                  # Operational guide (~60 lines max)\n├── IMPLEMENTATION_PLAN.md     # Prioritized task list (generated)\n└── specs/                     # Requirement specs\n    ├── topic-a.md\n    ├── topic-b.md\n    └── ...\n\nFile Purposes\nFile\tPurpose\tWho Creates\nspecs/*.md\tSource of truth for requirements\tHuman + Phase 1\nPROMPT_plan.md\tInstructions for planning mode\tCopy from template\nPROMPT_build.md\tInstructions for building mode\tCopy from template\nAGENTS.md\tBuild/test/lint commands\tHuman + Ralph\nIMPLEMENTATION_PLAN.md\tTask list with priorities\tRalph (Phase 2)\nProject Organization (Systems)\n\nFor Clawdbot systems, each Ralph project lives in <workspace>/systems/<name>/:\n\nsystems/\n├── health-tracker/           # Example system\n│   ├── specs/\n│   │   ├── daily-tracking.md\n│   │   └── test-scheduling.md\n│   ├── PROMPT_plan.md\n│   ├── PROMPT_build.md\n│   ├── AGENTS.md\n│   ├── IMPLEMENTATION_PLAN.md  # ← exists = past Phase 1\n│   └── src/\n└── activity-planner/\n    ├── specs/                  # ← empty = still in Phase 1\n    └── ...\n\nPhase Detection (Auto)\n\nDetect current phase by checking what files exist:\n\nWhat Exists\tCurrent Phase\tNext Action\nNothing / empty specs/\tPhase 1: Requirements\tRun requirements interview\nspecs/*.md but no IMPLEMENTATION_PLAN.md\tReady for Phase 2\tRun ./loop.sh plan\nspecs/*.md + IMPLEMENTATION_PLAN.md\tPhase 2 or 3\tReview plan, run ./loop.sh build\nPlan shows all tasks complete\tDone\tArchive or iterate\n\nQuick check:\n\n# What phase are we in?\n[ -z \"$(ls specs/ 2>/dev/null)\" ] && echo \"Phase 1: Need specs\" && exit\n[ ! -f IMPLEMENTATION_PLAN.md ] && echo \"Phase 2: Need plan\" && exit\necho \"Phase 3: Ready to build (or done)\"\n\nJTBD Breakdown\n\nThe hierarchy matters:\n\nJTBD (Job to Be Done)\n└── Topic of Concern (1 per spec file)\n    └── Tasks (many per topic, in IMPLEMENTATION_PLAN.md)\n\n\nExample:\n\nJTBD: \"Help designers create mood boards\"\nTopics:\nImage collection → specs/image-collection.md\nColor extraction → specs/color-extraction.md\nLayout system → specs/layout-system.md\nSharing → specs/sharing.md\nTasks: Each spec generates multiple implementation tasks\nTopic Scope Test\n\nCan you describe the topic in one sentence without \"and\"?\n\nIf you need \"and\" or \"also\", it's probably multiple topics. Split it.\n\nWhen to split:\n\nMultiple verbs in the description → separate topics\nDifferent user personas involved → separate topics\nCould be implemented by different teams → separate topics\nHas its own failure modes → probably its own topic\n\nExample split:\n\n❌ \"User management handles registration, authentication, profiles, and permissions\"\n\n✅ Split into:\n   - \"Registration creates new user accounts from email/password\"\n   - \"Authentication verifies user identity via login flow\"  \n   - \"Profiles let users view and edit their information\"\n   - \"Permissions control what actions users can perform\"\n\n\nCounter-example (don't split):\n\n✅ Keep together:\n   \"Color extraction analyzes images and returns dominant color palettes\"\n   \n   Why: \"analyzes\" and \"returns\" are steps in one operation, not separate concerns.\n\nBackpressure Mechanisms\n\nAutonomous loops converge when wrong outputs get rejected. Three layers:\n\n1. Downstream Gates (Hard)\n\nTests, type-checking, linting, build validation. Deterministic.\n\n# In AGENTS.md\n## Validation\n- Tests: `npm test`\n- Typecheck: `npm run typecheck`\n- Lint: `npm run lint`\n\n2. Upstream Steering (Soft)\n\nExisting code patterns guide the agent. It discovers conventions through exploration.\n\n3. LLM-as-Judge (Subjective)\n\nFor subjective criteria (tone, UX, aesthetics), use another LLM call with binary pass/fail.\n\nStart with hard gates. Add LLM-as-judge for subjective criteria only after mechanical backpressure works.\n\nPrompt Structure\n\nGeoffrey's prompts follow a numbered pattern:\n\nSection\tPurpose\n0a-0d\tOrient: Study specs, source, current plan\n1-4\tMain instructions: What to do this iteration\n999+\tGuardrails: Invariants (higher number = more critical)\nThe Numbered Guardrails Pattern\n\nGuardrails use escalating numbers (99999, 999999, 9999999...) to signal priority:\n\n99999. Important: Capture the why in documentation.\n\n999999. Important: Single sources of truth, no migrations.\n\n9999999. Create git tags after successful builds.\n\n99999999. Add logging if needed to debug.\n\n999999999. Keep IMPLEMENTATION_PLAN.md current.\n\n\nWhy this works:\n\nVisual prominence — Large numbers stand out, harder to skip\nImplicit priority — More 9s = more critical (like DEFCON levels in reverse)\nNo collisions — Sparse numbering lets you insert new rules without renumbering\nMnemonic — Claude treats these as invariants, not suggestions\n\nThe \"Important:\" prefix is deliberate — it triggers Claude's attention.\n\nKey Language Patterns\n\nUse Geoffrey's specific phrasing — it matters:\n\n\"study\" (not \"read\" or \"look at\")\n\"don't assume not implemented\" (critical!)\n\"using parallel subagents\" / \"up to N subagents\"\n\"only 1 subagent for build/tests\" (backpressure control)\n\"Ultrathink\" (deep reasoning trigger)\n\"capture the why\"\n\"keep it up to date\"\n\"resolve them or document them\"\nQuick Start\n1. Set Up Project Structure\nmkdir -p myproject/specs\ncd myproject\ngit init  # Ralph expects git for commits\n\n# Copy templates\ncp .//templates/PROMPT_plan.md .\ncp .//templates/PROMPT_build.md .\ncp .//templates/AGENTS.md .\ncp .//templates/loop.sh .\nchmod +x loop.sh\n\n2. Customize Templates (Required!)\n\nPROMPT_plan.md — Replace [PROJECT_GOAL] with your actual goal:\n\n# Before:\nULTIMATE GOAL: We want to achieve [PROJECT_GOAL].\n\n# After:\nULTIMATE GOAL: We want to achieve a fully functional mood board app with image upload and color extraction.\n\n\nPROMPT_build.md — Adjust source paths if not using src/:\n\n# Before:\n0c. For reference, the application source code is in `src/*`.\n\n# After:\n0c. For reference, the application source code is in `lib/*`.\n\n\nAGENTS.md — Update build/test/lint commands for your stack.\n\n3. Phase 1: Requirements Gathering (Don't Skip!)\n\nThis phase happens WITH the human. Use the interview template:\n\ncat .//templates/requirements-interview.md\n\n\nThe workflow:\n\nDiscuss the JTBD (Job to Be Done) — outcomes, not features\nBreak into Topics of Concern (each passes the \"one sentence\" test)\nWrite a spec file for each topic: specs/topic-name.md\nHuman reviews and approves specs\n\nExample output:\n\nspecs/\n├── image-collection.md\n├── color-extraction.md\n├── layout-system.md\n└── sharing.md\n\n4. Phase 2: Planning\n./loop.sh plan\n\n\nWait for IMPLEMENTATION_PLAN.md to be generated (usually 1-2 iterations). Review it — this is your task list.\n\n5. Phase 3: Building\n./loop.sh build 20  # Max 20 iterations\n\n\nWatch it work. Add backpressure (tests, lints) as patterns emerge. Check commits for progress.\n\nLoop Script Options\n./loop.sh              # Build mode, unlimited\n./loop.sh 20           # Build mode, max 20 iterations\n./loop.sh plan         # Plan mode, unlimited\n./loop.sh plan 5       # Plan mode, max 5 iterations\n\n\nOr use the Node.js wrapper for more control:\n\nnode skills/ralph-loops/scripts/ralph-loop.mjs \\\n  --prompt \"./PROMPT_build.md\" \\\n  --model opus \\\n  --max 20 \\\n  --done \"RALPH_DONE\"\n\nWhen to Regenerate the Plan\n\nPlans drift. Regenerate when:\n\nRalph is going off track (implementing wrong things)\nPlan feels stale or doesn't match current state\nToo much clutter from completed items\nYou've made significant spec changes\nYou're confused about what's actually done\n\nJust switch back to planning mode:\n\n./loop.sh plan\n\n\nRegeneration cost is one Planning loop. Cheap compared to Ralph going in circles.\n\nSafety\n\nRalph requires --dangerously-skip-permissions to run autonomously. This bypasses Claude's permission system entirely.\n\nPhilosophy: \"It's not if it gets popped, it's when. And what is the blast radius?\"\n\nProtections:\n\nRun in isolated environments (Docker, VM)\nOnly the API keys needed for the task\nNo access to private data beyond requirements\nRestrict network connectivity where possible\nEscape hatches: Ctrl+C stops the loop; git reset --hard reverts uncommitted changes\nCost Expectations\nTask Type\tModel\tIterations\tEst. Cost\nGenerate plan\tOpus\t1-2\t$0.50-1.00\nImplement simple feature\tOpus\t3-5\t$1.00-2.00\nImplement complex feature\tOpus\t10-20\t$3.00-8.00\nFull project buildout\tOpus\t50+\t$15-50+\n\nTip: Use Sonnet for simpler tasks where plan is clear. Use Opus for planning and complex reasoning.\n\nReal-World Results\n\nFrom Geoffrey Huntley:\n\n6 repos generated overnight at YC hackathon\n$50k contract completed for $297 in API costs\nCreated entire programming language over 3 months\nAdvanced: Running as Sub-Agent\n\nFor long loops, spawn as sub-agent so main session stays responsive:\n\nsessions_spawn({\n  task: `cd /path/to/project && ./loop.sh build 20\n         \nSummarize what was implemented when done.`,\n  label: \"ralph-build\",\n  model: \"opus\"\n})\n\n\nCheck progress:\n\nsessions_list({ kinds: [\"spawn\"] })\nsessions_history({ label: \"ralph-build\", limit: 5 })\n\nTroubleshooting\nRalph keeps implementing the same thing\nPlan is stale → regenerate with ./loop.sh plan\nBackpressure missing → add tests that catch duplicates\nRalph goes in circles\nAdd more specific guardrails to prompts\nCheck if specs are ambiguous\nRegenerate plan\nContext getting bloated\nEnsure one task per iteration (check prompt)\nKeep AGENTS.md under 60 lines\nMove status/progress to IMPLEMENTATION_PLAN.md, not AGENTS.md\nTests not running\nCheck AGENTS.md has correct validation commands\nEnsure backpressure section in prompt references AGENTS.md\nEdge Cases\nProjects Without Git\n\nThe loop script expects git for commits and pushes. For projects without version control:\n\nOption 1: Initialize git anyway (recommended)\n\ngit init\ngit add -A\ngit commit -m \"Initial commit before Ralph\"\n\n\nOption 2: Modify the prompts\n\nRemove git-related guardrails from PROMPT_build.md\nRemove the git push section from loop.sh\nUse file backups instead: add cp -r src/ backups/iteration-$ITERATION/ to loop.sh\n\nOption 3: Use tarball snapshots\n\n# Add to loop.sh before each iteration:\ntar -czf \"snapshots/pre-iteration-$ITERATION.tar.gz\" src/\n\nVery Large Codebases\n\nFor codebases with 100K+ lines:\n\nReduce subagent parallelism: Change \"up to 500 parallel Sonnet subagents\" to \"up to 50\" in prompts\nScope narrowly: Use focused specs that target specific directories\nAdd path restrictions: In AGENTS.md, note which directories are in-scope\nConsider workspace splitting: Treat large modules as separate Ralph projects\nWhen Claude CLI Isn't Available\n\nThe methodology works with any Claude interface:\n\nClaude API directly:\n\n# Replace loop.sh with API calls using curl or a script\ncurl https://api.anthropic.com/v1/messages \\\n  -H \"x-api-key: $ANTHROPIC_API_KEY\" \\\n  -H \"content-type: application/json\" \\\n  -d '{\"model\": \"claude-sonnet-4-20250514\", \"max_tokens\": 8192, \"messages\": [...]}'\n\n\nAlternative agents:\n\nAider: aider --opus --auto-commits\nContinue.dev: Use with Claude API key\nCursor: Composer mode with PROMPT files as context\n\nThe key principles (one task per iteration, fresh context, backpressure) apply regardless of tooling.\n\nNon-Node.js Projects\n\nAdapt AGENTS.md for your stack:\n\nStack\tBuild\tTest\tLint\nPython\tpip install -e .\tpytest\truff .\nGo\tgo build ./...\tgo test ./...\tgolangci-lint run\nRust\tcargo build\tcargo test\tcargo clippy\nRuby\tbundle install\trspec\trubocop\n\nAlso update path references in prompts (src/* → your source directory).\n\nLearn More\nGeoffrey Huntley: https://ghuntley.com/ralph/\nClayton Farr's Playbook: https://github.com/ClaytonFarr/ralph-playbook\nGeoffrey's Fork: https://github.com/ghuntley/how-to-ralph-wiggum\nCredits\n\nBuilt by Johnathan & Q — a human-AI dyad.\n\nTwitter: @spacepixel\nClawdHub: clawhub.ai/skills/ralph-loops"
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/qlifebot-coder/ralph-loops",
    "publisherUrl": "https://clawhub.ai/qlifebot-coder/ralph-loops",
    "owner": "qlifebot-coder",
    "version": "1.0.2",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/ralph-loops",
    "downloadUrl": "https://openagent3.xyz/downloads/ralph-loops",
    "agentUrl": "https://openagent3.xyz/skills/ralph-loops/agent",
    "manifestUrl": "https://openagent3.xyz/skills/ralph-loops/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/ralph-loops/agent.md"
  }
}