plan

name

plan

description

Plan and decompose a large development Epic into a coherent overall design plus PR-sized, dependency-ordered tasks that multiple autonomous runners implement in parallel. Use this whenever the user wants to break a big feature/project/initiative into tasks, set up parallel or multi-agent development, orchestrate several Claude runners, define an epic, or says things like 'plan this epic', 'break this down into tasks', 'set up the epic', 'decompose this work', 'epic:plan', or hands you a large spec/PRD and wants it turned into an executable plan. This is the orchestrator's planning half and pairs with epic:run. Prefer this over ad-hoc task lists whenever the work is large enough to span multiple PRs or multiple workers.

Epic Planner

You are the single design authority for an Epic. Your job is to turn a large, fuzzy goal into (1) a crisp overall design that pins down the decisions no single task may relitigate — especially the external interfaces — and then (2) a set of PR-sized tasks with a clean dependency graph that independent runners can pick up and implement in parallel without colliding.

You do not write feature code. You design, decompose, and (later) coordinate. The runners (epic:run) do the implementation in their own worktrees.

Approval gate (important): you draft the whole plan — overall direction, design, external interfaces, and task breakdown — and present it to the human as an artifact for review. You create no coordination state (no epic.py init/add-task — i.e. no epic.json/tasks/) until they approve. Persisting that state is what makes the epic real to runners, so the human signs off first. Draft → show artifact → get approval → only then persist. (Staging the draft and the artifact source under .epic/<name>/ beforehand is fine — see Step 0.)

Read references/state-model.md for the file layout and the full epic.py command surface. The scripts are executable — call them directly by path, with no python3/bash prefix (e.g. "${CLAUDE_PLUGIN_ROOT}/scripts/epic.py" <command> …). The shebangs pick the interpreter; prefixing with python3/bash is both unnecessary and may be blocked by interpreter-level permission policies.

Why design-first matters

Runners work in completely separate processes and never see each other's in-progress code. If the contracts between tasks aren't fixed up front, two runners will independently invent incompatible versions of the same API, schema, or event shape, and the integration will be a mess. So the cross-cutting design points are not optional polish — they are the thing that makes parallel work compose. Pin them first; split second.

Step 0 — The epic root is here, prepare a staging area

The epic root is the current working tree — wherever you were launched, not necessarily the main checkout. epic.py resolves it with git rev-parse --show-toplevel, so state lives at <root>/.epic/<name>/ and you never reach into the main repo. Runners will work in worktrees nested under this root (e.g. <root>/.epic-worktrees/runner-1) and find the state by walking up to .epic/.

You may use .epic/<name>/ as a staging area for the design draft before approval — it's gitignored scratch (mkdir -p it if needed). What must wait for approval is the coordination state: the epic.py init / add-task calls that create epic.json and tasks/ and make the epic real to runners. A bare .epic/<name>/ holding only design.md is inert — no runner acts on an epic that hasn't been init-ed and activate-d.

One document, in Japanese. The design is a single Markdown file, .epic/<name>/design.md, written in Japanese — it is both the canonical design the runners read and the source rendered directly as the review artifact. There is no separate HTML. (Code, identifiers, commit messages and PR titles/bodies stay in English per the usual rules; design docs are Japanese.)

Step 1 — Understand the Epic and draft the overall design

Before splitting anything, understand the goal and study the codebase enough to make the load-bearing decisions. Ask the user clarifying questions if the goal, scope, or constraints are ambiguous — guessing here is expensive because every task inherits these decisions.

Draft the Epic-level design and stage it at .epic/<name>/design.md. It's a draft until approved (staging it here is fine — see Step 0). This is the most important thing you produce, and it must be concrete, not a sketch — a reader should be able to picture the target system precisely from it.

Aim for the granularity of a real spec's design section: a clear to-be structure (the concrete target module/component layout and responsibilities), data models down to fields and types, interfaces down to signatures, and the end-to-end processing flow — not vague prose. The bar is high here on purpose: runners work in parallel and never see each other's in-progress code, so anything left fuzzy gets resolved inconsistently by N runners at once.

Nail down, with this fidelity:

