{
  "schemaVersion": "1.0",
  "item": {
    "slug": "ralph-loop-agent",
    "name": "Ralph Loop (Agent Mode)",
    "source": "tencent",
    "type": "skill",
    "category": "AI 智能",
    "sourceUrl": "https://clawhub.ai/addozhang/ralph-loop-agent",
    "canonicalUrl": "https://clawhub.ai/addozhang/ralph-loop-agent",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/ralph-loop-agent",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=ralph-loop-agent",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "README.md",
      "SKILL.md",
      "_meta.json",
      "package.json"
    ],
    "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. Then review README.md for any prerequisites, environment setup, or post-install checks. 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. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "slug": "ralph-loop-agent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-05-03T09:09:11.489Z",
      "expiresAt": "2026-05-10T09:09:11.489Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=ralph-loop-agent",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=ralph-loop-agent",
        "contentDisposition": "attachment; filename=\"ralph-loop-agent-1.1.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null,
        "slug": "ralph-loop-agent"
      },
      "scope": "item",
      "summary": "Item download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this item.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/ralph-loop-agent"
    },
    "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-loop-agent",
    "agentPageUrl": "https://openagent3.xyz/skills/ralph-loop-agent/agent",
    "manifestUrl": "https://openagent3.xyz/skills/ralph-loop-agent/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/ralph-loop-agent/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. Then review README.md for any prerequisites, environment setup, or post-install checks. 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. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "Overview",
        "body": "This skill guides OpenClaw agents to execute Ralph Loop workflows using the exec and process tools. The agent orchestrates AI coding agent sessions following the Ralph playbook flow:\n\nDefine Requirements → JTBD → Focus Topics → specs/*.md\nPLANNING Loop → Create/update IMPLEMENTATION_PLAN.md (do not implement)\nBUILDING Loop → Implement tasks, run tests (backpressure), update plan, commit\n\nThe loop persists context via PROMPT.md + AGENTS.md (loaded each iteration) and the plan/specs on disk."
      },
      {
        "title": "How This Skill Works",
        "body": "This skill generates instructions for OpenClaw agents to execute Ralph Loops using the exec and process tools.\n\nThe agent calls exec tool with the coding agent command\nUses pty: true to provide TTY for interactive CLIs\nUses background: true for monitoring capabilities\nUses process tool to monitor progress and detect completion\n\nImportant: Users don't run these scripts directly - the OpenClaw agent executes them using its tool capabilities."
      },
      {
        "title": "TTY Requirements",
        "body": "Some coding agents require a real terminal (TTY) to work properly, or they will hang:\n\nInteractive CLIs (need TTY):\n\nOpenCode, Codex, Claude Code, Pi, Goose\n\nNon-interactive CLIs (file-based):\n\naider, custom scripts\n\nSolution: Use exec + process mode for interactive CLIs, simple loops for file-based tools."
      },
      {
        "title": "Interactive CLIs (Recommended Pattern)",
        "body": "For OpenCode, Codex, Claude Code, Pi, and Goose - these require TTY support:\n\nWhen I (the agent) receive a Ralph Loop request, I will:\n\nUse exec tool to launch the coding agent:\nexec tool with parameters:\n- command: \"opencode run --model <MODEL> \\\"$(cat PROMPT.md)\\\"\"\n- workdir: <project_path>\n- background: true\n- pty: true\n- yieldMs: 60000\n- timeout: 3600\n\n\n\nCapture session ID from exec tool response\n\n\nUse process tool to monitor:\nprocess tool with:\n- action: \"poll\"\n- sessionId: <captured_session_id>\n\nprocess tool with:\n- action: \"log\"\n- sessionId: <captured_session_id>\n- offset: -30  (for recent output)\n\n\n\nCheck completion by reading IMPLEMENTATION_PLAN.md for sentinel text\n\n\nClean up with process kill if needed:\nprocess tool with:\n- action: \"kill\"\n- sessionId: <session_id>\n\nBenefits: TTY support, real-time logs, timeout handling, parallel sessions, workdir isolation"
      },
      {
        "title": "1) Gather Inputs",
        "body": "Required:\n\nGoal / JTBD\nCLI (opencode, codex, claude, goose, pi, other)\nMode (PLANNING, BUILDING, or BOTH)\nMax iterations (default: PLANNING=5, BUILDING=10)\n\nOptional:\n\nCompletion sentinel (default: STATUS: COMPLETE in IMPLEMENTATION_PLAN.md)\nWorking directory (default: $PWD)\nTimeout per iteration (default: 3600s)\nSandbox choice\nAuto-approval flags (--full-auto, --yolo, --dangerously-skip-permissions)\n\nAuto-detect:\n\nIf CLI in interactive list → use exec tool with pty: true\nExtract model flag from CLI requirements"
      },
      {
        "title": "2) Requirements → Specs (Optional)",
        "body": "If requirements are unclear:\n\nBreak JTBD into focus topics\nDraft specs/<topic>.md for each\nKeep specs short and testable"
      },
      {
        "title": "3) PROMPT.md + AGENTS.md",
        "body": "PROMPT.md references:\n\nspecs/*.md\nIMPLEMENTATION_PLAN.md\nRelevant project files\n\nAGENTS.md includes:\n\nTest commands (backpressure)\nBuild/run instructions\nOperational learnings"
      },
      {
        "title": "4) Prompt Templates",
        "body": "PLANNING Prompt (no implementation):\n\nYou are running a Ralph PLANNING loop for this goal: <goal>.\n\nRead specs/* and the current codebase. Only update IMPLEMENTATION_PLAN.md.\n\nRules:\n- Do not implement\n- Do not commit\n- Create a prioritized task list\n- Write down questions if unclear\n\nCompletion:\nWhen plan is ready, add: STATUS: PLANNING_COMPLETE\n\nBUILDING Prompt:\n\nYou are running a Ralph BUILDING loop for this goal: <goal>.\n\nContext: specs/*, IMPLEMENTATION_PLAN.md, AGENTS.md\n\nTasks:\n1) Pick the most important task\n2) Investigate code\n3) Implement\n4) Run backpressure commands from AGENTS.md\n5) Update IMPLEMENTATION_PLAN.md\n6) Update AGENTS.md with learnings\n7) Commit with clear message\n\nCompletion:\nWhen all done, add: STATUS: COMPLETE"
      },
      {
        "title": "5) CLI Command Reference",
        "body": "The agent constructs command strings using these patterns:\n\nCLICommand String PatternOpenCodeopencode run --model <MODEL> \"$(cat PROMPT.md)\"Codexcodex exec <FLAGS> \"$(cat PROMPT.md)\" (requires git)Claude Codeclaude <FLAGS> \"$(cat PROMPT.md)\"Pipi --provider <PROVIDER> --model <MODEL> -p \"$(cat PROMPT.md)\"Goosegoose run \"$(cat PROMPT.md)\"\n\nCommon flags:\n\nCodex: --full-auto, --yolo, --model <model>\nClaude: --dangerously-skip-permissions"
      },
      {
        "title": "Example 1: OpenCode Ralph Loop",
        "body": "Agent executes this sequence:\n\nStep 1: Launch OpenCode with exec tool\n{\n  command: \"opencode run --model github-copilot/claude-opus-4.5 \\\"$(cat PROMPT.md)\\\"\",\n  workdir: \"/path/to/project\",\n  background: true,\n  pty: true,\n  timeout: 3600,\n  yieldMs: 60000\n}\n\nStep 2: Capture session ID from response\nsessionId: \"abc123\"\n\nStep 3: Monitor with process tool every 10-30 seconds\n{\n  action: \"poll\",\n  sessionId: \"abc123\"\n}\n\nStep 4: Check recent logs\n{\n  action: \"log\",\n  sessionId: \"abc123\",\n  offset: -30\n}\n\nStep 5: Read IMPLEMENTATION_PLAN.md to check for completion\n- Look for: \"STATUS: COMPLETE\" or \"STATUS: PLANNING_COMPLETE\"\n\nStep 6: If complete or timeout, cleanup\n{\n  action: \"kill\",\n  sessionId: \"abc123\"\n}"
      },
      {
        "title": "Example 2: Codex with Full Auto",
        "body": "Agent tool calls:\n\nexec tool:\n{\n  command: \"codex exec --full-auto --model anthropic/claude-opus-4 \\\"$(cat PROMPT.md)\\\"\",\n  workdir: \"/path/to/project\",\n  background: true,\n  pty: true,\n  timeout: 3600\n}\n\n# Then monitor with process tool as above"
      },
      {
        "title": "Completion Detection",
        "body": "Use flexible regex to match variations:\n\ngrep -Eq \"STATUS:?\\s*(PLANNING_)?COMPLETE\" IMPLEMENTATION_PLAN.md\n\nMatches:\n\nSTATUS: COMPLETE\nSTATUS:COMPLETE\nSTATUS: PLANNING_COMPLETE\n## Status: PLANNING_COMPLETE"
      },
      {
        "title": "Auto-Approval Flags (Risky!)",
        "body": "Codex: --full-auto (sandboxed, auto-approve) or --yolo (no sandbox!)\nClaude: --dangerously-skip-permissions\nRecommendation: Use sandboxes (docker/e2b/fly) and limited credentials"
      },
      {
        "title": "Escape Hatches",
        "body": "Stop: Ctrl+C\nKill session: process tool with action: \"kill\"\nRollback: git reset --hard HEAD~N"
      },
      {
        "title": "Best Practices",
        "body": "Start small: Test with 1-2 iterations first\nWorkdir isolation: Prevent reading unrelated files\nSet timeouts: Default 1h may not fit all tasks\nMonitor actively: Check logs, don't terminate prematurely\nRequirements first: Clear specs before building\nBackpressure early: Add tests from the start"
      },
      {
        "title": "Troubleshooting",
        "body": "ProblemSolutionOpenCode hangsEnsure agent uses exec tool with pty: trueSession won't startCheck CLI path, git repo, command syntaxCompletion not detectedVerify sentinel format in IMPLEMENTATION_PLAN.mdProcess timeoutAgent should increase timeout parameter or simplify tasksParallel conflictsAgent should use git worktrees for isolationCan't see progressAgent should use process tool with action: \"log\""
      },
      {
        "title": "License",
        "body": "MIT"
      },
      {
        "title": "Credits",
        "body": "This skill builds upon work by:\n\n@jordyvandomselaar - Original Ralph Loop concept and workflow design\n@steipete - Coding agent patterns and exec/process tool usage with pty support\n\nKey improvement: Uses OpenClaw's exec tool with pty: true to provide TTY for interactive CLIs, solving the hanging issue that occurs with simple background bash execution."
      }
    ],
    "body": "Ralph Loop\nOverview\n\nThis skill guides OpenClaw agents to execute Ralph Loop workflows using the exec and process tools. The agent orchestrates AI coding agent sessions following the Ralph playbook flow:\n\nDefine Requirements → JTBD → Focus Topics → specs/*.md\nPLANNING Loop → Create/update IMPLEMENTATION_PLAN.md (do not implement)\nBUILDING Loop → Implement tasks, run tests (backpressure), update plan, commit\n\nThe loop persists context via PROMPT.md + AGENTS.md (loaded each iteration) and the plan/specs on disk.\n\nHow This Skill Works\n\nThis skill generates instructions for OpenClaw agents to execute Ralph Loops using the exec and process tools.\n\nThe agent calls exec tool with the coding agent command\nUses pty: true to provide TTY for interactive CLIs\nUses background: true for monitoring capabilities\nUses process tool to monitor progress and detect completion\n\nImportant: Users don't run these scripts directly - the OpenClaw agent executes them using its tool capabilities.\n\nTTY Requirements\n\nSome coding agents require a real terminal (TTY) to work properly, or they will hang:\n\nInteractive CLIs (need TTY):\n\nOpenCode, Codex, Claude Code, Pi, Goose\n\nNon-interactive CLIs (file-based):\n\naider, custom scripts\n\nSolution: Use exec + process mode for interactive CLIs, simple loops for file-based tools.\n\nAgent Tool Usage Patterns\nInteractive CLIs (Recommended Pattern)\n\nFor OpenCode, Codex, Claude Code, Pi, and Goose - these require TTY support:\n\nWhen I (the agent) receive a Ralph Loop request, I will:\n\nUse exec tool to launch the coding agent:\n\nexec tool with parameters:\n- command: \"opencode run --model <MODEL> \\\"$(cat PROMPT.md)\\\"\"\n- workdir: <project_path>\n- background: true\n- pty: true\n- yieldMs: 60000\n- timeout: 3600\n\n\nCapture session ID from exec tool response\n\nUse process tool to monitor:\n\nprocess tool with:\n- action: \"poll\"\n- sessionId: <captured_session_id>\n\nprocess tool with:\n- action: \"log\"\n- sessionId: <captured_session_id>\n- offset: -30  (for recent output)\n\n\nCheck completion by reading IMPLEMENTATION_PLAN.md for sentinel text\n\nClean up with process kill if needed:\n\nprocess tool with:\n- action: \"kill\"\n- sessionId: <session_id>\n\n\nBenefits: TTY support, real-time logs, timeout handling, parallel sessions, workdir isolation\n\nAgent Workflow\n1) Gather Inputs\n\nRequired:\n\nGoal / JTBD\nCLI (opencode, codex, claude, goose, pi, other)\nMode (PLANNING, BUILDING, or BOTH)\nMax iterations (default: PLANNING=5, BUILDING=10)\n\nOptional:\n\nCompletion sentinel (default: STATUS: COMPLETE in IMPLEMENTATION_PLAN.md)\nWorking directory (default: $PWD)\nTimeout per iteration (default: 3600s)\nSandbox choice\nAuto-approval flags (--full-auto, --yolo, --dangerously-skip-permissions)\n\nAuto-detect:\n\nIf CLI in interactive list → use exec tool with pty: true\nExtract model flag from CLI requirements\n2) Requirements → Specs (Optional)\n\nIf requirements are unclear:\n\nBreak JTBD into focus topics\nDraft specs/<topic>.md for each\nKeep specs short and testable\n3) PROMPT.md + AGENTS.md\n\nPROMPT.md references:\n\nspecs/*.md\nIMPLEMENTATION_PLAN.md\nRelevant project files\n\nAGENTS.md includes:\n\nTest commands (backpressure)\nBuild/run instructions\nOperational learnings\n4) Prompt Templates\n\nPLANNING Prompt (no implementation):\n\nYou are running a Ralph PLANNING loop for this goal: <goal>.\n\nRead specs/* and the current codebase. Only update IMPLEMENTATION_PLAN.md.\n\nRules:\n- Do not implement\n- Do not commit\n- Create a prioritized task list\n- Write down questions if unclear\n\nCompletion:\nWhen plan is ready, add: STATUS: PLANNING_COMPLETE\n\n\nBUILDING Prompt:\n\nYou are running a Ralph BUILDING loop for this goal: <goal>.\n\nContext: specs/*, IMPLEMENTATION_PLAN.md, AGENTS.md\n\nTasks:\n1) Pick the most important task\n2) Investigate code\n3) Implement\n4) Run backpressure commands from AGENTS.md\n5) Update IMPLEMENTATION_PLAN.md\n6) Update AGENTS.md with learnings\n7) Commit with clear message\n\nCompletion:\nWhen all done, add: STATUS: COMPLETE\n\n5) CLI Command Reference\n\nThe agent constructs command strings using these patterns:\n\nCLI\tCommand String Pattern\nOpenCode\topencode run --model <MODEL> \"$(cat PROMPT.md)\"\nCodex\tcodex exec <FLAGS> \"$(cat PROMPT.md)\" (requires git)\nClaude Code\tclaude <FLAGS> \"$(cat PROMPT.md)\"\nPi\tpi --provider <PROVIDER> --model <MODEL> -p \"$(cat PROMPT.md)\"\nGoose\tgoose run \"$(cat PROMPT.md)\"\n\nCommon flags:\n\nCodex: --full-auto, --yolo, --model <model>\nClaude: --dangerously-skip-permissions\nDetailed Agent Tool Usage Examples\nExample 1: OpenCode Ralph Loop\n\nAgent executes this sequence:\n\nStep 1: Launch OpenCode with exec tool\n{\n  command: \"opencode run --model github-copilot/claude-opus-4.5 \\\"$(cat PROMPT.md)\\\"\",\n  workdir: \"/path/to/project\",\n  background: true,\n  pty: true,\n  timeout: 3600,\n  yieldMs: 60000\n}\n\nStep 2: Capture session ID from response\nsessionId: \"abc123\"\n\nStep 3: Monitor with process tool every 10-30 seconds\n{\n  action: \"poll\",\n  sessionId: \"abc123\"\n}\n\nStep 4: Check recent logs\n{\n  action: \"log\",\n  sessionId: \"abc123\",\n  offset: -30\n}\n\nStep 5: Read IMPLEMENTATION_PLAN.md to check for completion\n- Look for: \"STATUS: COMPLETE\" or \"STATUS: PLANNING_COMPLETE\"\n\nStep 6: If complete or timeout, cleanup\n{\n  action: \"kill\",\n  sessionId: \"abc123\"\n}\n\nExample 2: Codex with Full Auto\n\nAgent tool calls:\n\nexec tool:\n{\n  command: \"codex exec --full-auto --model anthropic/claude-opus-4 \\\"$(cat PROMPT.md)\\\"\",\n  workdir: \"/path/to/project\",\n  background: true,\n  pty: true,\n  timeout: 3600\n}\n\n# Then monitor with process tool as above\n\nCompletion Detection\n\nUse flexible regex to match variations:\n\ngrep -Eq \"STATUS:?\\s*(PLANNING_)?COMPLETE\" IMPLEMENTATION_PLAN.md\n\n\nMatches:\n\nSTATUS: COMPLETE\nSTATUS:COMPLETE\nSTATUS: PLANNING_COMPLETE\n## Status: PLANNING_COMPLETE\nSafety & Safeguards\nAuto-Approval Flags (Risky!)\nCodex: --full-auto (sandboxed, auto-approve) or --yolo (no sandbox!)\nClaude: --dangerously-skip-permissions\nRecommendation: Use sandboxes (docker/e2b/fly) and limited credentials\nEscape Hatches\nStop: Ctrl+C\nKill session: process tool with action: \"kill\"\nRollback: git reset --hard HEAD~N\nBest Practices\nStart small: Test with 1-2 iterations first\nWorkdir isolation: Prevent reading unrelated files\nSet timeouts: Default 1h may not fit all tasks\nMonitor actively: Check logs, don't terminate prematurely\nRequirements first: Clear specs before building\nBackpressure early: Add tests from the start\nTroubleshooting\nProblem\tSolution\nOpenCode hangs\tEnsure agent uses exec tool with pty: true\nSession won't start\tCheck CLI path, git repo, command syntax\nCompletion not detected\tVerify sentinel format in IMPLEMENTATION_PLAN.md\nProcess timeout\tAgent should increase timeout parameter or simplify tasks\nParallel conflicts\tAgent should use git worktrees for isolation\nCan't see progress\tAgent should use process tool with action: \"log\"\nLicense\n\nMIT\n\nCredits\n\nThis skill builds upon work by:\n\n@jordyvandomselaar - Original Ralph Loop concept and workflow design\n@steipete - Coding agent patterns and exec/process tool usage with pty support\n\nKey improvement: Uses OpenClaw's exec tool with pty: true to provide TTY for interactive CLIs, solving the hanging issue that occurs with simple background bash execution."
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/addozhang/ralph-loop-agent",
    "publisherUrl": "https://clawhub.ai/addozhang/ralph-loop-agent",
    "owner": "addozhang",
    "version": "1.1.0",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/ralph-loop-agent",
    "downloadUrl": "https://openagent3.xyz/downloads/ralph-loop-agent",
    "agentUrl": "https://openagent3.xyz/skills/ralph-loop-agent/agent",
    "manifestUrl": "https://openagent3.xyz/skills/ralph-loop-agent/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/ralph-loop-agent/agent.md"
  }
}