feat(ralph): add user-level storage option

Add support for storing Ralph scripts in user home directory
(~/.config/flow-next/ralph/) instead of project-local scripts/ralph/.

Benefits:
- Scripts shared across multiple projects
- User config provides defaults, project config overrides
- Auto-updates via /flow-next:sync
- Project keeps only config.env (overrides) and runs/

Config loading:
1. User config (~/.config/flow-next/ralph/config.env) - defaults
2. Project config (scripts/ralph/config.env) - overrides

Changes:
- ralph.sh: detect user-level dir, load user+project config
- ralph-init SKILL: support --user flag for user-level install
- Add flow-next-sync skill for updating from plugin
- Add VERSION file for tracking plugin version

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: tiagoefreitas

plugins/flow-next/VERSION

@@ -0,0 +1 @@
+0.4.0

plugins/flow-next/skills/flow-next-ralph-init/SKILL.md

@@ -1,24 +1,48 @@
 ---
 name: flow-next-ralph-init
-description: Scaffold repo-local Ralph autonomous harness under scripts/ralph/. Use when user runs /flow-next:ralph-init.
+description: Scaffold Ralph autonomous harness. Supports project-local (scripts/ralph/) or user-level (~/.config/flow-next/ralph/) modes. Use when user runs /flow-next:ralph-init.
 ---
 
 # Ralph init
 
-Scaffold repo-local Ralph harness. Opt-in only.
+Scaffold Ralph autonomous harness. Opt-in only.
+
+## Installation Modes
+
+### Project-local (default)
+- Everything in `scripts/ralph/` in the current repo
+- Scripts, config, and runs all in one place
+- Good for: single project, team sharing via git
+
+### User-level (`--user` flag)
+- Scripts in `~/.config/flow-next/ralph/` (shared across projects)
+- Project gets `scripts/ralph/config.env` and symlinks
+- Runs stay in project `scripts/ralph/runs/`
+- Good for: multiple projects, personal workflow, auto-updates via `/flow-next:sync`
 
 ## Rules
 
-- Only create `scripts/ralph/` in the current repo.
-- If `scripts/ralph/` already exists, stop and ask the user to remove it first.
-- Copy templates from `templates/` into `scripts/ralph/`.
-- Copy `flowctl` and `flowctl.py` from `${CLAUDE_PLUGIN_ROOT}/scripts/` into `scripts/ralph/`.
-- Set executable bit on `scripts/ralph/ralph.sh`, `scripts/ralph/ralph_once.sh`, and `scripts/ralph/flowctl`.
+### Project-local mode
+- Create `scripts/ralph/` in the current repo
+- If exists, stop and ask user to remove it first
+- Copy all templates from `templates/` into `scripts/ralph/`
+- Copy `flowctl` and `flowctl.py` from `${CLAUDE_PLUGIN_ROOT}/scripts/`
+- Set executable bits
+
+### User-level mode (`--user`)
+- Create `~/.config/flow-next/ralph/` if not exists
+- If exists, ask user if they want to update (runs /flow-next:sync) or skip
+- Copy scripts to user dir: `ralph.sh`, `ralph_once.sh`, `flowctl`, `flowctl.py`, `watch-filter.py`, `prompt_*.md`
+- Write VERSION file to track plugin version
+- In project, create `scripts/ralph/` with:
+  - `config.env` (project-specific config)
+  - Symlinks: `ralph.sh -> ~/.config/flow-next/ralph/ralph.sh` etc.
+  - `runs/` directory for run logs
 
 ## Workflow
 
