{"_id":"@aldine/ralph-protocol","_rev":"2-3ef2a6127efc44c28ec12e7e05382245","name":"@aldine/ralph-protocol","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@aldine/ralph-protocol","version":"0.1.0","keywords":["llm","agent","scaffold","protocol","autonomous","confucius","ralph","vscode","mcp"],"license":"MIT","_id":"@aldine/ralph-protocol@0.1.0","maintainers":[{"name":"aldine","email":"aldine.chapman1@gmail.com"}],"homepage":"https://github.com/Aldine/confucius-vision-scafolding-sdk#readme","bugs":{"url":"https://github.com/Aldine/confucius-vision-scafolding-sdk/issues"},"bin":{"ralph":"build/index.js"},"dist":{"shasum":"7e18567cb18a2418955907c5de94395244ef2691","tarball":"https://registry.npmjs.org/@aldine/ralph-protocol/-/ralph-protocol-0.1.0.tgz","fileCount":4,"integrity":"sha512-Re5S3kt+A732Kyeq0dmfa2dLTWQQ7epaDgBiIJmGWOu90wAELCCProXXmTYHzgVw1kaKuCeD0dupRs7SMqaAxQ==","signatures":[{"sig":"MEQCICVvi2fb5gDBSBKbKAoZ1k+2m7wiF60L4kbFp4VrqowZAiBv2HlMwUHaN4NRNZ8kHFxXwqg13BNGTdYY9+kO2Vj81w==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":24833},"type":"module","engines":{"node":">=18.18.0"},"gitHead":"a0da82f08742f8788f6098d8cff39759456eb7dd","private":false,"scripts":{"dev":"tsc -p tsconfig.json --watch","build":"tsc -p tsconfig.json","prepublishOnly":"npm run build"},"_npmUser":{"name":"aldine","email":"aldine.chapman1@gmail.com"},"repository":{"url":"git+https://github.com/Aldine/confucius-vision-scafolding-sdk.git","type":"git","directory":"packages/ralph-protocol"},"_npmVersion":"11.6.2","description":"Ralph Protocol v2 - Global Agent Scaffold System. Text-based OS for LLM agents.","directories":{},"_nodeVersion":"25.2.1","dependencies":{"commander":"^12.0.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.4.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/ralph-protocol_0.1.0_1768361102376_0.9835250983468424","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@aldine/ralph-protocol","version":"0.2.0","description":"Ralph Protocol v3 - Global Agent Scaffold with 3-Strike Reset and Token Rot Prevention","type":"module","private":false,"license":"MIT","repository":{"type":"git","url":"git+https://github.com/Aldine/confucius-vision-scafolding-sdk.git","directory":"packages/ralph-protocol"},"keywords":["llm","agent","scaffold","protocol","autonomous","confucius","ralph","vscode","mcp"],"engines":{"node":">=18.18.0"},"bin":{"ralph":"build/index.js"},"scripts":{"build":"tsc -p tsconfig.json","dev":"tsc -p tsconfig.json --watch","prepublishOnly":"npm run build"},"dependencies":{"commander":"^12.0.0"},"devDependencies":{"@types/node":"^20.0.0","typescript":"^5.4.0"},"gitHead":"f82949a6d7d3edb26ccf1bea9b9060c47db1cd01","_id":"@aldine/ralph-protocol@0.2.0","bugs":{"url":"https://github.com/Aldine/confucius-vision-scafolding-sdk/issues"},"homepage":"https://github.com/Aldine/confucius-vision-scafolding-sdk#readme","_nodeVersion":"25.2.1","_npmVersion":"11.6.2","dist":{"integrity":"sha512-zZfS+CC3enQDifekb/+4+NX8CWlkCqo2BzPVwI4pHfnj0gBl4hGSVJBrBcHGhvnHyAfXaPLYMivo6PGxEbIOFQ==","shasum":"258ee8f66a6efa6dd74a555e457fdcb8a2bf6da0","tarball":"https://registry.npmjs.org/@aldine/ralph-protocol/-/ralph-protocol-0.2.0.tgz","fileCount":4,"unpackedSize":49625,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIGolOOCj4Hbtq6w77ml9lF80P8+1OaYAn0FTHxWil/wwAiEA9BEF3nazERjQ404NVIvDfke2OSEmH0HFLwkt5S5FjFA="}]},"_npmUser":{"name":"aldine","email":"aldine.chapman1@gmail.com"},"directories":{},"maintainers":[{"name":"aldine","email":"aldine.chapman1@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ralph-protocol_0.2.0_1768361806311_0.2559101945931608"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-14T03:25:02.315Z","modified":"2026-01-14T03:36:46.564Z","0.1.0":"2026-01-14T03:25:02.515Z","0.2.0":"2026-01-14T03:36:46.447Z"},"bugs":{"url":"https://github.com/Aldine/confucius-vision-scafolding-sdk/issues"},"license":"MIT","homepage":"https://github.com/Aldine/confucius-vision-scafolding-sdk#readme","keywords":["llm","agent","scaffold","protocol","autonomous","confucius","ralph","vscode","mcp"],"repository":{"type":"git","url":"git+https://github.com/Aldine/confucius-vision-scafolding-sdk.git","directory":"packages/ralph-protocol"},"description":"Ralph Protocol v3 - Global Agent Scaffold with 3-Strike Reset and Token Rot Prevention","maintainers":[{"name":"aldine","email":"aldine.chapman1@gmail.com"}],"readme":"# @aldine/ralph-protocol\r\n\r\n> \"Files are state, memory is cache\"\r\n\r\n**Ralph Protocol v3** - A text-based operating system for LLM agents with **3-Strike Reset** and **Token Rot Prevention**. A global CLI tool that provides a hardened scaffold for autonomous agent development.\r\n\r\n## ✨ What's New in v3\r\n\r\n- **3-Strike Failure Policy**: Auto-reset after 3 failed attempts\r\n- **Token Rot Prevention**: Hard cap on confucius.md, automatic archiving\r\n- **Loop Scripts**: Bash/PowerShell scripts for continuous agent execution\r\n- **Subagent Spawning**: Fresh context generation for hard resets\r\n- **IDEA.md**: New file for Problem/User/Outcome\r\n- **Commit Verification**: Enforces state file updates on every commit\r\n\r\n## 🚀 Quick Start\r\n\r\n### Global Installation\r\n\r\n```bash\r\nnpm install -g @aldine/ralph-protocol\r\n```\r\n\r\n### Initialize a Project\r\n\r\n```bash\r\ncd your-project\r\nralph init --name \"My AI Project\" --vision \"Build something amazing\"\r\n```\r\n\r\nThis creates:\r\n```\r\nyour-project/\r\n├── IDEA.md          # Problem, User, Outcome (one paragraph each)\r\n├── PRD.md           # Scope, Non-goals, User Stories, Metrics, Constraints\r\n├── tasks.md         # Current Task, Backlog, In Progress, Completed\r\n├── progress.txt     # Append-only: DATETIME | TASK | ACTION | RESULT | NEXT\r\n├── confucius.md     # State document (<200 lines)\r\n├── PROMPT.md        # Agent operating instructions\r\n└── .ralph/\r\n    ├── archive/     # Archived confucius.md and logs\r\n    ├── logs/        # Command execution logs\r\n    └── strikes.json # Strike counter state\r\n```\r\n\r\n## 📖 Commands\r\n\r\n### Core Commands\r\n\r\n```bash\r\nralph init                    # Initialize Ralph Protocol\r\nralph status                  # Show status, strikes, token health\r\nralph context                 # Display full agent context\r\nralph task \"Build API\"        # Set the current task\r\nralph progress \"Fixed bug\"    # Append to progress.txt\r\nralph idea --problem \"...\"    # Edit IDEA.md\r\n```\r\n\r\n### 🔴 Strike System (NEW)\r\n\r\n```bash\r\nralph strike \"Agent looping\"  # Record a strike (max 3)\r\nralph unstrike                # Clear all strikes on success\r\nralph reset --error \"...\"     # Hard reset: new run ID, fresh context\r\nralph history                 # View strike history\r\nralph check \"agent output\"    # Check output for failure patterns\r\n```\r\n\r\n**3-Strike Rule:**\r\n- Strike 1: Ask for single smallest change\r\n- Strike 2: Force diagnosis (reproduce → isolate → test)\r\n- Strike 3: **Hard reset** - spawn fresh subagent\r\n\r\n### 🔄 Loop Execution (NEW)\r\n\r\n```bash\r\nralph loop --powershell       # Generate PowerShell loop script\r\nralph loop --bash             # Generate Bash loop script\r\nralph loop --agent \"claude\"   # Specify agent CLI command\r\n```\r\n\r\nThe loop script:\r\n1. Feeds context to agent\r\n2. Detects failure patterns in output\r\n3. Records strikes automatically\r\n4. Auto-resets after 3 strikes\r\n5. Supports pause/resume\r\n\r\n### 🧠 Subagent Spawning (NEW)\r\n\r\n```bash\r\nralph subagent                # Generate minimal context for fresh agent\r\nralph subagent --error \"...\"  # Include the failing error\r\nralph subagent --output ctx.md # Write to file\r\n```\r\n\r\n**What gets passed to subagent:**\r\n- PRD.md (full)\r\n- confucius.md (full)\r\n- Failing error (if provided)\r\n- Touched file tree (git status)\r\n\r\n**What does NOT get passed:**\r\n- Chat history\r\n- Old logs\r\n- Progress history\r\n\r\n### Safety Commands\r\n\r\n```bash\r\nralph run git status          # Execute command with safety checks\r\nralph validate \"rm -rf /\"     # Check if safe (without running)\r\nralph pause                   # Pause agent execution\r\nralph resume                  # Resume agent execution\r\nralph commit -m \"message\"     # Commit with state file verification\r\n```\r\n\r\n### Token Rot Prevention\r\n\r\n```bash\r\nralph trim                    # Trim confucius.md (archives old)\r\nralph archive                 # List archived files\r\n```\r\n\r\n## 🛡️ Security Features\r\n\r\n### Command Whitelist (Expanded)\r\n\r\n```\r\ngit, make, npm, npx, pnpm, yarn, bun\r\npython, python3, pip, pip3, uv, poetry\r\nls, cat, echo, grep, head, tail, touch, mkdir, cp, mv, pwd\r\nnode, tsc, jest, vitest, pytest, cargo, go, dotnet, java, mvn, gradle\r\ndocker, kubectl, terraform, az, aws, gcloud\r\ncurl, wget, jq, yq, sed, awk, find, xargs, sort, uniq, wc\r\ncode, claude, copilot\r\n```\r\n\r\n### Blocked Patterns\r\n\r\n- `rm -rf`, `--force`, `--hard`\r\n- Pipe to bash/sh (`| bash`, `| sh`)\r\n- `eval`, `$()`, backticks\r\n- `chmod 777`, `drop database`, `truncate table`\r\n- Redirect to /etc/ or /dev/\r\n- `curl | sudo`\r\n\r\n### Failure Detection Patterns\r\n\r\n```\r\nI cannot, unable to, need more context\r\nlooping, repeating, stuck, same error\r\nI don't have access, missing information\r\ncannot proceed\r\n```\r\n\r\n## 📋 File Formats\r\n\r\n### IDEA.md (NEW)\r\n\r\n```markdown\r\n# Project Idea\r\n\r\n## Problem\r\nUsers waste hours debugging because error messages are cryptic.\r\n\r\n## User\r\nDevelopers working on complex codebases.\r\n\r\n## Outcome\r\nClear, actionable error messages that reduce debug time by 50%.\r\n```\r\n\r\n### progress.txt (Enhanced Format)\r\n\r\n```\r\n# Format: DATETIME | TASK | ACTION | RESULT | NEXT | FILES/COMMITS\r\n\r\n2024-01-15T10:30:00Z | AUTH | Added JWT validation | Success | Add refresh tokens | src/auth.ts\r\n2024-01-15T11:00:00Z | STRIKE | Agent looping | Strike 1/3 | Retry | .ralph/strikes.json\r\n2024-01-15T11:15:00Z | RESET | Hard reset triggered | run_id=2 | Fresh context | .ralph/strikes.json\r\n```\r\n\r\n### confucius.md (Under 200 lines)\r\n\r\n```markdown\r\n# Confucius State Document\r\n> Target: Under 200 lines\r\n\r\n## North Star\r\nReduce debugging time by 50% with clear error messages.\r\n\r\n## Current State\r\n- What works: JWT validation passes all tests\r\n- What fails: Refresh token flow not implemented\r\n- What you learned: Token expiry needs 15-min buffer\r\n\r\n## Current Task\r\nImplement refresh token endpoint\r\n\r\n## Constraints\r\n- Stack: Node.js, Express, PostgreSQL\r\n- APIs: Auth0 for SSO\r\n- Environment: Node 20+\r\n\r\n## Decisions\r\n1. Using RS256 for JWT signing (security requirement)\r\n2. 15-min access token expiry with 7-day refresh\r\n\r\n## Open Questions\r\n- [ ] Should refresh tokens be single-use?\r\n\r\n## Next Steps\r\n1. Create /auth/refresh endpoint\r\n2. Add refresh_token table\r\n3. Write integration tests\r\n```\r\n\r\n### PROMPT.md (Agent Instructions)\r\n\r\n```markdown\r\nYou are Ralph, a build loop agent.\r\n\r\n## Rules\r\n1. Read PRD.md, progress.txt, confucius.md, tasks.md before doing work.\r\n2. Do the next smallest step toward the current task.\r\n3. If you change code, you must also update progress.txt and confucius.md.\r\n4. You must give a run command and a verification step.\r\n5. You must stop and ask for missing inputs if you cannot run or verify.\r\n\r\n## Output Format\r\nA. Plan: 3 steps max\r\nB. Changes: list files changed\r\nC. Commands: exact commands to run\r\nD. Verification: what output proves success\r\nE. Updates: append-ready text for progress.txt and confucius.md\r\n\r\n## Failure Definition\r\n- Output does not compile or run\r\n- Repeating without new evidence\r\n- Ignoring constraints in PRD.md\r\n- Changes without updating progress.txt/confucius.md\r\n```\r\n\r\n## 🔄 Typical Workflow\r\n\r\n```bash\r\n# 1. Initialize\r\nralph init --name \"Error Messages v2\"\r\n\r\n# 2. Define the idea\r\nralph idea --problem \"Cryptic errors\" --user \"Developers\" --outcome \"Clear messages\"\r\n\r\n# 3. Set first task\r\nralph task \"Add error code enum\"\r\n\r\n# 4. Generate loop script\r\nralph loop --powershell  # Creates ralph-loop.ps1\r\n\r\n# 5. Start the loop\r\n.\\ralph-loop.ps1\r\n\r\n# 6. On success, commit\r\nralph commit -m \"feat: Add error code enum\"\r\n\r\n# 7. Check status\r\nralph status\r\n```\r\n\r\n## 🆘 Recovery Scenarios\r\n\r\n### Agent is Looping\r\n\r\n```bash\r\nralph strike \"Repeating same fix attempt\"\r\nralph strike \"Still not working\"\r\nralph strike \"Third failure\"  # Triggers: ⚠️ MAX STRIKES REACHED\r\nralph reset --error \"TypeError: Cannot read property...\"\r\n# Paste .ralph/subagent_context.md into fresh chat\r\n```\r\n\r\n### Token Rot (confucius.md too big)\r\n\r\n```bash\r\nralph status  # Shows: Token Health: confucius.md 180/200 lines (90%)\r\nralph trim    # Archives and compresses\r\n```\r\n\r\n### Manual Intervention Needed\r\n\r\n```bash\r\nralph pause   # Creates .ralph/PAUSE\r\n# Fix things manually\r\nralph resume  # Removes .ralph/PAUSE\r\nralph unstrike  # Clear strikes after manual fix\r\n```\r\n\r\n## 📦 Related Packages\r\n\r\n- [@aldine/confucius-mcp-browser](https://www.npmjs.com/package/@aldine/confucius-mcp-browser) - MCP server for browser automation and visual QA\r\n\r\n## 📄 License\r\n\r\nMIT\r\n","readmeFilename":"README.md"}