Plans

Clean up and make docs/plans manageable

High in-progress
2026-06-04 agentics chore High effort
Objective

Turn an unmanageable pile of 179 markdown plan and doc files into a clean, navigable library: relocate stray developer docs, archive every shipped plan after checking it for reusable knowledge, convert the keepers to template-styled HTML, normalize statuses, and stand up a repeatable six-month retention process so the mess never comes back. Scope is markdown only — the 18 existing HTML plans are left untouched.

Implement Read and implement all steps in the plan at docs/plans/clean-up-docs-and-plans.md — Clean up and make docs/plans manageable. Verify against the plan's Tests, Verification, and Acceptance Criteria before reporting done. If everything passed, mark completion in docs/plans/clean-up-docs-and-plans.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: Clean up and make docs/plans manageable. The plan at docs/plans/clean-up-docs-and-plans.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/clean-up-docs-and-plans.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 clean-up-docs-and-plans.html
Path docs/plans/clean-up-docs-and-plans.html
Spec docs/plans/clean-up-docs-and-plans.md
Definition of done 0 / 8 done

Context

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

The docs/ tree has grown unmanageable. Markdown is the problem; there are two in-scope piles plus excluded sets:

60 loose .md files at docs/ root — these are generated developer docs (they carry <!-- generated:start --> markers from the documenting-plans skill). They are valuable reference material but they clutter the repo root and are not organized.

119 markdown plans inside docs/plans/ — status frontmatter is inconsistent: 49 in-progress , 23 todo , 6 draft , plus stray completed , implemented , superseded , proposed , ready , and planned values.

18 HTML plans inside docs/plans/ — out of scope . This cleanup targets *.md only; existing .html plans are left exactly as they are (other than newly-created twins from Step 4).

82 files in docs/plans/archive/ — already-archived plans, organized under standard/ , artifact/ , fix/ , docs/ , and enhancement/ . Out of scope — left untouched per the repo's archive search-exclusion rule.

Decisions locked in during planning: scope = *.md files only, in docs/plans/ + the loose docs/ root (HTML plans and archive excluded); deliverable = a one-time cleanup pass and a scheduled retention routine; delete rule = retire plans whose status is completed , implemented , or superseded (verified shipped); preservation = convert developer-useful keepers to HTML using the implementation-plan template styles (deleting the .md after the twin verifies), and git-mv the rest to archive/ rather than hard-deleting so nothing is lost.

