Plans
Implementation Plan

Add a plans-library Skill to plan-agent

todo
2026-05-30 agentics feature
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 — filterable by status and type, searchable by title, and openable in the browser — mirroring the media-library skill from social-media-tools.

File add-plans-library-to-plan-agent.html
Path docs/plans/add-plans-library-to-plan-agent.html
Acceptance criteria 0 / 8 done

Context

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.

Files

  • new kit/plugins/plan-agent/skills/plans-library/SKILL.md — the scanning & rendering skill
  • new kit/plugins/plan-agent/templates/plans-gallery.html — static gallery template with placeholders
  • edit .claude-plugin/marketplace.json — bump plan-agent 0.10.0 → 0.11.0 (MINOR: new skill)
  • edit kit/plugins/plan-agent/CHANGELOG.md — add 0.11.0 entry
  • edit kit/plugins/plan-agent/README.md — document the skill; update structure tree & Components
  • edit kit/plugins/plan-agent/.claude-plugin/plugin.json — extend description to mention the library skill
  • edit docs/plans/create-plans-index-page.html — mark superseded

Steps

1
todoCreate the plans-gallery.html template
Presentation must live in a static template so the skill only substitutes data — 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
todoDefine the gallery card markup & placeholders
The card must surface exactly the fields plans carry: title, status badge, type badge, created date, and filename link — 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
todoWrite SKILL.md with the scan → parse → render → open workflow
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
todoResolve the plans directory & exclusions correctly
plan-agent already resolves a plans dir (plansDirectory setting → docs/plans/ → 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 → untyped, title → filename).
5
todoRegister the skill: bump version & update docs
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
todoMark create-plans-index-page.html as superseded
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.

Acceptance Criteria

Verification

End-to-end: Load the plugin locally with claude --plugin-dir ~/devbox/agentics/kit/plugins/plan-agent, then trigger the skill (e.g. “browse my plans”). 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.

Next Steps

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.
Wish List
Auto-regenerate the index via a PostToolUse hookWish List

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

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.