Plans

Add a Resources section to implementation plans

High completed
2026-07-09 agentics feature High effort
Objective

Let an implementation plan embed the images, screenshots, and reference links used to create it , so a reader can illustrate what the work is about and verify the implementation against the same material. Ship it as an opt-in Resources section in the plan skeleton — present when the plan was informed by visuals or external references, cleanly removed when it was not.

Implement Read and implement all steps in the plan at docs/plans/add-resources-section-to-plans.md — Add a Resources section to implementation plans. Verify against the plan's Tests, Verification, and Acceptance Criteria before reporting done. If everything passed, mark completion in docs/plans/add-resources-section-to-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
Pursue as goal — optimize for the outcome, in parallel
Achieve this goal: Add a Resources section to implementation plans. The plan at docs/plans/add-resources-section-to-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/add-resources-section-to-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 as workflow — launch parallel subagents
Run a workflow to implement the plan at docs/plans/add-resources-section-to-plans.md — Add a Resources section to implementation plans. Brief subagents with the plan file at docs/plans/add-resources-section-to-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/add-resources-section-to-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.
File add-resources-section-to-plans.html
Path docs/plans/add-resources-section-to-plans.html
Spec docs/plans/add-resources-section-to-plans.md
Definition of done 6 / 6 done

Context

The story behind this plan — what prompted the work and why it matters now.

Implementation plans are self-contained HTML documents produced by the plan-agent:implementation-plan skill from reference/SKELETON.html . They already carry rich structure — objective, context, an auto-generated file-tree, steps, tests, acceptance criteria — but there was no place to show the material a plan was built from : a screenshot of current behaviour, a design mockup, an architecture diagram, or the docs and issues consulted while planning.

Without that, a reader cannot easily illustrate what the plan changes or verify the implementation against the same references the author used. This plan adds an opt-in Resources section: an image grid of screenshots/mockups (each with mandatory alt text and a source-crediting caption) plus a list of reference links (each with a short note). It follows the same keep-or-delete, self-contained, no-CDN conventions as the existing opt-in visual blocks.

Files that change

Every file this plan touches, and what happens to each one.

agentics/
  • kit/plugins/plan-agent/skills/implementation-plan/reference/
    • SKELETON.html modified #ic-photo icon, .resource-* CSS, #resources section, nav link
    • SKELETON.md modified optional ## Resources in the markdown fallback
  • kit/plugins/plan-agent/skills/implementation-plan/SKILL.md modified document section + Resources Capture guide
  • kit/plugins/plan-agent/CHANGELOG.md modified add 2.16.0 entry
  • .claude-plugin/marketplace.json modified bump plan-agent 2.15.0 → 2.16.0
  • tests/plugins/test-resources-section.sh new Resources section smoke test
  • docs/plans/add-resources-section-to-plans.html new this plan document

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 the #ic-photo icon and the .resource-* CSS to reference/SKELETON.html .
Why
The section needs a sidebar/heading icon and self-contained styling. Add a Heroicons-outline #ic-photo symbol and the .resource-grid (auto-fill image grid), .resource-figure (bordered card with overflow:hidden ), .resource-figure > a (image-wrapper only — scoped so figcaption source links keep normal line-height), .resource-figure img , .resource-figure figcaption , .resource-links , and .resource-note rules. Pure CSS / inline SVG — no CDN.
Verify
grep -n 'id="ic-photo"' reference/SKELETON.html and grep -n '^ \.resource-grid {' reference/SKELETON.html both match.
2
done Add the opt-in #resources section between Context and Files, plus its sidebar nav link.
Why
Ships behind a removal comment like the other opt-in visuals. Contains a .resource-grid holding {resource-figures} (figure template: linked <img> with mandatory alt + a source-crediting <figcaption> ) and a .resource-links list holding {resource-links} (link + .resource-note ). Add a matching <li><a href="#resources"> nav entry using #ic-photo — the existing scroll-spy picks it up via querySelectorAll + filter(Boolean) , so no JS edit is needed.
Verify
The rendered section id order is Context → Resources → Files; filling {resource-figures} / {resource-links} yields a document that parses with an accessible <img alt> and a captioned link.
3
done Document the section in SKILL.md and add a Resources Capture guide.
Why
Add the section to Required Structure (Visual sections), HTML Output Requirements, and the Visual Components table, then a Resources Capture guide covering when to capture, image portability/no-CDN rules, mandatory alt text, and HTML-escaping. Wire capture reminders into Step 0b Explore and Step 1 Clarify so references are noted as they are consulted.
Verify
grep -n 'Resources Capture\|{resource-figures}\|{resource-links}' SKILL.md shows the guide and both placeholders; Step 0b/1 mention capturing references.
4
done Add an optional ## Resources section to the markdown fallback reference/SKELETON.md .
Why
Keeps the lightweight markdown template aligned with the HTML skeleton for headless/markdown output paths — an optional section between Objective and Steps with an example image (alt + source) and an example reference link.
Verify
grep -n '## Resources' reference/SKELETON.md matches, placed between Objective and Steps.
5
done Bump plan-agent to 2.16.0 in marketplace.json and add a CHANGELOG entry.
Why
A new opt-in section is a MINOR change; the value in marketplace.json is what ships (no CI bump). Update the plugin description to mention the Resources section and add a matching 2.16.0 section to CHANGELOG.md .
Verify
python3 -c "import json;d=json.load(open('.claude-plugin/marketplace.json'));print([p['version'] for p in d['plugins'] if p['name']=='plan-agent'][0])" prints 2.16.0 , and the CHANGELOG head shows the entry.
6
done Add the smoke test tests/plugins/test-resources-section.sh .
Why
Pins the section to the skeleton and its SKILL.md contract so the fill pipeline cannot silently drop it or diverge. Asserts the icon, section placement, placeholders, nav link, and CSS, plus a render check that fills the placeholders and confirms an accessible image and captioned link survive parsing.
Verify
bash tests/plugins/test-resources-section.sh exits 0 with all assertions passing.

