Ralph - Agent-Agnostic Autonomous Loop Creator

Ralph creates autonomous coding loops that implement features by breaking them into small user stories and completing them one at a time. Each iteration spawns a fresh headless agent with clean context. Memory persists via git,

progress.txt

prd.json

Workflow

Step 1: Understand the Feature

If the user tagged a markdown file via

@

Ask clarifying questions if needed:

• What problem does this solve?
• What are the key user actions?
• What's out of scope?
• How do we know it's done?

Step 2: Configure the Loop

Ask the user four questions to configure the loop:

2a. Which AI agent?

Present this list and ask the user to choose:

1. claude

   — Claude Code

2. droid

   — Factory Droid

3. codex

   — OpenAI Codex

4. opencode

   — OpenCode

5. gemini

   — Gemini CLI

6. copilot

   — GitHub Copilot

7. cc-compatible

   — Claude Code-compatible binary (user provides binary name, e.g.,

   zai

   ,

   minimax

   ,

   kimi

   )

8. custom

   — Fully custom command (user provides entire command template with

   $PROMPT_FILE

   as placeholder)

Headless command templates per agent (used when generating the loop script):

# claude — Claude Code
claude -p "$(cat "$PROMPT_FILE")" --dangerously-skip-permissions --model $MODEL

# droid — Factory Droid
droid exec --skip-permissions-unsafe -f "$PROMPT_FILE" --output-format text -m $MODEL

# codex — OpenAI Codex
codex exec --yolo -m $MODEL "$(cat "$PROMPT_FILE")"

# opencode — OpenCode
opencode run --yolo -m $MODEL "$(cat "$PROMPT_FILE")"

# gemini — Gemini CLI
gemini -p "$(cat "$PROMPT_FILE")" --yolo -m $MODEL

# copilot — GitHub Copilot
copilot -p "$(cat "$PROMPT_FILE")" --yolo --model $MODEL

# cc-compatible — Same as Claude Code with user-provided binary name
$BINARY -p "$(cat "$PROMPT_FILE")" --dangerously-skip-permissions --model $MODEL

# custom — User provides entire command template
# User's template must include $PROMPT_FILE where the prompt file path should go

If the user selects

cc-compatible

zai

custom

$PROMPT_FILE

2b. Which model?

Ask the user for the model identifier (free text input). Examples:

• Claude Code:

  opus

  ,

  claude-opus-4-6

  ,

  sonnet

  ,

  claude-sonnet-4-5-20250929

• Factory Droid:

  claude-opus-4-6

  ,

  o3

• OpenAI Codex:

  o3

  ,

  o4-mini

• OpenCode:

  anthropic/claude-opus-4-6

  ,

  openai/o3

  (format:

  provider/model

  )
• Gemini CLI:

  gemini-2.5-pro

  ,

  gemini-2.0-flash

• GitHub Copilot:

  claude-sonnet-4-5

  ,

  gpt-4o

