Implementation plan
The goal
Long plans have to be implemented in one sitting, because nothing marks a safe stopping point and nothing records the decisions an earlier session already made. Phases add declared checkpoints and a ledger, so a plan can be picked up cold in a fresh context window.
### Phase: <name> grouping over ## Steps and an optional ## Decisions section, and turn build's resume-from-first-unmarked-step behaviour into a designed checkpoint loop.
Implementation plans that exceed roughly ten steps consume more context than one session can hold. The repo already reaches this conclusion — guidelines/right-sizing.md tells the author that a plan needing more than ten steps "is probably two plans — split it", then offers no mechanism to split with.
Two capabilities are missing, and only one is about parallelism. The workflow prompt already fans out across subagents, which helps when slices are independent. Context exhaustion bites hardest on long sequential plans, where step seven depends on decisions made in step two — and there, fan-out does nothing. The fix for that shape is checkpointing.
One hazard is already latent. parseSpecMarkdown folds each step to a single line, so a ### Phase: heading placed between steps two and three is appended to step two's Verify text with no parse error at all. Phases are unsafe to author until step 1 lands.
✓
Make parseSpecMarkdown phase-aware by splitting the Steps chunk on ^###\s+Phase: before the numbered-item split.
Verify: text with no error raised.#.✓
Emit phases from buildDigest as a ### Phase: <name> line above the first step of each phase, keeping flat numbering unchanged.
buildDigest is the exact inverse of parseSpecMarkdown, so a phase it does not emit disappears whenever a spec is reconstructed from HTML.parseSpecMarkdown(buildDigest(parsed)).phases is deep-equal to parsed.phases.✓
Read phases back out of rendered HTML in extractSections by matching data-phase, and extend stripHeading to remove the phase <h3>.
<h3> would leak the phase name into the first step's extracted action text.✓
Add a phaseHeader helper emitting <div class="phase-group" data-phase="…">, and group step cards under it in flat document order.
.step-card with querySelectorAll, so nesting that breaks the selector would silently zero the progress bar.05
Add the ## Decisions section end to end — parse, re-emit, extract, add a SECTION_CHROME key, and render it after Context.
## Completion Report records gaps rather than decisions.06
Re-copy the three edited renderer sources over their counterparts under kit/plugins/plan-agent/scripts/, after steps 1–5 and before any test run.
diff reports no differences for all three files.07
Rewrite Step 2 of skills/build/SKILL.md as a phase checkpoint loop, with a --continue flag that pushes straight through.
--continue and the resume line; the unphased path still reads as one uninterrupted walk.08
Add the phase boundary offer — compact and continue, stop here, or continue without compacting — printing the /compact command with focus instructions.
/compact is a user-typed CLI built-in rather than a callable tool, so the skill can only recommend it./compact line appear; the headless path reports rather than chooses.09
Teach skills/finalize-plan/SKILL.md about phases so it refuses to set status: completed while any phase still holds unmarked steps.
build/SKILL.md line 303 requires the two skills' completion rules to stay consistent, so a phase-blind finalize-plan would close out a plan that stopped at its first checkpoint.in-progress with the unfinished phase named in the report.10
Document both sections in guidelines/section-catalog.md and replace the "probably two plans — split it" sentence in guidelines/right-sizing.md with a phase profile.
### Phase: example.11
Extend the two existing test files with phase and Decisions cases, and add tests/plugins/test-plan-phases.mjs asserting the render-extract-re-render cycle preserves both.
test-exitplanmode-guard.sh.12
Bump plan-agent from 7.0.1 to 7.1.0 in .claude-plugin/marketplace.json and add the matching CHANGELOG entry.
kit/plugins/ to ship a version exceeding the value on main, and a new spec section is a minor bump.BASE_REF=main node scripts/check-plugin-versions.mjs exits 0.Settled choices a resumed session must not re-litigate.
### Phase: headings rather than a phases: frontmatter range list — headings survive step insertion and reordering, which range lists do not.build stops at a phase boundary by default and takes --continue to push through, matching the skill's existing headless contract.status:, and the ledger — so a lossy summary costs nothing the next phase needs.[x] marker valid.