-1. Resolve repo root: `git rev-parse --show-toplevel`
-2. Check `scripts/ralph/` does not exist.
+1. Parse arguments: check for `--user` flag
+2. Resolve repo root: `git rev-parse --show-toplevel`
 3. Detect available review backends:
    ```bash
    HAVE_RP=$(which rp-cli >/dev/null 2>&1 && echo 1 || echo 0)
@@ -37,12 +61,35 @@ Scaffold repo-local Ralph harness. Opt-in only.
    - If only rp-cli available: use `rp`
    - If only codex available: use `codex`
    - If neither available: use `none`
-5. Write `scripts/ralph/config.env` with:
-   - `PLAN_REVIEW=<chosen>` and `WORK_REVIEW=<chosen>`
-   - replace `{{PLAN_REVIEW}}` and `{{WORK_REVIEW}}` placeholders in the template
-6. Copy templates and flowctl files.
-7. Print 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)
-   - Uninstall: `rm -rf scripts/ralph/`
+
+### If project-local mode (no --user):
+5. Check `scripts/ralph/` does not exist
+6. Copy templates to `scripts/ralph/`
+7. Copy flowctl files
+8. Replace `{{PLAN_REVIEW}}` and `{{WORK_REVIEW}}` in config.env
+9. Set executable bits
+
+### If user-level mode (--user):
+5. Check/create `~/.config/flow-next/ralph/`
+6. Copy scripts to user dir (skip config.env)
+7. Write `~/.config/flow-next/ralph/VERSION` with plugin version
+8. In project `scripts/ralph/`:
+   - Copy config.env template, replace placeholders
+   - Create symlinks to user scripts
+   - Create `runs/` directory
+9. Set executable bits on user scripts
+
+## Print next steps
+
+### Project-local:
+- Edit `scripts/ralph/config.env` to customize settings
+- `./scripts/ralph/ralph_once.sh` (one iteration, observe)
+- `./scripts/ralph/ralph.sh` (full loop, AFK)
+- Uninstall: `rm -rf scripts/ralph/`
+
+### User-level:
+- Edit `scripts/ralph/config.env` for project-specific settings
+- `./scripts/ralph/ralph.sh` (runs from user-level scripts)
+- Update scripts: `/flow-next:sync` (backs up changes, updates from plugin)
+- Uninstall project: `rm -rf scripts/ralph/`
+- Uninstall user-level: `rm -rf ~/.config/flow-next/ralph/`

plugins/flow-next/skills/flow-next-ralph-init/templates/ralph.sh

@@ -1,11 +1,92 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-ROOT_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
-CONFIG="$SCRIPT_DIR/config.env"
+# ─────────────────────────────────────────────────────────────────────────────
+# Path resolution: supports user-level or project-local installation
+# ─────────────────────────────────────────────────────────────────────────────
+# User-level mode:
+#   - Scripts in ~/.config/flow-next/ralph/
+#   - User config in ~/.config/flow-next/ralph/config.env (defaults)
+#   - Project config in scripts/ralph/config.env (overrides)
+#   - Runs in scripts/ralph/runs/ (always project-local)
+#
+# Project-local mode: everything in scripts/ralph/ (original behavior)
+#
+# Detection order:
+# 1. RALPH_USER_DIR env var (explicit user-level path)
+# 2. ~/.config/flow-next/ralph/ if exists
+# 3. Fall back to project-local (script's directory)
+# ─────────────────────────────────────────────────────────────────────────────
+
+_resolve_script_dir() {
+  local self_dir
+  self_dir="$(cd "$(dirname "$0")" && pwd)"
+
+  # Check if we're a symlink to user-level scripts
+  if [[ -L "$0" ]]; then
+    local target
+    target="$(readlink -f "$0")"
+    self_dir="$(dirname "$target")"
+  fi
+
+  echo "$self_dir"
+}
+
+_resolve_user_dir() {
+  # Explicit env var takes precedence
+  if [[ -n "${RALPH_USER_DIR:-}" ]]; then
+    echo "$RALPH_USER_DIR"
+    return
+  fi
+  # Default user-level location
+  local default_user_dir="${HOME}/.config/flow-next/ralph"
+  if [[ -d "$default_user_dir" ]]; then
+    echo "$default_user_dir"
+    return
+  fi
+  echo ""
+}
+
+_resolve_project_dir() {
+  # Project scripts/ralph/ directory (for config and runs)
+  local root="$1"
+  echo "$root/scripts/ralph"
+}
+
+# Determine actual script source (may be user-level)
+SCRIPT_DIR="$(_resolve_script_dir)"
+USER_DIR="$(_resolve_user_dir)"
+ROOT_DIR="$(git rev-parse --show-toplevel 2>/dev/null)" || ROOT_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
+PROJECT_DIR="$(_resolve_project_dir "$ROOT_DIR")"
+
+# Scripts come from user-level if available, else project-local
+if [[ -n "$USER_DIR" && -f "$USER_DIR/ralph.sh" ]]; then
+  SCRIPT_DIR="$USER_DIR"
+fi
+
+# Config: user-level defaults + project overrides
+# User config provides defaults, project config overrides
+USER_CONFIG=""
+PROJECT_CONFIG=""
+if [[ -n "$USER_DIR" && -f "$USER_DIR/config.env" ]]; then
+  USER_CONFIG="$USER_DIR/config.env"
+fi
+if [[ -f "$PROJECT_DIR/config.env" ]]; then
+  PROJECT_CONFIG="$PROJECT_DIR/config.env"
+fi
+# For compatibility, CONFIG points to the primary config (user or project)
+if [[ -n "$USER_CONFIG" ]]; then
+  CONFIG="$USER_CONFIG"
+elif [[ -n "$PROJECT_CONFIG" ]]; then
+  CONFIG="$PROJECT_CONFIG"
+else
+  CONFIG="$SCRIPT_DIR/config.env"
+fi
 FLOWCTL="$SCRIPT_DIR/flowctl"
 
+# Ensure runs directory exists in project
+mkdir -p "$PROJECT_DIR/runs" 2>/dev/null || true
+
 fail() { echo "ralph: $*" >&2; exit 1; }
 log() {
   # Machine-readable logs: only show when UI disabled
@@ -264,12 +345,15 @@ ui_waiting() {
   ui "   ${C_DIM}⏳ Claude working...${C_RESET}"
 }
 
-[[ -f "$CONFIG" ]] || fail "missing config.env"
+# Require at least one config file
+[[ -n "$USER_CONFIG" || -n "$PROJECT_CONFIG" ]] || fail "missing config.env (user or project)"
 [[ -x "$FLOWCTL" ]] || fail "missing flowctl"
 
+# Load config: user-level first (defaults), then project (overrides)
 # shellcheck disable=SC1090
 set -a
-source "$CONFIG"
+[[ -n "$USER_CONFIG" && -f "$USER_CONFIG" ]] && source "$USER_CONFIG"
+[[ -n "$PROJECT_CONFIG" && -f "$PROJECT_CONFIG" ]] && source "$PROJECT_CONFIG"
 set +a
 
 MAX_ITERATIONS="${MAX_ITERATIONS:-25}"
@@ -421,7 +505,7 @@ PY
 }
 
 RUN_ID="$(date -u +%Y%m%dT%H%M%SZ)-$(hostname -s 2>/dev/null || hostname)-$(sanitize_id "$(get_actor)")-$$-$(rand4)"
-RUN_DIR="$SCRIPT_DIR/runs/$RUN_ID"
+RUN_DIR="$PROJECT_DIR/runs/$RUN_ID"
 mkdir -p "$RUN_DIR"
 ATTEMPTS_FILE="$RUN_DIR/attempts.json"
 ensure_attempts_file "$ATTEMPTS_FILE"

plugins/flow-next/skills/flow-next-ralph-init/templates/ralph_once.sh

@@ -3,7 +3,12 @@
 # Use this to observe behavior before going fully autonomous
 
 set -euo pipefail
+
+# Resolve script directory (follows symlinks for user-level mode)
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+if [[ -L "$0" ]]; then
+  SCRIPT_DIR="$(dirname "$(readlink -f "$0")")"
+fi
 
 export MAX_ITERATIONS=1
 exec "$SCRIPT_DIR/ralph.sh" "$@"

plugins/flow-next/skills/flow-next-sync/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: flow-next-sync
+description: Sync user-level Ralph scripts from plugin. Backs up local changes before updating. Use when user runs /flow-next:sync.
+---
+
+# Flow-Next Sync
+
+Update user-level Ralph scripts from plugin templates. Creates diff backups of local changes.
+
+## Overview
+
+When using user-level Ralph installation (`~/.config/flow-next/ralph/`), this command:
+1. Compares current scripts with plugin templates
+2. Backs up any local modifications
+3. Updates scripts to latest plugin version
+4. Reports what changed
+
+## Rules
+
+- Only operates on user-level installation (`~/.config/flow-next/ralph/`)
+- If user-level dir doesn't exist, suggest running `/flow-next:ralph-init --user`
+- Always create backup before overwriting modified files
+- Backup location: `~/.config/flow-next/ralph/backups/<timestamp>/`
+- Update VERSION file after sync
+
+## Workflow
+
+1. Check `~/.config/flow-next/ralph/` exists
+   - If not: print "No user-level Ralph found. Run `/flow-next:ralph-init --user` first."
+
+2. Read current VERSION from `~/.config/flow-next/ralph/VERSION`
+   - If missing, assume version "0.0.0"
+
+3. Read plugin VERSION from `${CLAUDE_PLUGIN_ROOT}/VERSION`
+
+4. Compare versions:
+   - If same: print "Already up to date (version X.Y.Z)"
+   - If different: proceed with sync
+
+5. For each script file, check if modified:
+   ```bash
+   # Files to sync:
+   ralph.sh
+   ralph_once.sh
+   watch-filter.py
+   prompt_plan.md
+   prompt_work.md
+   flowctl
+   flowctl.py
+   ```
+
+6. Create backup directory if any files modified:
+   ```bash
+   BACKUP_DIR="$HOME/.config/flow-next/ralph/backups/$(date +%Y%m%dT%H%M%S)"
+   mkdir -p "$BACKUP_DIR"
+   ```
+
+7. For each modified file:
+   - Create diff: `diff -u <plugin_file> <user_file> > $BACKUP_DIR/<filename>.diff`
+   - Copy user file to backup: `cp <user_file> $BACKUP_DIR/<filename>`
+   - Print: "Backed up: <filename> (modified)"
+
+8. Copy all template files from plugin:
+   - From: `${CLAUDE_PLUGIN_ROOT}/skills/flow-next-ralph-init/templates/`
+   - To: `~/.config/flow-next/ralph/`
+   - Skip: `config.env`, `runs/`, `.gitignore`
+
+9. Copy flowctl files from plugin:
+   - From: `${CLAUDE_PLUGIN_ROOT}/scripts/flowctl`, `flowctl.py`
+   - To: `~/.config/flow-next/ralph/`
+
+10. Update VERSION file:
+    ```bash
+    cp "${CLAUDE_PLUGIN_ROOT}/VERSION" "$HOME/.config/flow-next/ralph/VERSION"
+    ```
+
+11. Set executable bits:
+    ```bash
+    chmod +x ~/.config/flow-next/ralph/ralph.sh
+    chmod +x ~/.config/flow-next/ralph/ralph_once.sh
+    chmod +x ~/.config/flow-next/ralph/flowctl
+    chmod +x ~/.config/flow-next/ralph/watch-filter.py
+    ```
+
+12. Print summary:
+    ```
+    Synced to version X.Y.Z
+    Updated: <list of files>
+    Backups: ~/.config/flow-next/ralph/backups/<timestamp>/
+    ```
+
+## Detecting Modifications
+
+Compare file checksums (md5sum or sha256sum):
+```bash
+PLUGIN_HASH=$(md5sum "$PLUGIN_FILE" | cut -d' ' -f1)
+USER_HASH=$(md5sum "$USER_FILE" | cut -d' ' -f1)
+if [[ "$PLUGIN_HASH" != "$USER_HASH" ]]; then
+  # File was modified
+fi
+```
+
+## Force Mode
+
+If user says "force" or passes `--force`:
+- Skip version check
+- Always sync all files
+- Still create backups of modified files