Cloning /ultraplan: make the plan prove itself

A good plan is the cheapest thing in software and the most often skipped. Claude Code's /ultraplan exists to make planning worth doing again — it hands the job to a more capable setting and gives you something solid to review before a line of code is written. This is the first in a short series on cloning the Ultra commands locally, and planning is the right place to start: get the plan right and the rest is mostly execution.

One thing to get out of the way first. /ultraplan may not even be available to you — it is first-party, but it needs the right plan and a GitHub-hosted repo, and in another coding agent it isn't there at all. That is fine. What it produces is a plan rigorous enough that a reviewer, human or agent, can check it, and a coder can execute it without re-deriving your intent — and we can produce the same thing locally, running anywhere your Claude Code does.

What /ultraplan actually is

Per the official docs, /ultraplan hands a planning task from your terminal to a Claude Code session running in plan mode on the web. Claude drafts the plan in the cloud while your terminal stays free; when it's ready you open it in the browser to leave inline comments, react to sections, and skim a structured outline, then choose where to execute — in the same cloud session, which opens a pull request, or teleported back to your terminal. It needs a Pro or Max plan and a GitHub-hosted repository, which makes it a claude.ai feature rather than something you can run through Bedrock, Vertex, or Foundry.

So the cloud surface — the browser review, the managed container, the teleport — is off the table for a local clone. What we can rebuild is the plan itself, and a plan is just structured text written under a few strict rules. Those rules are what we are cloning.

The shape

The clone is a small loop, not one command. /hongyplan writes the plan; a coding pass implements it; a review pass runs the gate and writes a verdict; and on a failure /hongyplan re-plans from those failures rather than starting over. That last step is where the feedback loop begins — the plan learns from the gate instead of being thrown away, which is the whole reason it lives in a durable file, PLAN.md, that you and the next agent both read. This tutorial builds the planner. Its siblings — /hongycode and /hongyreview — are the next instalments and don't exist yet; until they ship, any coder and any reviewer fill those slots. The planner comes first, because it only earns its keep through the rules it follows.

Rule one: keep planning and coding apart

The planner is read-only with respect to source. It gathers context and writes exactly one file, PLAN.md. It never edits code. This is not fastidiousness — it is the entire point. A plan is valuable precisely because you can inspect it before anything changes, and because the next re-plan can be diffed against the last one. The moment the planner starts editing source, both properties evaporate: there is nothing to review, and nothing to diff.

A caveat on enforcement, though. A skill's allowed-tools list controls which tools are available; it cannot enforce plan-mode semantics the way a subagent with permissionMode: plan can. Write has to be allowed so the skill can author PLAN.md at all — which means don't edit source is a contract the prompt states, not a lock the runtime enforces. If you need the hard guarantee — an unattended loop, a regulated repo — run the planner as a subagent with permissionMode: plan. Treat the instruction as the contract and the subagent as the lock.

Rule two: a task is not done until a command says so

This is the rule that does the most work. Every task in the plan carries a definition of done expressed as a command whose exit code settles it — not a sentence someone has to interpret.

Good — the exit code settles it:
  pytest tests/auth/test_login.py -q
  npm run typecheck
  cargo build --release && cargo test session::

Weak — a human still has to interpret it:
  "login works"        ->  which path? success, lockout, expired token?
  "code is clean"       ->  npm run lint is the command; clean is not
  "perf is acceptable"  ->  if it matters: k6 run ... --threshold p95<200ms

The test is simple: if you cannot write the definition of done in one line, the task is too big or too vague — split it until each piece has a one-line command. When the verifying test does not exist yet, the first task in the group is write the failing test, and the implementation task's done is that same command going green. The plan comes out test-first wherever that helps, by construction rather than by discipline.

Rule three: the acceptance gate is the merge authority

Every plan ends with an acceptance gate: the exact, deterministic commands that decide whether the whole change is mergeable — usually lint, typecheck, and tests, kept identical to what CI runs. The ordering is deliberate: the gate is the authority, and an LLM reviewer's opinion is an advisory input, not the decision. Models are good at catching what a suite misses — they are not a substitute for the suite. Keeping the gate commands identical to CI is what makes passes locally and passes the gate the same sentence.

Build it

A slash command in Claude Code is just a skill. Drop a SKILL.md in .claude/skills/hongyplan/ — or ~/.claude/skills/ to make it global — and you have /hongyplan. The command name comes from the directory, not the frontmatter. Here is a faithful, trimmed version of the one I run:

---
name: hongyplan
description: >-
  Produce a rigorous, staged, reviewable implementation plan and write it to
  PLAN.md before any code is written. Use to plan, scope, or break down a
  non-trivial change, and to re-plan after a failed review by consuming
  REVIEW.md. Read-only with respect to source: it writes PLAN.md only.
argument-hint: <task to plan, or 'revise' to re-plan from REVIEW.md>
allowed-tools: Read, Grep, Glob, Write, Bash(git status:*), Bash(git diff:*), Bash(git log:*)
model: opus
---

Turn a coding task into a plan a reviewer can check and a coder can execute
without re-deriving your intent. The output is one durable file, PLAN.md. You do
not write code: planning and implementing are separated so the plan can be
reviewed before any change lands, and re-planned cheaply when a review fails.

