From ralph-crispies
Ralph Crispies: bootstrap QRDS-PI workflow in any project. Sets up beads workspace, copies scripts, installs formula, and installs AGENTS.md workflow instructions. Triggers on: rc-init, rc init, setup ralph, bootstrap.
How this skill is triggered — by the user, by Claude, or both
Slash command
/ralph-crispies:rc-initThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Bootstrap the QRDS-PI workflow in any project.
Bootstrap the QRDS-PI workflow in any project.
Target directory: $ARGUMENTS (default: .scripts/)
Installs everything a project needs to run the QRDS-PI cycle:
PLANS.md) and plans/AGENTS.mdCLAUDE.md optional; if present, it should point readers to AGENTS.mdEach step is idempotent. Re-running is safe.
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 initfirst, then re-runrc-init."
Stop on any failure. Both checks must pass before continuing.
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:
- Restart Claude Code so the SessionStart hook can write /tmp/.ralph-crispies-plugin-root-$(id -u)
- Or install the plugin: /install-plugin ralph-crispies"
- If running from Codex, ensure
ralph-loopis on PATH or setPLUGIN_ROOTmanually
Record PLUGIN_ROOT — all later steps reference it.
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.
Determine the target directory:
$ARGUMENTS is non-empty, use that path as-is..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:
.scripts/ (default) — "Copy to .scripts/ in this project."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 variableralph-dashboard: local dashboard surface that reads .ralph-overseer/state.jsonralph-cmux: supported cmux workspace launcher for overseer + dashboard surfacesUse AskUserQuestion for optional scripts:
Question: "Which optional scripts should I include?" Header: "Optional scripts" Options:
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:
If yes, append to .gitignore:
echo "<target-dir>/" >> .gitignore
(Check first that the line doesn't already exist to stay idempotent.)
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).
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
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
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
<!-- BEGIN RALPH-CRISPIES v:1 --> ... <!-- END RALPH-CRISPIES -->) is already present: replace the entire block with the current content above. This updates outdated versions.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.
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 ./...
This project uses bd (beads) for issue tracking. Run bd prime to see full workflow context and commands.
bd ready # Find available work
bd show <id> # View issue details
bd update <id> --claim # Claim work
bd close <id> # Complete work
bd for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO listsbd prime for detailed command reference and session close protocolbd remember for persistent knowledge — do NOT use MEMORY.md filesWhen ending a work session, you MUST complete ALL steps below. Work is NOT complete until git push succeeds.
MANDATORY WORKFLOW:
git pull --rebase
bd dolt push
git push
git status # MUST show "up to date with origin"
CRITICAL RULES:
git push succeeds
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.
npx claudepluginhub mwarger/ralph-crispies --plugin ralph-crispiesCreates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.