# Plan Phase > Work breakdown for a plan — the current planning suite. Reads a `Format: v2` plan.md, proposes an ordered phase list (noting in prose which phases are independent and which reconciles them), then writes one phase document per phase plus the checkbox execution.md tracker (never phases.md). UI phases get a spec item and a visual-verify gate box; every phase carries a compact evidence record. Use when the user invokes /plan-phase, or says "break this plan into phases", "WBS the plan", "create the execution.md tracker". - Skill: `rosslevinsky/plan-phase` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add rosslevinsky/plan-phase` - Raw SKILL.md: https://api.skillmd.com/api/skills/rosslevinsky/plan-phase/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: rosslevinsky (https://skillmd.com/u/rosslevinsky) - Updated: 2026-09-21 - Page: https://skillmd.com/skills/rosslevinsky/plan-phase --- # Work Breakdown Structure (v2) ## Overview Read a `Format: v2` plan document, propose an ordered **phase list** for approval, then produce v2 phase documents and an **`execution.md`** tracker. The original plan is never modified. Two things distinguish this from `/plan-phase-v1`: 1. **The phase document is the durable state; the tracker is a derived index.** Every item of Work, every Test and every Gate box in a phase document is a checkbox ticked as the work proceeds, and `execution.md` holds one checkbox per phase, ticked when that phase's gate passes. There are no status values and no scheduling keys anywhere: two levels of record, the child authoritative, is what makes a crash at any point recoverable. Phases that are genuinely independent are noted in **prose** above the list; that is advisory and is not parsed. 2. **A distinct tracker filename — `execution.md`, never `phases.md`.** With `plan.md`'s `Format: v2` marker this is the entire v1↔v2 non-collision mechanism: v2 skills act only on `Format: v2` plans and read/write `execution.md`; the v1 skills only ever touch `phases.md`. Each phase is independently committable and sized for review cost. Every phase it emits carries a per-phase gate whose independent-review axis is a **cross-model** `diff-review` when a second runtime is installed (Codex reviewing Claude's code or the reverse — see Step 5), giving at review time the same different-model scrutiny `/plan-duel` gives at plan time. The document contract (phase-document shape and tracker structure) is defined in `references/v2-templates.md` — emit against it exactly. Where the pack's tracker check is present in the repository you are working in, `scripts/check_plan_tracker.py` machine-checks what you emit; it is not installed with the skills, so in another project it will not be there and the templates are the whole contract. --- ## Step 1 — Locate the plan and confirm it is v2 If the user provided a path argument, use it. Otherwise search for `plans/**/plan.md`; if exactly one exists use it, else list them and ask which to break down (autonomously: choose the only `Format: v2` plan, or the most recently modified one, and note the assumption). Read the plan in full. **Confirm the `Format: v2` marker** — the `| Format | v2 |` row in the Status table. If it is absent, this is a v1 plan: do **not** proceed. Tell the user to run `/plan-phase-v1` instead (which writes `phases.md`). If operating autonomously, stop and report: "plan is not `Format: v2` — refusing to avoid a v1/v2 tracker collision." **Output directory:** phase documents and `execution.md` are always written into the **same directory as the plan file you just read** — every `plans//` path below names that directory, whatever it turns out to be. Discovery above accepts a plan anywhere, so when the plan lives outside `plans/` (say `docs/proposal.md`) the phase documents and `execution.md` go beside it, in `docs/`, never into an invented `plans//`. That is where `/plan-run` looks: it reads `execution.md` from the plan's own directory, so a tracker written anywhere else is a tracker nothing will ever find. --- ## Step 2 — Explore for breakdown context and shared surfaces Explore the plan's affected areas in the codebase (read the key files, find natural seams, note existing tests and migration concerns), verifying every path against reality. In addition, so you can say honestly which phases are independent, identify: - The **affected-file set** each prospective phase would touch. - **Shared surfaces** — coupling that hides behind disjoint file lists: shared APIs/contracts, schema/migrations, generated files, lockfiles, global/theme CSS, shared test fixtures, and shared test-env state. --- ## Step 3 — Design the phase list (internal) Design the phases first (foundation before consumers; tests mandatory per phase; risky changes isolated; a final verification-gate phase). **Every phase that introduces new behaviour is test-first:** for logic, API endpoints, and utilities the failing test is written before the implementation (TDD); for UI and wiring, tests are written alongside — no phase is complete until its tests pass. This ordering flows into each emitted phase doc's Tests section (the template's test-first note is load-bearing — keep it). Then decide which, if any, are genuinely **independent**. **Independent phases are rare, and that is correct.** Almost every phase executed so far has been a single sequential unit. Note independence when it is real; do not reach for it to signal that work is parallelisable in principle. The test: - Phases are independent only if their affected-file sets are **disjoint** *and* none of them shares a surface with another. **Disjoint files is a filter, not proof of independence** — any shared surface means run them in order, because isolating writers covers *files* and cannot reconcile shared non-file state like a DB, ports, or caches. - Where phases are independent, **say so in prose above the phase list**, and name the phase that **reconciles** them. That phase's own document carries the reconciliation: its Work brings the work together and its Verification runs the full suite. Nothing about this is a key in the tracker. - A phase that changes the **build / dependency-resolution / CI topology** can't be verified in the dev environment alone (resolution and hoisting differ from CI); make **"the CI round for the commit this phase ends at is green"** one of its Gate boxes — naming the repository and ref it runs in — and keep it an ordinary sequential phase. Size each phase so its diff is cheap to review — reviewability is a first-class constraint. Target 3–8 phases. --- ## Step 4 — Propose the breakdown and get approval **Before writing any files**, present the proposed phase list in one message: the ordered phases; which (if any) are independent of one another and why (disjoint files, no shared surface); which shared surfaces forced sequencing; and which phase reconciles each independent set. Invite the user to add, remove, merge, re-order, or re-scope phases, or to make an independent set strictly sequential. Wait for approval; revise and re-present until confirmed. If operating autonomously (no user available), proceed with the proposed graph and note that it was not user-reviewed. --- ## Step 5 — Write phase documents **Before writing anything into `plans//`, check whether that plan directory already holds an execution tracker *or any* `phase-*.md`.** This check belongs here, ahead of the first write — not beside the tracker write in Step 6 — because Step 5 recreates every phase document. A guard that only protects `execution.md` still lets a literal execution destroy a finished plan's phase documents and their evidence before it stops. If `plans//execution.md` exists, **or the directory holds any `phase-*.md`**, do not overwrite anything. Three cases, all destructive to get wrong: - **It is a checkbox tracker** — the plan is live and possibly mid-run; its unticked boxes are exactly where the run resumes. Overwriting resets that progress. Ask the user whether to re-plan or resume; autonomously, stop and report rather than discarding execution state. - **It is a superseded `- phase:` tracker** — the directory is the finished record of a run executed under an older shape. Writing fresh documents over it destroys that record. Leave it alone; start a new plan directory instead. - **`phase-*.md` documents with no tracker beside them at all** — an earlier run of this skill stopped between Step 5 and Step 6. This is the case a tracker-only guard waves straight through, and the one where the damage is worst: with no tracker there is nothing to resume from, so nothing looks wrong until the evidence records are already overwritten. Stop and ask; do not assume an unfinished directory is a scratch one. For each approved phase N, create `plans//phase--.md` from the **phase document template** in `references/v2-templates.md`. Fill: - **Goal / Work / Tests / Verification / Gate / Evidence**, using real codebase paths. **Verification commands are scoped to the phase's changed surface** — the full suite appears only in a reconciling phase or a final verification-gate phase, never in an ordinary phase. Include the phase's cheap per-surface static checks (linter check-only, and a scoped type-check where the project has one); defer only genuinely environment-bound checks to CI. - **Emit only the boxes that apply.** The Gate section always carries the two review boxes — author review completed, independent review with no open blocker/major — and those two are ticked with a reason even when the phase produced no reviewable diff. A **UI** phase also gets a spec item under Work and a visual-verification box (run the `web-verify` skill; where unavailable, its bundled manual checklist across the mandatory viewports). A phase whose verification needs the **CI/prod environment shape** also gets a CI box naming the repository and ref — that is the whole mechanism, and it needs no tracker state. A phase with neither gets neither: an inapplicable box is one nobody can tick, and `plan-run` reads any open box as unfinished work. - **Never emit a box that restates another, or one that cannot be true.** No "every task above is checked off", no universal "the previous phase is done" (the tracker's order already says it), and never "this phase's box is ticked in `execution.md`" — `plan-run` reads the document to decide that, so as a criterion it is circular. - **Every box is ticked as it becomes true, never in a batch at the end.** Say so explicitly in any phase whose Work includes an irreversible action (creating a tag, a release, a PR), and write that item so its outcome is *checkable*: on resume, `plan-run` looks for the outcome before repeating the action. --- ## Step 6 — Write the `execution.md` tracker Create `plans//execution.md` (never `phases.md`) from the **tracker template** in `references/v2-templates.md`: one checkbox per phase, in execution order, each linking its phase document. It carries **no** format marker, no status values and no scheduling keys. It must satisfy the validator's rules: - every column-0 checkbox line is the exact canonical form — `- [ ] [](./phase--.md)`, or the same with `- [x] `, where `` is at least two digits and `` is kebab-case; - each link resolves to an existing regular file in the same plan directory — not a symlink — and no phase is listed twice; - every `phase-*.md` entry in that directory appears in the list exactly once; - there is **at least one checkbox** — zero is a hard error, never "all phases complete"; - no code fence or HTML comment appears anywhere in the file. They are banned rather than parsed: either can hide a whole region from the checker while a reader sees it plainly. Which phases are independent, and which phase reconciles them, goes in **prose above the list**. It is advisory and is not parsed. Do not use a `###` sub-heading for it — a blank line does not end a `###` section, so the reconciling phase would read as another member. **Put every checkbox under the one `## Phases` heading.** Neither the checker nor `plan-run` parses that heading — both read every column-0 checkbox in the file, in order — so a box placed under some other heading is executed anyway, in list position, which is unlikely to be what its author meant. The orchestrator owns this file; phases never write it. **Machine-check the tracker before finishing.** If the pack's tracker check is present in this repo (you are working inside portable-agent-skills), run it against the file you just wrote and fix every reported issue before continuing: ```bash # native Windows: py -3 instead of python3 python3 scripts/check_plan_tracker.py plans//execution.md ``` **One of its findings has a destructive wrong fix.** `'' is in this directory but no checkbox links it` names a `phase-*.md` the tracker does not reference. Fix it by **adding the checkbox**, in that phase's right position. Never delete the document to silence the check: if you did not write it this run it belongs to a plan you have not read, and deleting it discards that plan's evidence record. If you cannot place it confidently, stop and ask. If the tracker check is not present (the usual case when running inside another project), re-read the tracker against the rules above and confirm each by hand — the emitted tracker must satisfy the same contract either way. --- ## Step 7 — Report to the user Print a summary: the location of `execution.md` and the phase files; a one-line description of each phase (and which, if any, are independent of one another); the total checklist items; and the next step: "Run `/plan-run ` to execute the phases." Name its real path — a literal `plans//plan.md` points the runner at a file that does not exist whenever the plan came from anywhere else. ## References - `references/v2-templates.md` — the v2 phase-document template (Goal / Work / Tests / Verification / Gate / Evidence, and what is deliberately not in it) and the `execution.md` checkbox tracker template.