Plan with Opus, Ship with Parallel Sonnet: My write-plan and run-plan Skills for Claude Code

Big features break long agent sessions. By the time the agent reaches the third module, its context is full of files it read an hour ago, it has forgotten a decision from the start, and the token bill keeps climbing. I fixed this with two Claude Code skills, write-plan and run-plan, and two small subagents. This post explains how they work, how to install them, and the exact prompts I use.

Everything is free to copy: github.com/vxlabs/vibecoding_plans/tree/main/claude-skills

The idea in one paragraph

Spend your strongest model (Opus) once, on planning. It writes a folder of slices: small, self-contained task files, each one readable by an agent that has never seen your project. Then an orchestrator hands each slice to a fresh Sonnet or Haiku subagent, runs independent slices in parallel, checks every result itself, and ticks a checklist. No agent ever carries the whole project in its head.

/write-plan  ──►  docs/plans/12-billing/
                    00-README.md   (goal, decisions, status, dependency table)
                    01-schema.md   02-api.md   03-webhooks.md   04-ui.md   05-acceptance.md

/run-plan 12 ──►  slice-worker (Sonnet) ──► verify gate ──► tick README
                  slice-worker (Sonnet) ──► verify gate ──► tick README   (parallel)
                  slice-checker ──► evidence ──► you confirm acceptance

Part 1: what /write-plan produces

You give it a sentence: /write-plan add Stripe billing to the dashboard. It surveys your code with grep (not by reading every file), drafts a short brief with the scope and the out of scope list, asks you the product questions that change the design (one round only), and writes docs/plans/NN-<slug>/.

The README is the contract

00-README.md has four parts:

• Decisions table. One row per decision, each with an ID such as B3. Names, limits, status codes and permissions are written down once. Slices pull only the rows they need with grep -E '^\| (B3|B4) ' 00-README.md, so no agent reads 20k characters of requirements it doesn't need.
• Status checklist. One tickbox per slice. This is the durable state of the whole run, so a crashed or compacted session loses nothing.
• Dependency table. For each slice: prerequisites, which slices it can run alongside, the model to use, and the files it touches. This table is what lets the orchestrator parallelise safely.
• Acceptance checklist. Observable behaviours someone can check.

The skill stops here and asks you to approve the decisions. Changing a decision after the slices exist means rewriting every slice that used it, so this is the cheap moment to disagree.

Every slice is self-contained

# 12/03 — Webhook handler

Plan folder: 00-README.md · Model: Sonnet · Prerequisites: 12/01 · Parallel with: 12/04

## Decisions you need
B6 (signature check), B7 (idempotency) — run `grep -E '^\| (B6|B7) ' 00-README.md`.

## Read first
src/billing/gateway.ts (StripeGateway), src/events/outbox.ts (publish)

