| name | ralph-deploy |
| description | Plan and configure ralph-orchestrator deployments for projects at any stage — from a vague phase plan to a mature codebase. Use this skill whenever the user wants to set up ralph for a new project, choose between deployment topologies (direct, Claude+MCP, multi-project supervisor), pick the right config for their project's maturity, run oneshot autonomous builds, or manage multiple concurrent ralph loops across tmux sessions. Also use when the user asks "how should I run ralph on this?", mentions phase plans, or wants to configure cost budgets, hat workflows, or guardrails for a specific project type. |
Ralph Deploy
Configure and launch ralph-orchestrator. Install: cargo install --git https://github.com/mikeyobrien/ralph-orchestrator ralph-cli
Directory Discipline
.kiro/specs/ # specs (committed)
NN-<name>/
requirements.md # input: the spec AND the ralph prompt (-P)
design.md # output: archived scratchpad after loop
progress.txt # output: timestamped task log
steering/ # optional: product vision, tech decisions
.ralph/ # orchestrator (gitignored runtime state)
ralph.yml # config (core.specs_dir → .kiro/specs)
hats/greenfield.yml # hat definitions with ceremony instructions
agent/scratchpad.md # hat handoff channel (ephemeral)
agent/memories.md # persistent constraints (seed with ceremony rules)
Rules: No root pollution. requirements.md IS the prompt — no separate prompt.md. design.md is an output, not an input. .kiro/specs/ is canonical — migrate legacy locations. Number spec dirs sequentially (01-, 02-).
Before You Start
ralph loops list
tmux has-session -t ralph-$NAME 2>/dev/null && echo "running"
ls .ralph/loop.lock 2>/dev/null
If running: monitor, don't start another. If stale lock with no session: rm .ralph/loop.lock.
Hats = Roles in the Loop
work.start → [planner] → plan.ready → [builder] → build.done → [reviewer]
↑ ↑ │
│ └── work.resume ───────────┤ (code bug)
└──────── replan ────────────────────────────────────┘ (plan wrong)
│
LOOP_COMPLETE (verified)
Hats communicate via scratchpad (task breakdown + acceptance criteria), memories (persistent constraints), and event payloads. Sonnet MUST NOT be reviewer — it ignores event constraints and causes stale loops. Use Opus for planner and reviewer; Opus or Sonnet for builder.
Tmux Setup
SPEC="<spec-name>"
tmux new-session -d -s "$NAME" -c "$PROJECT_PATH"
tmux send-keys -t "$NAME:0" "ralph run -q -c .ralph/ralph.yml -H .ralph/hats/greenfield.yml -P .kiro/specs/$SPEC/requirements.md > .ralph/run.log 2>&1" Enter
tmux split-window -v -t "$NAME:0" -c "$PROJECT_PATH" -l 80%
tmux send-keys -t "$NAME:0.1" "bash .ralph/monitor.sh" Enter
tmux resize-pane -t "$NAME:0.0" -y 3
Monitor: .ralph/monitor.sh (copy from scripts/monitor.sh in this skill) or ralph tui (needs real TTY, attach directly). Set up CronCreate every 3 minutes to poll events + commits. Auto-cancel when loop terminates.
Codex Periodic Watch
For Codex, periodic Ralph monitoring can be implemented by reusing a watcher sub-agent as a timer-like harness.
- Spawn one monitor sub-agent and keep reusing the same agent id/thread.
- Give it a bounded instruction such as: wait 60-180 seconds, inspect the Ralph loop, then return a compact status summary.
- When it returns, the main Codex agent should:
- summarize status to the user if needed
- decide whether to steer Ralph
- send the next timed watch instruction to that same monitor sub-agent
- Treat this as a reusable monitor channel, not as a native always-on daemon.
Recommended Codex watch cycle:
- Create monitor agent once.
- Instruct: wait N minutes, check Ralph status, report
progressing, stuck, failed, or needs-input.
- Main agent inspects result and optionally emits steering.
- Main agent reuses the same monitor agent for the next cycle.
Use this when Codex is the meta-orchestrator and no built-in timer tool is available. If another frontend provides a native timer tool, prefer that simpler primitive over a sub-agent watch loop.
CLI Reference
| Action | Command |
|---|
| Loop status | ralph loops list |
| Events | ralph events --last 10 |
| View plan | cat .ralph/agent/scratchpad.md |
| Stop | touch .ralph/stop-requested |
| Resume | ralph run --continue |
| Steer | ralph wave emit human.guidance --payloads "msg" |
| Validate | ralph preflight -c .ralph/ralph.yml -H .ralph/hats/greenfield.yml |
| Dry run | ralph run --dry-run -c .ralph/ralph.yml -H .ralph/hats/greenfield.yml -P .kiro/specs/<name>/requirements.md |
Writing the Spec (requirements.md)
Human-authored, variable-depth. The planner fills gaps; never overrides what the human specified.
Thin (domain is well-understood):
Rework Docker/Splunk infra from the devcontainer template.
Splunk 10.2.1+, Python 3.12. Ports: 18000/18088/18089.
Accept when: `docker compose config` validates and all 7 checks pass.
Detailed (high stakes, specific opinions):
### Requirement 1: Strategy wiring
1. WHEN scene JSON has `"strategy": "rule-based"`, THE Bot SHALL use RuleBasedStrategy
2. WHEN strategy is omitted, THE Bot SHALL default to RuleBasedStrategy
3. WHEN unknown strategy specified, THE ScenePlayer SHALL raise ScenePlayerError
Include: code deliverables, infrastructure tasks, handoff artifacts, verification requirements. Claude can help draft — but should not author unilaterally.
Lifecycle
human writes requirements.md → ralph run -P requirements.md
↓
planner → builder → reviewer loop
↓
ceremony: archive scratchpad → design.md
write progress.txt
↓
update PROJECT_PLAN.md → next spec
One spec = one loop. Only write requirements.md before launching. Archive after loop. Migrate legacy spec locations on sight.
Operational Discipline
- Minimize loop restarts — each costs a planner re-analysis
- Don't ask human questions unless blocked
- Update PROJECT_PLAN.md after each spec completes
- TUI needs real TTY — use
-q mode in tmux
- Handoff artifacts are deliverables with acceptance criteria
- Ceremony is enforced in hat instructions and seeded memories — not here
Greenfield Hat Config
event_loop:
starting_event: "work.start"
completion_promise: "LOOP_COMPLETE"
hats:
planner:
name: "Architect"
description: "Reads specs, breaks work into tasks with acceptance criteria"
backend: claude
backend_args: ["--model", "opus"]
triggers: ["work.start", "phase.next", "replan"]
publishes: ["plan.ready", "scaffold.done"]
default_publishes: "plan.ready"
max_activations: 4
instructions: |
RESEARCH FIRST: Read existing code, the requirements.md (passed via -P),
CLAUDE.md, scratchpad, and .ralph/agent/memories.md. Understand what's
built, what works, what's broken. Do not plan from requirements.md alone.
Write an ARTIFACT REGISTRY in the scratchpad — a table of every
deliverable with columns: Exists | Tests | Runtime Verified | Acceptance Criteria
Break work into tasks. For EACH task, write concrete acceptance criteria:
commands to run, output to expect, endpoints to curl, files to check.
Include infrastructure setup and handoff artifacts as tasks when needed.
Emit scaffold.done if scaffolding, then plan.ready.
builder:
name: "Builder"
description: "Implements tasks from the plan"
backend: claude
backend_args: ["--model", "opus"]
triggers: ["plan.ready", "work.resume"]
publishes: ["build.done", "tests.passing"]
default_publishes: "build.done"
instructions: |
Read the scratchpad for the current task and its acceptance criteria.
Read .ralph/agent/memories.md for known constraints and past fixes.
Implement the task. Write appropriate tests. Verify your own work against
the acceptance criteria before committing. If a criterion says "run this
command and see X", actually run it. Commit after each logical unit.
PROGRESS TRACKING — after each task commit:
1. Find the spec directory (parent dir of the -P requirements.md file).
If unsure, check .ralph/agent/memories.md for the spec dir path.
2. Append a line to progress.txt in that spec directory:
[YYYY-MM-DD HH:MM] DONE task-id — one-line description (commit-hash)
3. Update the SUMMARY line at the top:
4. If progress.txt doesn't exist yet, create it with this header:
Write to .ralph/agent/memories.md when you discover non-obvious constraints.
reviewer:
name: "Reviewer"
description: "Verifies implementation and diagnoses failures"
backend: claude
backend_args: ["--model", "opus"]
triggers: ["build.done"]
publishes: ["LOOP_COMPLETE", "work.resume", "plan.ready", "replan"]
default_publishes: "plan.ready"
max_activations: 1
instructions: |
Read the scratchpad for the current task's acceptance criteria.
Read .ralph/agent/memories.md for known constraints and past fixes.
Verify by actually running what they specify — commands, curl, file checks.
Run the test suite as a baseline but do NOT stop there.
WHEN VERIFICATION FAILS:
1. Capture the actual error (stderr, stack trace, diff from expected)
2. Diagnose root cause — read the code, identify what's wrong
3. Write diagnosis in scratchpad under "## Reviewer Findings"
4. Write root cause to .ralph/agent/memories.md if non-obvious
5. Code bug → emit work.resume. Plan wrong → emit replan.
WHEN VERIFICATION PASSES:
- Mark task verified in scratchpad with what you ran
- More tasks remain → emit plan.ready
COMPLETION CEREMONY — when ALL tasks verified, do these IN ORDER:
1. SPEC DIR: parent directory of the -P requirements.md file.
Example: -P .kiro/specs/06-foo/requirements.md → .kiro/specs/06-foo/
2. ARCHIVE: cp .ralph/agent/scratchpad.md <spec-dir>/design.md
3. PROGRESS: verify <spec-dir>/progress.txt has a DONE line per task.
Update SUMMARY to:
If missing or incomplete, write it now with all tasks.
4. VERIFY: confirm spec dir has requirements.md, design.md, progress.txt
5. EMIT LOOP_COMPLETE only after steps 1-4 are done.
NEVER emit build.done.
NEVER emit LOOP_COMPLETE without completing ALL ceremony steps.
