Plans

Create Plans Index Page

Medium completed
2026-05-30 agentics feature Medium effort
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.

Implement Read and implement all steps in the plan at docs/plans/create-plans-index-page.md — Create Plans Index Page. Verify against the plan's Tests, Verification, and Acceptance Criteria before reporting done. If everything passed, mark completion in docs/plans/create-plans-index-page.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: Create Plans Index Page. The plan at docs/plans/create-plans-index-page.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/create-plans-index-page.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 create-plans-index-page.html
Path docs/plans/create-plans-index-page.html
Spec docs/plans/create-plans-index-page.md
Definition of done 8 / 8 done

Context

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

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

The step-by-step work, in order — each step says what to do, why it matters, and how to check it worked.

1
done Audit existing docs/plans/*.html files to verify the meta-tag schema
Why
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
done Write docs/plans/build-index.sh — the bash script that extracts meta tags and emits the embedded JSON block
Why
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
done Build docs/plans/index.html — a single self-contained file with pre-rendered plan cards, status badges, and filter controls
Why
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
done Surface the rebuild command visibly on the index page itself
Why
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).

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.

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.

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.

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.
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:

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

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:

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

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.