Prune outdated docs/plans markdown and reconcile plan-related docs safely for a target project.
Prereqs:
bash, git, find, and rg available on PATH.docs/plans/.--execute.Inputs:
--project-path <path>: target project path override. Default resolution order: --project-path > $PROJECT_PATH > current directory.--keep-plan <path|name>: plan to preserve (repeatable). Supports:
docs/plans/foo-plan.md),foo-plan.md),foo-plan).--keep-plans-file <path>: newline list of plans to preserve (# comments allowed).--execute: apply deletions (default is dry-run).--delete-important: also delete and files only tied to removed plans.docs/specs/**docs/runbooks/**--delete-empty-dirs: remove empty directories under docs/ after deletion.Outputs:
docs-plan-cleanup-report:v1 with sections:
[plan_md_to_clean][plan_related_md_to_clean][plan_related_md_kept_referenced_elsewhere][plan_related_md_to_rehome][plan_related_md_manual_review][non_docs_md_referencing_removed_plan]--execute mode:
docs/plans/**/*.md,docs/**/*.md that only depend on removed plans and are not externally referenced,--delete-important is explicitly set.Exit codes:
0: success1: runtime failure2: usage error or invalid keep-plan inputFailure modes:
docs/plans/ is missing in the target project.git, rg, find).--keep-plan / --keep-plans-file references unknown or ambiguous plans.$AGENT_HOME/skills/workflows/plan/docs-plan-cleanup/scripts/docs-plan-cleanup.shIdentify plans that must be kept.
Run dry-run first (defaults to $PROJECT_PATH when exported):
PROJECT_PATH=/path/to/project bash $AGENT_HOME/skills/workflows/plan/docs-plan-cleanup/scripts/docs-plan-cleanup.sh --keep-plan active-planReview report sections:
plan_related_md_kept_referenced_elsewhere are protected from auto-delete.plan_related_md_to_rehome should be consolidated before deletion.Apply cleanup after review:
bash $AGENT_HOME/skills/workflows/plan/docs-plan-cleanup/scripts/docs-plan-cleanup.sh --project-path /path/to/project --keep-plan active-plan --execute --delete-empty-dirs
Use --delete-important only when you are sure docs/specs/** and docs/runbooks/** candidates are obsolete.
references/ASSISTANT_RESPONSE_TEMPLATE.md as the response format when reporting cleanup results.[execution] with status: applied, the response must include:
total_plan_mdplan_md_to_keepplan_md_to_cleanplan_related_md_to_cleanplan_related_md_kept_referenced_elsewhereplan_related_md_to_rehomeplan_related_md_manual_reviewnon_docs_md_referencing_removed_planplan_md_to_keepplan_md_to_cleanplan_related_md_to_cleanplan_related_md_kept_referenced_elsewhereplan_related_md_to_rehomeplan_related_md_manual_reviewnon_docs_md_referencing_removed_plannone row in that table.