/flow-next-ralph-init

name: flow-next-ralph-init
description: Scaffold repo-local Ralph autonomous harness under scripts/ralph/. Use when user runs /flow-next:ralph-init.
user-invocable: false

Ralph init

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

Preamble

The plugin root resolves once via the cross-platform env-var fallback (Droid uses `DROID_PLUGIN_ROOT`; Claude Code documents `CLAUDE_PLUGIN_ROOT` as its compat alias). Subsequent blocks use `$PLUGIN_ROOT`:

PLUGIN_ROOT="${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}"

Rules

• **Every write lands under `scripts/ralph/` in the current repo.** A file written anywhere else has broken this.
• If `scripts/ralph/` already exists, offer to update (preserves config.env).
• Copy templates from `templates/` into `scripts/ralph/` (includes `ralphctl.py` for pause/resume/stop/status).
• Copy `flowctl`, `flowctl.cmd`, `flowctl.py`, `flowctl_bootstrap.py`, `flowctl-help.txt`, and the `flowctl_tracker/` package (from `$PLUGIN_ROOT/scripts/`) and `pick-python.sh` (from `$PLUGIN_ROOT/scripts/lib/`) into `scripts/ralph/` — **flat, so the resolver lands at `scripts/ralph/pick-python.sh`** where `ralph.sh` and the hook wrapper source it. A `pick-python.sh` that landed under `scripts/ralph/lib/` has broken this.
• Set executable bit on `scripts/ralph/ralph.sh`, `scripts/ralph/ralph_once.sh`, `scripts/ralph/flowctl`, and `scripts/ralph/ralphctl.py`.
• **Hook registration is agent-driven skill prose only.** The plugin ships no hooks by default; you (the host agent) merge the guard entries into the project's host settings via Read+Edit, idempotently, without clobbering unrelated hooks. **The boundary is hard: there is no flowctl subcommand for hook install/remove/status and no hook machinery in Python.** A settings file whose hooks object now holds only flow-next entries, or a hook-install subcommand added to the CLI, has broken this.

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

   if command -v rpce-cli >/dev/null 2>&1 \
     || [ -x "$HOME/RepoPrompt/repoprompt_ce_cli" ] \
     || [ -x "$HOME/Library/Application Support/RepoPrompt CE/repoprompt_ce_cli" ] \
     || command -v rp-cli >/dev/null 2>&1; then HAVE_RP=1; else HAVE_RP=0; fi
   HAVE_CODEX=$(which codex >/dev/null 2>&1 && echo 1 || echo 0)
   HAVE_COPILOT=$(which copilot >/dev/null 2>&1 && echo 1 || echo 0)
   HAVE_CURSOR=$(which cursor-agent >/dev/null 2>&1 && echo 1 || echo 0)
   HAVE_CLAUDE=$(which claude >/dev/null 2>&1 && echo 1 || echo 0)

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

• If several are available, ask the user (do NOT use AskUserQuestion tool).

Show only the options whose CLIs were detected:

     Multiple review backends available. Which one?
     a) RepoPrompt (macOS, visual builder)
     b) Codex CLI (cross-platform, reviewer models via a Codex subscription)
     c) GitHub Copilot CLI (cross-platform, Claude/GPT via Copilot)
     d) Cursor CLI (cross-platform, runs cursor-agent; reviewer models via a Cursor subscription)
     e) Claude Code CLI (cross-platform, runs claude -p; Claude-family reviewer — same-family when Ralph drives Claude Code)

     (Reply: "a", "rp", "b", "codex", "c", "copilot", "d", "cursor", "e", "claude", or just tell me)

Wait for response. Default if empty/ambiguous: prefer `rp` > `codex` > `copilot` > `cursor` > `claude`.

• If only the RepoPrompt CLI ladder resolves: use `rp`
• If only codex available: use `codex`
• If only copilot available: use `copilot`
• If only cursor-agent available: use `cursor`
• If only claude available: use `claude`
• If none available: use `none`

5. Copy files using bash — **the copies run through `cp`, never the Write tool.** A template reproduced by writing its contents has broken this:

**If UPDATE_MODE=1 (updating):**

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

   # Update templates (preserves runs/)
   cp "$PLUGIN_ROOT/skills/flow-next-ralph-init/templates/ralph.sh" scripts/ralph/
   cp "$PLUGIN_ROOT/skills/flow-next-ralph-init/templates/ralph_once.sh" scripts/ralph/
   cp "$PLUGIN_ROOT/skills/flow-next-ralph-init/templates/prompt_plan.md" scripts/ralph/
   cp "$PLUGIN_ROOT/skills/flow-next-ralph-init/templates/prompt_work.md" scripts/ralph/
   cp "$PLUGIN_ROOT/skills/flow-next-ralph-init/templates/prompt_completion.md" scripts/ralph/
   cp "$PLUGIN_ROOT/skills/flow-next-ralph-init/templates/watch-filter.py" scripts/ralph/
   cp "$PLUGIN_ROOT/skills/flow-next-ralph-init/templates/ralphctl.py" scripts/ralph/
   cp "$PLUGIN_ROOT/scripts/flowctl" "$PLUGIN_ROOT/scripts/flowctl.cmd" "$PLUGIN_ROOT/scripts/flowctl.py" "$PLUGIN_ROOT/scripts/flowctl_bootstrap.py" "$PLUGIN_ROOT/scripts/flowctl-help.txt" "$PLUGIN_ROOT/scripts/lib/pick-python.sh" scripts/ralph/
   rm -rf scripts/ralph/flowctl_tracker && cp -R "$PLUGIN_ROOT/scripts/flowctl_tracker" scripts/ralph/flowctl_tracker
   # Verify the tracker package post-copy - fail loudly here, never
   # later as an ImportError mid-run
   python3 "$PLUGIN_ROOT/scripts/lib/verify_tracker_manifest.py" scripts/ralph
   mkdir -p scripts/ralph/hooks
   cp "$PLUGIN_ROOT/scripts/hooks/ralph-guard.py" "$PLUGIN_ROOT/scripts/hooks/ralph-guard" scripts/ralph/hooks/
   chmod +x scripts/ralph/ralph.sh scripts/ralph/ralph_once.sh scripts/ralph/flowctl scripts/ralph/ralphctl.py scripts/ralph/hooks/ralph-guard.py scripts/ralph/hooks/ralph-guard

   # 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 "$PLUGIN_ROOT/s