Objective
Make the visible plan DOM the single source of truth: derive the spec on demand with a shared scripts/extract-plan-spec.mjs extractor, and retire the embedded #plan-digest block plus its refresh and closing-script escaping machinery — while keeping the same self-contained HTML deliverable and the ~15× token savings for downstream consumers.
Implement
Read and implement all steps in the plan at docs/plans/replace-plan-digest-with-extractor.md — Replace the stored plan digest with a compute-on-read extractor. Verify against the plan's Tests, Verification, and Acceptance Criteria before reporting done. If everything passed, mark completion in docs/plans/replace-plan-digest-with-extractor.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: Replace the stored plan digest with a compute-on-read extractor. The plan at docs/plans/replace-plan-digest-with-extractor.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/replace-plan-digest-with-extractor.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/replace-plan-digest-with-extractor.md — Replace the stored plan digest with a compute-on-read extractor. Brief subagents with the plan file at docs/plans/replace-plan-digest-with-extractor.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/replace-plan-digest-with-extractor.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
replace-plan-digest-with-extractor.html
Path
docs/plans/replace-plan-digest-with-extractor.html
Spec
docs/plans/replace-plan-digest-with-extractor.md
Definition of done
8 / 8 done
Context
The story behind this plan — what prompted the work and why it matters now.
Since plan-agent 2.3.0, every generated plan embeds a spec-only markdown digest — a <script type="text/markdown" id="plan-digest"> block — as the first element child of <body> . The digest is a denormalized cache of the plan spec, which already lives in the visible DOM ( .objective-card , .step-card with .step-action / .step-why / .verify-body , #criteria-list , #verification ).
Like any cache, that duplication creates an invalidation problem — and the codebase already pays for it: implementation-plan SKILL.md must "refresh the digest" on every content edit (Steps 2/6/8), review-plan adds a dedicated "Pass 1b — Refresh the digest", and a closing-script escaping contract guards the block. All of that machinery exists only because the spec is stored twice.
Compute-on-read removes the duplication: derive the spec from the DOM on demand. Crucially, scripts/backfill-plan-digests.mjs already exports hasDigest , decodeEntities , extractSections , and buildDigest — the exact HTML→markdown logic, already unit-tested — so this is mostly rewiring proven code, not writing a parser. New plans stop embedding the digest; the extractor reads an embedded digest first (old plans, verbatim) and derives from the DOM otherwise (new plans), so existing plans are never touched.
Files that change
Every file this plan touches, and what happens to each one.
agentics/
scripts/lib/plan-spec.mjsnew shared parse fns (extractSections/buildDigest/guard+unguard)- scripts/
extract-plan-spec.mjsnew read-time spec extractor; imports scripts/lib/plan-spec.mjsbackfill-plan-digests.mjsmodified import shared fns from scripts/lib/plan-spec.mjs (behavior unchanged)
.claude-plugin/marketplace.jsonmodified bump plan-agent 2.7.0 → 2.8.0skills/implementation-plan/reference/SKELETON.htmlmodified remove digest block + placeholder; repoint buildImplementPrompt()skills/implementation-plan/SKILL.mdmodified drop digest section + refresh rules; prompts call extractorskills/review-plan/SKILL.mdmodified reviewers run extractor; remove refresh passskills/review-plan/references/role-prompts.mdmodified 7 reviewer briefs read via extractoragents/plan-reviewer-*.mdmodified 7 reviewer defs read via extractorREADME.mdmodified document the extractorCHANGELOG.mdmodified 2.8.0 entry- tests/plugins/
test-extract-plan-spec.mjsnew objective + unit coveragetest-extractor-wiring.shmodified renamed from test-plan-digest.sh; asserts no digest + wiringtest-goal-prompt.shmodified update any assertion on the old awk one-liner
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
Extract shared parse functions into scripts/lib/plan-spec.mjs
Why
Gives the dependency graph the right shape — a shared library consumed by both the write-side backfill and the read-side extractor — instead of a read tool importing from an injector. It is also the natural home for the new unguardScriptClose helper the extractor needs. (Architecture + Conventions reviewers; pulled in per your decision.)
Verify
Move hasDigest , decodeEntities , extractSections , buildDigest , and guardScriptClose from backfill-plan-digests.mjs into scripts/lib/plan-spec.mjs ; add unguardScriptClose (reverses <\/script → </script ); update backfill-plan-digests.mjs to import them from ./lib/plan-spec.mjs with no behavior change. Confirm: node tests/plugins/test-backfill-digest.mjs still passes, and node -e "import('./scripts/lib/plan-spec.mjs').then(m=>console.log(Object.keys(m)))" lists all six exports.
2
done
Build scripts/extract-plan-spec.mjs — embedded-first, DOM-derive fallback
Why
One read-time tool replaces the awk one-liner across every consumer. Importing from the shared lib keeps the read path decoupled from the injector, and reusing the already-tested parse functions means no new parser.
Verify
Import from ./lib/plan-spec.mjs ; if hasDigest(html) , print the embedded digest via readEmbeddedDigest() , which un-guards <\/script → </script so the output is clean markdown (the resolved contract — not the raw guarded bytes, so it will not match awk byte-for-byte); else print buildDigest(extractSections(html)) . Exit non-zero with a clear message on a missing/unparseable file. Add a JSDoc header documenting the read-on-demand role and the lib dependency. Confirm: on an embedded-digest plan the output is the unguarded spec; on a digest-stripped copy it is DOM-derived with identical ## Objective / ## Steps / ## Verification headings; a missing file exits 1. (Resolves the Step-1 verbatim-vs-unguard contradiction — Completeness + Testability reviewers.)
3
done
Strip the digest from SKELETON.html and repoint its runtime prompt JS
Why
New plans must stop embedding the cache for the single-source-of-truth goal. The skeleton hardcodes the digest in two places: the <script id="plan-digest"> block and the buildImplementPrompt() JS ( digestCmd at ~line 1661) that builds the Copy-button prompt at runtime.
Verify
Remove the digest <script> block, its guiding comment, and the {plan-digest} placeholder; change buildImplementPrompt() 's digestCmd to "node scripts/extract-plan-spec.mjs " + planPath with updated instruction text. Confirm: grep -c 'id="plan-digest"' SKELETON.html returns 0, and the runtime Copy path emits the extractor — assert the buildImplementPrompt() JS constructs node scripts/extract-plan-spec.mjs (not the awk string), so clicking Copy on a rendered plan yields the new command. (Architecture + Completeness reviewers — runtime path is distinct from the static placeholder.)
4
done
Rewire implementation-plan/SKILL.md — remove every digest reference
Why
The skill instructs every consumer; it must stop generating and refreshing the digest and point all three prompt formats at the extractor. The digest is referenced in more places than the main section.
Verify
Swap the implement, goal, and workflow prompt formats to "Start from the plan spec: node scripts/extract-plan-spec.mjs <file> "; delete the "Machine-Readable Digest" section (~316+), the {plan-digest} fill prose (~117), the digest-refresh language in Steps 2/6/8 and the Step-8 Edit loop (~260), the "Status updates never modify the #plan-digest block" notes (~169, ~215), and the HTML-output bullet mandating the block (~296). Confirm: grep -in "machine-readable digest\|refresh the digest\|#plan-digest\|{plan-digest}" SKILL.md returns nothing, and all three prompt formats contain extract-plan-spec.mjs . (Completeness reviewer — verified orphan refs at those lines.)
5
done
Repoint the review team (SKILL + 7 briefs + 7 agent defs) to the extractor
Why
The 5–7 reviewers were the biggest beneficiaries of the cheap read, so they must use the new path. Removing the "Pass 1b — Refresh the digest" step also deletes the last piece of sync machinery.
Verify
In review-plan/SKILL.md remove the "Pass 1b — Refresh the digest" pass and update the "Lead-vs-reviewer read split" language to the extractor; in references/role-prompts.md and each of the 7 agents/plan-reviewer-*.md defs, swap the awk digest read for node scripts/extract-plan-spec.mjs with a full-HTML fallback. Confirm: grep -l extract-plan-spec.mjs agents/plan-reviewer-*.md | wc -l equals 7, the briefs file references the extractor, and no "Refresh the digest" pass remains.
6
done
Update tests — add extractor test, repurpose the digest test, fix the corpus assertion
Why
Lock the new contract and fix the test that would otherwise fail the instant a digest-free plan is committed. The existing digest smoke test now asserts the opposite of what it used to.
Verify
(a) Add tests/plugins/test-extract-plan-spec.mjs : objective smoke (round-trip — write a known digest, run the extractor, assert output equals the known unguarded spec; and a digest-stripped fixture yields DOM-derived output containing ## Objective , ## Steps with ≥1 action, ## Acceptance Criteria , ## Verification , and ## Tests ) plus unit cases (embedded-vs-DOM resolution; readEmbeddedDigest un-guards a <\/script fixture without stopping early; missing file exits non-zero; the scripts/lib/plan-spec.mjs import resolves). (b) git mv test-plan-digest.sh test-extractor-wiring.sh and rewrite its assertions: drop the digest-present checks, rephrase the digestCmd /SKILL/brief checks to assert the extractor, and migrate the self-quoting/guarded-close fixture into the node test. (c) Update test-backfill-digest.mjs 's "every checked-in parseable plan carries a digest" assertion (~line 290) to scope to legacy/embedded plans, so committing digest-free plans does not fail it. (d) test-goal-prompt.sh needs no change (it never references the awk one-liner). Confirm all three test commands exit 0. (Testability + Completeness reviewers — verified the corpus assertion at line 290.)
7
done
Docs + version bump (README, CHANGELOG, marketplace.json)
Why
Project convention requires a manual semver bump and a CHANGELOG entry on every plugin change; the README currently documents the digest + awk, and the awk-empty break for old consumers must be recorded.
Verify
Update plan-agent/README.md to document extract-plan-spec.mjs and note that the awk one-liner returns empty for new (digest-free) plans so consumers must use the extractor; add a ## 2.8.0 CHANGELOG entry describing the compute-on-read switch, the shared scripts/lib/plan-spec.mjs , the retained backfill injector, and the awk-empty caveat; bump plan-agent in .claude-plugin/marketplace.json from 2.7.0 to 2.8.0. Confirm: grep '"version": "2.8.0"' near the plan-agent entry, a matching CHANGELOG header, and README mentions extract-plan-spec.mjs . (MINOR bump kept per your decision; awk-empty caveat per Risk reviewer.)
Tests
The tests that prove the change does what it promises.
Tier 1 — Code-touching plan
Objective Extractor reproduces the spec from any plan, embedded or not File: tests/plugins/test-extract-plan-spec.mjs Type: smoke test Asserts: for a fixture plan with an embedded #plan-digest , the extractor's stdout equals the known spec markdown after un-guarding — a round-trip fixture (write a known digest, extract, compare to the unguarded expected string), not a comparison to the raw awk bytes; for a digest-stripped fixture, the stdout is DOM-derived and contains ## Objective , ## Steps (with ≥1 step action), ## Acceptance Criteria , ## Verification , and ## Tests — proving the DOM is a sufficient single source of truth. Run: node tests/plugins/test-extract-plan-spec.mjs
Unit Extractor resolution order & readEmbeddedDigest un-guarding File: tests/plugins/test-extract-plan-spec.mjs Targets: the extractor's resolve logic + readEmbeddedDigest() / unguardScriptClose() helpers Key cases: embedded digest present → unguarded embedded path; embedded absent → buildDigest(extractSections()) DOM path; a digest body containing a guarded <\/script sequence un-guards to </script> without the extractor stopping early (migrated from the old digest test's self-quoting fixture); the scripts/lib/plan-spec.mjs import resolves (guards the dependency chain); missing file exits non-zero.
Integration Skeleton + skill + reviewer wiring references the extractor File: tests/plugins/test-extractor-wiring.sh Targets: SKELETON.html , both SKILL.md files, role-prompts.md , the 7 plan-reviewer-*.md defs, and test-backfill-digest.mjs Key cases: skeleton contains no id="plan-digest" and its buildImplementPrompt() JS emits extract-plan-spec.mjs (not awk); implement/goal/workflow prompt formats reference the extractor; all 7 reviewer briefs and 7 agent defs reference it; no residual "Refresh the digest" pass; test-backfill-digest.mjs 's corpus assertion is scoped so committed digest-free plans don't fail it.
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.
Generate a fresh plan with the modified skill and confirm it has no embedded digest, its implement prompt and the Copy-button output reference the extractor, and node scripts/extract-plan-spec.mjs on it emits correct DOM-derived spec. Run the extractor on an older plan (e.g. docs/plans/embed-markdown-digest-in-html-plans.html ) and confirm the output is the unguarded spec markdown (the embedded digest with <\/script reversed to </script ) — not byte-identical to awk, by design. Run node tests/plugins/test-extract-plan-spec.mjs , bash tests/plugins/test-extractor-wiring.sh , and node tests/plugins/test-backfill-digest.mjs — all must pass (the last with its corpus assertion scoped to legacy plans). Finally, grep -rn "plan-digest" across the plan-agent tree and confirm only intentional references remain: the retained backfill injector, the shared scripts/lib/plan-spec.mjs , the tests, and historical CHANGELOG entries.
Wrapping up
Three gates that must all pass before this plan is marked completed.
Required
Completion Report
No items to report — all requirements met.