Plan: Clean up and make docs/plans manageable

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.html — Triage and archive plans, convert keepers to HTML, add 6-month retention

Run as workflow — launch parallel subagents

Run a workflow to implement the plan at docs/plans/clean-up-docs-and-plans.html — Triage and archive plans, convert keepers to HTML, add 6-month retention

File clean-up-docs-and-plans.html

Path docs/plans/clean-up-docs-and-plans.html

Acceptance criteria 0 / 8 done

Context

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

done Build a triage manifest of every doc and plan

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.

done Relocate the 60 loose developer docs out of docs/ root

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

done Flag the developer-useful plans worth keeping

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.

todo Convert kept markdown plans to template-styled HTML

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.

done Archive shipped plans after a knowledge check

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

done Normalize status frontmatter on the survivors

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

done Stand up a scheduled six-month retention routine + policy doc

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.

done Rebuild the plans gallery to reflect the clean state

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.

Acceptance Criteria

A triage manifest exists listing all 179 in-scope *.md files (60 root + 119 plans) with a decision and rationale per row; no .html plan is included.
find docs -maxdepth 1 -name '*.md' returns zero results — no stray plan/doc files at docs/ root.
The 60 relocated developer docs live under docs/guides/ and are tracked by git as renames (history preserved).
Every kept plan has an HTML twin built from the implementation-plan template styles and renders correctly in a browser.
No completed/implemented/superseded markdown plan remains loose in docs/plans/; each was knowledge-checked before being git mv'd to archive/.
Every surviving active plan uses only the canonical status vocabulary: todo, in-progress, or completed.
A scheduled six-month retention routine is registered, its dry-run reports zero eligible plans today, and a docs/plans/README.md documents the lifecycle policy.
The regenerated docs/plans/index.html gallery shows only surviving plans with an accurate count and working filters.

Verification

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.

Completion Checklist

Required

All step TODOs marked as done
All acceptance criteria verified and checked off
Plan status updated to completed

Completion Report

No items to report — all requirements met.

Next Steps

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.

Wish List

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:

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.

Unresolved Questions

Should the 49 stale in-progress plans be re-confirmed or downgraded?

In the agentics repo, list every docs/plans/*.md plan with status: in-progress alongside its last git commit date. Recommend which are genuinely active versus abandoned (no commits in 60+ days), and propose downgrading abandoned ones to todo or archiving them if the work actually shipped. Present as a table for approval — do not change anything yet.