cleanup

cleanup

Essential Principles

1. Always present a multiSelect list. Even if the user says "just remove them all" or "I trust you" — present the list and let them confirm. This is not optional. The confirmation step is the entire point of the skill: it prevents accidental deletion and provides an audit trail.
2. Never touch .planning/codebase/. It is the shared codebase map regenerated by jc:map and referenced by every active task. Deleting it forces a full re-map and breaks in-progress plans. Do not list it, do not offer to remove it, do not suggest it might be stale.
3. Commit the removal. After deleting selected directories, stage the specific deletions and commit. The commit message must list which directories were removed so the deletion is auditable in git log without diffing.

Process

Step 1: Scan .planning/ directory

List only directories (ignore loose files):

ls -d .planning/*/ 2>/dev/null

If .planning/ doesn't exist or has no subdirectories: report "No .planning/ directory found" and stop.

Filter results: exclude codebase/. Everything else is a task-scoped directory.

If no task directories remain after filtering: report "No task directories to clean up" and stop.

Step 2: Determine status for each task directory

For each task directory, read .planning/{task-id}/plans/PLAN.md frontmatter to extract status:

Status found	Label
completed	Completed
paused	Paused
executing	Executing
verifying	Verifying
planning	Planned
No plans/PLAN.md found	No plan
PLAN.md exists but status unreadable	Unknown

Step 3: Present multiSelect list

Use AskUserQuestion with multiSelect: true. Each option is a task directory with its status label.

Format each option label as: {task-id} ({status label})

Description for each: brief context (e.g., wave progress if available, "research only" if no plan).

If no directories are selected (or user cancels), report "Nothing selected — no changes made" and stop.

Step 4: Remove selected directories

For each user-selected directory:

rm -rf .planning/{task-id}  # {task-id} = directory basename from Step 1

Verify each deletion succeeded. If any rm -rf fails, report which directories could not be removed and stop before committing.

Step 5: Commit the removal

Stage only the deleted paths:

git add .planning/{task-id-1} .planning/{task-id-2} ...

Commit with a message listing removed directories:

chore: clean up planning directories

Removed:
- .planning/{task-id-1}
- .planning/{task-id-2}

Anti-Patterns

Excuse	Reality
"User said 'just do it' so I'll skip confirmation"	See Principle #1 — the confirmation IS the skill, regardless of user urgency
"All tasks are completed, no need to ask"	Users may want to keep completed tasks for reference. Always let them choose
"I'll also clean up codebase/ since it looks stale"	codebase/ is never a cleanup target. It's shared infrastructure managed by /jc:map
"I'll use git add -A to stage everything"	-A can catch unrelated changes. Stage only the specific deleted paths

Related Skills

• jc:implement — modifies plan state (status fields, execution)
• jc:map — manages .planning/codebase/
• jc:status — read-only reporting on .planning/ state

Success Criteria

• Every task directory shown with its correct status label
• User confirmed selection before any deletion occurred
• Commit message lists each removed directory by name