Tests

The tests that prove the change does what it promises.

Tier 1 — Code-touching plan
Objective Plans can embed resources, and the section cleanly omits when unused File: tests/plugins/test-resources-section.sh Type: smoke test Asserts: the skeleton defines the #ic-photo icon, the #resources section between Context and Files, the {resource-figures} / {resource-links} placeholders, the nav link, and the .resource-* CSS; filling the placeholders yields a parseable section carrying an accessible <img alt> , a <figcaption> , and a captioned reference link; and SKILL.md documents the section and Resources Capture. The plan's objective, verified through the real skeleton. Run: bash tests/plugins/test-resources-section.sh
Unit Skeleton markup + CSS contract File: tests/plugins/test-resources-section.sh Targets: reference/SKELETON.html — icon symbol, section element, placeholders, nav link, .resource-* CSS blocks. Key cases: #ic-photo present; section.card-resources#resources present; both placeholders live inside .resource-grid / .resource-links ; #resources nav link uses the photo icon; CSS classes defined.
Integration Filled section renders accessibly File: tests/plugins/test-resources-section.sh Targets: the fill path — {resource-figures} / {resource-links} substituted with sample content, parsed via html.parser . Key cases: filled document parses without error; the section retains a non-empty alt , a <figcaption> , and the reference link with its .resource-note .

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.

Run the smoke test: bash tests/plugins/test-resources-section.sh — it must exit 0 with every assertion passing (icon, section placement, placeholders, nav link, CSS, the filled-render check, and the SKILL.md contract).

Then exercise the section in a real render: copy reference/SKELETON.html , substitute {resource-figures} with a linked <figure> (image + alt + captioned source) and {resource-links} with a reference <li> , open it in a browser, and confirm the image grid and link list render with the photo icon in the sidebar. Finally, delete the whole #resources block and its nav link and confirm the plan still renders and the scroll-spy is unaffected (it filters to existing sections).

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.

Auto-capture Step 7 browser-verification screenshots into Resources

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

In the agentics repo, extend plan-agent's implementation-plan skill so the Step 7 browser-verification screenshot (saved via mcp__claude-in-chrome__computer) is optionally added to the plan's Resources section as a committed asset under docs/plans/assets/, with descriptive alt text. Keep it opt-in and skip in headless/no-browser runs. Update SKILL.md and the smoke test; bump plan-agent and add a CHANGELOG entry.
🔭 Wish List Pull mockups straight from Figma into Resources

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

Run a workflow to design a Figma-to-Resources bridge for plan-agent: when a plan objective references a Figma URL, fetch the frame via the Figma MCP server, export a PNG into docs/plans/assets/, and emit a .resource-figure card citing the Figma source. Research the Figma MCP capabilities, propose the skill changes, and draft an implementation plan.