Plans

Reference the markdown spec in plan prompts and render Next Steps again

High completed
2026-07-13 agentics feature High effort
Objective

Point the derived implement/goal/workflow prompts at the plan's markdown spec instead of the rendered HTML (cutting ~90% of the tokens an implementing agent spends reading the plan), keep the HTML plan fully updated — steps checked and marked complete — via explicit spec-edit + re-render instructions, and render the ## Next Steps section into the HTML plan as legacy plans had it.

At a glance

Implementing agents were being briefed with the 60–120 KB rendered HTML when the 5–10 KB markdown spec carries strictly more information — and the old copy-button prompt invited the HTML hand-edits the markdown-first architecture forbids. After this change every derived prompt points at the spec, agents tick progress in the spec and re-render, and the Next Steps follow-up cards render in the HTML again.

Implement Read and implement all steps in the plan at docs/plans/reference-md-spec-in-plan-prompts.md — Reference the markdown spec in plan prompts and render Next Steps again. Verify against the plan's Tests, Verification, and Acceptance Criteria before reporting done. If everything passed, mark completion in docs/plans/reference-md-spec-in-plan-prompts.md — tick each step's [x] marker and each criterion's - [x], set status: completed — and re-render the HTML from the spec. If any check failed, leave status: in-progress and say which.
More ways to run this plan — goal & workflow prompts, file path
Pursue as goal — optimize for the outcome, in parallel
Achieve this goal: Reference the markdown spec in plan prompts and render Next Steps again. The plan at docs/plans/reference-md-spec-in-plan-prompts.md describes one approach — use it as reference, but optimize for the outcome. Fan out across parallel subagents where that serves the outcome. Verify against the plan's Tests, Verification, and Acceptance Criteria before reporting done. If everything passed, mark completion in docs/plans/reference-md-spec-in-plan-prompts.md — tick each step's [x] marker and each criterion's - [x], set status: completed — and re-render the HTML from the spec. If any check failed, leave status: in-progress and say which.
Run as workflow — launch parallel subagents
Run a workflow to implement the plan at docs/plans/reference-md-spec-in-plan-prompts.md — Reference the markdown spec in plan prompts and render Next Steps again. Brief subagents with the plan file at docs/plans/reference-md-spec-in-plan-prompts.md. Reserve a final verification phase for the lead agent, not a subagent. Verify against the plan's Tests, Verification, and Acceptance Criteria before reporting done. If everything passed, mark completion in docs/plans/reference-md-spec-in-plan-prompts.md — tick each step's [x] marker and each criterion's - [x], set status: completed — and re-render the HTML from the spec. If any check failed, leave status: in-progress and say which.
File reference-md-spec-in-plan-prompts.html
Path docs/plans/reference-md-spec-in-plan-prompts.html
Spec docs/plans/reference-md-spec-in-plan-prompts.md
Definition of done 7 / 7 done

Context

The story behind this plan — what prompted the work and why it matters now.

