Get the FREE Ultimate OpenClaw Setup Guide →

flow-next-ralph-init

npx machina-cli add skill gmickel/gmickel-claude-marketplace/flow-next-ralph-init --openclaw
Files (1)
SKILL.md
4.9 KB

Ralph init

Scaffold or update repo-local Ralph harness. Opt-in only.

Rules

  • Only create/update scripts/ralph/ in the current repo.
  • If scripts/ralph/ already exists, offer to update (preserves config.env).
  • Copy templates from templates/ into scripts/ralph/.
  • Copy flowctl and flowctl.py from ${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/ into scripts/ralph/.
  • Set executable bit on scripts/ralph/ralph.sh, scripts/ralph/ralph_once.sh, and scripts/ralph/flowctl.

Workflow

  1. Resolve repo root: git rev-parse --show-toplevel

  2. Check if scripts/ralph/ exists:

    • If exists: ask "Update existing Ralph setup? (preserves config.env and runs/) [y/n]"
      • If no: stop
      • If yes: set UPDATE_MODE=1
    • If not exists: set UPDATE_MODE=0

  3. Detect available review backends (skip if UPDATE_MODE=1):

    HAVE_RP=$(which rp-cli >/dev/null 2>&1 && echo 1 || echo 0)
HAVE_CODEX=$(which codex >/dev/null 2>&1 && echo 1 || echo 0)

  4. Determine review backend (skip if UPDATE_MODE=1):

    • If BOTH available, ask user (do NOT use AskUserQuestion tool): 
      Both RepoPrompt and Codex available. Which review backend?
a) RepoPrompt (macOS, visual builder)
b) Codex CLI (cross-platform, GPT 5.2 High)

(Reply: "a", "rp", "b", "codex", or just tell me)
      Wait for response. Default if empty/ambiguous: rp
    • If only rp-cli available: use rp
    • If only codex available: use codex
    • If neither available: use none

  5. Copy files using bash (MUST use cp, NOT Write tool):

    If UPDATE_MODE=1 (updating):

    # Backup config.env
cp scripts/ralph/config.env /tmp/ralph-config-backup.env

# Update templates (preserves runs/)
cp "${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/skills/flow-next-ralph-init/templates/ralph.sh" scripts/ralph/
cp "${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/skills/flow-next-ralph-init/templates/ralph_once.sh" scripts/ralph/
cp "${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/skills/flow-next-ralph-init/templates/prompt_plan.md" scripts/ralph/
cp "${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/skills/flow-next-ralph-init/templates/prompt_work.md" scripts/ralph/
cp "${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/skills/flow-next-ralph-init/templates/prompt_completion.md" scripts/ralph/
cp "${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/skills/flow-next-ralph-init/templates/watch-filter.py" scripts/ralph/
cp "${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/flowctl" "${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/flowctl.py" scripts/ralph/
mkdir -p scripts/ralph/hooks
cp "${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/hooks/ralph-guard.py" scripts/ralph/hooks/
chmod +x scripts/ralph/ralph.sh scripts/ralph/ralph_once.sh scripts/ralph/flowctl scripts/ralph/hooks/ralph-guard.py

# Restore config.env
cp /tmp/ralph-config-backup.env scripts/ralph/config.env

    If UPDATE_MODE=0 (fresh install):

    mkdir -p scripts/ralph/runs scripts/ralph/hooks
cp -R "${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/skills/flow-next-ralph-init/templates/." scripts/ralph/
cp "${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/flowctl" "${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/flowctl.py" scripts/ralph/
cp "${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/hooks/ralph-guard.py" scripts/ralph/hooks/
chmod +x scripts/ralph/ralph.sh scripts/ralph/ralph_once.sh scripts/ralph/flowctl scripts/ralph/hooks/ralph-guard.py

    Note: cp -R templates/. copies all files including dotfiles (.gitignore).

  6. Edit scripts/ralph/config.env to set the chosen review backend (skip if UPDATE_MODE=1):

    • Replace PLAN_REVIEW={{PLAN_REVIEW}} with PLAN_REVIEW=<chosen>
    • Replace WORK_REVIEW={{WORK_REVIEW}} with WORK_REVIEW=<chosen>
    • Replace COMPLETION_REVIEW={{COMPLETION_REVIEW}} with COMPLETION_REVIEW=<chosen>

  7. Print next steps (run from terminal, NOT inside Claude Code):

    If UPDATE_MODE=1:

    Ralph updated! Your config.env was preserved.

Changes in this version:
- Removed local hooks requirement (plugin hooks work when installed normally)

Run from terminal:
- ./scripts/ralph/ralph_once.sh (one iteration, observe)
- ./scripts/ralph/ralph.sh (full loop, AFK)

    If UPDATE_MODE=0:

    Ralph initialized!

Next steps (run from terminal, NOT inside Claude Code):
- Edit scripts/ralph/config.env to customize settings
- ./scripts/ralph/ralph_once.sh (one iteration, observe)
- ./scripts/ralph/ralph.sh (full loop, AFK)

Maintenance:
- Re-run /flow-next:ralph-init after plugin updates to refresh scripts
- Uninstall (run manually): rm -rf scripts/ralph/

Source

git clone https://github.com/gmickel/gmickel-claude-marketplace/blob/main/plugins/flow-next/skills/flow-next-ralph-init/SKILL.mdView on GitHub

Overview

flow-next-ralph-init scaffolds or updates a repo-local Ralph harness inside your project by creating scripts/ralph and related resources. It preserves config.env when updating and copies templates and flowctl utilities from the plugin root. This opt-in step ensures a self-contained Ralph environment for local testing and automation.

How This Skill Works

The tool resolves the repository root, checks for the existence of scripts/ralph, and either updates an existing harness or creates a fresh one. It copies templates from templates/ into scripts/ralph, brings in flowctl and flowctl.py from the plugin root, and sets executable permissions on the Ralph scripts and hooks.

When to Use It

  • When you want to add a repo-local Ralph harness to a new repository.
  • When updating an existing scripts/ralph/ setup to pick up new templates while preserving config.env.
  • When the plugin provides updated templates for Ralph and you need to apply them locally.
  • When you need the flowctl and related scripts available under scripts/ralph/ with proper permissions.
  • When you run /flow-next:ralph-init to scaffold or update the Ralph harness.

Quick Start

  1. Step 1: Run the command that triggers Ralph init (e.g., /flow-next:ralph-init).
  2. Step 2: If prompted, choose to update or perform a fresh install; confirm if updating.
  3. Step 3: Review the newly created scripts/ralph/ and commit the changes to your repo.

Best Practices

  • Limit changes to the current repo by only creating/updating scripts/ralph/ in place.
  • Back up config.env before performing an update (as the workflow prescribes).
  • Use the cp commands shown in the workflow to copy templates and flowctl utilities.
  • Preserve existing runs/ configuration where updating to avoid losing history.
  • Ensure the executable bits are set on ralph.sh, ralph_once.sh, and flowctl.

Example Use Cases

  • A new project scaffolds a local Ralph harness to run repo-local tests.
  • An existing repository updates Ralph to latest templates, preserving runs and config.env.
  • A team migrates from a central Ralph install to a repo-local harness for isolation.
  • You ensure scripts/ralph/flowctl and ralph hooks are present and executable.
  • You run /flow-next:ralph-init and review prompts for backing up config.env.

Frequently Asked Questions

Add this skill to your agents
Sponsor this space

Reach thousands of developers ↗