1. Detect mode. If REVIEW.md exists with unresolved `VERDICT: FAIL` or
   `BLOCKER:` findings, this is a RE-PLAN (step 8). Otherwise, a fresh plan.

2. Gather context (read-only). Read CLAUDE.md and any existing PLAN.md; inspect
   the areas the task touches; check `git status` and recent `git log`. Pull
   just enough to plan accurately.

3. Decide the approach in a few sentences. For each non-obvious choice, record
   the options, the choice, why, and the risk it carries.

4. Decompose into small, independently verifiable tasks. Each gets an imperative
   description, the files it touches, and a definition of done expressed as a
   command whose exit code proves it. If you cannot write that command in one
   line, the task is too big: split it.

5. Define the acceptance gate: the exact, deterministic commands that decide
   whether the whole change is mergeable. Keep them identical to CI. This is the
   merge authority; an LLM review verdict is advisory, not the gate.

6. Capture the few real risks, their mitigation, and how to roll back.

7. Write PLAN.md: objective; context and constraints; approach and decisions;
   the staged `- [ ]` tasks; the acceptance-gate command block; risks and
   rollback; a re-plan log. Then stop. Do not implement: that is the coder's job, not the planner's.

8. Re-plan. Map each failed criterion in REVIEW.md to a concrete plan change,
   append an entry to the re-plan log quoting the failure, and rewrite PLAN.md
   in place, keeping unaffected `- [x]` tasks checked. A re-plan that does not
   tie each change to a named failure is a guess: it will fail the same gate.

Two details matter. model: opus, because planning is the step where extra reasoning pays for itself — a wrong call here multiplies downstream. And step one checks for a REVIEW.md: that single branch is what turns a one-shot planner into a loop.

When the review fails, re-plan — do not restart

When a review writes a REVIEW.md with failures, the planner does not regenerate from scratch and it does not re-issue the plan that just failed. It maps each failure to a specific change:

• Missed requirement — add a task, with its command-based done, that covers it.
• Wrong approach — revise the approach and the affected tasks, and say why the new one avoids the failure.
• Correctness bug in a task that passed — the command passed but did not actually prove the property, so strengthen the command and reopen the task.
• Gate gap — a bug slipped through a green gate, so add or tighten a gate command, and the same class of bug cannot pass next time.

Each change is logged against the failure that caused it, and unaffected tasks stay checked. The anti-pattern is re-emitting the same plan with cosmetic edits: if nothing in the approach, the tasks, or the gates changed, the next iteration fails the same way and burns a cycle for nothing. A re-plan that does not tie each change to a named failure is just a guess.

Structurally, this is the evaluator-optimiser pattern from Anthropic's Building effective agents: a generator (/hongyplan, then whatever implements the plan) paired with an evaluator (the gate, plus a review pass) that feeds concrete failures back in. It is the same shape as my hongyflow loop, scoped down to a single artefact.

Extending the planner

A planner that writes a solid PLAN.md is already worth having on its own, and you can push it further today — before any of the rest of the series exists. The highest-leverage extension is your own risk posture:

• Encode your security and risk appetite. Because the planner is read-only and the plan is reviewed before a line of code is written, planning time is the cheapest place to enforce risk posture — settle it before the build stage rather than bolting it on after. Add a threat-modelling task for anything that touches auth, data, or external input; fold the security checks you care about (npm audit, a secrets scan, a SAST run) into the acceptance gate so they are non-negotiable; and require a rollback for anything risky. In a regulated codebase, this is where your controls live.
• Budget scaling. Set model per task — cheap work on haiku or sonnet, the plan and the gate on opus — and scale the depth of decomposition with the effort level.
• Graduate to a workflow. When you want several plans drafted in parallel and merged, a single conversation runs out of room. Have Claude write it as a dynamic workflow and save the run as a command; the candidate plans then live in script variables instead of your context window — the closest local analogue to what the cloud does. Start with Using Claude Code Dynamic Workflows.

The rest of the series isn't built yet. Here is what is coming, and how each piece leans on the planner:

• /hongycode (next). It will read PLAN.md, implement the tasks in order, and run each task's command as it goes — so the coder always knows when to stop.
• /hongyreview (after that). It will review the diff, run the acceptance gate, and write REVIEW.md in a form the planner can consume. A stronger version is worth building: the hongyflow-review workflow I already use makes every finding survive refutation by two independent sceptics before it counts.

What a local clone cannot do

Be honest about the ceiling. The clone reproduces the rigour and the loop. It does not reproduce /ultraplan's browser review surface — the inline comments, the reactions, the outline sidebar — its managed cloud container, or the teleport back to your terminal. If you want those, use the real thing; that is what it is for. What the clone buys you instead: it runs anywhere your Claude Code runs, including Bedrock, Vertex, and Foundry, where /ultraplan is not available; it costs nothing on top of what you already pay; and you own every rule it follows, so you can bend them to your codebase.

Next in the series

Same idea, different verb — and two commands are coming next. /hongyreview will point the rigour at a diff (deterministic gate first, model judgement second), and /hongycode will turn a checked plan into checked code. Start with the planner regardless: a plan where every step names the command that proves it is one a machine can drive. Build that one first.