Replace the Pipeline Flow with a UML Activity Diagram
Hightodo
2026-06-10 agentics refactor High effort
Objective
Swap the stacked pipeline flow for a hand-authored, fully self-contained UML activity diagram — initial node, action steps, decision branches, final node — across every plan-output template, so a developer reads a plan's flow at a glance in familiar notation instead of parsing a column of look-alike boxes.
ImplementRead and implement all steps in the plan at docs/plans/replace-pipeline-with-uml-activity-diagram.md — Replace the Pipeline Flow with a UML Activity Diagram. Verify against the plan's Tests, Verification, and Acceptance Criteria before reporting done. If everything passed, mark completion in docs/plans/replace-pipeline-with-uml-activity-diagram.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 Pipeline Flow with a UML Activity Diagram. The plan at docs/plans/replace-pipeline-with-uml-activity-diagram.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-pipeline-with-uml-activity-diagram.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-pipeline-with-uml-activity-diagram.md — Replace the Pipeline Flow with a UML Activity Diagram. Brief subagents with the plan file at docs/plans/replace-pipeline-with-uml-activity-diagram.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-pipeline-with-uml-activity-diagram.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.
The story behind this plan — what prompted the work and why it matters now.
Two plan-output templates ship a generic flow diagram today. plan-agent 's SKELETON.html renders a stacked .pipeline (one box per stage) inside its opt-in #diagram section, and plan-interview 's markdown-to-html auto-generates a .section-diagram SVG that maps the document's sections as a row of nodes. Neither uses a recognised modelling notation, so the visual carries no more meaning than an indented list.
The Nulab UML diagrams guide identifies the activity diagram as the standard behavioural notation for workflows — start/end markers, action nodes, decision diamonds, and directed control flow. A plan is fundamentally an ordered set of steps with the occasional branch, so the activity diagram is the natural fit: developers already read it, and it makes a plan's flow scannable.
Hard constraint: every plan is a single self-contained .html file — no CDN, no external scripts, no <canvas> . That rules out Mermaid and PlantUML; the diagram must be hand-authored inline SVG styled with the skeleton's existing CSS theme tokens so it inherits light/dark and prints cleanly. Only the flow representation changes — the comparison grid, bar chart, and data table in the #diagram section stay exactly as they are.
Files that change
Every file this plan touches, and what happens to each one.
agentics/
.claude-plugin/marketplace.jsonmodifiedminor version bump for both plugins
kit/plugins/plan-agent/CHANGELOG.mdmodifiedlog the activity-diagram swap
kit/plugins/plan-interview/skills/markdown-to-html/reference/html-spec.mdmodifiedconvert section diagram to UML activity
tests/pages/test-uml-activity-diagram.shnewobjective smoke test for the swap
Steps
The step-by-step work, in order — each step says what to do, why it matters, and how to check it worked.
1
todoAdd the .uml-activity style block to SKELETON.html , replacing the .pipeline rules.
Why
The activity diagram needs a themed figure wrapper, a caption, and SVG node/edge styling driven by CSS vars ( --surface , --border , --accent , --text ) so it inherits light/dark and prints cleanly; the old .pipeline flex-stack rules no longer apply. Leave the .compare-grid , .bar-chart , and .plan-table CSS untouched.
Verify
grep -n 'uml-activity' …/SKELETON.html shows the new rules and grep -c 'pipeline-node' … returns 0, while the .compare-grid / .bar-chart / .plan-table selectors remain. No hard-coded hex appears inside the .uml-activity rules.
2
todoReplace the Flow / pipeline sub-block in the #diagram section with an inline-SVG activity diagram.
Why
This is the core swap. Wrap an inline <svg> in <figure class="uml-activity" role="img" aria-label="…"> with a reusable <defs><marker> arrowhead, an initial node (filled circle), the {activity-diagram-svg} action and decision nodes, and a final node (ringed circle) — while the comparison-grid, bar-chart, and data-table sub-blocks survive. role="img" plus a full-text aria-label hands screen readers the whole flow as one sentence, mirroring the existing .bar-chart aria pattern.
Verify
grep -n 'figure class="uml-activity"' and grep -n '<marker' both match in SKELETON.html ; the {diagram-nodes} / .pipeline markup is gone; the {compare-columns} , {chart-rows} , and {table-rows} blocks remain. A sample render shows the initial node, action nodes, a decision diamond, directed arrows, and the final node.
3
todoRewrite the diagram guidance in SKILL.md and add a deterministic vertical-stack SVG recipe.
Why
Update four spots — the diagram bullet under Visual sections , the Visual components note, the Flow / pipeline row of the Visual Components table (rename to Activity diagram (UML) ), and the skeleton-blocks note. Then document a fixed-geometry recipe: fixed viewBox width, fixed node height and vertical gap, a single trunk column, decision diamonds with a documented horizontal branch offset, and the rule that the model fills node text only — never free-form coordinates. SKILL.md is the runtime instruction set; without it the model keeps emitting .pipeline , and a fixed recipe removes the biggest failure mode (an LLM hand-computing overlapping coordinates).
Verify
grep -ni 'activity diagram' …/SKILL.md matches in all four locations; grep -ni 'pipeline' …/SKILL.md shows no remaining authoring guidance; the recipe names a fixed node height, a fixed gap, the role="img" + aria-label rule, and the "text only, no free-form coordinates" constraint.
4
todoConvert plan-interview 's section diagram in html-spec.md into a true UML activity diagram.
Why
Scope includes plan-interview , so its document-flow diagram must match plan-agent 's notation. Rewrite the SVG Section Diagram block: prepend an initial node (filled circle), render each section as an action node connected by directed arrows via a <defs><marker> arrowhead, and append a final node (ringed circle) — keeping the navigation behaviour developers rely on.
Verify
grep -ni 'activity' …/html-spec.md matches in the diagram section and the intro; the block now contains an initial node, a <marker> arrowhead, and a final node; the geometry formulae ( nodeWidth , gap , W ) and the role="img" / aria-labelledby / <title> lines are still present; the .svg-node click listener is unchanged.
5
todoCreate the objective smoke test tests/pages/test-uml-activity-diagram.sh .
Why
Make it executable with set -euo pipefail and a FAILURES counter like test-pages-smoke.sh . Assert that SKELETON.html contains class="uml-activity" , <marker , and role="img" ; contains no pipeline-node ; still contains compare-grid , bar-chart , and plan-table ; that html-spec.md contains the activity initial/final nodes; and that none of the three templates contain mermaid , a CDN URL, <script src , or <canvas> . This locks the change against silent regression and matches the repo's bash smoke-test convention.
Verify
bash tests/pages/test-uml-activity-diagram.sh exits 0 and prints PASS lines after the templates are updated; temporarily reverting SKELETON.html to .pipeline makes it exit non-zero (negative check).
6
todoBump both plugin versions and update changelogs.
Why
Bump the plan-agent and plan-interview version (minor) in .claude-plugin/marketplace.json and add a dated entry to each plugin's CHANGELOG.md describing the swap, using conventional wording ( feat(plan-agent): … , feat(plan-interview): … ). Repo convention requires a manual minor bump + changelog on any plugin change, and the new versions must exceed main ; .claude/settings.json auto-validates marketplace.json on save.
Verify
node -e "JSON.parse(require('fs').readFileSync('.claude-plugin/marketplace.json','utf8'))" succeeds; both plugins' versions are higher than on main (compare with git show main:.claude-plugin/marketplace.json ); both CHANGELOG.md files have a new top entry dated 2026-06-10.
Tests
The tests that prove the change does what it promises.
Tier 1 — Code-touching plan
Objective Every plan template emits a self-contained UML activity diagram, not a pipeline File: tests/pages/test-uml-activity-diagram.sh Type: smoke test Asserts: SKELETON.html and html-spec.md contain the activity-diagram markup ( uml-activity / initial & final nodes, <marker> arrowhead, role="img" ); the old .pipeline / pipeline-node markup is gone; the kept visuals ( compare-grid , bar-chart , plan-table ) remain; and no template references a CDN, Mermaid, <canvas> , or external <script src> (the self-contained invariant). Run: bash tests/pages/test-uml-activity-diagram.sh
Integration A generated plan page serves the activity diagram over HTTP File: tests/pages/test-pages-smoke.sh (extended) Targets: a docs/plans/*.html generated from the updated skeleton, served through the GitHub Pages path. Key cases: a sample plan returns HTTP 200 and its served body contains class="uml-activity" and role="img" ; the plans gallery still lists the file. Exercises template → generated artifact → serving layer together.
E2E A developer sees the activity diagram render in the browser File: tests/pages/uml-activity.e2e.mjs (new; driven by the playwright-cli skill, no committed runner required) Targets: a served plan and a rendered markdown-to-html document opened in a headless browser. Key cases: the initial node, action nodes, a decision diamond, directed arrowheads, and the final node are visible; the diagram stays legible under prefers-color-scheme: dark ; the figure's aria-label reads the full flow as text.
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.
Confirm the swap end-to-end in five passes:
Smoke test: run bash tests/pages/test-uml-activity-diagram.sh — it exits 0 with PASS lines for the new markup, the absent .pipeline , the retained visuals, and the no-CDN invariant.
plan-agent output: generate a fresh plan with /plan-agent:implementation-plan on a multi-step objective and confirm the produced .html contains a figure.uml-activity inline-SVG activity diagram and no .pipeline markup.
plan-interview output: render a multi-section markdown plan through markdown-to-html and confirm the section diagram now shows an initial node, directed arrowheads, and a final node, and that clicking a node still scrolls to its section.
Browser + a11y: serve both outputs ( /serve-docs ), open them, and confirm the diagram is legible in light, dark, and print; the arrowheads point downstream; and the figure's aria-label announces the full flow as a sentence.
Packaging: JSON.parse marketplace.json succeeds, both plugin versions exceed main , and each CHANGELOG.md has a dated entry.
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.
Add class and sequence diagrams as additional opt-in UML components
Paste this prompt into Claude to execute this follow-up:
In the agentics repo, extend the plan-output templates to support two more UML diagram types alongside the activity diagram: a class diagram (boxes with name/attributes/methods compartments and association lines) and a sequence diagram (lifelines with message arrows). Add the CSS plus an inline-SVG authoring recipe for each to kit/plugins/plan-agent/skills/implementation-plan/reference/SKELETON.html, and document them in that plugin's SKILL.md Visual Components section. Keep everything self-contained inline SVG — no CDN or Mermaid. Add assertions to tests/pages/test-uml-activity-diagram.sh and bump both plugin versions in .claude-plugin/marketplace.json with CHANGELOG entries.
Bring the review-plan output template in line with the activity diagram
Paste this prompt into Claude to execute this follow-up:
In the agentics repo, update kit/plugins/plan-agent/skills/review-plan/references/output-template.md so any diagram it renders uses the same hand-authored inline-SVG UML activity-diagram notation introduced in SKELETON.html (initial/action/decision/final nodes, a marker arrowhead, role="img" plus a full-text aria-label, CSS theme tokens, no CDN). Follow the deterministic vertical-stack recipe documented in the implementation-plan SKILL.md. Bump the plan-agent version in .claude-plugin/marketplace.json and add a CHANGELOG entry.
Regenerate existing committed plans onto the new diagram
Paste this prompt into Claude to execute this follow-up:
In the agentics repo, scan docs/plans/*.html (ignore docs/plans/archive/) for plan files that still contain the old .pipeline flow markup. For each, migrate the #diagram flow block to the new inline-SVG UML activity-diagram component, leaving compare-grid/bar-chart/plan-table untouched. Do not change any completed plan's status. Report a table of files changed.
Lint hook that blocks new plans using the old .pipeline class Wish List
Speculative / blue-sky idea — not on the critical path. Paste into Claude when ready to explore:
Paste this prompt into Claude to execute this follow-up:
In the agentics repo, draft a minimum-viable PostToolUse hook (alongside plan-agent's existing validate-plan-filename hook) that fires on Write/Edit of *.html files under docs/plans/ and rejects any plan whose #diagram section still uses .pipeline / .pipeline-node markup, pointing the author to the UML activity-diagram component instead. Skip files whose meta plan-status is "completed". Recommend whether it should warn or hard-block, with reasoning.
Animate the activity diagram as steps are checked off Wish List
Speculative / blue-sky idea — not on the critical path. Paste into Claude when ready to explore:
Paste this prompt into Claude to execute this follow-up:
Explore making the plan's UML activity diagram interactive: as each step card flips from todo to done, highlight the matching action node in the inline SVG (via a CSS class toggled by the plan's existing JavaScript) so the diagram doubles as a live progress view. Keep it pure inline SVG plus the plan's existing minimal JS — no external libraries. Sketch the data-attribute wiring between step cards and SVG nodes before implementing.