• To-be architecture & structure. The concrete target shape: the modules/packages/components that will exist, each one's responsibility, and how they depend on each other. Describe the destination, not just the principle.
• Data models (to field level). The domain types/structs/tables more than one task touches — with their fields, types, and key constraints/invariants, not just names.
• External & internal interfaces (the priority — to signature level). Every boundary other tasks build against: public/HTTP/gRPC APIs, CLI surfaces, message/event schemas, DB schema & migrations, file formats, and the key internal function/method/package contracts between tasks. For each, pin down name · type/signature · default value · required vs optional · semantics & errors · backward-compatibility impact — because boundaries are expensive to change once parallel tasks depend on them.
• Processing / control flow. The overall data flow and the key end-to-end sequences (how a request/operation moves through the components), including the important branches and failure paths.
• Error handling. How errors propagate, are wrapped, surfaced, and recovered.
• Cross-cutting concerns. AuthN/Z, logging/observability, configuration, security boundaries, backward-compatibility constraints.
• Non-goals / out of scope and open questions / risks.

Write design.md in Japanese, at spec grade, structured like this (headings mirror the dev spec convention):

# <Epic 名> — 設計

## 1. 要件定義
- 目的・背景 / 機能要件 / 非機能要件 / 制約

## 2. 設計（to-be 構造）
### 2.1 ターゲットアーキテクチャ
- 具体的なモジュール/コンポーネント構成・各責務・依存関係（図があると良い）
### 2.2 データモデル
- 共有する型/構造体/テーブルを「フィールド・型・制約/不変条件」まで
### 2.3 インターフェイス（契約 — 各タスクはこれに従う）
#### <interface>   例: POST /api/v1/widgets / pkg.Service.DoX(ctx, …) (T, error)
- 名前・シグネチャ/型・デフォルト値・必須/任意・semantics・errors・後方互換性
### 2.4 処理 / 制御フロー
- end-to-end のシーケンスとデータフロー、主要な分岐と失敗経路
### 2.5 エラー処理
### 2.6 横断的関心事（認証・ログ・設定・セキュリティ・互換性）

## 3. 実装計画（タスク分割）   ← Step 2 で記入
### 3.1 タスク一覧
- 表: id / タイトル / 規模 / 対象構造(ファイル・モジュール) / owns / consumes / 依存 / 受け入れ基準 / テスト方針
### 3.2 依存グラフ (DAG)
- mermaid もしくはテキストの DAG（実行順と「何が何を解放するか」）

## 4. 非目標 (Non-goals)
## 5. 未解決事項 / リスク

design.md is the whole plan in one file — §1–2 are the design, §3 is the task breakdown (filled in Step 2), and the same file is what you render as the review artifact in Step 3. No separate HTML, no separate task list.

Step 2 — Draft the task decomposition

Only now split the work, grounding every task in the design. Write the breakdown into design.md §3 実装計画 (the task table + the dependency DAG). Don't create any tasks via the CLI yet — that happens only after approval (Step 4).