## Scope (files you own)
src/billing/webhooks/**, test/billing/webhooks.spec.ts

## Tasks
1. **Route.** POST /billing/webhooks, 400 on bad signature, 200 on duplicate event id...

## Done when
webhooks.spec.ts passes; build, lint and tests pass. Append `## Result`.

The header and Scope come first on purpose. The orchestrator schedules by reading only the top of each file, up to ## Tasks.

Rules the planner follows

• Parallel only on disjoint files. Two slices may run together only if their "Files touched" don't overlap. Schema and migration slices always run alone.
• Two tracks. A UI slice depends only on the API slices whose endpoints it calls, so backend and frontend usually run side by side.
• Right model per slice. Haiku for mechanical work and docs, Sonnet for real code, Opus for cross-module refactors and security-sensitive flows.
• Fewer, fuller slices. Every slice costs a cold start plus a full build and lint run, so the target is 5 to 9 slices per plan, including acceptance.

Part 2: what /run-plan does

/run-plan 12 loads the README, reads the top of each unticked slice, and starts working:

1. Rolling schedule. Up to three slices in flight. The moment a slice finishes and unblocks another, that one starts. There are no "batches" to wait for.
2. A three-line dispatch prompt. Slice path, what's running in parallel (and not to touch), plus any fact from a finished slice that changes this one. Rules and reply format live in the agent definition, so they aren't repeated per call.
3. Gate every slice itself. When a worker says DONE, the orchestrator checks git diff --stat against the slice's Scope and re-runs tools/verify-slice.sh. It never trusts the agent's own PASS.
4. Small failures get a fresh Haiku. A missing test or one failing assertion goes to a new Haiku agent with a three-line prompt. The original worker's context is already large, so resuming it is the expensive option.
5. Tick, then continue. The box in 00-README.md is ticked only after script output it has actually read.
6. Acceptance. slice-checker maps each acceptance row to a real test or command and saves raw evidence. A row is PASS, FAIL, UNPROVEN, or MANUAL (needs a real browser or a third-party account). The orchestrator reads the evidence before ticking anything. Unproven never gets rounded up.
7. Close out. New open items go into docs/plans/KNOWN-ISSUES.md and you get a report of at most 15 lines.

The orchestrator never writes slice code. If something unexpected happens it stops and tells you, rather than patching around it.

Install

Everything is plain files, so there's nothing to build. The repo layout maps to your project like this:

In the repo	Goes to
claude-skills/write-plan, claude-skills/run-plan	.claude/skills/
claude-skills/agents/*.md	.claude/agents/
claude-skills/tools/verify-slice.*	tools/
claude-skills/verify.env.example	.claude/verify.env

macOS, Linux, Git Bash:

git clone --depth 1 https://github.com/vxlabs/vibecoding_plans /tmp/vp
mkdir -p .claude/skills .claude/agents tools
cp -r /tmp/vp/claude-skills/write-plan /tmp/vp/claude-skills/run-plan .claude/skills/
cp /tmp/vp/claude-skills/agents/*.md .claude/agents/
cp /tmp/vp/claude-skills/tools/verify-slice.* tools/
cp /tmp/vp/claude-skills/verify.env.example .claude/verify.env
chmod +x tools/verify-slice.sh

Windows PowerShell:

git clone --depth 1 https://github.com/vxlabs/vibecoding_plans $env:TEMP\vp
New-Item -ItemType Directory -Force .claude\skills, .claude\agents, tools | Out-Null
Copy-Item -Recurse $env:TEMP\vp\claude-skills\write-plan, $env:TEMP\vp\claude-skills\run-plan .claude\skills\
Copy-Item $env:TEMP\vp\claude-skills\agents\*.md .claude\agents\
Copy-Item $env:TEMP\vp\claude-skills\tools\verify-slice.* tools\
Copy-Item $env:TEMP\vp\claude-skills\verify.env.example .claude\verify.env

Want them in every project? Copy the skills and agents into ~/.claude/skills and ~/.claude/agents instead. Keep tools/ and verify.env per project, because your build commands differ.

Tell the gate how to build and test your project. Open .claude/verify.env:

BUILD_CMD="npm run typecheck"
LINT_CMD="npm run lint"
TEST_CMD="npx vitest run"

Python, .NET and Go examples are in the file. The gate runs the three steps, prints one PASS or FAIL line per step, and keeps full logs on disk so they never flood an agent's context. Leave a line empty to skip a step.

Check it loaded. Restart Claude Code, type /, and look for /write-plan and /run-plan. The two subagents show up under /agents.

Prompt examples

1. Using the skills

/write-plan add Stripe billing to the dashboard: monthly plans, a customer portal link, and webhook-driven status

Review the decisions it shows you, approve, then open a fresh session (so the planner's context isn't carried over) and run:

/run-plan 12

Resume or skip ahead:

/run-plan 12 03

2. No skill installed? Use the plain prompts

These are the free-form versions of the same workflow. They work in any Claude Code session.

Create the plan:

Plan <feature> and write it as orchestration-ready slices in docs/plans/<plan-name>/.

- 00-README.md: goal, decisions table (already made, don't revisit),
  status checklist, and a dependency table showing which slices can run
  in parallel (e.g. backend track vs frontend track).
- Each NN-<name>.md must be self-contained so a fresh agent can run it
  with no other context:
  Goal · Prerequisites (slice numbers) · Files touched · Suggested model
  (Sonnet for code, Haiku for docs/checks) · Read only these files ·
  Background (copy in the decisions and API contracts it needs) · Tasks ·
  Out of scope · Done when (exact build/test commands) · Finish.
- Size each slice for one Sonnet session. Avoid two parallel slices
  editing the same files; if unavoidable, make them sequential.
- Each slice updates the spec docs its own changes affect.

Run the plan:

Orchestrate the plan in docs/plans/<plan-name>/, starting from slice NN.

- Run each slice as its own background subagent with a fresh, separate context.
  Don't execute slices inline in this conversation.
- Model: Sonnet for code slices, Haiku (or lower) for docs/check-only slices.
- Build the dependency graph from each slice's Prerequisites.
  Start every slice whose prerequisites are done in parallel, but serialize
  slices that edit the same files or share a build (e.g. same frontend files).
- Tell each agent: which files/folders it must not touch, don't commit,
  don't tick the README (you do that), and run the build/tests before reporting.
- Pass relevant facts and deviations from finished slices into later agents' prompts.
- After each slice: tick its box in 00-README.md, give me a short summary
  with anything flagged, then start whatever is now unblocked.
- You are the orchestrator, you decide. Also make sure we don't go overboard
  on token usage, and if we need auto-compact, do that too.

The skills are these prompts with the lessons baked in: the gate that re-runs tests itself, the read budgets, the fresh-Haiku fix-ups, and the evidence rules.

3. Other prompts that work well

A migration-heavy feature, where order matters:

/write-plan move user profiles to a new table with a backfill. Schema and backfill must be strictly sequential; the API and UI can follow in parallel tracks.

Planning only, to review before you spend tokens:

/write-plan add CSV export to the reports page. Stop after the README so I can approve the decisions.

After a blocked slice, once you've fixed the cause:

/run-plan 12 04

Keeping token use down

• Plan once, on the strongest model. Execution runs on cheaper ones.
• Read budgets. Workers find code with grep -n and read about 60 lines around the match. Every line read stays in their context for the whole slice.
• Decisions are quoted or grepped, never re-derived. A slice trusts its decisions and doesn't reopen the README.
• Fresh agents for fixes. Resuming a big agent re-pays for everything it read.
• Compact the orchestrator. The README checkboxes hold the state, so /compact between slices is safe.

Customising

• Models. Change the model: line in slice-worker.md, or override per slice in the dependency table.
• Parallelism. "Up to 3 slices in flight" is a single line in run-plan/SKILL.md. Raise it if your machine and rate limits allow.
• Your rules. Workers read your CLAUDE.md or AGENTS.md, so architecture rules, naming and forbidden commands you already keep there apply automatically.
• Generated code. If your project has generated API clients or schema types, keep them out of workers' scope. The orchestrator regenerates them after each gate.
• Known issues. Open items go in docs/plans/KNOWN-ISSUES.md. Point the skill at your tracker instead if you'd rather.

Wrap-up

The pattern is simple: decisions once, slices that stand alone, parallel workers that can't collide, and a gate that trusts scripts over agents. Try it on your next medium-sized feature and see how much of the work runs without you.

Grab the files and tell me what you change: github.com/vxlabs/vibecoding_plans/tree/main/claude-skills