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 different-model diff-review when one is available (the other CLI, or your own CLI on a backend running another model — plan-run runs it), 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/<slug>/ 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/<slug>/. 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 behavior 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 (keep the template's test-first note — it carries this rule into every phase doc). Then decide which, if any, are genuinely independent.

Independent phases are rare, and that is correct. Almost every phase is a single sequential unit. Note independence when it is real; do not reach for it to signal that work is parallelizable 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/<slug>/, 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/<slug>/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 - phase: tracker — its entries are - phase: lines, not checkboxes, so the directory is the finished record of a run this suite no longer drives. 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/<slug>/phase-<NN>-<name>.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/<slug>/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 — - [ ] [<Name>](./phase-<NN>-<slug>.md), or the same with - [x] , where <NN> is at least two digits and <slug> 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:

# native Windows: py -3 instead of python3
python3 scripts/check_plan_tracker.py plans/<slug>/execution.md

One of its findings has a destructive wrong fix. '<name>' 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); and the total checklist items.

Then ask whether to run the xc skill on the phase documents and execution.md, with plan.md given as context, for a different model's review before anything runs. Autonomously, do not run it; name it in the summary as an optional step before /plan-run. If the xc skill is unavailable, make no offer.

Last, the next step: "Run /plan-run <the plan file you read> to execute the phases." Name its real path — a literal plans/<slug>/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.