/ralphex-update

description: Smart-merge updated ralphex defaults into customized prompts/agents
allowed-tools: [Bash, Read, Write, Glob, AskUserQuestion]

ralphex-update - Smart Prompt Merging

**SCOPE**: Compare current embedded defaults with user's installed config, and intelligently merge updates into customized files. Preserves user intent while incorporating structural changes.

Step 0: Verify CLI Installation

which ralphex

**If not found**, guide installation:

• **macOS (Homebrew)**: `brew install umputun/apps/ralphex`
• **Any platform with Go**: `go install github.com/umputun/ralphex/cmd/ralphex@latest`

**Do not proceed until `which ralphex` succeeds.**

Step 1: Extract Current Defaults

Create temp directory and dump embedded defaults:

DUMP_DIR=$(mktemp -d /tmp/ralphex-defaults-XXXX)
ralphex --dump-defaults "$DUMP_DIR"
echo "$DUMP_DIR"

Save the dump directory path for later use.

Step 2: Determine Config Directory

Resolve the user's config directory:

# check environment variable first
echo "${RALPHEX_CONFIG_DIR:-}"

If `RALPHEX_CONFIG_DIR` is empty, use default:

• **macOS/Linux**: `~/.config/ralphex/`

Verify the directory exists:

ls -la <config-dir>/

If it doesn't exist, inform user that ralphex hasn't been configured yet and there's nothing to update.

How ralphex Config Files Work

ralphex installs config, prompt, and agent files with all content **commented out** (every line prefixed with `# `). At runtime, `stripComments()` removes these lines, finds nothing, and falls back to **embedded defaults** compiled into the binary. These all-commented files are functionally identical to missing files — they are do-nothing placeholders.

When ralphex is updated, new embedded defaults take effect **automatically** for every file that hasn't been customized. No file changes are needed.

A file is **customized** only if it contains at least one uncommented, non-empty line that was intentionally modified by the user. The `--dump-defaults` command produces the raw (uncommented) embedded content for comparison.

Step 3: Compare Files

For each file in the defaults dump (`config`, `prompts/*.txt`, `agents/*.txt`), compare with the corresponding file in the user's config directory.

**Algorithm to detect customized files**: a file is customized if it contains at least one non-empty line that does NOT start with `#`. Files that are missing, empty, or contain only comment lines (`# ...`) and whitespace are do-nothing defaults.

**Classify each file into one of these categories:**

Skip (do-nothing default)

• File is missing in user's config, OR
• File is empty, OR
• File contains only comments and whitespace (every non-empty line starts with `#`)
• **Action**: no action needed — embedded defaults handle it automatically

Note: files that exist only in the dump directory (no corresponding user file) are also do-nothing — do NOT offer to install them. Files that exist only in the user's config directory (no corresponding dump file) are user-created custom files — ignore them entirely.

Skip (unchanged)

• File has uncommented content that matches the raw dump default
• **Action**: no action needed — user's file already matches current defaults

**How to compare**: strip all `#`-prefixed lines from BOTH the user's file and the dump file, then compare the remaining non-comment content. This handles the config file where the dump has descriptive comment lines mixed with value lines — only the actual values matter for comparison.

Smart merge needed

• File has uncommented content that differs from the raw dump default (after stripping `#`-prefixed lines from both sides)
• **Action**: needs Claude to semantically analyze and propose merge

Step 4: Present Summary

Show the user a summary with two groups:

ralphex config update summary:

No changes needed (N files):
  prompts/task.txt, prompts/review_first.txt, agents/quality.txt, prompts/codex.txt, ...

Smart merge needed (N files):
  prompts/review_second.txt, agents/implementation.txt

If nothing needs merging, report "all config files are up to date — no changes needed" and skip to cleanup.

Otherwise, use AskUserQuestion to confirm proceeding:

• header: "Proceed"
• question: "Review smart merges? Each customized file will be reviewed one by one."
• options:
• label: "Yes, proceed"

description: "Review and merge customized files one at a time"

• label: "Skip, just show details"

description: "Show what changed without modifying anything"

If user selects "Skip, just show details": for each file needing smart merge, show the diff between the user's file and the new default, then skip to Step 6 (Cleanup) without modifying any files.

Step 5: Process Smart Merges

For each customized file that needs merging:

1. **Read both versions** - the new default and the user's current version 2. **Analyze the differences semantically**:

• What did the user customize? (added content, changed wording, different instructions)
• What changed in the new default? (structural changes, new template variables, new sections, removed sections)

3. **Propose a merged version** that:

• Preserves user additions not present in defaults
• Applies structural/pattern changes from new defaults
• Updates template variable references (e.g., new `{{VARIABLE}}` usage)
• Preserves user's tone and style choices
• Flags direct conflicts where both changed the same thing

4. **Show the user**:

• Brief summary of what changed in defaults
• Brief summary of what user customized
• The proposed merged version

5. **Use AskUserQuestion** for each file:

• header: "Merge"
• question: "How to handle <filename>?"
• options:
• label: "Accept merge"

description: "Use the proposed merged version"

• label: "Keep mine"

description: "Keep your current version unchanged"

• label: "Use new default"

description: "Replace with new def