Plans
Implementation Plan

Create Plans Index Page

completed
2026-05-30 agentics feature
Objective

Ship a self-contained docs/plans/index.html that renders every .html plan file in docs/plans/ as a status-badged card with title, type, created date, and a direct link — plus client-side filters by status and type — all regenerated from a single bash script.

File create-plans-index-page.html
Path docs/plans/create-plans-index-page.html
Acceptance criteria 0 / 8 done

Context

Superseded 2026-05-30 — the plans-library skill added in plan-agent v0.11.0 implements this as a reusable plugin skill. Use plans-library instead. See plan add-plans-library-to-plan-agent.html.

The plan-agent plugin generates .html plan files in docs/plans/. With over 100 plan files now in that directory, there is no way to browse or navigate them without knowing exact filenames. An index page that reads each plan's <meta> tags (plan-status, plan-type, plan-created, plan-repo) and renders them as filterable, sortable cards would make the plan archive discoverable without requiring a server or build toolchain.

The page will be pre-rendered at build time by a bash script that greps meta tags from each .html file and inlines the data, keeping it openable directly from the filesystem at a file:// URL.

Steps

1
todo Audit existing docs/plans/*.html files to verify the meta-tag schema
The card renderer reads five fields from each plan file (plan-status, plan-type, plan-created, plan-repo, <title>); gaps cause blank or broken cards. Knowing actual coverage first lets the build script apply correct fallback values.
Verify
Read at least five existing .html plan files; confirm all five meta fields are present in each. Note any missing fields so the build script can handle them.
2
todo Write docs/plans/build-index.sh — the bash script that extracts meta tags and emits the embedded JSON block
The build script is the data layer; defining it before the HTML template locks the data shape so the template can reference stable field names. Writing it first also makes the output testable in isolation.
Verify
Run the script against three existing plan files and confirm the output JSON block contains correct title, status, type, created, and repo values for each. The script must skip index.html itself.
3
todo Build docs/plans/index.html — a single self-contained file with pre-rendered plan cards, status badges, and filter controls
A pre-rendered, no-dependency static file opens at a file:// URL without a server and stays consistent with plan-agent's single-file philosophy. Embedding JSON rather than hard-coding card HTML makes the build script output trivially diffable and the template reusable.
Verify
Open docs/plans/index.html directly in a browser (no server). Confirm: all current .html plan cards render with correct title, status badge, type chip, and created date; filter by status shows/hides cards correctly; each card's "Open plan" link navigates to the correct file.
4
todo Surface the rebuild command visibly on the index page itself
The pre-rendered approach only stays current if the rebuild command is discoverable; burying it in a README means it will be forgotten. Showing it directly on the page ensures anyone viewing the index can regenerate it without hunting for documentation.
Verify
Open docs/plans/index.html in a browser; confirm a visible "Regenerate" instruction block showing bash docs/plans/build-index.sh is present on the page (not hidden in HTML comments or source only).

Acceptance Criteria

Verification

Delete docs/plans/index.html, run bash docs/plans/build-index.sh from the repo root, then open the output in a browser. Confirm: all current .html plan cards render with correct metadata; status filter controls show/hide cards correctly; "Open plan" links navigate to the correct files. Add one new .html plan file, re-run the script, and confirm the new card appears.

Next Steps

Integrate index rebuild into a plan-agent PostToolUse hook

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

Add a PostToolUse hook to kit/plugins/plan-agent that runs `bash docs/plans/build-index.sh` whenever a new .html plan file is written to docs/plans/. The hook should only fire when the written file matches the pattern `docs/plans/*.html` and is not `docs/plans/index.html`. Wire the hook into kit/plugins/plan-agent/.claude-plugin/plugin.json under the hooks key. Verify by writing a new test plan and confirming the index regenerates automatically.
Add text search to the index page

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

Add a live text search input to docs/plans/index.html that filters plan cards by title as the user types. The filter should be client-side (inline JS, no library), debounced at 150ms, and should compose with the existing status and type filter controls (i.e. all three filters apply simultaneously). Update build-index.sh if the data shape needs to change to support title search. Verify by typing a partial plan title and confirming only matching cards remain visible.
Wish List
Timeline view — Gantt-style grouping by created date Wish List

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

Add an optional timeline view to docs/plans/index.html that groups plan cards by month (based on plan-created date) in a vertical swimlane layout. The view should be toggleable from the existing card grid view without a page reload. Use the same design tokens and colour scheme as the card grid. No external libraries — inline CSS + JS only.
Export filtered results as a markdown summary Wish List

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

Add an "Export as Markdown" button to docs/plans/index.html that generates a markdown table of currently visible (filtered) plan cards and copies it to the clipboard. Each row should include: plan title (linked to the file), status, type, and created date. The export should respect the active status/type/search filters so the user can export a curated subset.