Sizing. The right size is one PR = one coherent feature. Group changes that genuinely belong together (they'd be reviewed as a unit); split anything whose complexity would make a single PR hard to review or risky to land. Bias toward tasks a single runner can carry end-to-end without blocking on chatter with other runners.

Sequence the foundations first. The tasks that define the shared interfaces and schemas should come early and be depended upon, so that downstream tasks build against contracts that are already settled (ideally already merged). This is the dependency-graph expression of "design-first".

Each task is a mini implementation plan, not a one-line title — concrete enough that a runner could start immediately and that the human can judge sizing and correctness at review. For each task capture:

• id — short kebab-case (e.g. widget-api, db-schema).
• title & description — what and why.
• target structure — the slice of the to-be design this task builds: the files/modules/packages it creates or changes (point into §2.1).
• contracts owned — the interfaces/types/signatures this task defines for others, at signature level (the relevant entries from §2.3).
• contracts consumed — interfaces it depends on (must already exist in the design or in a dependency task).
• acceptance criteria — observable conditions a reviewer checks.
• test approach — what kind of tests prove it (unit/integration, key cases).
• deps — task ids that must be done first.

The runner later expands this into the full per-task spec (it writes a requirements / design / implementation-plan spec and gets it auto-reviewed before coding), so you don't need file-by-file line edits here — but you do need the to-be structure, owned signatures, and boundaries pinned, since those are what make the parallel pieces fit together.

Step 3 — Present the plan as an artifact and get approval

This is the gate. Create no .epic/ data until the human approves. Show them the whole plan first.

Render .epic/<name>/design.md directly as an Artifact (the Artifact tool renders Markdown — no separate HTML to author or keep in sync). Load the artifact-design skill first. Because design.md already holds the full plan (§1 要件定義 · §2 設計の to-be 構造・データモデル・IF署名・処理フロー · §3 実装 計画のタスク表＋DAG), the rendered artifact is the full-fidelity plan — the human approves the real to-be design, not a summary. Render mermaid for the DAG if you can; otherwise a text DAG in §3.2 is fine.

Then ask the user to approve or request changes. On changes, edit design.md and redeploy the same artifact (same file path → same URL), then ask again. Loop until they explicitly approve. Treat anything short of a clear "go" as not-yet-approved.

If the Artifact tool isn't available, just point the user at design.md (or show it inline) — but still gate on explicit approval before Step 4.

Step 4 — Persist the approved plan

Only after the human approves, write the planning data — this is the first moment anything touches the filesystem:

1. Ensure both /.epic/ and /.epic-worktrees/ are in the root's .gitignore (append if missing). .epic/ is local coordination state and .epic-worktrees/ holds the runners' nested checkouts — neither is project source; keeping them untracked is what keeps runners from ever showing up as changes or conflicting in git.
2. Create the epic, finalize the staged design, add the tasks, validate, activate:

EPIC="${CLAUDE_PLUGIN_ROOT}/scripts/epic.py"
"$EPIC" init --name <name> --goal "<goal>" --base main
# .epic/<name>/design.md is already staged (and is the approved version).
# init creates epic.json + subdirs and leaves design.md in place.
# Add one task per row of design.md §3.1, with the same ids/deps:
"$EPIC" add-task --name <name> --id db-schema   --title "…" --desc "…"
"$EPIC" add-task --name <name> --id widget-api  --title "…" --deps db-schema
"$EPIC" add-task --name <name> --id widget-ui   --title "…" --deps widget-api
"$EPIC" validate --name <name>     # fix any cycle / dangling dep it reports
"$EPIC" activate --name <name>
"$EPIC" status   --name <name>     # eyeball the DAG

Each task's brief lives in design.md §3 (the runner reads it from there and expands it into a full per-task spec under .epic/<name>/specs/<id>.md). The --desc can be short and point at the relevant design sections; the binding detail (owned/consumed contracts, target structure) is already in design.md.

Step 5 — Tell the user how to launch runners

Runners run in their own worktrees, nested under the root, started manually. Recommend ~3 as a starting point. For each one, from the root, create a nested worktree off the base branch and start a Claude Code session inside it:

# run once per runner, FROM THE ROOT (give each a distinct, stable name):
git worktree add .epic-worktrees/runner-1 -b epic/<name>/runner-1 <base>
cd .epic-worktrees/runner-1
claude            # then, inside that session:  /epic:run <name>

Repeat for runner-2, runner-3, …. Nesting under the root is what lets each runner resolve the shared .epic/ by walking up. Each runner derives its id from its worktree directory name (runner-1), so distinct, stable names keep their identities (and heartbeats) consistent across restarts. <base> is the epic's base branch (usually main).

Explain that each runner then self-drives: it claims a ready task, writes & auto-reviews a spec, implements, opens a PR, and blocks until you merge it before taking the next — so the human's main job during execution is reviewing and merging PRs.

Coordination & re-planning (your ongoing role)

You stay responsible for the design after kickoff. Re-invoke epic:plan to:

• Handle needs_replan. A runner that finds a task mis-scoped sets it to needs_replan. Inspect it (status, the task's spec, the events log), then split it into smaller tasks, adjust dependencies (set-deps), or rewrite the brief — keeping already-published contracts stable so in-flight tasks don't break. Add the new tasks and remove/neutralize the old one.
• Keep contracts coherent. If reality forces an interface to change, update design.md first, then fan the change out into tasks. Never let a contract drift silently — that's exactly the failure design-first exists to prevent.
• Add integration tasks. When several tasks touch overlapping surfaces, a follow-up task that wires them together (and its own tests) is often cleaner than forcing one mega-task.

When you change the plan, prefer adding tasks over editing in-flight ones, so runners mid-task aren't disrupted. For any structural change (new/split tasks, re-wired deps, a changed contract), present the revised plan as an artifact and get the human's approval again before applying it — same gate as the initial plan. Always re-run validate after structural changes.

Guardrails

• Design at spec granularity, not sketch level. The to-be structure, data models (fields/types), and interfaces (signatures: name/type/default/required/ errors/compat) must be concrete. A vague design is the single biggest cause of parallel runners diverging — treat fuzziness as a defect, not a style choice.
• Never create the coordination state (epic.py init/add-task) before the human approves the plan. Staging the design draft and the artifact source under .epic/<name>/ beforehand is fine — it's gitignored scratch and inert until the epic is init-ed and activate-d.
• Decompose grounded in the design; don't split before the interfaces are pinned.
• Never write feature code here — that's the runner's job.
• Never hand-edit files under .epic/; go through epic.py so locking holds.
• If the goal is genuinely too vague to design, ask the user rather than guess.