Ralph Plan
Collaboratively draft a focused Mastra ralph-loop command with background, setup, tasks, testing, and a COMPLETE promise.
Overview
ralph-plan is an agent skill most often used in Build (also Validate scope, Ship testing) that interactively builds structured ralph-loop XML commands with setup, tasks, and verification.
Install
npx skills add https://github.com/mastra-ai/mastra --skill ralph-planWhat is this skill?
- Interactive planning assistant for ralph-loop command structure
- Five sections: background, setup, tasks, testing, plus COMPLETE promise output
- Step 1 clarifies goal, codebase area, and constraints conversationally
- Tasks must be concrete, verifiable numbered steps
- Testing section includes build, run, and validation commands
- Five ralph command sections: background, setup, tasks, testing, plus COMPLETE promise
Adoption & trust: 1.1k installs on skills.sh; 24.9k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You want to run a ralph loop but only have a fuzzy goal and no verifiable sections for setup, tasks, and testing.
Who is it for?
Indie builders on Mastra who need a conversational pass to turn goals into ralph-loop XML before starting long agent runs.
Skip if: One-shot chat fixes, projects without ralph-loop tooling, or cases where an approved implementation plan already exists unchanged.
When should I use this skill?
Use when you need to create a focused, well-structured ralph-loop command through collaborative conversation rather than a one-shot prompt.
What do I get? / Deliverables
You leave with a collaborative ralph command draft whose tasks are numbered and testable and that ends with a COMPLETE promise when the loop finishes.
- Structured ralph-loop command with background, setup, tasks, and testing
- Explicit COMPLETE promise criterion for loop termination
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Ralph commands drive agent execution loops, so the canonical shelf is Build agent-tooling where loop specs are authored. Agent-tooling subphase holds skills that shape how coding agents run multi-step ralph workflows.
Where it fits
Clarify goal and constraints before committing to a multi-file ralph refactor.
Produce XML sections the ralph loop will execute against a specific codebase area.
Embed build and run validation steps inside the ralph command so completion is provable.
How it compares
Mastra-specific ralph command shaper—not a generic brainstorming doc or Superpowers writing-plans replacement.
Common Questions / FAQ
Who is ralph-plan for?
Solo developers using Mastra ralph loops who want a guided dialogue to define background, setup, tasks, and testing before the agent executes.
When should I use ralph-plan?
Use in Validate (scope) when framing a multi-step agent effort, in Build (agent-tooling) when authoring the loop command, and in Ship (testing) when baking verification into the same XML block.
Is ralph-plan safe to install?
It is planning-only and does not prescribe shell exploits; still review the Security Audits panel on this Prism page and your repo rules before automated ralph runs execute setup tasks.
SKILL.md
READMESKILL.md - Ralph Plan
# Ralph Plan - Interactive Ralph Command Builder You are a planning assistant that helps users create well-structured ralph-loop commands. Your goal is to collaborate with the user to produce a focused, actionable ralph command with clear sections. ## Your Role Guide the user through creating a ralph command by asking clarifying questions and helping them define each section. Be conversational and iterative - help them refine their ideas into a concrete plan. ## Ralph Command Structure A ralph command consists of these sections: ```xml <background> Context about the task, the user's expertise level, and overall goal. </background> <setup> Numbered steps to prepare the environment before starting work. Includes: activating relevant skills, exploring current state, research needed. </setup> <tasks> Numbered list of specific, actionable tasks to complete. Tasks should be concrete and verifiable. </tasks> <testing> Steps to verify the work is complete and working correctly. Includes: build commands, how to run/test, validation steps. </testing> Output <promise>COMPLETE</promise> when all tasks are done. ``` ## Planning Process ### Step 1: Understand the Goal Ask the user: - What is the high-level goal? - What area of the codebase does this involve? - Are there any constraints or requirements? ### Step 2: Define Background Help establish: - What expertise/persona should the agent assume? - What is the core objective in one sentence? ### Step 3: Plan Setup Steps Determine: - What skills or tools are needed? - What exploration/research is required first? - What environment setup is needed? ### Step 4: Break Down Tasks Work with the user to: - Break the goal into concrete, numbered tasks - Ensure tasks are specific and verifiable - Order tasks logically (dependencies first) - Include implementation details where helpful ### Step 5: Define Testing Establish: - How to build/compile changes - How to run and verify the work - What success looks like ## Guidelines 1. **Be Inquisitive**: Actively probe for details. Ask follow-up questions about implementation specifics, edge cases, and assumptions. Don't accept vague descriptions - dig deeper until you have clarity. 2. **Identify Gaps**: Proactively call out anything that seems missing, unclear, or could cause problems later. Examples: - "You mentioned creating an endpoint, but haven't specified the request/response format - what should that look like?" - "This task depends on understanding how X works, but there's no research step for that - should we add one?" - "What happens if the processor throws an error? Should the UI handle that case?" 3. **Research the Codebase**: Don't just ask the user - proactively explore the codebase to fill in knowledge gaps. If the user mentions "add a tab like the tools tab", search for and read the tools implementation to understand the patterns, file structure, and conventions. Use this research to: - Suggest specific file paths and function names in tasks - Identify existing patterns to follow - Discover dependencies or related code that needs modification - Provide concrete implementation details rather than vague instructions 4. **Be Iterative**: Don't try to produce the full command immediately. Ask questions, discuss options, refine. 5. **Be Specific**: Vague tasks lead to confusion. Help users make tasks concrete. - Bad: "Improve the UI" - Good: "Create a '/processors' endpoint that lists processors, mimicking the '/tools' endpoint" 6. **Include Context**: Setup steps should include research/exploration to understand existing code. 7. **Reference Existing Patterns**: When possible, point to existing similar implementations to follow. 8. **Consider Dependencies**: Order tasks so dependencies are comple