{
  "schemaVersion": "1.0",
  "item": {
    "slug": "ralph-mode",
    "name": "Ralph Mode - Autonomous Development Loops",
    "source": "tencent",
    "type": "skill",
    "category": "开发工具",
    "sourceUrl": "https://clawhub.ai/richginsberg/ralph-mode",
    "canonicalUrl": "https://clawhub.ai/richginsberg/ralph-mode",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/ralph-mode",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=ralph-mode",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "SKILL.md",
      "scripts/loop.sh",
      "references/backpressure.md",
      "references/patterns.md"
    ],
    "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-05-07T17:22:31.273Z",
      "expiresAt": "2026-05-14T17:22:31.273Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=afrexai-annual-report",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=afrexai-annual-report",
        "contentDisposition": "attachment; filename=\"afrexai-annual-report-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-mode"
    },
    "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-mode",
    "agentPageUrl": "https://openagent3.xyz/skills/ralph-mode/agent",
    "manifestUrl": "https://openagent3.xyz/skills/ralph-mode/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/ralph-mode/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 Mode - Autonomous Development Loops",
        "body": "Ralph Mode implements the Ralph Wiggum technique adapted for OpenClaw: autonomous task completion through continuous iteration with backpressure gates, completion criteria, and structured planning."
      },
      {
        "title": "When to Use",
        "body": "Use Ralph Mode when:\n\nBuilding features that require multiple iterations and refinement\nWorking on complex projects with acceptance criteria to validate\nNeed automated testing, linting, or typecheck gates\nWant to track progress across many iterations systematically\nPrefer autonomous loops over manual turn-by-turn guidance"
      },
      {
        "title": "Three-Phase Workflow",
        "body": "Phase 1: Requirements Definition\n\nDocument specs in specs/ (one file per topic of concern)\nDefine acceptance criteria (observable, verifiable outcomes)\nCreate implementation plan with prioritized tasks\n\nPhase 2: Planning\n\nGap analysis: compare specs against existing code\nGenerate IMPLEMENTATION_PLAN.md with prioritized tasks\nNo implementation during this phase\n\nPhase 3: Building (Iterative)\n\nPick one task from plan per iteration\nImplement, validate, update plan, commit\nContinue until all tasks complete or criteria met"
      },
      {
        "title": "Backpressure Gates",
        "body": "Reject incomplete work automatically through validation:\n\nProgrammatic Gates (Always use these):\n\nTests: [test command] - Must pass before committing\nTypecheck: [typecheck command] - Catch type errors early\nLint: [lint command] - Enforce code quality\nBuild: [build command] - Verify integration\n\nSubjective Gates (Use for UX, design, quality):\n\nLLM-as-judge reviews for tone, aesthetics, usability\nBinary pass/fail - converges through iteration\nOnly add after programmatic gates work reliably"
      },
      {
        "title": "Context Efficiency",
        "body": "One task per iteration = fresh context each time\nSpawn sub-agents for exploration, not main context\nLean prompts = smart zone (~40-60% utilization)\nPlans are disposable - regenerate cheap vs. salvage"
      },
      {
        "title": "File Structure",
        "body": "Create this structure for each Ralph Mode project:\n\nproject-root/\n├── IMPLEMENTATION_PLAN.md     # Shared state, updated each iteration\n├── AGENTS.md                  # Build/test/lint commands (~60 lines)\n├── specs/                     # Requirements (one file per topic)\n│   ├── topic-a.md\n│   └── topic-b.md\n├── src/                        # Application code\n└── src/lib/                    # Shared utilities"
      },
      {
        "title": "IMPLEMENTATION_PLAN.md",
        "body": "Priority task list - single source of truth. Format:\n\n# Implementation Plan\n\n## In Progress\n- [ ] Task name (iteration N)\n  - Notes: discoveries, bugs, blockers\n\n## Completed\n- [x] Task name (iteration N)\n\n## Backlog\n- [ ] Future task"
      },
      {
        "title": "Topic Scope Test",
        "body": "Can you describe the topic in one sentence without \"and\"?\n\n✅ \"User authentication with JWT and session management\"\n❌ \"Auth, profiles, and billing\" → 3 topics"
      },
      {
        "title": "AGENTS.md - Operational Guide",
        "body": "Succinct guide for running the project. Keep under 60 lines:\n\n# Project Operations\n\n## Build Commands\nnpm run dev      # Development server\nnpm run build     # Production build\n\n## Validation\nnpm run test      # All tests\nnpm run lint      # ESLint\nnpm run typecheck  # TypeScript\nnpm run e2e       # E2E tests\n\n## Operational Notes\n- Tests must pass before committing\n- Typecheck failures block commits\n- Use existing utilities from src/lib over ad-hoc copies"
      },
      {
        "title": "Hats (Personas)",
        "body": "Specialized roles for different tasks:\n\nHat: Architect (@architect)\n\nHigh-level design, data modeling, API contracts\nFocus: patterns, scalability, maintainability\n\nHat: Implementer (@implementer)\n\nWrite code, implement features, fix bugs\nFocus: correctness, performance, test coverage\n\nHat: Tester (@tester)\n\nTest authoring, validation, edge cases\nFocus: coverage, reliability, reproducibility\n\nHat: Reviewer (@reviewer)\n\nCode reviews, PR feedback, quality assessment\nFocus: style, readability, adherence to specs\n\nUsage:\n\n\"Spawn a sub-agent with @architect hat to design the data model\""
      },
      {
        "title": "Outer Loop (You coordinate)",
        "body": "Your job as main agent: engineer setup, observe, course-correct.\n\nDon't allocate work to main context - Spawn sub-agents\nLet Ralph Ralph - LLM will self-identify, self-correct\nUse protection - Sandbox is your security boundary\nPlan is disposable - Regenerate when wrong/stale\nMove outside the loop - Sit and watch, don't micromanage"
      },
      {
        "title": "Inner Loop (Sub-agent executes)",
        "body": "Each sub-agent iteration:\n\nStudy - Read plan, specs, relevant code\nSelect - Pick most important uncompleted task\nImplement - Write code, one task only\nValidate - Run tests, lint, typecheck (backpressure)\nUpdate - Mark task done, note discoveries, commit\nExit - Next iteration starts fresh"
      },
      {
        "title": "Stopping Conditions",
        "body": "Loop ends when:\n\n✅ All IMPLEMENTATION_PLAN.md tasks completed\n✅ All acceptance criteria met\n✅ Tests passing, no blocking issues\n⚠️ Max iterations reached (configure limit)\n🛑 Manual stop (Ctrl+C)"
      },
      {
        "title": "Completion Criteria",
        "body": "Define success upfront - avoid \"seems done\" ambiguity."
      },
      {
        "title": "Programmatic (Measurable)",
        "body": "All tests pass: [test_command] returns 0\nTypecheck passes: No TypeScript errors\nBuild succeeds: Production bundle created\nCoverage threshold: e.g., 80%+"
      },
      {
        "title": "Subjective (LLM-as-Judge)",
        "body": "For quality criteria that resist automation:\n\n## Completion Check - UX Quality\nCriteria: Navigation is intuitive, primary actions are discoverable\nTest: User can complete core flow without confusion\n\n## Completion Check - Design Quality\nCriteria: Visual hierarchy is clear, brand consistency maintained\nTest: Layout follows established patterns\n\nRun LLM-as-judge sub-agent for binary pass/fail."
      },
      {
        "title": "Next.js Full Stack",
        "body": "specs/\n├── authentication.md\n├── database.md\n└── api-routes.md\n\nsrc/\n├── app/                    # App Router\n├── components/              # React components\n├── lib/                    # Utilities (db, auth, helpers)\n└── types/                   # TypeScript types\n\nAGENTS.md:\n  Build: npm run dev\n  Test: npm run test\n  Typecheck: npx tsc --noEmit\n  Lint: npm run lint"
      },
      {
        "title": "Python (Scripts/Notebooks/FastAPI)",
        "body": "specs/\n├── data-pipeline.md\n├── model-training.md\n└── api-endpoints.md\n\nsrc/\n├── pipeline.py\n├── models/\n├── api/\n└── tests/\n\nAGENTS.md:\n  Build: python -m src.main\n  Test: pytest\n  Typecheck: mypy src/\n  Lint: ruff check src/"
      },
      {
        "title": "GPU Workloads",
        "body": "specs/\n├── model-architecture.md\n├── training-data.md\n└── inference-pipeline.md\n\nsrc/\n├── models/\n├── training/\n├── inference/\n└── utils/\n\nAGENTS.md:\n  Train: python train.py\n  Test: pytest tests/\n  Lint: ruff check src/\n  GPU Check: nvidia-smi"
      },
      {
        "title": "Quick Start Command",
        "body": "Start a Ralph Mode session:\n\n\"Start Ralph Mode for my project at ~/projects/my-app. I want to implement user authentication with JWT.\n\nI will:\n\nCreate IMPLEMENTATION_PLAN.md with prioritized tasks\nSpawn sub-agents for iterative implementation\nApply backpressure gates (test, lint, typecheck)\nTrack progress and announce completion"
      },
      {
        "title": "Operational Learnings",
        "body": "When Ralph patterns emerge, update AGENTS.md:\n\n## Discovered Patterns\n\n- When adding API routes, also add to OpenAPI spec\n- Use existing db utilities from src/lib/db over direct calls\n- Test files must be co-located with implementation"
      },
      {
        "title": "Escape Hatches",
        "body": "When trajectory goes wrong:\n\nCtrl+C - Stop loop immediately\nRegenerate plan - \"Discard IMPLEMENTATION_PLAN.md and re-plan\"\nReset - \"Git reset to last known good state\"\nScope down - Create smaller scoped plan for specific work"
      },
      {
        "title": "Advanced: LLM-as-Judge Fixture",
        "body": "For subjective criteria (tone, aesthetics, UX):\n\nCreate src/lib/llm-review.ts:\n\ninterface ReviewResult {\n  pass: boolean;\n  feedback?: string;\n}\n\nasync function createReview(config: {\n  criteria: string;\n  artifact: string; // text or screenshot path\n}): Promise<ReviewResult>;\n\nSub-agents discover and use this pattern for binary pass/fail checks."
      },
      {
        "title": "Critical Operational Requirements",
        "body": "Based on empirical usage, enforce these practices to avoid silent failures:"
      },
      {
        "title": "1. Mandatory Progress Logging",
        "body": "Ralph MUST write to PROGRESS.md after EVERY iteration. This is non-negotiable.\n\nCreate PROGRESS.md in project root at start:\n\n# Ralph: [Task Name]\n\n## Iteration [N] - [Timestamp]\n\n### Status\n- [ ] In Progress | [ ] Blocked | [ ] Complete\n\n### What Was Done\n- [Item 1]\n- [Item 2]\n\n### Blockers\n- None | [Description]\n\n### Next Step\n[Specific next task from IMPLEMENTATION_PLAN.md]\n\n### Files Changed\n- `path/to/file.ts` - [brief description]\n\nWhy: External observers (parent agents, crons, humans) can tail one file instead of scanning directories or inferring state from session logs."
      },
      {
        "title": "2. Session Isolation & Cleanup",
        "body": "Before spawning a new Ralph session:\n\nCheck for existing Ralph sub-agents via sessions_list\nKill or verify completion of previous sessions\nDo NOT spawn overlapping Ralph sessions on same codebase\n\nAnti-pattern: Spawning Ralph v2 while v1 is still running = file conflicts, race conditions, lost work."
      },
      {
        "title": "3. Explicit Path Verification",
        "body": "Never assume directory structure. At start of each iteration:\n\n// Verify current working directory\nconst cwd = process.cwd();\nconsole.log(`Working in: ${cwd}`);\n\n// Verify expected paths exist\nif (!fs.existsSync('./src/app')) {\n  console.error('Expected ./src/app, found:', fs.readdirSync('.'));\n  // Adapt or fail explicitly\n}\n\nWhy: Ralph may be spawned from different contexts with different working directories."
      },
      {
        "title": "4. Completion Signal Protocol",
        "body": "When done, Ralph MUST:\n\nWrite final PROGRESS.md with \"## Status: COMPLETE\"\nList all created/modified files\nExit cleanly (no hanging processes)\n\nExample completion PROGRESS.md:\n\n# Ralph: Influencer Detail Page\n\n## Status: COMPLETE ✅\n\n**Finished:** [ISO timestamp]\n\n### Final Verification\n- [x] TypeScript: Pass\n- [x] Tests: Pass  \n- [x] Build: Pass\n\n### Files Created\n- `src/app/feature/page.tsx`\n- `src/app/api/feature/route.ts`\n\n### Testing Instructions\n1. Run: `npm run dev`\n2. Visit: `http://localhost:3000/feature`\n3. Verify: [specific checks]"
      },
      {
        "title": "5. Error Handling Requirements",
        "body": "If Ralph encounters unrecoverable errors:\n\nLog to PROGRESS.md with \"## Status: BLOCKED\"\nDescribe blocker in detail\nList attempted solutions\nExit cleanly (don't hang)\n\nDo not silently fail. A Ralph that stops iterating with no progress log is indistinguishable from one still working."
      },
      {
        "title": "6. Iteration Time Limits",
        "body": "Set explicit iteration timeouts:\n\n## Operational Parameters\n- Max iteration time: 10 minutes\n- Total session timeout: 60 minutes\n- If iteration exceeds limit: Log blocker, exit\n\nWhy: Prevents infinite loops on stuck tasks, allows parent agent to intervene."
      },
      {
        "title": "Memory Updates",
        "body": "After each Ralph Mode session, document:\n\n## [Date] Ralph Mode Session\n\n**Project:** [project-name]\n**Duration:** [iterations]\n**Outcome:** success / partial / blocked\n**Learnings:**\n- What worked well\n- What needs adjustment\n- Patterns to add to AGENTS.md"
      },
      {
        "title": "Appendix: Hall of Failures",
        "body": "Common anti-patterns observed:\n\nAnti-PatternConsequencePreventionNo progress loggingParent agent cannot determine statusMandatory PROGRESS.mdSilent failureWork lost, time wastedExplicit error loggingOverlapping sessionsFile conflicts, corrupt stateCheck/cleanup before spawnPath assumptionsWrong directory, wrong filesExplicit verificationNo completion signalParent waits indefinitelyClear COMPLETE statusInfinite iterationResource waste, no progressTime limits + blockersComplex initial promptsSub-agent never starts (empty session logs)SIMPLIFY instructions"
      },
      {
        "title": "Problem: Sub-agents spawn but don't execute",
        "body": "Evidence: Empty session logs (2 bytes), no tool calls, 0 tokens used"
      },
      {
        "title": "Root Causes",
        "body": "Instructions too complex - Overwhelms isolated session initialization\nNo clear execution trigger - Agent doesn't know to start\nBranching logic - \"If X do Y, if Z do W\" confuses task selection\nMultiple files mentioned - Can't decide which to start with"
      },
      {
        "title": "Fix: SIMPLIFIED Ralph Task Template",
        "body": "## Task: [ONE specific thing]\n\n**File:** exact/path/to/file.ts\n**What:** Exact description of change\n**Validate:** Exact command to run\n**Then:** Update PROGRESS.md and exit\n\n## Rules\n1. Do NOT look at other files\n2. Do NOT \"check first\"\n3. Make the change, validate, exit"
      },
      {
        "title": "BEFORE (Bad - causes stalls):",
        "body": "Fix all TypeScript errors across these files:\n- lib/db.ts has 2 errors\n- lib/proposal-service.ts has 5 errors\n- route.ts has errors\nCheck which ones to fix first, then..."
      },
      {
        "title": "AFTER (Good - executes):",
        "body": "Fix lib/db.ts line 27:\nChange: PoolClient to pg.PoolClient\nValidate: npm run typecheck\nExit immediately after"
      },
      {
        "title": "CRITICAL: Single File Rule",
        "body": "Each Ralph iteration gets ONE file. Not \"all errors\", not \"check then decide\". ONE file, ONE change, validate, exit."
      },
      {
        "title": "CRITICAL: Update PROGRESS.md",
        "body": "MANDATORY: After EVERY iteration, update PROGRESS.md with:\n\n## Iteration [N] - [Timestamp]\n\n### Status: Complete ✅ | Blocked ⛔ | Failed ❌\n\n### What Was Done\n- [Specific changes made]\n\n### Validation\n- [Test/lint/typecheck results]\n\n### Next Step\n- [What should happen next]\n\nWhy this matters: Cron job reads PROGRESS.md for status updates. If not updated, status appears stale/repetitive."
      },
      {
        "title": "Debugging Ralph Stalls",
        "body": "If Ralph stalls:\n\nCheck session logs (should show tool calls within 60s)\nIf empty after spawn → instructions too complex\nReduce: ONE file, ONE line number, ONE change\nShorter timeout forces smaller tasks (300s not 600s)"
      },
      {
        "title": "Fixing Stale Status Reports",
        "body": "If cron reports same status repeatedly:\n\nCheck PROGRESS.md was updated by sub-agent\nIf not updated → sub-agent skipped documentation step\nUpdate skill: Add \"MANDATORY PROGRESS.md update\" to prompt\nManual fix: Update PROGRESS.md to reflect actual state"
      },
      {
        "title": "Summary",
        "body": "Ralph works when: Single file focus + explicit change + validate + exit\nRalph stalls when: Complex decisions + multiple files + conditional logic"
      }
    ],
    "body": "Ralph Mode - Autonomous Development Loops\n\nRalph Mode implements the Ralph Wiggum technique adapted for OpenClaw: autonomous task completion through continuous iteration with backpressure gates, completion criteria, and structured planning.\n\nWhen to Use\n\nUse Ralph Mode when:\n\nBuilding features that require multiple iterations and refinement\nWorking on complex projects with acceptance criteria to validate\nNeed automated testing, linting, or typecheck gates\nWant to track progress across many iterations systematically\nPrefer autonomous loops over manual turn-by-turn guidance\nCore Principles\nThree-Phase Workflow\n\nPhase 1: Requirements Definition\n\nDocument specs in specs/ (one file per topic of concern)\nDefine acceptance criteria (observable, verifiable outcomes)\nCreate implementation plan with prioritized tasks\n\nPhase 2: Planning\n\nGap analysis: compare specs against existing code\nGenerate IMPLEMENTATION_PLAN.md with prioritized tasks\nNo implementation during this phase\n\nPhase 3: Building (Iterative)\n\nPick one task from plan per iteration\nImplement, validate, update plan, commit\nContinue until all tasks complete or criteria met\nBackpressure Gates\n\nReject incomplete work automatically through validation:\n\nProgrammatic Gates (Always use these):\n\nTests: [test command] - Must pass before committing\nTypecheck: [typecheck command] - Catch type errors early\nLint: [lint command] - Enforce code quality\nBuild: [build command] - Verify integration\n\nSubjective Gates (Use for UX, design, quality):\n\nLLM-as-judge reviews for tone, aesthetics, usability\nBinary pass/fail - converges through iteration\nOnly add after programmatic gates work reliably\nContext Efficiency\nOne task per iteration = fresh context each time\nSpawn sub-agents for exploration, not main context\nLean prompts = smart zone (~40-60% utilization)\nPlans are disposable - regenerate cheap vs. salvage\nFile Structure\n\nCreate this structure for each Ralph Mode project:\n\nproject-root/\n├── IMPLEMENTATION_PLAN.md     # Shared state, updated each iteration\n├── AGENTS.md                  # Build/test/lint commands (~60 lines)\n├── specs/                     # Requirements (one file per topic)\n│   ├── topic-a.md\n│   └── topic-b.md\n├── src/                        # Application code\n└── src/lib/                    # Shared utilities\n\nIMPLEMENTATION_PLAN.md\n\nPriority task list - single source of truth. Format:\n\n# Implementation Plan\n\n## In Progress\n- [ ] Task name (iteration N)\n  - Notes: discoveries, bugs, blockers\n\n## Completed\n- [x] Task name (iteration N)\n\n## Backlog\n- [ ] Future task\n\nTopic Scope Test\n\nCan you describe the topic in one sentence without \"and\"?\n\n✅ \"User authentication with JWT and session management\"\n❌ \"Auth, profiles, and billing\" → 3 topics\nAGENTS.md - Operational Guide\n\nSuccinct guide for running the project. Keep under 60 lines:\n\n# Project Operations\n\n## Build Commands\nnpm run dev      # Development server\nnpm run build     # Production build\n\n## Validation\nnpm run test      # All tests\nnpm run lint      # ESLint\nnpm run typecheck  # TypeScript\nnpm run e2e       # E2E tests\n\n## Operational Notes\n- Tests must pass before committing\n- Typecheck failures block commits\n- Use existing utilities from src/lib over ad-hoc copies\n\nHats (Personas)\n\nSpecialized roles for different tasks:\n\nHat: Architect (@architect)\n\nHigh-level design, data modeling, API contracts\nFocus: patterns, scalability, maintainability\n\nHat: Implementer (@implementer)\n\nWrite code, implement features, fix bugs\nFocus: correctness, performance, test coverage\n\nHat: Tester (@tester)\n\nTest authoring, validation, edge cases\nFocus: coverage, reliability, reproducibility\n\nHat: Reviewer (@reviewer)\n\nCode reviews, PR feedback, quality assessment\nFocus: style, readability, adherence to specs\n\nUsage:\n\n\"Spawn a sub-agent with @architect hat to design the data model\"\n\nLoop Mechanics\nOuter Loop (You coordinate)\n\nYour job as main agent: engineer setup, observe, course-correct.\n\nDon't allocate work to main context - Spawn sub-agents\nLet Ralph Ralph - LLM will self-identify, self-correct\nUse protection - Sandbox is your security boundary\nPlan is disposable - Regenerate when wrong/stale\nMove outside the loop - Sit and watch, don't micromanage\nInner Loop (Sub-agent executes)\n\nEach sub-agent iteration:\n\nStudy - Read plan, specs, relevant code\nSelect - Pick most important uncompleted task\nImplement - Write code, one task only\nValidate - Run tests, lint, typecheck (backpressure)\nUpdate - Mark task done, note discoveries, commit\nExit - Next iteration starts fresh\nStopping Conditions\n\nLoop ends when:\n\n✅ All IMPLEMENTATION_PLAN.md tasks completed\n✅ All acceptance criteria met\n✅ Tests passing, no blocking issues\n⚠️ Max iterations reached (configure limit)\n🛑 Manual stop (Ctrl+C)\nCompletion Criteria\n\nDefine success upfront - avoid \"seems done\" ambiguity.\n\nProgrammatic (Measurable)\nAll tests pass: [test_command] returns 0\nTypecheck passes: No TypeScript errors\nBuild succeeds: Production bundle created\nCoverage threshold: e.g., 80%+\nSubjective (LLM-as-Judge)\n\nFor quality criteria that resist automation:\n\n## Completion Check - UX Quality\nCriteria: Navigation is intuitive, primary actions are discoverable\nTest: User can complete core flow without confusion\n\n## Completion Check - Design Quality\nCriteria: Visual hierarchy is clear, brand consistency maintained\nTest: Layout follows established patterns\n\n\nRun LLM-as-judge sub-agent for binary pass/fail.\n\nTechnology-Specific Patterns\nNext.js Full Stack\nspecs/\n├── authentication.md\n├── database.md\n└── api-routes.md\n\nsrc/\n├── app/                    # App Router\n├── components/              # React components\n├── lib/                    # Utilities (db, auth, helpers)\n└── types/                   # TypeScript types\n\nAGENTS.md:\n  Build: npm run dev\n  Test: npm run test\n  Typecheck: npx tsc --noEmit\n  Lint: npm run lint\n\nPython (Scripts/Notebooks/FastAPI)\nspecs/\n├── data-pipeline.md\n├── model-training.md\n└── api-endpoints.md\n\nsrc/\n├── pipeline.py\n├── models/\n├── api/\n└── tests/\n\nAGENTS.md:\n  Build: python -m src.main\n  Test: pytest\n  Typecheck: mypy src/\n  Lint: ruff check src/\n\nGPU Workloads\nspecs/\n├── model-architecture.md\n├── training-data.md\n└── inference-pipeline.md\n\nsrc/\n├── models/\n├── training/\n├── inference/\n└── utils/\n\nAGENTS.md:\n  Train: python train.py\n  Test: pytest tests/\n  Lint: ruff check src/\n  GPU Check: nvidia-smi\n\nQuick Start Command\n\nStart a Ralph Mode session:\n\n\"Start Ralph Mode for my project at ~/projects/my-app. I want to implement user authentication with JWT.\n\n\nI will:\n\nCreate IMPLEMENTATION_PLAN.md with prioritized tasks\nSpawn sub-agents for iterative implementation\nApply backpressure gates (test, lint, typecheck)\nTrack progress and announce completion\nOperational Learnings\n\nWhen Ralph patterns emerge, update AGENTS.md:\n\n## Discovered Patterns\n\n- When adding API routes, also add to OpenAPI spec\n- Use existing db utilities from src/lib/db over direct calls\n- Test files must be co-located with implementation\n\nEscape Hatches\n\nWhen trajectory goes wrong:\n\nCtrl+C - Stop loop immediately\nRegenerate plan - \"Discard IMPLEMENTATION_PLAN.md and re-plan\"\nReset - \"Git reset to last known good state\"\nScope down - Create smaller scoped plan for specific work\nAdvanced: LLM-as-Judge Fixture\n\nFor subjective criteria (tone, aesthetics, UX):\n\nCreate src/lib/llm-review.ts:\n\ninterface ReviewResult {\n  pass: boolean;\n  feedback?: string;\n}\n\nasync function createReview(config: {\n  criteria: string;\n  artifact: string; // text or screenshot path\n}): Promise<ReviewResult>;\n\n\nSub-agents discover and use this pattern for binary pass/fail checks.\n\nCritical Operational Requirements\n\nBased on empirical usage, enforce these practices to avoid silent failures:\n\n1. Mandatory Progress Logging\n\nRalph MUST write to PROGRESS.md after EVERY iteration. This is non-negotiable.\n\nCreate PROGRESS.md in project root at start:\n\n# Ralph: [Task Name]\n\n## Iteration [N] - [Timestamp]\n\n### Status\n- [ ] In Progress | [ ] Blocked | [ ] Complete\n\n### What Was Done\n- [Item 1]\n- [Item 2]\n\n### Blockers\n- None | [Description]\n\n### Next Step\n[Specific next task from IMPLEMENTATION_PLAN.md]\n\n### Files Changed\n- `path/to/file.ts` - [brief description]\n\n\nWhy: External observers (parent agents, crons, humans) can tail one file instead of scanning directories or inferring state from session logs.\n\n2. Session Isolation & Cleanup\n\nBefore spawning a new Ralph session:\n\nCheck for existing Ralph sub-agents via sessions_list\nKill or verify completion of previous sessions\nDo NOT spawn overlapping Ralph sessions on same codebase\n\nAnti-pattern: Spawning Ralph v2 while v1 is still running = file conflicts, race conditions, lost work.\n\n3. Explicit Path Verification\n\nNever assume directory structure. At start of each iteration:\n\n// Verify current working directory\nconst cwd = process.cwd();\nconsole.log(`Working in: ${cwd}`);\n\n// Verify expected paths exist\nif (!fs.existsSync('./src/app')) {\n  console.error('Expected ./src/app, found:', fs.readdirSync('.'));\n  // Adapt or fail explicitly\n}\n\n\nWhy: Ralph may be spawned from different contexts with different working directories.\n\n4. Completion Signal Protocol\n\nWhen done, Ralph MUST:\n\nWrite final PROGRESS.md with \"## Status: COMPLETE\"\nList all created/modified files\nExit cleanly (no hanging processes)\n\nExample completion PROGRESS.md:\n\n# Ralph: Influencer Detail Page\n\n## Status: COMPLETE ✅\n\n**Finished:** [ISO timestamp]\n\n### Final Verification\n- [x] TypeScript: Pass\n- [x] Tests: Pass  \n- [x] Build: Pass\n\n### Files Created\n- `src/app/feature/page.tsx`\n- `src/app/api/feature/route.ts`\n\n### Testing Instructions\n1. Run: `npm run dev`\n2. Visit: `http://localhost:3000/feature`\n3. Verify: [specific checks]\n\n5. Error Handling Requirements\n\nIf Ralph encounters unrecoverable errors:\n\nLog to PROGRESS.md with \"## Status: BLOCKED\"\nDescribe blocker in detail\nList attempted solutions\nExit cleanly (don't hang)\n\nDo not silently fail. A Ralph that stops iterating with no progress log is indistinguishable from one still working.\n\n6. Iteration Time Limits\n\nSet explicit iteration timeouts:\n\n## Operational Parameters\n- Max iteration time: 10 minutes\n- Total session timeout: 60 minutes\n- If iteration exceeds limit: Log blocker, exit\n\n\nWhy: Prevents infinite loops on stuck tasks, allows parent agent to intervene.\n\nMemory Updates\n\nAfter each Ralph Mode session, document:\n\n## [Date] Ralph Mode Session\n\n**Project:** [project-name]\n**Duration:** [iterations]\n**Outcome:** success / partial / blocked\n**Learnings:**\n- What worked well\n- What needs adjustment\n- Patterns to add to AGENTS.md\n\nAppendix: Hall of Failures\n\nCommon anti-patterns observed:\n\nAnti-Pattern\tConsequence\tPrevention\nNo progress logging\tParent agent cannot determine status\tMandatory PROGRESS.md\nSilent failure\tWork lost, time wasted\tExplicit error logging\nOverlapping sessions\tFile conflicts, corrupt state\tCheck/cleanup before spawn\nPath assumptions\tWrong directory, wrong files\tExplicit verification\nNo completion signal\tParent waits indefinitely\tClear COMPLETE status\nInfinite iteration\tResource waste, no progress\tTime limits + blockers\nComplex initial prompts\tSub-agent never starts (empty session logs)\tSIMPLIFY instructions\nNEW: Session Initialization Best Practices (2025-02-07)\nProblem: Sub-agents spawn but don't execute\n\nEvidence: Empty session logs (2 bytes), no tool calls, 0 tokens used\n\nRoot Causes\nInstructions too complex - Overwhelms isolated session initialization\nNo clear execution trigger - Agent doesn't know to start\nBranching logic - \"If X do Y, if Z do W\" confuses task selection\nMultiple files mentioned - Can't decide which to start with\nFix: SIMPLIFIED Ralph Task Template\n## Task: [ONE specific thing]\n\n**File:** exact/path/to/file.ts\n**What:** Exact description of change\n**Validate:** Exact command to run\n**Then:** Update PROGRESS.md and exit\n\n## Rules\n1. Do NOT look at other files\n2. Do NOT \"check first\"\n3. Make the change, validate, exit\n\nBEFORE (Bad - causes stalls):\nFix all TypeScript errors across these files:\n- lib/db.ts has 2 errors\n- lib/proposal-service.ts has 5 errors\n- route.ts has errors\nCheck which ones to fix first, then...\n\nAFTER (Good - executes):\nFix lib/db.ts line 27:\nChange: PoolClient to pg.PoolClient\nValidate: npm run typecheck\nExit immediately after\n\nCRITICAL: Single File Rule\n\nEach Ralph iteration gets ONE file. Not \"all errors\", not \"check then decide\". ONE file, ONE change, validate, exit.\n\nCRITICAL: Update PROGRESS.md\n\nMANDATORY: After EVERY iteration, update PROGRESS.md with:\n\n## Iteration [N] - [Timestamp]\n\n### Status: Complete ✅ | Blocked ⛔ | Failed ❌\n\n### What Was Done\n- [Specific changes made]\n\n### Validation\n- [Test/lint/typecheck results]\n\n### Next Step\n- [What should happen next]\n\n\nWhy this matters: Cron job reads PROGRESS.md for status updates. If not updated, status appears stale/repetitive.\n\nDebugging Ralph Stalls\n\nIf Ralph stalls:\n\nCheck session logs (should show tool calls within 60s)\nIf empty after spawn → instructions too complex\nReduce: ONE file, ONE line number, ONE change\nShorter timeout forces smaller tasks (300s not 600s)\nFixing Stale Status Reports\n\nIf cron reports same status repeatedly:\n\nCheck PROGRESS.md was updated by sub-agent\nIf not updated → sub-agent skipped documentation step\nUpdate skill: Add \"MANDATORY PROGRESS.md update\" to prompt\nManual fix: Update PROGRESS.md to reflect actual state\nSummary\n\nRalph works when: Single file focus + explicit change + validate + exit Ralph stalls when: Complex decisions + multiple files + conditional logic"
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/richginsberg/ralph-mode",
    "publisherUrl": "https://clawhub.ai/richginsberg/ralph-mode",
    "owner": "richginsberg",
    "version": "1.2.0",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/ralph-mode",
    "downloadUrl": "https://openagent3.xyz/downloads/ralph-mode",
    "agentUrl": "https://openagent3.xyz/skills/ralph-mode/agent",
    "manifestUrl": "https://openagent3.xyz/skills/ralph-mode/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/ralph-mode/agent.md"
  }
}