Note on the six-month rule: today is 2026-06-04 and the oldest plan's created: date is 2026-01-19, so nothing currently qualifies for age-based deletion (the cutoff is 2025-12-04). The six-month retention work is therefore forward-looking — we build the mechanism now and it will start retiring plans once they age past the threshold.

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 Build a triage manifest of every doc and plan
Why
You cannot clean what you have not inventoried. A single manifest turns 179 scattered markdown files into a reviewable decision table and becomes the audit trail for every move and deletion.
Verify
Write docs/plans/_cleanup-manifest.csv (or .json ) with one row per *.md file under docs/ root and docs/plans/ (excluding archive/ and any .html ), capturing: path, kind (root-doc / md-plan), status frontmatter, created date, age in days, and a decision column ( relocate / keep+convert / archive / normalize ). Confirm row count = 60 root + 119 md plans = 179.
2
done Relocate the 60 loose developer docs out of docs/ root
Why
The root-level .md files are generated developer guides, not plans — they are exactly the "info useful to developers" we want to keep, but they belong in their own home so the repo root stays clean.
Verify
Create docs/guides/ and git mv all 60 root-level .md files (those with <!-- generated:start --> markers) into it. Run find docs -maxdepth 1 -name '*.md' and confirm it returns zero results. Confirm docs/guides/ contains 60 files and git tracks them as renames.
3
done Flag the developer-useful plans worth keeping
Why
Not every active plan deserves a permanent home. Marking the keepers (reusable architecture, design decisions, ongoing initiatives) before converting prevents wasted conversion effort on throwaway plans.
Verify
In the manifest, every todo / in-progress / draft markdown plan has an explicit keep+convert or archive decision with a one-line rationale. No active plan is left undecided. Spot-check 5 decisions against the plan's actual content.
4
todo Convert kept markdown plans to template-styled HTML
Why
HTML plans render in the browser, show status badges, and live in the gallery. Reusing the implementation-plan template guarantees the converted plans look identical to freshly-generated ones — one consistent visual system.
Verify
For each keep+convert plan, run the plan-interview:markdown-to-html skill (or fill SKELETON.html directly) so the output references the same design tokens/structure as plan-agent/…/implementation-plan/reference/SKELETON.html . Each produces a .html twin with valid <meta name="plan-*"> tags. Open 2–3 in a browser and confirm they render with the standard header, status badge, and step cards. Remove the original .md once the HTML twin is verified.
5
done Archive shipped plans after a knowledge check
Why
Plans marked completed , implemented , or superseded represent work already in the codebase. Moving (not deleting) them to archive/ keeps the active directory lean while preserving history — but only after confirming no unique insight is lost.
Verify
For each plan with status completed / implemented / superseded : (1) confirm the work shipped via git log or by inspecting the affected files; (2) scan for any unique decision/insight not already captured in a docs/guides/ doc — if found, extract it into the relevant guide first; (3) git mv the plan into docs/plans/archive/<type>/ . Confirm no completed / implemented / superseded .md remains loose in docs/plans/ .
6
done Normalize status frontmatter on the survivors
Why
Seven different status values ( draft , proposed , ready , planned , …) make the gallery filters and any automation unreliable. Collapsing them to the canonical three makes status machine-readable everywhere.
Verify
Map every non-canonical status on the remaining active markdown plans to todo | in-progress | completed (e.g. draft / proposed / planned / ready → todo ; implemented → completed ). Run grep -rh '^status:' docs/plans/*.md and confirm only the three canonical values appear. (HTML plans are out of scope and left untouched.)
7
done Stand up a scheduled six-month retention routine + policy doc
Why
The whole point is that the cleanup is repeatable. A /schedule routine that runs on a cadence — plus a written policy — means future retirement happens automatically instead of accumulating into another 197-file mess.
Verify
Create a /schedule routine (backed by a dry-run-capable script) that lists plans whose created date is > 6 months old AND status ∈ { completed , implemented , superseded }, posts a dry-run report, and archives on approval. Run the underlying check today and confirm it reports zero eligible plans and explains the 2025-12-04 cutoff. Confirm the routine is registered (e.g. visible via the schedule/routine list). Write docs/plans/README.md documenting the keep/convert/archive rules, the six-month policy, the canonical status vocabulary, and the directory layout.
8
done Rebuild the plans gallery to reflect the clean state
Why
After moves, conversions, and archival, the gallery index is stale. Regenerating it gives an immediate visual confirmation that the directory is now manageable and every surviving plan is accounted for.
Verify
Run /plan-agent:plans-library to regenerate docs/plans/index.html . Confirm the card count equals the number of surviving (non-archived) plans, that no archived or deleted plan appears, and that the gallery opens cleanly in a browser with working status/type filters.

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.

End-to-end, the cleanup is correct when a fresh checkout shows: a clean docs/ root (no loose .md ), a populated docs/guides/ , a lean docs/plans/ containing only active HTML plans plus the gallery and policy README, a grown docs/plans/archive/ holding every retired shipped plan, and a uniform status vocabulary throughout.

Run the full sweep: find docs -maxdepth 1 -name '*.md' | wc -l → 0; grep -rh '^status:' docs/plans/*.md | sort -u → only canonical values; the retention mechanism's dry-run → "0 eligible (cutoff 2025-12-04)"; and the regenerated gallery opens with a card count matching find docs/plans -maxdepth 1 -name '*.html' ! -name 'index.html' | wc -l . Confirm git status shows the moves as renames (not delete+add) so history survives, and that git log can still reach every archived plan.

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.

Re-triage the 82-file archive into the same conventions

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

Run a workflow to re-triage docs/plans/archive/ in the agentics repo. The archive has 82 files under standard/, artifact/, fix/, docs/, enhancement/. For each, verify the type subdirectory matches the plan's actual type frontmatter, flag any duplicates of plans still active in docs/plans/, and produce a report of misfiled or redundant archive entries. Do not delete anything — report proposed moves as a table for approval.
Automate status normalization with a PostToolUse hook

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

Add a PostToolUse hook to the plan-agent plugin that fires when a plan file under docs/plans/ is written, and rejects any status frontmatter value outside the canonical set {todo, in-progress, completed}. Model it on the existing validate-plan-filename hook. Include a clear error message naming the offending value and the allowed set.
Auto-generate a knowledge index from docs/guides/ 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:

Build a searchable index page for docs/guides/ in the agentics repo, modeled on the plans gallery: scan every guide, parse its title and first-paragraph summary, and emit a filterable docs/guides/index.html. Bonus: group guides by the plugin or domain they document.