Plans

Add plans-library Skill to plan-agent

Medium completed
2026-05-30 agentics feature Medium effort
Objective

Ship a plans-library skill in the plan-agent plugin that scans every HTML plan in the plans directory, reads each plan's status, type, title, and created date from its <meta> tags, and renders them into a single self-contained docs/plans/index.html gallery &mdash; filterable by status and type, searchable by title, and openable in the browser &mdash; mirroring the media-library skill from social-media-tools.

Implement Read and implement all steps in the plan at docs/plans/add-plans-library-to-plan-agent.md — Add plans-library Skill to plan-agent. Verify against the plan's Tests, Verification, and Acceptance Criteria before reporting done. If everything passed, mark completion in docs/plans/add-plans-library-to-plan-agent.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
Achieve this goal: Add plans-library Skill to plan-agent. The plan at docs/plans/add-plans-library-to-plan-agent.md describes one approach — use it as reference, but optimize for the outcome. Verify against the plan's Tests, Verification, and Acceptance Criteria before reporting done. If everything passed, mark completion in docs/plans/add-plans-library-to-plan-agent.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-plans-library-to-plan-agent.html
Path docs/plans/add-plans-library-to-plan-agent.html
Spec docs/plans/add-plans-library-to-plan-agent.md
Definition of done 8 / 8 done

Context

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

The plan-agent plugin now emits every plan as a self-contained .html file in docs/plans/ , each carrying machine-readable <meta> tags ( plan-status , plan-type , plan-created , plan-repo ) and a <title> . With 100+ plan files in that directory there is no way to browse or organise them without knowing exact filenames.

The sibling social-media-tools plugin already solves the identical problem for its cards: the media-library skill scans docs/media/social/*.html , parses each file, populates a static templates/gallery.html with one card per entry, writes index.html , and opens it in the browser. This plan ports that proven template-plus-skill pattern to plan-agent, adapting the data source (plan <meta> tags instead of filename parsing) and the filter dimensions (status + type instead of card type).

An existing todo plan, create-plans-index-page.html , describes a one-off bash-script index for this repo only. Per the chosen direction this plan supersedes it: instead of a repo-local script, we deliver a reusable plugin skill any plan-agent user can invoke. The old plan is marked superseded in Step 6.

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 Create the plans-gallery.html template
Why
Presentation must live in a static template so the skill only substitutes data &mdash; the same separation media-library uses. Reuse the light-theme design tokens from SKELETON.html so the gallery matches the plans it indexes.
Verify
Open the template in a browser with placeholder rows hand-filled; confirm status chips (todo / in-progress / completed), type chips (feature / fix / refactor / docs / chore), a search box, and a card grid all render, and that the embedded JS filters cards by both data-status and data-type plus title search.
2
done Define the gallery card markup & placeholders
Why
The card must surface exactly the fields plans carry: title, status badge, type badge, created date, and filename link &mdash; no PNG thumbnail (plans have no screenshots). Placeholders {{GALLERY_ENTRIES}} , {{PLAN_COUNT}} , {{GENERATED_AT}} mirror media-library's contract.
Verify
Each card is an <a href="{filename}"> with data-status and data-type attributes; clicking a card opens the underlying plan file via a relative link.
3
done Write SKILL.md with the scan &rarr; parse &rarr; render &rarr; open workflow
Why
The skill is the only runtime artefact Claude loads; all imperative logic lives here. Model it on media-library's six-step structure, swapping in plan-specific parsing.
Verify
Frontmatter declares name: plans-library , a two-sentence description with a trigger phrase, and allowed-tools: Bash, Read, Write, ToolSearch, ExitPlanMode . Body covers: locate plans dir, scan *.html (exclude index.html and archive/ ), parse meta tags + title per file, build entries, substitute into template, write index.html , open in browser, then STOP.
4
done Resolve the plans directory & exclusions correctly
Why
plan-agent already resolves a plans dir ( plansDirectory setting &rarr; docs/plans/ &rarr; default). The library must scan that same directory, and must never include docs/plans/archive/ (global + project search-exclusion rule) or the generated index.html .
Verify
Dry-run the scan command: it lists only top-level docs/plans/*.html , omits index.html , and does not descend into archive/ . Plans missing a meta tag fall back gracefully (e.g. plan-type &rarr; untyped , title &rarr; filename).
5
done Register the skill: bump version & update docs
Why
A new skill is a MINOR bump per the marketplace versioning table. Version lives only in marketplace.json for relative-path plugins; CHANGELOG, README, and plugin.json description keep the plugin self-documenting.
Verify
marketplace.json shows plan-agent 0.11.0 ; plugin.json has no version field; CHANGELOG has a 0.11.0 entry; README lists plans-library under Features, the structure tree, and Components; the .claude/settings.json marketplace-JSON validator passes.
6
done Mark create-plans-index-page.html as superseded
Why
The chosen direction supersedes the one-off index plan; leaving it as todo would invite duplicate work on a now-redundant approach.
Verify
That plan's status is updated (both <html data-status> and the plan-status meta) with a one-line note pointing to this plan / the plans-library skill.

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.

End-to-end: Load the plugin locally with claude --plugin-dir ~/devbox/agentics/kit/plugins/plan-agent , then trigger the skill (e.g. &ldquo;browse my plans&rdquo;). Confirm it scans docs/plans/ , writes docs/plans/index.html , and opens it in the browser.

In the browser: Verify the card count matches ls docs/plans/*.html | grep -v index.html | wc -l ; click a completed chip and confirm only completed plans remain; click a feature chip and confirm the set narrows further; type a known plan title into the search box and confirm a single card matches; click a card and confirm the underlying plan opens.

Regression: Re-run the skill and confirm index.html is regenerated (not duplicated) and is itself excluded from the next scan. Confirm no archive/ plans appear. Confirm the marketplace-JSON validator passes after the version bump.

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 a sort control (newest / status / type) to the gallery

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

In kit/plugins/plan-agent/templates/plans-gallery.html, add a sort dropdown to the toolbar with options: Newest first (by plan-created desc), Oldest first, Status, and Type. Implement the sort client-side in the existing inline script by reordering the .gallery-card elements in #galleryGrid. Keep it dependency-free and ensure it composes with the existing status/type/search filters. Update the plans-library SKILL.md only if the placeholder contract changes.
Auto-regenerate the index via a PostToolUse hook Wish List

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

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

Design a PostToolUse hook for the plan-agent plugin that regenerates docs/plans/index.html automatically whenever a plan .html file under docs/plans/ is created or edited. Reuse the plans-library scan/render logic (extract it into a small script the hook and skill share). The hook must be debounced/cheap, must skip when only index.html itself changed, and must never descend into docs/plans/archive/. Recommend whether the shared logic should be a bash or python script and justify the choice.