rc-init

Bootstrap the QRDS-PI workflow in any project.

Target directory: $ARGUMENTS (default: .scripts/)

What this skill does

Installs everything a project needs to run the QRDS-PI cycle:

1. Verifies prerequisites (bd CLI, git repo)
2. Locates the ralph-crispies plugin source
3. Initializes the beads workspace
4. Copies scripts into the project
5. Installs the qrds-pi formula
6. Installs the PI planning contract (PLANS.md) and plans/
7. Installs or updates the Ralph Crispies block in AGENTS.md
8. Leaves CLAUDE.md optional; if present, it should point readers to AGENTS.md

Each step is idempotent. Re-running is safe.

Steps

Step 1: Prerequisites check

Verify bd is installed and the version is >= 1.0.0:

bd --version

If bd is not found or the version is too old, stop and show:

"bd CLI not found (or too old). Install from: https://github.com/beads-dev/beads Required: bd >= 1.0.0"

Verify we are inside a git repo:

git rev-parse --git-dir 2>/dev/null || echo "NOT_A_GIT_REPO"

If not a git repo:

"Not inside a git repository. Run git init first, then re-run rc-init."

Stop on any failure. Both checks must pass before continuing.

Step 2: Locate plugin source

If Claude is running the plugin, it writes its own path to /tmp/.ralph-crispies-plugin-root-$(id -u) at session start via the SessionStart hook. Read it first:

cat /tmp/.ralph-crispies-plugin-root-$(id -u) 2>/dev/null

If the file exists and the path is non-empty, use that as PLUGIN_ROOT.

Fallback 1 — scan the Claude plugin cache (Claude-only):

