Docs Plan Cleanup

Outputs:

• Stable dry-run/execute report 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]
• In --execute mode:
  • removes non-preserved docs/plans/**/*.md,
  • removes related docs/**/*.md that only depend on removed plans and are not externally referenced,
  • preserves important docs unless --delete-important is explicitly set.

Exit codes:

• 0: success
• 1: runtime failure
• 2: usage error or invalid keep-plan input

Failure modes:

• Target is not inside a git work tree.
• docs/plans/ is missing in the target project.
• Required tool missing (git, rg, find).
• --keep-plan / --keep-plans-file references unknown or ambiguous plans.
• Deletion fails due to filesystem permissions or path conflicts.

Scripts (only entrypoints)

• $AGENT_HOME/skills/workflows/plan/docs-plan-cleanup/scripts/docs-plan-cleanup.sh

Workflow

1. Identify plans that must be kept.

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

3. Review report sections:

   • plan_related_md_kept_referenced_elsewhere are protected from auto-delete.
   • plan_related_md_to_rehome should be consolidated before deletion.

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

5. Use --delete-important only when you are sure docs/specs/** and docs/runbooks/** candidates are obsolete.

Output and clarification rules

• Use references/ASSISTANT_RESPONSE_TEMPLATE.md as the response format when reporting cleanup results.
• When script output contains [execution] with status: applied, the response must include:
  1. The exact summary counters from script output, rendered as a Markdown table:
     • total_plan_md
     • plan_md_to_keep
     • 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
  2. All itemized sections from the script report, rendered as Markdown tables:
     • plan_md_to_keep
     • 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
• Do not omit empty sections. If a section has no values, keep it and render a none row in that table.
• Copy values from script output directly; do not infer or re-count manually.