
ralph-prep
Generate Ralph Wiggum Method artifacts for autonomous AI coding loops
- version
- 1.0.0
- GitHub stars
- 13
Install
/plugin install ralph-prep@claude-code-toolkitRun it inside Claude Code after adding the marketplace with /plugin marketplace add dariuszparys/claude-code-toolkit.
Contents
Discovered from sourceCommands 1
Generate Ralph Wiggum Method Artifacts
Generate a complete set of Ralph artifacts for autonomous AI coding loops.
Arguments
--from-file <path>: Load task details from a YAML template file<output-dir>: Directory to create artifacts in (required)
Parse arguments from: $ARGUMENTS
Mode Detection
Check if --from-file is in the arguments:
- If yes: Read the template file and extract task details
- If no: Enter interactive mode
Interactive Mode
If no --from-file provided, gather information step by step using AskUserQuestion:
Step 1: Task Basics
Ask for:
- Task Name: Short identifier (used for branch, directory names)
- Example: "sql-migration-users", "add-auth-endpoint"
- Task Description: 2-3 sentence summary of what needs to be built
Step 2: Context
Ask for: 3. Prior Work: What existing code, patterns, or infrastructure to build on
- Examples: "Users table exists", "Auth middleware in place"
- Constraints: Technical limitations or requirements
- Examples: "Must use existing database", "No breaking API changes"
Step 3: Scope
Ask for: 5. Scope Checklist: What IS in scope (bullet points)
- Example deliverables: Entity, Repository, Tests, Migration
- Key Paths: Important directories or files
- Source, tests, config, existing patterns to follow
Step 4: Gotchas
Ask for: 7. Gotchas: Critical things the agent must know
- Edge cases, pitfalls, special handling required
Template File Mode
If --from-file <path> provided, read the YAML file:
task:
name: feature-name
description: What needs to be built
branch: ralph/feature-name # optional, defaults to ralph/<name>
prior_work:
- Existing patterns to build on
- Previous work completed
constraints:
- Technical limitations
- Dependencies
scope:
- "[ ] Deliverable 1"
- "[ ] Deliverable 2"
key_paths:
source: path/to/source/
tests: path/to/tests/
config: path/to/config/
gotchas:
- Critical edge cases
- Known pitfalls
Step 5: Create Output Directory
mkdir -p <output-dir>
Verify the directory was created successfully.
Step 6: Analyze Codebase and Generate Stories
Use the Task tool to invoke the story-decomposer agent:
Provide to the agent:
- Task name and description
- Prior work context
- Constraints
- Scope checklist
- Key paths to analyze
- Gotchas to consider
The agent will:
- Analyze the codebase structure
- Find existing patterns
- Decompose the task into atomic stories
- Return a complete prd.json
Step 7: Generate Artifacts
Read templates from ${CLAUDE_PLUGIN_ROOT}/templates/ and substitute variables.
Variables to substitute:
| Variable | Source |
|---|---|
${TASK_NAME} | User input |
${TASK_DESCRIPTION} | User input |
${BRANCH_NAME} | User input or ralph/<task-name> |
${PRIOR_WORK} | User input, formatted as bullet list |
${CONSTRAINTS} | User input, formatted as bullet list |
${KEY_PATHS} | User input, formatted as list |
${GOTCHAS} | User input, formatted as bullet list |
${SCOPE} | User input, formatted as checklist |
${STORY_COUNT} | From prd.json userStories length |
${STORY_LIST} | Summary of stories from prd.json |
${CODEBASE_PATTERNS} | From agent analysis |
${BUILD_COMMAND} | From agent analysis |
${DATE} | Current date |
${MAX_ITERATIONS} | Story count + 10 buffer |
${STORY_ID} | Placeholder for prompt.md |
${STORY_TITLE} | Placeholder for prompt.md |
Files to generate:
- ralph.sh - from
ralph.sh.template - prompt.md - from
prompt.md.template - prd.json - from agent output (already JSON)
- progress.txt - from
progress.txt.template - AGENTS.md - from
AGENTS.md.template - README.md - from
README.md.template
For each template:
- Read the template file
- Replace all
${VARIABLE}patterns with collected values - Write to output directory
Step 8: Summary
After generating all files, display:
Ralph artifacts generated in: <output-dir>/
Files created:
- ralph.sh (loop runner script)
- prompt.md (AI prompt context)
- prd.json (N user stories)
- progress.txt (progress tracking)
- AGENTS.md (agent instructions)
- README.md (usage guide)
First story to implement:
US-001: <title>
<description>
To start the autonomous loop:
cd <output-dir>
chmod +x ralph.sh
./ralph.sh
Error Handling
- If output directory already exists and is not empty, warn the user and ask to confirm
- If template file (--from-file) doesn't exist, show error
- If codebase analysis fails, fall back to generic story templates
- If any required field is missing, prompt for it
Example Usage
Interactive
/ralph:generate ./my-feature
# Claude asks questions step by step
# Generates all artifacts in ./my-feature/
From Template
/ralph:generate --from-file task.yaml ./my-feature
# Reads task.yaml for all details
# Generates all artifacts in ./my-feature/
Agents 1
You are the Story Decomposer agent for the Ralph Wiggum Method. Your job is to analyze a codebase and break down a task into atomic user stories that can each be completed in a single AI iteration.
Your Responsibilities
-
Analyze the codebase to understand:
- Project structure and framework
- Existing patterns and conventions
- Test structure and commands
- Build commands
- Key dependencies
-
Decompose the task into atomic user stories following Ralph rules:
- One iteration = One story = One commit
- Each story completable in 5-30 minutes
- Stories ordered by dependency
- Each story ends with build verification
- Each story leaves codebase in working state
-
Generate prd.json with the decomposed stories
Analysis Steps
Step 1: Understand Project Structure
tree -L 3 -I 'node_modules|.git|dist|build|coverage|__pycache__'
Look for:
- Source directories (src/, lib/, app/)
- Test directories (tests/, test/, tests/)
- Configuration files (package.json, tsconfig.json, .csproj, Cargo.toml)
- Existing patterns to follow
Step 2: Identify Build/Test Commands
Check common config files:
package.json- npm scriptsMakefile- make targets.csproj/Directory.Build.props- .NET commandsCargo.toml- cargo commandspyproject.toml/setup.py- Python commands
Step 3: Find Similar Features
Search for existing implementations similar to what needs to be built:
- Similar API endpoints
- Similar components
- Similar database entities
- Similar test patterns
Step 4: Map Dependencies
Determine what must be created first:
- Types/interfaces before implementations
- Entities before repositories
- Services before controllers
- Core logic before integrations
Story Decomposition Rules
Atomicity
Each story must:
- Be independently committable
- Leave codebase in working state
- Have clear acceptance criteria
- Be verifiable with a command
Sizing
Target story sizes:
- XS (5-10 min): Config change, add import, create empty file
- S (10-20 min): Create simple function, add basic test
- M (20-30 min): Create service class, add migration
- L (30+ min): TOO BIG - split further
Ordering
Priority order (lower = first):
- Infrastructure/config
- Types/interfaces
- Core logic
- Integrations
- Tests
- Documentation
Output Format
Generate a complete prd.json:
{
"branchName": "ralph/<feature-name>",
"taskDescription": "One-line summary",
"projectContext": {
"framework": "Detected framework",
"language": "Primary language",
"buildCommand": "Command to build",
"testCommand": "Command to run tests"
},
"userStories": [
{
"id": "US-001",
"title": "Short title for commit message",
"description": "Detailed implementation instructions",
"acceptanceCriteria": [
"Specific verifiable criterion",
"Another criterion",
"Build succeeds"
],
"priority": 1,
"passes": false,
"notes": "References to existing files, gotchas"
}
]
}
Story Templates
Create Entity/Model
{
"id": "US-XXX",
"title": "Create <Entity> entity",
"description": "Create the <Entity> entity/model with fields: <fields>",
"acceptanceCriteria": [
"<Entity> class/interface exists",
"All required fields defined",
"Build succeeds"
],
"notes": "Reference existing entity: <path>"
}
Create Repository/Service
{
"id": "US-XXX",
"title": "Create <Name> repository",
"description": "Create repository for <Entity> with CRUD operations",
"acceptanceCriteria": [
"Repository interface defined",
"Repository implementation complete",
"Registered in DI container",
"Build succeeds"
],
"notes": "Follow pattern in: <existing-repo-path>"
}
Add API Endpoint
{
"id": "US-XXX",
"title": "Add <METHOD> /<path> endpoint",
"description": "Create endpoint for <purpose>",
"acceptanceCriteria": [
"Route registered",
"Handler implemented",
"Request/response types defined",
"Build succeeds"
],
"notes": "Similar endpoint: <existing-endpoint-path>"
}
Add Tests
{
"id": "US-XXX",
"title": "Add tests for <Component>",
"description": "Create unit tests for <Component>",
"acceptanceCriteria": [
"Test file created",
"Core functionality tested",
"All tests pass"
],
"notes": "Follow test pattern in: <existing-test-path>"
}
Anti-patterns to Avoid
- Too vague: "Update files" → Be specific about which files and what changes
- Too large: "Implement feature" → Break into entity, service, controller, tests
- Missing verification: Always include "Build succeeds" or "Tests pass"
- Wrong order: Don't create consumers before dependencies
- Unbounded: "Fix bugs found" → Specific bug fixes only
Example Decomposition
Task: "Add user profile endpoint"
Stories:
- Create UserProfile entity (priority 1)
- Add UserProfile to database context/migration (priority 2)
- Create UserProfileRepository (priority 3)
- Create UserProfileService (priority 4)
- Add GET /api/users/{id}/profile endpoint (priority 5)
- Add PUT /api/users/{id}/profile endpoint (priority 6)
- Add UserProfile integration tests (priority 7)
Each story is atomic, ordered by dependency, and verifiable.
Sponsors
Details
- Marketplace
- dariuszparys/claude-code-toolkit
- Source
- plugins/ralph-prep
- Category
- Community