ls -td ~/.claude/plugins/cache/ralph-crispies/ralph-crispies/*/  2>/dev/null | head -1

Take the first (latest) directory returned.

Fallback 2 — locate via the ralph-loop binary (works for Claude or Codex):

dirname "$(dirname "$(which ralph-loop)")" 2>/dev/null

After selecting a candidate, verify it contains bin/ralph-loop:

test -f "${PLUGIN_ROOT}/bin/ralph-loop" && echo "FOUND" || echo "MISSING"

If no candidate passes this check, stop and show:

"Cannot locate the ralph-crispies plugin. Try:

1. Restart Claude Code so the SessionStart hook can write /tmp/.ralph-crispies-plugin-root-$(id -u)
2. Or install the plugin: /install-plugin ralph-crispies"
3. If running from Codex, ensure ralph-loop is on PATH or set PLUGIN_ROOT manually

Record PLUGIN_ROOT — all later steps reference it.

Step 3: Beads workspace

Check if .beads/ already exists:

test -d .beads && echo "EXISTS" || echo "MISSING"

If it exists, skip with: [skip] .beads/ already initialized

If missing, initialize:

bd init

If bd init fails, stop and report the error output.

Step 4: Script copy

Determine the target directory:

• If $ARGUMENTS is non-empty, use that path as-is.
• If empty, use .scripts/ as default.

Show the user the intended target and ask for confirmation or a different path using AskUserQuestion:

Question: "Where should I copy the ralph-crispies scripts?" Header: "Script directory" Options:

1. .scripts/ (default) — "Copy to .scripts/ in this project."
2. Custom path — "Enter a different directory."
3. Skip — "Don't copy scripts now (you can run rc-init again later)."

If the user chooses Skip, skip to Step 5.

Create the target directory if it does not exist:

mkdir -p "<target-dir>"

Essential scripts — always copy these:

cp -f "${PLUGIN_ROOT}/bin/ralph-loop"        "<target-dir>/ralph-loop"
cp -f "${PLUGIN_ROOT}/bin/ralph-lib.sh"      "<target-dir>/ralph-lib.sh"
cp -f "${PLUGIN_ROOT}/bin/ralph-stream-parse" "<target-dir>/ralph-stream-parse"
cp -f "${PLUGIN_ROOT}/bin/ralph-overseer"    "<target-dir>/ralph-overseer"

Optional scripts — ask before copying each:

• ralph-tts-elevenlabs: requires ELEVENLABS_API_KEY environment variable
• ralph-dashboard: local dashboard surface that reads .ralph-overseer/state.json
• ralph-cmux: supported cmux workspace launcher for overseer + dashboard surfaces

Use AskUserQuestion for optional scripts:

Question: "Which optional scripts should I include?" Header: "Optional scripts" Options:

1. All runtime helpers — "Copy ralph-tts-elevenlabs, ralph-dashboard, and ralph-cmux."
2. TTS only (ralph-tts-elevenlabs) — "Needs ELEVENLABS_API_KEY."
3. Dashboard only — "Copy ralph-dashboard and ralph-cmux. Needs cmux."
4. Neither — "Skip optional scripts."

Copy selected optional scripts:

cp -f "${PLUGIN_ROOT}/bin/ralph-tts-elevenlabs" "<target-dir>/ralph-tts-elevenlabs"
cp -f "${PLUGIN_ROOT}/bin/ralph-dashboard"      "<target-dir>/ralph-dashboard"
cp -f "${PLUGIN_ROOT}/bin/ralph-cmux"           "<target-dir>/ralph-cmux"

Make all copied scripts executable:

chmod +x "<target-dir>"/ralph-loop \
          "<target-dir>"/ralph-lib.sh \
          "<target-dir>"/ralph-stream-parse \
          "<target-dir>"/ralph-overseer

(Add chmod for optional scripts too if copied.)

Never copy test-gate-autoclose — it is a regression test for the plugin itself, not a project tool.

Ask the user if the target directory should be added to .gitignore:

Use AskUserQuestion:

Question: "Add <target-dir> to .gitignore?" Header: ".gitignore" Options:

1. Yes — "Keep scripts out of version control."
2. No — "Commit scripts alongside the project."

If yes, append to .gitignore:

echo "<target-dir>/" >> .gitignore

(Check first that the line doesn't already exist to stay idempotent.)

Step 5: Formula install

Check if the formula is already installed:

test -f ~/.beads/formulas/qrds-pi.formula.json && echo "EXISTS" || echo "MISSING"

If EXISTS, compare versions:

python3 -c "import json,sys; print(json.load(open(sys.argv[1])).get('version','unknown'))" ~/.beads/formulas/qrds-pi.formula.json 2>/dev/null
python3 -c "import json,sys; print(json.load(open(sys.argv[1])).get('version','unknown'))" "${PLUGIN_ROOT}/formulas/qrds-pi.formula.json" 2>/dev/null

If both versions are identical, skip with: [skip] qrds-pi formula already at current version

If missing or outdated, copy:

mkdir -p ~/.beads/formulas
cp -f "${PLUGIN_ROOT}/formulas/qrds-pi.formula.json" ~/.beads/formulas/qrds-pi.formula.json

Verify the copy:

bd formula list | grep qrds-pi

If qrds-pi does not appear, report the error and continue (non-fatal — the formula can be installed manually).

Step 6: PI planning contract

Install the ExecPlan contract and default plan directory.

Check whether PLANS.md already exists:

test -f PLANS.md && echo "EXISTS" || echo "MISSING"

If MISSING, copy it from the plugin:

cp -f "${PLUGIN_ROOT}/PLANS.md" PLANS.md

If EXISTS, do not overwrite it. User/project-local planning contracts win.

Ensure the plan directory exists:

mkdir -p plans

Ensure a placeholder exists so the directory can be committed if desired:

test -f plans/.gitkeep || : > plans/.gitkeep

Step 7: AGENTS.md integration

Inject a versioned block into AGENTS.md. The block is delimited by:

<!-- BEGIN RALPH-CRISPIES v:1 -->
...
<!-- END RALPH-CRISPIES -->

The block content to inject:

<!-- BEGIN RALPH-CRISPIES v:1 -->
## Ralph Crispies — QRDS-PI Workflow

This project uses the QRDS-PI cycle for planned development.

The PI implementation contract lives in `PLANS.md`. After structure approval,
`plan-research` writes a checked-in ExecPlan under `plans/`, and `expand`
decomposes implementation beads from that ExecPlan.

### Runner selection

Ralph Crispies can run beads with Claude Code or Codex. Runner selection uses:

1. `--runner <claude|codex>` when supported by a script
2. `runner:claude` / `runner:codex` bead labels
3. `RALPH_RUNNER`
4. default `claude`

See `docs/dual-runner.md` for label schema details.

### Workflow overview

rc-questions → interview + bead graph ralph-loop → autonomous R-D-S phases rc-next → review plan, approve, or iterate ralph-loop --worktree → implementation rc-next → review diff, create PR

### Quick reference

```bash
bd ready              # Show unblocked beads
bd show <id>          # Read bead details
rc-next               # Daily driver — read state and route
rc-questions <task>   # Start a new QRDS cycle
ralph-loop <epic-id>  # Run autonomous loop

Session completion

Before ending any session: commit changes, push to remote, push beads data.

git pull --rebase && bd dolt push && git push

**Idempotency logic:**

Read the current `AGENTS.md` (if it exists):

```bash
cat AGENTS.md 2>/dev/null

• If the block (<!-- BEGIN RALPH-CRISPIES v:1 --> ... <!-- END RALPH-CRISPIES -->) is already present: replace the entire block with the current content above. This updates outdated versions.
• If the file exists but the block is absent: append the block at the end of the file.
• If the file does not exist: create it with only the block.

When replacing an existing block, use Edit to do a precise find-replace between the markers. When appending, write a newline before the block.

If CLAUDE.md exists in the target project, do NOT use it as the primary workflow contract. Append one short note if absent:

See `AGENTS.md` for the Ralph Crispies workflow and project agent instructions.

Do not install the Ralph workflow block into CLAUDE.md.

Step 8: AGENTS.md setup

Check if AGENTS.md already exists:

test -f AGENTS.md && echo "EXISTS" || echo "MISSING"

If EXISTS: do not overwrite user content. The step above should append or update only the Ralph Crispies block.

If MISSING, create it:

# Agent Instructions

This project uses **bd (beads)** for issue tracking. Run `bd prime` for full workflow context.

## Build / Test / Lint

```bash
# TODO: Fill in your project's build, test, and lint commands.
# Examples:
# npm test
# cargo test
# pytest
# go test ./...

Beads Issue Tracker

This project uses bd (beads) for issue tracking. Run bd prime to see full workflow context and commands.

Quick Reference

bd ready              # Find available work
bd show <id>          # View issue details
bd update <id> --claim  # Claim work
bd close <id>         # Complete work

Rules

• Use bd for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists
• Run bd prime for detailed command reference and session close protocol
• Use bd remember for persistent knowledge — do NOT use MEMORY.md files

Session Completion

When ending a work session, you MUST complete ALL steps below. Work is NOT complete until git push succeeds.

MANDATORY WORKFLOW:

1. File issues for remaining work - Create issues for anything that needs follow-up
2. Run quality gates (if code changed) - Tests, linters, builds
3. Update issue status - Close finished work, update in-progress items
4. PUSH TO REMOTE - This is MANDATORY:

   git pull --rebase
   bd dolt push
   git push
   git status  # MUST show "up to date with origin"
   

5. Clean up - Clear stashes, prune remote branches
6. Verify - All changes committed AND pushed
7. Hand off - Provide context for next session

CRITICAL RULES:

• Work is NOT complete until git push succeeds
• NEVER stop before pushing - that leaves work stranded locally

Use the Write tool to create this file if it did not already exist.

## Completion report

After all steps complete, output a summary:

> "**Ralph Crispies initialized.**"
>
> - bd workspace: [initialized / already present]
> - Scripts: copied to `<target-dir>/` [list of scripts]
> - Formula: [installed / updated / already current]
> - PI contract: [`PLANS.md` copied / already exists], `plans/` [created / already present]
> - AGENTS.md: [created / Ralph block injected / Ralph block updated / already present]
> - CLAUDE.md: [left alone / note appended pointing to AGENTS.md]
>
> **Start your first cycle:**
> ```
> rc-questions <describe what you want to build>
> ```

## Hard rules

1. Never overwrite `AGENTS.md` if it exists — user content is sacred.
2. Never copy `test-gate-autoclose` — it is an internal plugin regression test.
3. All file copy operations use `cp -f` — never plain `cp` (may be aliased to interactive mode).
4. If plugin source cannot be found, stop at Step 2 with clear install guidance.
5. Steps 3–8 run even if Step 4 is skipped (script copy is optional; workspace, formula, `PLANS.md`, and `AGENTS.md` are not).
6. The AGENTS.md block version marker is `v:1` — future versions increment this number. Always replace a lower version with the current one.