If the user says "default" or leaves it blank, omit the model flag entirely (use the agent's built-in default).

2c. Loop name?

Suggest a name based on the feature in kebab-case (e.g.,

add-task-priorities

.ralph/<loop-name>.sh

2d. Auto-push and create PR?

Ask the user: "Should Ralph automatically push the branch and create a PR when the loop finishes?"

• Yes — When the loop ends (all stories complete or max iterations reached), the script will push the branch to

  origin

  and create a pull request via

  gh pr create

  . The base branch (e.g.,

  main

  or

  master

  ) is auto-detected at generation time by checking which branch exists on the remote.
• No — The script only runs locally. All commits stay local. The user pushes and creates PRs themselves.

If the user says yes, detect the base branch now (at generation time) by checking:

1. Does

   refs/remotes/origin/main

   exist? → use

   main

2. Does

   refs/remotes/origin/master

   exist? → use

   master

3. Neither → default to

   main

Bake the resolved base branch directly into the generated script as

DEFAULT_BRANCH="main"

"master"

Step 3: Create prd.json

Generate a

prd.json

{
  "project": "[Project Name]",
  "branchName": "ralph/[feature-name-kebab-case]",
  "description": "[Feature description]",
  "userStories": [
    {
      "id": "US-001",
      "title": "[Story title]",
      "description": "As a [user], I want [feature] so that [benefit]",
      "acceptanceCriteria": [
        "Criterion 1",
        "Criterion 2",
        "Typecheck passes"
      ],
      "priority": 1,
      "passes": false,
      "notes": ""
    }
  ]
}

Step 4: Generate and Run the Loop

1. Create

   .ralph/

   directory in the project root if it doesn't exist
2. Check

   .gitignore

   — add

   .ralph/

   ,

   .ralph-archive/

   , and

   .ralph-last-branch

   if missing (create

   .gitignore

   if it doesn't exist)
3. Read

   scripts/ralph.sh

   (the reference template in this skill) to understand the loop structure
4. Generate

   .ralph/<loop-name>.sh

   using the reference template's structure, with the selected agent command baked in:
   • Use the exact command template from Step 2a, substituting the user's model from Step 2b
   • If no model was specified, omit the model flag from the command
   • Set

     PROMPT_FILE="$SCRIPT_DIR/<loop-name>-prompt.md"

     (co-located with the script)
   • Set

     AGENT_BIN

     to the selected executable (for

     custom

     , use the command's executable token)
   • Keep all existing logic: archive, branch tracking, progress init, completion detection, 2s sleep between iterations
   • If the user opted for auto-push+PR in Step 2d: include the

     finalize()

     function with

     DEFAULT_BRANCH

     set to the resolved base branch, and

     AUTO_PUSH_PR="true"

     . Otherwise set

     AUTO_PUSH_PR="false"

     and omit the

     finalize()

     function.
5. Copy

   scripts/prompt.md

   (from this skill) →

   .ralph/<loop-name>-prompt.md

6. Make the script executable:

   chmod +x .ralph/<loop-name>.sh

7. Tell the user:

   Run with: .ralph/<loop-name>.sh [max_iterations]

Critical Rules for User Stories

Size: Small but Substantive

Each story MUST be completable in ONE iteration. If you can't describe it in 2-3 sentences, it's too big. But each story must also involve meaningful work — if it's a single find-and-replace or a one-line edit, it's too small and should be combined with related work.

Too small (combine with related work):

• "Replace nvidia-smi with rocm-smi in one file" → combine into a broader documentation accuracy story
• "Add one missing env var to README" → combine with other doc gaps
• "Fix a typo in a config file" → combine with other config improvements
• Any story that a developer could complete in under 5 minutes

Right-sized:

• Add a database column and migration
• Add a UI component to an existing page
• Update a server action with new logic
• Add a filter dropdown to a list
• Fix a validation bug, add tests for the fix, and update docs
• Consolidate duplicated helper functions across multiple files

Too big (split these):

• "Build the entire dashboard" → schema, queries, UI components, filters
• "Add authentication" → schema, middleware, login UI, session handling

Order: Dependencies First

1. Schema/database changes (migrations)
2. Server actions / backend logic
3. UI components that use the backend
4. Dashboard/summary views

Acceptance Criteria: Verifiable

Good:

• "Add

  status

  column with default 'pending'"
• "Filter dropdown has options: All, Active, Completed"
• "Typecheck passes"

Bad:

• "Works correctly"
• "Good UX"

Always include:

• "Typecheck passes"

  on every story

• "Verify in browser"

  on UI stories

Example

User says: "use ralph to add task priorities"

Step 1: Read the feature description, ask clarifying questions.

Step 2: Ask: Which agent? →

claude

sonnet

add-task-priorities

yes

Step 3: Create prd.json:

{
  "project": "TaskApp",
  "branchName": "ralph/task-priority",
  "description": "Add priority levels (high/medium/low) to tasks",
  "userStories": [
    {
      "id": "US-001",
      "title": "Add priority field to database",
      "description": "As a developer, I need to store task priority.",
      "acceptanceCriteria": [
        "Add priority column: 'high' | 'medium' | 'low' (default 'medium')",
        "Migration runs successfully",
        "Typecheck passes"
      ],
      "priority": 1,
      "passes": false,
      "notes": ""
    },
    {
      "id": "US-002",
      "title": "Display priority badge on task cards",
      "description": "As a user, I want to see priority at a glance.",
      "acceptanceCriteria": [
        "Colored badge: red=high, yellow=medium, gray=low",
        "Visible without hovering",
        "Typecheck passes",
        "Verify in browser"
      ],
      "priority": 2,
      "passes": false,
      "notes": ""
    }
  ]
}

Step 4: Generate

.ralph/add-task-priorities.sh

claude -p "$(cat "$PROMPT_FILE")" --dangerously-skip-permissions --model sonnet

AUTO_PUSH_PR="true"

DEFAULT_BRANCH="main"

.ralph/add-task-priorities-prompt.md

.ralph/

.ralph-archive/

.ralph-last-branch

.gitignore

prd.json created with 2 user stories. Run

.ralph/add-task-priorities.sh

to start autonomous execution.

How Ralph Executes

Each iteration, a fresh headless agent:

1. Reads

   prd.json

   and

   progress.txt

2. Picks highest priority story where

   passes: false

3. Implements it
4. Runs quality checks (typecheck, lint, test)
5. Commits if passing (or commits progress notes if stuck — see "If You Get Stuck" in prompt)
6. Updates

   prd.json

   to mark

   passes: true

   (or updates

   notes

   if blocked)
7. Appends learnings to

   progress.txt

8. Exits

Loop continues until all stories pass or max iterations hit.

If the user opted for auto-push+PR (Step 2d), then after the loop ends (all stories complete or max iterations reached):

1. The loop script pushes the branch to origin
2. Creates a PR via

   gh pr create

   from the ralph branch to the default branch
3. If

   gh

   CLI is not available or PR creation fails, prints manual instructions instead of aborting
4. Push or PR failures are handled gracefully — they never mask a successful loop run

If the user chose local-only, the script simply exits after the loop. All commits remain local.

Files Reference

prd.json

progress.txt

.ralph/<name>.sh

.ralph/<name>-prompt.md

scripts/prompt.md

Decompose Mode

Triggered by:

/ralph decompose <input>

What it does

Reverse Ralph takes any description of an existing feature and decomposes it — recursively and completely — into an atomized

prd.json

Decomposition is behavioral and functional: it captures what the feature does and how it behaves from the outside, not how it is built internally. The forward loop handles all implementation decisions.

Inputs accepted

• URLs (fetched and spidered up to 2 hops of linked documentation)
• Local file paths (read directly)
• Natural language descriptions
• Any combination of the above

Agent workflow

Follow the detailed instructions in

scripts/decompose-init-prompt.md

1. Gather inputs. Read all provided sources. For URLs, fetch the page and follow documentation links up to 2 hops deep (same documentation domain only). Synthesize all gathered content into a capability surface: a structured description of all observable behaviors, states, inputs, outputs, configuration options, and integrations of the feature.

2. Ask the loop name. Ask the user what to name this decomposition run. Used for the generated script filename:

   .ralph/decompose-<n>.sh

   .

3. Ask which execution agent to use for the decomposition loop. Same agent matrix as forward Ralph:

   claude

   ,

   droid

   ,

   codex

   ,

   opencode

   ,

   gemini

   ,

   copilot

   ,

   cc-compatible

   , or

   custom

   .

4. Ask which model (optional — leave blank to use the CLI default).

5. Seed

   decomp.json

   . Generate the initial state file with top-level capability clusters extracted from the capability surface. Each cluster gets status

   needs_split

   .

6. Generate

   .ralph/decompose-<n>.sh

   from

   scripts/decompose.sh

   , substituting

   __AGENT__

   ,

   __MODEL__

   , and

   __LOOP_NAME__

   . Copy

   scripts/decompose-prompt.md

   to

   .ralph/decompose-<n>-prompt.md

   .

7. Instruct the user to run:

   .ralph/decompose-<n>.sh [max_iterations]
   

   Default

   max_iterations

   is 50. The loop runs autonomously until all leaf nodes in

   decomp.json

   have status

   atomic

   (split parent nodes get status

   split

   ), then emits

   prd.json

   .

Known Limitations

• Context window: The full

  decomp.json

  is appended to each iteration's prompt. For very large feature decompositions (hundreds of nodes), this may approach agent context limits. If this happens, increase

  max_iterations

  and let the loop resume across runs.

Decompose Files Reference

scripts/decompose-init-prompt.md

decomp.json

prd.json

.ralph/decompose-<n>.sh

.ralph/decompose-<n>-prompt.md