Generate Ralph Wiggum Method artifacts for autonomous AI coding loops

version
1.0.0
GitHub stars
13

Install

/plugin install ralph-prep@claude-code-toolkit

Run it inside Claude Code after adding the marketplace with /plugin marketplace add dariuszparys/claude-code-toolkit.

Contents

Discovered from source

Commands 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:

  1. Task Name: Short identifier (used for branch, directory names)
    • Example: "sql-migration-users", "add-auth-endpoint"
  2. 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"
  1. 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
  1. 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:

  1. Analyze the codebase structure
  2. Find existing patterns
  3. Decompose the task into atomic stories
  4. Return a complete prd.json

Step 7: Generate Artifacts

Read templates from ${CLAUDE_PLUGIN_ROOT}/templates/ and substitute variables.

Variables to substitute:

VariableSource
${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:

  1. ralph.sh - from ralph.sh.template
  2. prompt.md - from prompt.md.template
  3. prd.json - from agent output (already JSON)
  4. progress.txt - from progress.txt.template
  5. AGENTS.md - from AGENTS.md.template
  6. README.md - from README.md.template

For each template:

  1. Read the template file
  2. Replace all ${VARIABLE} patterns with collected values
  3. 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

  1. Analyze the codebase to understand:

    • Project structure and framework
    • Existing patterns and conventions
    • Test structure and commands
    • Build commands
    • Key dependencies
  2. 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
  3. 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 scripts
  • Makefile - make targets
  • .csproj / Directory.Build.props - .NET commands
  • Cargo.toml - cargo commands
  • pyproject.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):

  1. Infrastructure/config
  2. Types/interfaces
  3. Core logic
  4. Integrations
  5. Tests
  6. 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

  1. Too vague: "Update files" → Be specific about which files and what changes
  2. Too large: "Implement feature" → Break into entity, service, controller, tests
  3. Missing verification: Always include "Build succeeds" or "Tests pass"
  4. Wrong order: Don't create consumers before dependencies
  5. Unbounded: "Fix bugs found" → Specific bug fixes only

Example Decomposition

Task: "Add user profile endpoint"

Stories:

  1. Create UserProfile entity (priority 1)
  2. Add UserProfile to database context/migration (priority 2)
  3. Create UserProfileRepository (priority 3)
  4. Create UserProfileService (priority 4)
  5. Add GET /api/users/{id}/profile endpoint (priority 5)
  6. Add PUT /api/users/{id}/profile endpoint (priority 6)
  7. 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

More from dariuszparys/claude-code-toolkit

All 6