Since the markdown-first rewrite (2.18–2.20) the .md spec is the source of truth: all progress state is checkbox syntax in the spec, and hand-editing the rendered HTML is forbidden. But the three derived prompts still pointed at the .html file (10–20× the spec's size, mostly CSS/JS/SVG chrome), and the copy-button prompt told agents to read "a self-contained HTML file" and "mark it done in the plan" — inviting exactly the checked-attribute edits the architecture bans. The workflow prompt multiplied the waste by briefing every subagent with the HTML.

Separately, the markdown-first renderer skipped ## Next Steps, a section legacy hand-written plans rendered as collapsible cards with paste-ready prompts — the CSS, icon, and copyPrompt() JS never left the shell, only the parsing and rendering wiring was missing.

Files that change

Every file this plan touches, and what happens to each one.

agentics/
  • scripts/build-plan-html.mjs modified prompts use the spec path; plan-md meta; Next Steps card + nav filter; CLI passes the real spec path
  • scripts/lib/
    • plan-spec.mjs modified parse ## Next Steps into a nextSteps key beside sections (round-trip stays byte-stable)
    • plan-shell.mjs modified next-steps chrome + nav entry, nextStepsBlock template, plan-md meta tag, Spec drawer row, markdown-first buildImplementPrompt
  • kit/plugins/plan-agent/scripts/build-plan-html.mjs modified byte-identical bundled copy
  • kit/plugins/plan-agent/scripts/lib/
    • plan-spec.mjs modified byte-identical bundled copy
    • plan-shell.mjs modified byte-identical bundled copy
  • kit/plugins/plan-agent/skills/implementation-plan/reference/
    • SKELETON.html modified plan-md meta, Spec row, markdown-first copy-button JS
    • SKELETON.md modified Next Steps bullet/fence syntax
  • kit/plugins/plan-agent/skills/implementation-plan/guidelines/section-catalog.md modified Next Steps catalog entry; removed from the markdown-only group
  • kit/plugins/plan-agent/skills/implementation-plan/SKILL.md modified spec-path prompts, plan-md meta, Next Steps cards documented
  • kit/plugins/plan-agent/CHANGELOG.md modified 2.21.0 entry
  • .claude-plugin/marketplace.json modified plan-agent 2.20.0 → 2.21.0
  • tests/plugins/
    • test-build-plan-html.mjs modified spec-path prompt pins, plan-md meta, Next Steps parse/render coverage
    • test-extractor-wiring.sh modified pins the new self-contained copy-button JS

Steps

The step-by-step work, in order — each step says what to do, why it matters, and how to check it worked.

1
done Parse ## Next Steps in parseSpecMarkdown into a nextSteps key returned beside sections (bullets → summary/desc/prompt items, bullet-less content → prose).
Why
the extract → digest → parse round trip over committed plans must stay byte-stable, so the section travels like progress does — outside sections.
Verify
node tests/plugins/test-build-plan-html.mjs — the round-trip check still passes and the new Next Steps parse test passes.
2
done Render the Next Steps section card (collapsible details items with Copy-prompt buttons, matching the legacy markup) plus a filtered sidebar nav entry.
Why
legacy hand-written plans carried this section and the shell still ships its CSS, icon, and copyPrompt() JS — only wiring was missing.
Verify
render a spec with a ## Next Steps section and confirm the card, <pre> prompt, and nav entry appear; a spec without the section renders neither.
3
done Point the implement, goal, and workflow prompts at the markdown spec path — new mdPath render option, CLI passes the real spec path, .html → .md fallback — and emit it as the plan-md meta tag plus a Spec drawer row.
Why
the spec is 10–20× smaller than the rendered HTML and is where progress updates land; the workflow prompt briefs every subagent with the file, so the saving multiplies.
Verify
rendered head carries plan-implement/plan-goal/plan-workflow contents ending in .md and a plan-md meta tag.
4
done Rewrite the copy-button buildImplementPrompt() to walk the markdown-first loop: read the spec, insert [x] step markers, flip criteria to - [x], set status: completed, then re-render the sibling HTML — never hand-edit it.
Why
the old instructions predate markdown-first and invited HTML checked-attribute edits; the re-render step is what keeps the HTML plan checked and marked complete exactly as before.
Verify
the rendered plan's JS contains the five-step instructions referencing the spec path, and tests/plugins/test-extractor-wiring.sh check 2 passes.
5
done Mirror the shell changes into reference/SKELETON.html and document the new behavior in SKELETON.md, section-catalog.md, and SKILL.md.
Why
the skeleton is the versioned template the shell was extracted from and the docs are what authors follow — drift between them and the renderer is a defect.
Verify
bash tests/plugins/test-humanized-skeleton.sh and bash tests/plugins/test-goal-prompt.sh pass; section-catalog.md documents the Next Steps syntax.
6
done Sync the byte-identical bundled copies under kit/plugins/plan-agent/scripts/, update the pinned tests, and bump plan-agent to 2.21.0 with a CHANGELOG entry.
Why
a test enforces bundled-copy identity, the old prompt strings were pinned by tests, and marketplace versioning is manual per the repo rules.
Verify
node tests/plugins/test-build-plan-html.mjs reports the byte-identity check passing and marketplace.json says 2.21.0.

Tests

The tests that prove the change does what it promises.

Tier 1 — This plan changes application code
Objective: derived prompts reference the markdown spec and Next Steps renders. File: tests/plugins/test-build-plan-html.mjs; Type: unit + integration; Asserts: plan-implement/plan-goal/plan-workflow metas carry the .md spec path, plan-md meta and Spec row render, ## Next Steps parses beside sections and renders as collapsible cards with copy buttons, and committed plans still round-trip; Run: node tests/plugins/test-build-plan-html.mjs
Integration: skeleton copy-button JS is markdown-first and self-contained. File: tests/plugins/test-extractor-wiring.sh; Targets: reference/SKELETON.html buildImplementPrompt(); Key cases: reads the spec by path, no repo-local script references
Smoke: skeleton machine contract intact. File: tests/plugins/test-humanized-skeleton.sh; Targets: meta tags, ids, nav-label/heading parity; Key cases: all plan-* metas present, nav labels match section headings

Definition of done

The plan counts as done when every statement below is true — check each one off as you verify it.

Final check

One last pass to confirm the whole change works end to end.

Render a spec containing a ## Next Steps section with the bundled renderer and open the HTML: the Implement row and drawer prompts name the .md spec, the drawer shows File/Path/Spec rows, and the Next Steps card expands to a paste-ready prompt with a working Copy button. Run the full plugin test suite — node tests/plugins/test-build-plan-html.mjs plus the goal-prompt, extractor-wiring, and humanized-skeleton shell tests — and confirm every check passes, including the ≥10-plan round-trip and the bundled-copy identity check. Flip a criterion in a spec, re-render, and confirm the HTML checkbox state follows the spec.

Wrapping up

Three gates that must all pass before this plan is marked completed.

Required

Completion Report

No items to report — all requirements met.

Next steps

Follow-up ideas that came up along the way — none of them are required to finish this plan.

Extract Next Steps from legacy HTML plans so conversion keeps them

extractSections() ignores the legacy #next-steps markup today, so re-deriving a spec from a pre-2.18 HTML plan drops its follow-ups.

Paste this prompt into Claude to execute this follow-up:

In the agentics repo, teach extractSections() in scripts/lib/plan-spec.mjs
to read the legacy #next-steps section (details.next-step-item summary +
pre prompt) into the nextSteps shape parseSpecMarkdown returns, and emit it
from extract-plan-spec.mjs output so legacy-plan conversion preserves
follow-ups. Keep sections round-trip byte-stable. Sync the bundled copies,
bump the plan-agent minor version in .claude-plugin/marketplace.json, and
add a CHANGELOG entry.
Render Unresolved Questions and Resources too

The renderer still skips the two remaining markdown-only sections; the skeleton already carries an Unresolved Questions shell.

Paste this prompt into Claude to execute this follow-up:

In the agentics repo, extend parseSpecMarkdown and build-plan-html.mjs so
## Unresolved Questions and ## Resources render into HTML plans (following
the nextSteps-beside-sections pattern from 2.21.0), update
section-catalog.md, sync the bundled plan-agent script copies, bump the
plan-agent minor version, and add a CHANGELOG entry.