Plans

Convert 24 keeper markdown plans to HTML and set up retention routine

Medium todo
2026-06-04 agentics chore Medium effort
Objective

Convert all 24 remaining keeper .md plans in docs/plans/ to HTML format using the implementation-plan SKELETON.html template, delete the .md originals, rebuild the plans gallery to show all 43 active plans, and register a scheduled retention check for the six-month archival rule.

Implement Read and implement all steps in the plan at docs/plans/convert-keeper-plans-to-html.md — Convert 24 keeper markdown plans to HTML and set up retention routine. Verify against the plan's Tests, Verification, and Acceptance Criteria before reporting done. If everything passed, mark completion in docs/plans/convert-keeper-plans-to-html.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: Convert 24 keeper markdown plans to HTML and set up retention routine. The plan at docs/plans/convert-keeper-plans-to-html.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/convert-keeper-plans-to-html.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 convert-keeper-plans-to-html.html
Path docs/plans/convert-keeper-plans-to-html.html
Spec docs/plans/convert-keeper-plans-to-html.md
Definition of done 0 / 6 done

Context

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

The docs cleanup workflow (PR #242) triaged 179 files across docs/: 60 developer guides relocated to docs/guides/, 95 shipped/stale plans archived to docs/plans/archive/, and statuses normalized to three canonical values. Two items from the parent plan ( docs/plans/clean-up-docs-and-plans.html ) remain incomplete:

Step 4 — Convert 24 keeper .md plans to HTML using the implementation-plan template styles. Each conversion requires populating the 1,420-line SKELETON.html template with content extracted from the markdown source.

AC7 — Set up a scheduled retention routine for the six-month archival rule defined in docs/plans/README.md . The policy is written but has no automated enforcement.

The 24 .md plans are active keepers that need HTML twins so they appear in the plans gallery ( docs/plans/index.html ) and follow the project’s HTML-first plan convention. Currently the gallery shows only 19 of the 43 active plans.

Steps

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

1
todo Build a conversion manifest from the 24 keeper .md plans
Why
Need structured metadata (title, status, type, created, objective, steps) from each .md file to populate HTML template placeholders accurately. A manifest prevents re-parsing and gives the workflow a deterministic work list.
Verify
Manifest JSON contains 24 entries. Each entry has: source .md path, target .html filename (verb-target kebab-case), extracted title, status, type, and created date. No entry has empty required fields.
2
todo Convert each .md plan to HTML using SKELETON.html
Why
HTML format is the project convention for active plans; the plans gallery only indexes .html files. Using the same SKELETON.html template as /plan-agent:implementation-plan ensures visual and structural consistency.
Verify
find docs/plans -maxdepth 1 -name "*.html" ! -name "index.html" | wc -l returns at least 43 (19 existing + 24 new). Each new .html has valid <meta name="plan-status"> , <meta name="plan-type"> , <meta name="plan-created"> , and <meta name="plan-repo"> tags.
3
todo Delete the 24 original .md plan files
Why
Keeping both .md and .html creates confusion about which is canonical. The .html is now the source of truth; the .md originals are redundant.
Verify
find docs/plans -maxdepth 1 -name "*.md" ! -name "README.md" | wc -l returns 0. Only README.md remains as a non-HTML file in docs/plans/.
4
todo Rebuild the plans gallery with all 43 active plans
Why
The gallery at docs/plans/index.html only indexes .html files and currently shows 19 cards. After conversion it must reflect the full set of 43 active plans.
Verify
Open docs/plans/index.html in a browser. The header shows &ldquo;43 plans&rdquo;. All 43 cards render with correct title, status chip, type chip, and created date. Search and filter controls work.
5
todo Register a scheduled retention check for the six-month archival rule
Why
The retention policy in docs/plans/README.md defines a six-month archival window for completed plans, but has no automated enforcement. A scheduled check prevents stale plans from accumulating again.
Verify
A scheduled task or cron entry exists that scans docs/plans/ for plans with status: completed and created date older than 6 months, then reports eligible plans for archival.
6
todo Mark parent plan steps and criteria as complete
Why
Completing these items closes the remaining gaps from the docs cleanup workflow and brings the parent plan to fully done.
Verify
Read docs/plans/clean-up-docs-and-plans.html . Step 4 has class completed and chip shows &ldquo;done&rdquo;. AC7 checkbox is checked. If all other ACs are also checked, the plan status is updated to completed .

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 find docs/plans -maxdepth 1 -name "*.html" ! -name "index.html" | wc -l to confirm 43 HTML plans. Run find docs/plans -maxdepth 1 -name "*.md" ! -name "README.md" | wc -l to confirm 0 remaining .md plans. Open docs/plans/index.html in a browser and verify 43 cards render with correct status/type badges. Spot-check 3 converted plans for correct meta tags and content fidelity against the original .md. Verify the parent plan&rsquo;s Step 4 and AC7 are marked done.

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.

Audit converted plans for content fidelity

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

Read every .html plan in docs/plans/ that was converted from a .md source (24 files). For each, compare the HTML content against the original .md in git history (use git show HEAD~1:docs/plans/<name>.md). Report any plans where the title, objective, steps, or acceptance criteria differ materially from the .md original. Flag missing sections or truncated content. Output a table: filename, status (match/drift/missing-section), details.
Backfill implement and workflow prompts for converted plans

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

Scan every .html plan in docs/plans/ and check for empty or placeholder implement prompt (<meta name="plan-implement">) and workflow prompt (<meta name="plan-workflow">) meta tags. For each plan missing a real implement prompt, generate one following the format: "Read and implement all steps in the plan at docs/plans/<filename> &mdash; <condensed objective>". Write the prompts into both the meta tag and the visible implement-cmd code element. Report which files were updated.
Rename random-slug .md plans before conversion

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

Check the 24 keeper .md plans in docs/plans/ for random-slug filenames (e.g. i-want-social-media-synthetic-thimble.md, in-its-use-there-atomic-horizon.md, show-the-claude-changelog-clever-rabbit.md, social-media-tools-plugin-purring-tome.md, review-the-plan-agent-serialized-ullman.md). For each, read the plan title and objective, then propose a verb-target kebab-case rename. Present a table of (current name, proposed name, rationale) for approval before renaming.