Ship a machine-readable markdown digest inside every HTML plan — a non-rendering <script type="text/markdown" id="plan-digest"> block as the first element child of <body> — so the implementer, the workflow author, and the 5–7 review-team agents read ~3.7k tokens of spec instead of re-reading ~21k tokens of styled HTML, with zero second source-of-truth file.
Read and implement all steps in the plan at docs/plans/embed-markdown-digest-in-html-plans.md — Embed a machine-readable markdown digest in every HTML plan. Verify against the plan's Tests, Verification, and Acceptance Criteria before reporting done. If everything passed, mark completion in docs/plans/embed-markdown-digest-in-html-plans.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
Achieve this goal: Embed a machine-readable markdown digest in every HTML plan. The plan at docs/plans/embed-markdown-digest-in-html-plans.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/embed-markdown-digest-in-html-plans.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 a workflow to implement the plan at docs/plans/embed-markdown-digest-in-html-plans.md — Embed a machine-readable markdown digest in every HTML plan. Brief subagents with the plan file at docs/plans/embed-markdown-digest-in-html-plans.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/embed-markdown-digest-in-html-plans.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.
embed-markdown-digest-in-html-plans.html
docs/plans/embed-markdown-digest-in-html-plans.html
docs/plans/embed-markdown-digest-in-html-plans.md
Context
The story behind this plan — what prompted the work and why it matters now.
A generated HTML plan is a single self-contained file of ~86–97 KB (~21.5k tokens), but only about 17% of that is plan content — the other ~83% is the fixed skeleton CSS and JS, byte-for-byte identical in every plan. The Read tool cannot skip <style> or <script> blocks, so every consumer that opens a plan pays for the whole file.
That cost is paid repeatedly. The implementer reads it; a Run a workflow… author reads it; and a single review-plan cycle has the lead plus up to 7 reviewer agents each instructed to read the plan — roughly ~170k tokens per review, of which ~140k is the same CSS read eight times. review-plan already says "exclude <style> and <script> " but the Read tool can't honor that — it's aspiration, not mechanism.
This plan embeds a spec-only markdown digest inside the plan rather than writing a sibling .md file. A sibling file is a second source of truth that drifts the moment implementation flips checkboxes or review-plan edits content, and it collides with the plan-interview .md tooling. An embedded <script type="text/markdown"> block keeps the single-file guarantee, never renders, and is extractable in any session — no plugin install required — via a flag-and-exit awk : awk '/<script[^>]*id="plan-digest"/{f=1;next} f&&/<\/script>/{exit} f' <file> (a simple awk range would re-trigger on later mentions of the id, as this very plan demonstrates).
Resolved decisions (from clarification): the block is the first element child of <body> (extracted with awk ); the digest is spec-only so status flips and checkbox ticks never invalidate it; this plan backfills the ~50 existing plans via an idempotent script; and the 7 reviewers read the digest only while the lead keeps full HTML for its selector-based edits.
Files that change
Every file this plan touches, and what happens to each one.
.claude-plugin/marketplace.jsonmodified bump plan-agent 2.1.0 → 2.2.0- kit/plugins/plan-agent/
CHANGELOG.mdmodified add 2.2.0 entryREADME.mdmodified document the digest + extraction
agents/plan-reviewer-*.mdmodified 7 defs read the digest, not full HTMLskills/implementation-plan/SKILL.mdmodified contract, generation, refresh, prompts; includes buildImplementPrompt() instruction updatereference/SKELETON.htmlmodified add #plan-digest block (first element child of body)skills/review-plan/SKILL.mdmodified digest-only reviewers, Step 7 refreshreferences/role-prompts.mdmodified 7 briefs read the digestscripts/backfill-plan-digests.mjsnew idempotent injector over existing plans- tests/plugins/
test-plan-digest.shnew objective smoke testtest-backfill-digest.mjsnew backfill unit + integration
Steps
The step-by-step work, in order — each step says what to do, why it matters, and how to check it worked.
Tests
The tests that prove the change does what it promises.
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.
Generation path: run /plan-agent:implementation-plan on a throwaway objective and confirm the resulting plan has a #plan-digest block as the first element child of <body> , that its markdown matches the visible objective/steps/criteria/verification, that the block renders nothing in a browser, and that the canonical flag-and-exit awk extractor returns the spec. Confirm both the implement and workflow prompts carry the extraction clause.
Backfill path: run node scripts/backfill-plan-digests.mjs --dry-run then a real run over docs/plans/ ; spot-check one completed, one in-progress, and one todo plan — each must gain a digest while git diff shows no change to data-status , <meta name="plan-status"> , or any criteria checkbox. Re-run and confirm 0 injected.
Review path: run review-plan on a sample plan; confirm each reviewer was briefed with the digest (not full HTML), that a digest-less plan falls back to full HTML, and that Step 7 regenerated the digest after applying inline edits.
Tests: bash tests/plugins/test-plan-digest.sh and node tests/plugins/test-backfill-digest.mjs both exit 0.
Wrapping up
Three gates that must all pass before this plan is marked completed.
Completion Report
- Version criterion — planned 2.2.0, shipped 2.3.0
- PR #317 (markdown plan conversion) took 2.2.0 on main while this plan was in flight. The criterion's intent — bump plan-agent above the value on main with a matching CHANGELOG entry — is met at 2.3.0.