Plan Cleanup

/plan-cleanup

Remove planning artifacts and tech debt after a plan has been executed. No new work. No scope additions. Just cleanup.

Structured execution spec: protocol.yon. Read it for the canonical rules and step sequence; this file is explanation. The two must stay in sync — if you edit one, update the other and refresh the @STAMP date.

Phase 1 — Identify Artifacts

Scan for artifacts left behind by the planning and execution cycle:

Planning docs (created by /plan-create, /plan-phases, /plan-deep-dive):

• PLAN.md
• implementation_plan.md
• task.md (if created as a plan artifact, not a pre-existing project file)
• Any *-plan.md files in the project root

Execution scaffolding (created by /plan-execute or setup steps):

• Temp files, stub files, or files explicitly marked as temporary in the plan
• Any file whose sole purpose was to scaffold or support the plan run

Tool artifacts:

• .claude/ directories created incidentally in skill or tool folders (not the user's project .claude/)

For each candidate, verify: is this file needed by the project going forward? If yes, leave it. If it exists only because of the planning cycle, it's an artifact.

Gate: list every artifact found before removing anything. If none found, declare "No artifacts found — workspace is clean" and stop.

Phase 2 — Confirm and Remove

Present the artifact list to the user:

"Found the following planning artifacts:

• [file 1]
• [file 2]

Remove all? (y / skip [filename] / cancel)"

On confirmation:

• Remove each confirmed artifact
• For git repos: use git rm if the file is tracked, rm if untracked
• Never remove files outside the current project scope

Gate: do not remove any file not explicitly identified in Phase 1. Do not remove files the user skipped.

Phase 3 — Verify and Commit

1. Confirm each artifact is gone — list what was removed.
2. If in a git repo and files were tracked: commit with message chore: remove planning artifacts.
3. Push if the user's workflow includes pushing (check if prior commits in this session were pushed).

Terminal declaration (required):

• Cleanup complete — [N] artifacts removed.
• Cleanup complete — workspace was already clean.
• Cleanup halted — [reason]. Removed: [list]. Skipped: [list].

Rules

• MUST list artifacts before removing — never silently delete
• MUST verify each candidate is a planning artifact, not a project file
• MUST NOT remove files outside the current project scope
• MUST NOT remove files the user explicitly skipped
• MUST end with a terminal declaration

Human output. This skill's handler-facing output obeys the human-output contract (human-output/SKILL.md).

Self-improvement. On completion, run the Self-Improvement Protocol (self-improve/SKILL.md): if this run surfaced a concrete, blocking-or-recurring weakness in this skill, propose a specific fix for the handler to approve. Conservative — silent otherwise. Never auto-apply.