Guide · Agent skill
How to use the Ralplan Consensus Planner agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
Ralplan is an agent skill that makes an AI coding agent write a careful, reviewed plan for a software task before it touches any code. It comes from the oh-my-claudecode toolkit and is an alias for that toolkit's consensus planning command. This guide explains what the skill does, how to install it from the ZIP on this page, how to call it, and where it needs care. By the end you will know how to get a reviewed plan that waits for your approval.
Ralplan Consensus PlannerYeachan-Heo/oh-my-claudecode · MIT Download the skill Quick start
- 1Install the oh-my-claudecode plugin. Ralplan calls the plan, team and ralph skills from that plugin, so it must be present before you start.
- 2Download the ZIP from this page. The package contains SKILL.md, the skill definition.
- 3Unzip into a skills folder. Place the contents in ~/.claude/skills/ for all projects, or in a project's .claude/skills/ folder for one project.
- 4Or upload it in the Claude apps. Go to Settings, then Capabilities, then Skills, and upload the skill there.
- 5Call the skill with a task. Run the slash command with a clear task description, adding --interactive or --deliberate if needed.
- 6Review the pending plan. Read the consensus plan, which includes principles, options and an ADR-style summary, and check the test and verification steps.
- 7Approve or request changes. Only after you explicitly approve execution should the agent move on to implementation through the team or ralph skills.
What the ralplan skill makes the agent do
Ralplan runs a planning loop instead of letting the agent start coding. A Planner role drafts the plan and a compact summary of principles, decision drivers and at least two viable options. Separate Architect and Critic roles then review that same fixed draft, and the Planner revises it. The loop repeats until the Critic approves or five iterations have run.
When the loop finishes, the plan is marked as pending approval and the agent stops. According to the skill file, it must not edit source files, commit, push, open pull requests, or delegate implementation until you explicitly approve execution.
- Planner drafts the plan and an options summary
- Architect checks architectural soundness and must give the strongest counter-argument and at least one real tradeoff
- Critic checks option fairness, risk mitigation, testable acceptance criteria and concrete verification steps
- Up to five revision rounds, then the best version is presented to you
Install the ralplan skill from the ZIP
Download the ZIP for this skill from this page. The skill package contains a single file, SKILL.md. Then choose one of the two install locations below.
For a personal install that applies to all your projects, unzip the file into ~/.claude/skills/. To limit it to one project, unzip it into that project's .claude/skills/ folder. If you use the Claude apps instead, you can upload the skill under Settings, then Capabilities, then Skills.
- Personal: ~/.claude/skills/
- Single project: .claude/skills/ inside the project folder
- Claude apps: Settings → Capabilities → Skills, then upload
Requirements before you run it
The skill is a thin alias. It calls other commands in the oh-my-claudecode plugin, namely the plan, team and ralph skills. This file does not include those, so the plugin must be installed or ralplan will have nothing to call.
The skill is written for Claude Code. The optional Codex CLI is only needed if you use the codex options for the Architect or Critic role. If Codex is not available, the skill notes the fallback and uses its default Claude review. An optional company-context tool can also be configured in .claude/omc.jsonc or ~/.config/claude-omc/config.jsonc.
- oh-my-claudecode plugin (provides the plan, team and ralph skills)
- Claude Code runtime
- Optional: Codex CLI for --architect codex or --critic codex
- Optional: a company-context MCP tool set in .claude/omc.jsonc or ~/.config/claude-omc/config.jsonc
How to trigger ralplan and the main flags
The documented way to call the skill is the slash command below, with a plain description of the task. The source describes ralplan as an entrypoint that catches vague ralph, autopilot or team requests before execution, so a loosely worded build request can be routed through planning first. Naming the skill directly is the most reliable option.
Without --interactive the workflow runs fully automatically and ends with a plan marked pending approval. With --interactive, the agent pauses at a draft review and at final approval so you can choose to proceed, request changes or reject. Use --deliberate for high-risk work. It adds a three-scenario pre-mortem and a wider test plan. Deliberate mode can also switch on by itself when the request clearly involves auth or security, migrations, destructive changes, production incidents, personal data or compliance, or public API breakage.
- --interactive: pause for your input at the draft and at final approval
- --deliberate: force high-risk mode with pre-mortem and expanded tests
- --architect codex: use Codex for the Architect pass if available
- --critic codex: use Codex for the Critic pass if available
/oh-my-claudecode:ralplan --interactive --deliberate "task description"Examples of good requests
Give the skill a concrete target and a boundary. A request like 'ralph improve the app' gives the agent no clear target, which is the situation the skill's pre-execution gate is meant to catch. A request that names the goal, the affected area and any constraints gives the planner something to review.
For a risky change, say so in the request. The skill checks for high-risk signals, and stating them plainly makes it more likely that deliberate mode is applied.
- Weak: 'ralph improve the app'
- Clearer: 'plan a rewrite of the session token check in the login module, keeping existing API responses unchanged'
- Risky: 'plan a schema migration that drops the legacy orders table, with a rollback path'
Safety notes and tips
The skill file lists no scripts and no network use, and it works by instruction only. Its main safety property is the planning boundary: it should not change your code until you approve. Still, read the plan before you say yes. The Architect and Critic are AI roles reviewing an AI-written plan, so they can miss things.
If you configure the optional company-context tool, the skill will send it a summary of your task, constraints and likely files before the review loop. Treat returned text as background only. Check which tool you point it at, and what its onError setting does on failure, before you rely on it.
- Review the final plan and its acceptance criteria before approving execution
- Use --deliberate for auth, data deletion and migrations
- Skip ralplan for small, obvious edits to avoid extra time and cost
- Remember that the company-context tool, if configured, receives a task summary
What people use it for
- Planning a risky auth change with a pre-mortem before any code is edited
- Reviewing a database migration plan with expanded test coverage
- Getting a second-opinion critique of a multi-file refactor before work starts
- Structuring a large feature into a reviewed plan before handing it to a team of agents
Frequently asked questions
Is the ralplan skill free?
This page does not state a price or licence terms for the skill beyond the item's listed licence of MIT. The skill itself depends on the oh-my-claudecode plugin and the Claude Code runtime, which are separate requirements. Check those projects for their own terms before you rely on them.
How do I install ralplan?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for all projects, or into a project's .claude/skills/ folder for one project. You can also upload it in the Claude apps under Settings, then Capabilities, then Skills.
Does ralplan need the oh-my-claudecode plugin?
Yes. The skill file is only an alias that calls /oh-my-claudecode:plan --consensus, and it relies on the plan, team and ralph skills from that plugin. The skill file does not include those, so without the plugin it cannot do its work.
Will ralplan change my code automatically?
No, not by default. The skill marks the plan as pending approval and stops. It should not edit files, commit or run changes until you explicitly approve execution, either in the current turn or through the approval prompt when --interactive is set.
What is the difference between ralplan and ralph?
According to the skill file, ralph is an execution mode that runs work sequentially, while ralplan is a planning step that runs first. Ralplan's gate is designed to send vague execution requests through planning before ralph, autopilot or team start.
Can I use ralplan with Codex or a different model?
The skill supports --architect codex and --critic codex when the Codex CLI is available. If it is not, the skill notes the fallback and uses its default Claude review. Codex runs are kept sequential, not parallel, to avoid cascade failures from rate limits.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Ralplan suits developers and teams who want a reviewed plan before an agent writes code, especially for risky work like auth, migrations or data deletion. It is a poor fit for small edits, where the multi-round review costs more time than it saves, and for anyone without the oh-my-claudecode plugin, since the skill cannot run without it.
Download the skill