Objective
Make every generated plan read like a briefing from a teammate — a plain-language summary first, one clear call-to-action, and the machinery tucked into a collapsed drawer — without breaking a single machine contract the galleries, hooks, and tests depend on.
Implement
Read and implement all steps in the plan at docs/plans/humanize-plan-output.md — Humanize the implementation-plan output. Verify against the plan's Tests, Verification, and Acceptance Criteria before reporting done. If everything passed, mark completion in docs/plans/humanize-plan-output.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: Humanize the implementation-plan output. The plan at docs/plans/humanize-plan-output.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/humanize-plan-output.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/humanize-plan-output.md — Humanize the implementation-plan output. Brief subagents with the plan file at docs/plans/humanize-plan-output.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/humanize-plan-output.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
humanize-plan-output.html
Path
docs/plans/humanize-plan-output.html
Spec
docs/plans/humanize-plan-output.md
Definition of done
9 / 9 done
Context
The story behind this plan — what prompted the work and why it matters now.
The /plan-agent:implementation-plan skill produces dense, tool-first HTML. Immediately after the objective, readers hit four stacked copy-paste prompt rows (implement, goal, workflow, file/path) before any human explanation. Headings are terse uppercase jargon (“ACCEPTANCE CRITERIA”, “VERIFICATION”, “Tier 1 — Code-touching plan”), and step cards use bare Why: / Verify labels. The feedback driving this plan: the output feels very technical and needs to be easier to read and more user-friendly.
The constraint that shapes every decision here: a web of downstream consumers — the plans-library gallery, the finalize-plan skill, the filename and index-rebuild hooks, and the contract tests under tests/plugins/ — greps exact ids, classes, and <meta name="plan-*"> tags out of every plan file. So this is a presentation-and-copy refactor of the skeleton and its authoring contract, never a rename of the machine layer.
Files that change
Every file this plan touches, and what happens to each one.
agentics/
kit/plugins/plan-agent/skills/implementation-plan/reference/SKELETON.htmlmodified at-a-glance block, prompt drawer, human copykit/plugins/plan-agent/skills/implementation-plan/SKILL.mdmodified document new placeholders, copy rules, frozen stringskit/plugins/plan-agent/skills/implementation-plan/reference/SKELETON.mdmodified mirror humanized structure into markdown fallbackkit/plugins/plan-agent/CHANGELOG.mdmodified 2.17.0 entry.claude-plugin/marketplace.jsonmodified bump plan-agent to 2.17.0tests/plugins/test-humanized-skeleton.shnew human layer + machine contract smoke test
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
Add an “At a glance” plain-language summary block to SKELETON.html via a new {at-a-glance} placeholder — a .plan-glance element rendered as a sibling immediately after div#objective (never a child), with its own accessible name (a visible “At a glance” label wired via aria-labelledby or aria-label )
Why
Readers currently land on prompt strings and file paths before any human explanation; a two-to-three sentence summary gives every reader — technical or not — an entry point. The objective and the glance get distinct jobs so they never restate each other: objective = the one-line what ; at-a-glance = why it matters and how we’ll know it worked . Sibling placement is load-bearing: scripts/extract-plan-spec.mjs derives the objective spec from div#objective ’s inner HTML, so nesting the glance inside would silently pollute every downstream automated review.
Verify
The skeleton contains a .plan-glance block with the {at-a-glance} placeholder as a sibling between div#objective and the Implement row, and node scripts/extract-plan-spec.mjs run against a filled plan emits objective text that does not contain the glance copy.
2
done
Regroup the four prompt rows: keep Implement visible as the single call-to-action, and collapse the goal, workflow, and plan-source rows into one flat <details class="plan-more-ways"> disclosure labelled “More ways to run this plan” — three plainly-labelled rows inside, never nested <details>
Why
Four stacked tool rows before the Context section is the loudest “a machine wrote this” signal on the page; one clear action plus a collapsed drawer keeps every power-user feature without the clutter. Each row keeps its distinguishing scent text (“Pursue as goal — optimize for the outcome”, “Run as workflow — launch parallel subagents”, File/Path) so opening costs exactly one click and nothing loses meaning. When no workflow prompt was generated, the workflow row is omitted entirely and the drawer still opens with the remaining rows. The drawer’s chevron reuses the existing .optional-section > summary::before rotate + prefers-reduced-motion pair rather than new transition CSS.
Verify
grep confirms the implement-cmd , goal-cmd , workflow-cmd , plan-file , and plan-path ids plus their copyCmd / copyGoal / copyWorkflow / copyPath handlers are all unchanged; the drawer is a single details.plan-more-ways element without the open attribute containing no nested <details> ; and the raw skeleton shows exactly one visible prompt row on first paint.
3
done
Rewrite headings, labels, and step-card copy in plain sentence-case English, adding a one-line <p class="section-intro"> under each section heading — scoping the uppercase removal to the .section-card h2 rules only
Why
“Acceptance Criteria”, “Verification”, and bare “Why:” labels read like a compliance document; “Definition of done”, “Final check”, “Why this matters”, and “How to check this worked” say the same thing in human terms, and a short intro orients readers who skipped the docs. Three guardrails: the intro is a <p> styled with var(--muted) (4.83:1 contrast) — never var(--subtle) (2.86:1, fails WCAG 1.4.3) and never a heading element; intros inside #objective , #context , and #verification must sit outside the text that extractSections() in scripts/lib/plan-spec.mjs extracts (or that helper learns to strip .section-intro ); and the other ~17 text-transform: uppercase rules ( .step-chip , .completion-badge , .file-badge , .pipeline-label , .compare-header , .plan-table thead th , .diagram-subheading , …) stay untouched.
Verify
Every h2 keeps its existing id (all sidebar links still scroll to their section); text-transform: uppercase is gone from .section-card h2 but still present on chips, badges, and table headers; each .section-card opens with a p.section-intro ; and node scripts/extract-plan-spec.mjs emits objective/context/verification text free of intro copy.
4
done
Update SKILL.md so generated plans actually use the new structure: an {at-a-glance} generation rule, the .plan-more-ways drawer contract (including the omit-workflow-row-when-empty rule), humanized tier-label strings, a plain-language writing rule, and a frozen-strings list
Why
The skeleton is only half the contract — SKILL.md tells the model what to write into it; without these rules, newly generated plans would skip the new blocks or fill them with the same jargon. The frozen-strings list is load-bearing: finalize-plan does a literal find/replace on <span class="step-chip">todo</span> → done and leaves the report-empty sentence (“No items to report — all requirements met.”) verbatim, and test-goal-prompt.sh greps the literal Pursue as goal label — reword any of these and those consumers silently no-op.
Verify
SKILL.md names the {at-a-glance} placeholder, the .plan-glance block, and the .plan-more-ways disclosure using the exact class names the skeleton ships; the Writing Style section instructs: write for a reader who wasn’t in the planning session, expanding jargon on first use; a “frozen strings” subsection lists the step-chip todo / done tokens, the report-empty sentence, and the Pursue as goal label as byte-for-byte invariants; and the tier-label rewrite targets the exact rule that currently sets {test-tier-label} to “Tier 1 — Code-touching plan” / “Tier 2 — Non-code plan”.
5
done
Mirror the humanized structure into the markdown fallback reference/SKELETON.md
Why
The 2.16.0 release established the twin-file convention (the Resources section landed in both skeletons in lockstep); leaving the markdown fallback jargon-heavy would let the two templates drift apart.
Verify
reference/SKELETON.md opens with an “At a glance” analog and uses the same de-jargoned section names as the HTML skeleton (“Definition of done”, “Final check”, …); no HTML-only mechanics (drawer markup, ids) are copied into it.
6
done
Add tests/plugins/test-humanized-skeleton.sh covering the new human layer, the untouched machine contract, and the frozen strings
Why
The whole change hinges on “humanize without breaking consumers”; a test asserting both sides keeps every future skeleton edit honest.
Verify
bash tests/plugins/test-humanized-skeleton.sh passes — asserting the literal new heading strings (“Definition of done”, “Final check”), the frozen strings ( Pursue as goal , step-chip todo , the report-empty sentence), a details.plan-more-ways element without the open attribute, and extractor output purity — and the existing suite ( test-goal-prompt.sh , test-extractor-wiring.sh , test-save-pdf.sh , test-resources-section.sh , and test-responsive-retrofit.sh , whose byte-identical #plan-responsive-fix style block must survive every skeleton edit) still passes without any edits.
7
done
Bump plan-agent to 2.17.0 in .claude-plugin/marketplace.json and describe the change in CHANGELOG.md
Why
Marketplace convention: every plugin change ships a manual semver bump (minor — the output format changed) plus a changelog line so users and the merge driver can track it.
Verify
marketplace.json parses as valid JSON (the settings hook auto-validates on write) with plan-agent at 2.17.0 , and kit/plugins/plan-agent/CHANGELOG.md has a 2.17.0 entry in the established format ( ## X.Y.Z — Title (date) with ### Added / ### Changed subsections), including a one-line note on why this is a minor bump (output format changed; nothing removed or renamed).
Tests
The tests that prove the change does what it promises.
Tier 1 — Code-touching plan
Objective Generated plans lead with human content on an intact machine contract File: tests/plugins/test-humanized-skeleton.sh Type: smoke test Asserts: the skeleton leads with human content — the .plan-glance block sits above the Implement row, exactly one prompt row is visible on first paint, and every section carries a .section-intro — while every machine hook ( plan-* meta tags, implement-cmd / goal-cmd / workflow-cmd ids, #criteria-list , #completion-list , .step-card , data-status ) is still present and unrenamed. Run: bash tests/plugins/test-humanized-skeleton.sh
Integration Existing plan-agent contract suite stays green File: tests/plugins/test-goal-prompt.sh , test-extractor-wiring.sh , test-save-pdf.sh , test-resources-section.sh , test-responsive-retrofit.sh Targets: the prompt-row ids, meta tags, literal labels, and section markers that the plans gallery, hooks, extractor, and finalize flow grep out of plan files Key cases: goal and workflow meta tags plus their rows survive the regroup (including the literal Pursue as goal label); no #plan-digest regression; the Save-as-PDF button and print CSS are intact; the Resources section contract is unchanged; the #plan-responsive-fix style block stays byte-identical to the retrofit script’s STYLE_BLOCK
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.
Open the updated SKELETON.html raw in a browser and confirm the reading order: title → objective → at a glance → one Implement action → progress → sections with sentence-case headings and intros, with the goal, workflow, and source rows collapsed. Run the full tests/plugins/ suite (the new smoke test plus the existing contract tests). Finally, generate one real plan with /plan-agent:implementation-plan --quick and confirm the humanized layout appears and the plans gallery still indexes the new file. Render the raw skeleton at a ~375px viewport to confirm the glance block and the details.plan-more-ways drawer behave on mobile, and run node scripts/extract-plan-spec.mjs against the generated plan to confirm objective, context, and verification text stays free of glance and intro copy.
Wrapping up
Three gates that must all pass before this plan is marked completed.
Required
Completion Report
No items to report — all requirements met.