ralph

# Ralph - Autonomous Agent Ralph breaks big projects into user stories and executes them autonomously. The workflow: 1. **Create a PRD** - Define user stories with acceptance criteria 2. **Run it** - `ralph.mjs create --prd path/to/prd.json --start` 3. **Monitor** - `ralph.mjs logs <session-id> --follow` ## Creating a PRD Create a project folder and prd.json: ``` .claude/skills/ralph/projects/<project-name>/prd.json ``` ### PRD Structure ```json { "description": "Brief description of the feature", "branchName": "feature/my-feature", "userStories": [ { "id": "US001", "title": "Short descriptive title", "description": "As a [user], I want [feature] so that [benefit]", "acceptanceCriteria": [ "Specific testable criterion", "Typecheck passes" ], "priority": 1, "passes": false } ] } ``` ### Story Guidelines - **Priority 1**: Foundation - migrations, types, base components - **Priority 2-3**: Core functionality - **Priority 4+**: Secondary features, polish - Each story should touch 1-3 files, not 10-file refactors - Include "Typecheck passes" in acceptance criteria ## CLI Commands The daemon starts automatically when you run any command. ### Running Sessions ```bash # Create and start a session ralph.mjs create --prd path/to/prd.json --start # List all sessions ralph.mjs list # Check session status ralph.mjs status <session-id> # Follow logs in real-time ralph.mjs logs <session-id> --follow ``` ### Session Control ```bash # Pause a session ralph.mjs pause <session-id> --reason "Waiting for API" # Resume with guidance ralph.mjs resume <session-id> --guidance "API is ready on port 3000" # Inject guidance into running session ralph.mjs inject <session-id> --message "Try using the helper in utils.ts" # Abort a session ralph.mjs abort <session-id> ``` ### Orchestration (Multi-Level) For orchestrator PRDs that spawn child sessions: ```bash # Spawn a child session ralph.mjs spawn <parent-id> --prd child/prd.json --start # List children of a session ralph.mjs children <session-id> # Wait for all children to complete ralph.mjs wait <session-id> # View session tree ralph.mjs tree <session-id> # Abort parent and all children ralph.mjs abort <session-id> --cascade ``` ## PRD Types | Type | Use Case | |------|----------| | `code` (default) | Implement features, commit code | | `orchestrator` | Coordinate multiple sub-Ralphs | | `testing` | Browser automation testing | Set via `"type": "orchestrator"` in prd.json. ## Full CLI Reference Run `ralph.mjs --help` for complete documentation. --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/civitai) — claim your Tome and manage your conversions. <!-- tomevault:4.0:skill_md:2026-04-11 -->