Plans
Implementation Plan

Add visual components (file-tree, diagrams, charts, tables) to the implementation-plan skill

completed
2026-06-05 agentics feature
Objective

Promote four reusable, pure-CSS visual components — a file-tree, a flow/pipeline diagram, a comparison/bar chart, and a data table — into the implementation-plan SKELETON template as opt-in sections, and document in SKILL.md when the skill should reach for each, so generated plans can show file changes, flows, comparisons, and tabular data at a glance.

Implement Read and implement all steps in the plan at docs/plans/add-visual-components-to-plan-skill.html — Add opt-in visual components to the plan template
File add-visual-components-to-plan-skill.html
Path docs/plans/add-visual-components-to-plan-skill.html
Acceptance criteria 7 / 7 done

Context

The plan-agent:implementation-plan skill generates self-contained HTML plan documents from a template. Today those plans are text-only: numbered step cards, acceptance-criteria checkboxes, a progress bar, and collapsible disclosures. There is no first-class way to show which files a plan touches, the flow/architecture it introduces, comparisons/trade-offs, or tabular data — exactly the visuals that make a plan scannable and concrete.

Two facts make this low-risk, high-value:

  • A gold reference already exists in-repo. docs/plans/build-clean-plugin-dist.html was hand-authored with a .file-tree (lines 848–890), a .pipeline flow diagram (893–937), and a 3-column comparison diagram (940–981) — all pure CSS, token-driven, on-brand. They were one-offs, never promoted into the template.
  • The gallery scanner is insulated. Both plans-library/SKILL.md and the auto-rebuild hook hooks/build-index.sh only regex-match <meta name="plan-*"> tags and <title>. New <body> sections are invisible to them — no scanner changes needed.

Hard constraint: plans are single self-contained .html files — no CDN, no external scripts. Every visual must be pure CSS / inline SVG. Mermaid and Chart.js are out; the reference components already honor this.

Decision (confirmed): add all four components, all opt-in — the skill renders a visual only when the plan content warrants it; no mandatory placeholders that would clutter a small plan. This very plan dogfoods the proposal: the sections below are live instances of all four components.

Files to Modify

agentics/
  • kit/plugins/plan-agent/
    • skills/implementation-plan/
      • reference/SKELETON.html modified component CSS + 4 opt-in sections + nav
      • SKILL.md modified document the components & triggers
    • CHANGELOG.md modified v1.5.0 entry
  • .claude-plugin/
    • marketplace.json modified bump plan-agent 1.4.1 → 1.5.0
  • docs/plans/
    • add-visual-components-to-plan-skill.html this plan

Visual Components & Build Flow

Build sequence
Step 1–2
SKELETON.html <style>
port proven CSS + tokenize + add chart/table CSS
Step 3–4
SKELETON.html <body>
4 opt-in sections + conditional nav links
Step 5
SKILL.md
document components, triggers, a11y, no-CDN rule
Step 6
CHANGELOG + marketplace.json
v1.5.0 (MINOR — new capability)
The four components, by intent
Always-useful
  • file-tree → which files change
Flow / structure
  • pipeline → process & data flow
  • compare-grid → trade-offs
Data
  • bar-chart → distributions
  • plan-table → structured mappings
Share of CSS reused from the existing reference plan
Component reference
Each component, its source, and the CSS classes it introduces.
ComponentSourceCSS classes
File-treeported.file-tree, .file-list, .file-badge
Flow diagramported.pipeline, .pipeline-node, .pipeline-arrow
Comparison gridported + renamed.compare-grid, .compare-col-*
Bar chartnew.bar-chart, .bar-fill
Data tablenew.plan-table

Steps

