Plans
Implementation Plan

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

todo
2026-06-04 agentics chore
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.html — Convert 24 keeper .md plans to HTML and add retention routine
Run as workflow — launch parallel subagents
Run a workflow to implement the plan at docs/plans/convert-keeper-plans-to-html.html — Convert 24 keeper .md plans to HTML and add retention routine
File convert-keeper-plans-to-html.html
Path docs/plans/convert-keeper-plans-to-html.html
Acceptance criteria 0 / 6 done

Context

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

1
todo Build a conversion manifest from the 24 keeper .md plans
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
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
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
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 “43 plans”. 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
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
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 “done”. AC7 checkbox is checked. If all other ACs are also checked, the plan status is updated to completed.

Acceptance Criteria

Verification

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’s Step 4 and AC7 are marked done.

Completion Checklist

Required

Completion Report

No items to report — all requirements met.

Next Steps

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