1
donePort the three proven components into the SKELETON <style> block.
Reuses already-validated, on-brand CSS instead of reinventing it — guarantees visual fidelity. Generic class names let the comparison block serve any 2–3-way comparison.
Verify
Copy .file-tree/.file-list/.file-badge (ref 848–890), .pipeline/.pipeline-node/.pipeline-arrow (893–937), and the comparison rules (940–981) from build-clean-plugin-dist.html into SKELETON.html before </style>; rename .allowlist-*/.allow-keep|drop|generated to generic .compare-grid/.compare-col-add|neutral|remove. grep -n "\.file-tree\|\.pipeline\|\.compare-grid" SKELETON.html returns the rules; browser console shows no CSS errors.
2
doneTokenize the new colors in :root and add net-new CSS for the bar chart and data table.
Eliminates one-off hex so all visuals theme consistently; the bar chart and table are the two requested components the reference lacks. Inline --val keeps the bar chart script-free.
Verify
Add --amber-bg, --red, --red-bg (and reuse --green/--accent) to :root and repoint the ported rules. Author .bar-chart (label + .bar-track/.bar-fill sized by style="--val:NN%" + visible value) and .plan-table (<caption>, <th scope="col">, zebra rows). Render a scratch snippet: bars fill to width; table exposes caption + scoped headers in the DevTools a11y pane.
3
doneAdd the four opt-in section blocks to the SKELETON <body>.
Opt-in means the markup ships ready-to-fill but is removed when unused; the removal-comment convention is already used by .plan-workflow and unresolved-questions, so no new mechanism is introduced.
Verify
Insert a Files section (card-files#files, after Context), a Diagram section (card-diagram#diagram) hosting .pipeline/.compare-grid/.bar-chart, and a .plan-table usage — each wrapped in <!-- OPTIONAL … delete this block otherwise --> with {placeholder} tokens. Open SKELETON.html: all render with placeholders; delete one block and the page still renders cleanly with no orphaned styling.
4
doneWire the new sections into the sidebar nav and confirm scroll-spy tolerates removal.
A nav link to a removed section is a dead anchor; the TOC must stay in sync. The existing IntersectionObserver already iterates only existing sections, so missing ones are a no-op.
Verify
Add Files/Diagram <li> entries to .plan-nav ul, documented as add-only-when-section-kept. Scroll a plan with the sections: the matching nav link gains .active/aria-current. Remove a section + its <li>: no console errors; remaining links still highlight.
5
doneDocument the components in SKILL.md.
The template markup is inert without skill-side guidance on when to instantiate each visual and how to keep it accessible and self-contained. Content-anchored triggers prevent gratuitous visuals.
Verify
In Required Structure add optional files/diagram/chart/table sections with one-line "include when…" triggers. In HTML Output Requirements add bullets for each component's classes, the keep/remove rule, the no-CDN/pure-CSS constraint, and a11y (table scope/caption, bar-chart visible numeric labels, badges not color-only). Add a Visual Components subsection naming each trigger (Files → multi-file; Diagram → flow/architecture; Chart → distribution/before-after; Table → mappings/matrices). Re-read SKILL.md to confirm.
6
doneBump version and update the changelog.
A new skill capability is a MINOR bump per marketplace.md; the changelog keeps the marketplace discoverable and honest.
Verify
Add ## v1.5.0 — 2026-06-05 — Add visual components … under ### Added in CHANGELOG.md; change plan-agent version in marketplace.json from 1.4.1 to 1.5.0; leave plugin.json without a version. grep '"version"' .claude-plugin/marketplace.json shows 1.5.0; the settings auto-validator reports valid JSON.

Acceptance Criteria

Verification

1. Visual render check. Serve the updated SKELETON.html (or a test plan exercising all four components) via python3 -m http.server and confirm each renders correctly, themed by the design tokens, with the existing progress bar / step cards / completion checklist unaffected.

2. Opt-in / removal check. Produce a second minimal test plan with all optional visual blocks removed; confirm it renders identically to a pre-change plan — no orphaned CSS, no dead nav anchors, clean console.

3. Accessibility spot-check. In DevTools, confirm the data table exposes a caption + column headers, the bar chart shows visible numeric values (not color-only), and file badges pair color with a text label.

4. Gallery integrity. Trigger the rebuild hook (write a plan into docs/plans/) and confirm docs/plans/index.html still lists plans with correct status/type/title — proving the new sections didn't disturb the scanner.

5. Manifest validity. Confirm the marketplace.json auto-validator passes and the version guard (scripts/check-version-bump.sh) is satisfied at 1.5.0.

Completion Checklist

Required

Completion Report

No items to report — all requirements met.

Next Steps

Retrofit visuals into existing plans

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

Scan docs/plans/*.html (skip docs/plans/archive/) for plans that touch multiple files or describe a process flow but render text-only. For each strong candidate, add the new opt-in Files file-tree and/or Diagram section from the updated SKELETON.html, filling them from the plan's existing Steps/Context. Do not alter meta tags or titles. Report which plans you enhanced.
Auto-derive a file-tree from the "Files to modify" list

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

Extend the plan-agent implementation-plan skill so that when a plan enumerates files to create/modify/delete, it automatically generates the opt-in Files file-tree section — grouping by directory and assigning new/modified/deleted badges — instead of relying on the author to hand-build it. Keep it pure CSS and self-contained.
Wish List
Script-free "mini-Mermaid" flow shorthand Wish List

Speculative / blue-sky idea — not on the critical path. Paste into Claude when ready to explore:

Design a documented author shorthand for expressing simple DAGs / flows that the implementation-plan skill compiles into the pure-CSS .pipeline component (nodes + arrows + branches), so common architectures can be diagrammed from a compact notation — all still inline-CSS and CDN-free, no Mermaid runtime.