Pre-Presentation Cleanup Skill

Purpose: Ensure all cleanup is completed BEFORE presenting changes to user for final approval in AWAITING_USER_APPROVAL state.

Why This Matters: Presenting changes with unsquashed commits or lingering agent branches requires rework and creates a poor user experience. Complete cleanup first, then present clean commits for review.

Commit Structure: Task branch should have TWO commits (or one if no config changes):

1. Config commit (first, if applicable): .claude/, docs/project/, CLAUDE.md changes
2. Implementation commit (second): Source code, tests, changelog.md, todo.md changes

When to Use This Skill

Use pre-presentation-cleanup When:

• Task is in AWAITING_USER_APPROVAL state (after validation passes)
• About to present changes to user for final approval
• Before showing commit SHA and git diff --stat

Do NOT Use When:

• Still in IMPLEMENTATION or VALIDATION state
• Already presented and awaiting user response
• Task cleanup already completed

Mandatory Cleanup Steps

Execute ALL steps before presenting changes to user:

Step 1: Remove Agent Worktrees

CRITICAL: Use FULL ABSOLUTE PATHS for worktree removal. Git worktree commands require the exact path.

⚠️ IMPORTANT: Execute each worktree removal as a SEPARATE bash command to avoid multi-line parse errors. Do NOT combine multiple git worktree remove commands in a single multi-line bash call.

# ✅ CORRECT: Separate bash calls (each command standalone)
TASK_NAME="{task-name}"
git worktree remove /workspace/tasks/$TASK_NAME/agents/architect/code --force 2>/dev/null || true

# Second separate call
git worktree remove /workspace/tasks/$TASK_NAME/agents/tester/code --force 2>/dev/null || true

# Third separate call
git worktree remove /workspace/tasks/$TASK_NAME/agents/formatter/code --force 2>/dev/null || true

# ❌ WRONG: Multi-line command (causes parse errors)
# git worktree remove /path1 --force
# git worktree remove /path2 --force
# git worktree remove /path3 --force

Alternative - Single Line with Chaining:

TASK_NAME="{task-name}"
git worktree remove /workspace/tasks/$TASK_NAME/agents/architect/code --force 2>/dev/null || true && git worktree remove /workspace/tasks/$TASK_NAME/agents/tester/code --force 2>/dev/null || true && git worktree remove /workspace/tasks/$TASK_NAME/agents/formatter/code --force 2>/dev/null || true

Step 2: Delete Subagent Branches

# Delete agent branches (task branch preserved)
git branch -D ${TASK_NAME}-architect 2>/dev/null || true
git branch -D ${TASK_NAME}-tester 2>/dev/null || true
git branch -D ${TASK_NAME}-formatter 2>/dev/null || true

Step 3: Update Archival Files (MANDATORY)

⚠️ CRITICAL: The task branch commit MUST include todo.md and changelog.md updates. This ensures the atomic commit includes both implementation AND archival.

TASK_NAME="{task-name}"
cd /workspace/tasks/$TASK_NAME/code

# Update todo.md: DELETE the entire task entry (NOT mark with [x] or DONE)
# Update changelog.md: Add task completion entry with date and summary

# Stage archival files
git add todo.md changelog.md

Archival Content Requirements:

todo.md update:

• DELETE the entire task entry (do NOT mark with [x] or change status to DONE)
• Remove the task line and all its sub-items (Dependencies, Blocks, etc.)
• Per CLAUDE.md: "Completed tasks are REMOVED from todo.md (entire entry deleted)"

changelog.md update:

• Add entry under current date section
• Format: - [task-name] Brief description of what was accomplished
• Include key deliverables

Step 4: Squash Commits (Two-Commit Structure)

Squash task branch commits into TWO commits (or one if no config changes):

Step 4a: Identify file categories

# From task worktree
cd /workspace/tasks/$TASK_NAME/code

# List all changed files
git diff --name-only main...HEAD

# Categorize:
# CONFIG FILES: .claude/*, docs/project/*, CLAUDE.md
# IMPLEMENTATION FILES: Everything else (*.java, tests, changelog.md, todo.md)

Step 4b: Create config commit (if config files changed)

# If any .claude/, docs/project/, or CLAUDE.md files changed:
# 1. Create a separate commit with ONLY config files
# 2. Use git rebase -i to reorder/squash config changes into first commit

# Example: If you have mixed commits, use interactive rebase to:
# - Move all config file changes into first commit
# - Move all implementation changes into second commit

Step 4c: Create implementation commit

# Squash all implementation changes (source, tests, changelog, todo) into second commit
# Use git-squash skill for the implementation portion

# IMPORTANT: Ensure todo.md and changelog.md are in the implementation commit
git status  # Should show todo.md and changelog.md staged

Post-Squash Verification:

# Count commits (should be 1 or 2)
git rev-list --count main..$TASK_NAME
# Expected: 1 (no config changes) or 2 (has config changes)

# Verify commit structure
git log --oneline main..$TASK_NAME
# Expected format:
#   abc123 Implement feature X (implementation commit - LAST)
#   def456 Update config for feature X (config commit - FIRST, if applicable)

# Verify archival files are in IMPLEMENTATION commit (last commit)
git show --stat HEAD | grep "todo.md" || echo "❌ ERROR: todo.md not in commit"
git show --stat HEAD | grep "changelog.md" || echo "❌ ERROR: changelog.md not in commit"

# Verify config files are in CONFIG commit (if applicable)
if git rev-list --count main..$TASK_NAME | grep -q "2"; then
  git show --stat HEAD~1 | grep -E "\.claude|docs/project|CLAUDE\.md"
fi

Step 5: Verify Cleanup

# Verify only task branch remains (no agent branches)
git branch | grep $TASK_NAME
# Expected output: ONLY "{task-name}" (no -architect, -tester, -formatter suffixes)

Step 6: Verify Commit Structure

# Count commits ahead of main
COMMIT_COUNT=$(git rev-list --count main..$TASK_NAME)
echo "Commits: $COMMIT_COUNT"
# Expected output: 1 (no config) or 2 (with config)

# If 2 commits, verify structure:
if [ "$COMMIT_COUNT" -eq 2 ]; then
  echo "Config commit (first):"
  git show --stat HEAD~1 | head -10
  echo ""
  echo "Implementation commit (second):"
  git show --stat HEAD | head -15
fi

# MANDATORY: Verify archival files are in implementation commit (HEAD)
git show --stat HEAD | grep -E "todo.md|changelog.md"
# Expected: Both todo.md and changelog.md appear in HEAD commit

Complete Cleanup Script

#!/bin/bash
set -euo pipefail

TASK_NAME="${1:?Task name required}"
TASK_DIR="/workspace/tasks/$TASK_NAME"

echo "=== Pre-Presentation Cleanup for $TASK_NAME ==="

# Step 1: Remove agent worktrees
echo "Step 1: Removing agent worktrees..."
for agent in architect tester formatter; do
  WORKTREE="$TASK_DIR/agents/$agent/code"
  if [ -d "$WORKTREE" ]; then
    git worktree remove "$WORKTREE" --force 2>/dev/null && echo "  Removed $agent worktree" || true
  fi
done

# Step 2: Delete agent branches
echo "Step 2: Deleting agent branches..."
for agent in architect tester formatter; do
  BRANCH="${TASK_NAME}-${agent}"
  if git branch --list "$BRANCH" | grep -q .; then
    git branch -D "$BRANCH" && echo "  Deleted $BRANCH" || true
  fi
done

# Step 3: Squash commits (two-commit structure)
echo "Step 3: Organizing commits (config first, implementation second)..."
echo "  → Check for config files: .claude/*, docs/project/*, CLAUDE.md"
echo "  → Squash config changes into first commit (if any)"
echo "  → Squash implementation changes into second commit"

# Step 4: Verify cleanup
echo "Step 4: Verifying cleanup..."
REMAINING=$(git branch | grep "$TASK_NAME" | grep -v "^  $TASK_NAME$" || true)
if [ -n "$REMAINING" ]; then
  echo "  ❌ ERROR: Found remaining agent branches:"
  echo "$REMAINING"
  exit 1
else
  echo "  ✅ Only task branch remains"
fi

# Step 5: Verify commit structure
echo "Step 5: Verifying commit structure..."
COMMIT_COUNT=$(git rev-list --count main..$TASK_NAME)
if [ "$COMMIT_COUNT" -eq 1 ]; then
  echo "  ✅ Single commit (no config changes)"
elif [ "$COMMIT_COUNT" -eq 2 ]; then
  echo "  ✅ Two commits (config + implementation)"
else
  echo "  ❌ ERROR: Found $COMMIT_COUNT commits (expected 1 or 2)"
  echo "  Squash into: 1. config commit, 2. implementation commit"
  exit 1
fi

echo ""
echo "=== Cleanup Complete ==="
echo "Ready to present changes for user approval"

Common Mistakes

Mistake: Presenting Unsquashed Commits

❌ WRONG:
User, here are the changes:
  commit abc123 - Architect implementation
  commit def456 - Tester additions
  commit ghi789 - Formatter fixes
  commit jkl012 - Merge agent work

✅ CORRECT (with config changes):
[Complete all cleanup steps first]
User, here are the changes:
  commit def456 - Update hook for X handling (config)
  commit xyz789 - Implement feature X with tests (implementation)

✅ CORRECT (no config changes):
[Complete all cleanup steps first]
User, here is the change:
  commit xyz789 - Implement feature X with tests and formatting

Mistake: Mixing Config and Implementation in Same Commit

❌ WRONG: Single commit with mixed files
$ git show --stat HEAD
  .claude/hooks/my-hook.sh   | 10 ++++
  Parser.java                | 50 +++++++
  Test.java                  | 30 +++++

✅ CORRECT: Separate commits
$ git log --oneline main..HEAD
  xyz789 Implement parser feature
  def456 Add validation hook

$ git show --stat HEAD~1  # Config commit
  .claude/hooks/my-hook.sh   | 10 ++++

$ git show --stat HEAD      # Implementation commit
  Parser.java                | 50 +++++++
  Test.java                  | 30 +++++

Mistake: Subagent Branches Still Visible

# ❌ WRONG: Agent branches still exist
$ git branch | grep my-task
  my-task
  my-task-architect
  my-task-formatter
  my-task-tester

# ✅ CORRECT: Only task branch remains
$ git branch | grep my-task
  my-task

Mistake: Missing Archival Files in Commit

# ❌ WRONG: Presenting without archival
$ git show --stat
  Parser.java   | 10 ++++
  Test.java     | 50 +++++++++++
  2 files changed, 60 insertions(+)
# Missing: todo.md and changelog.md!

# ✅ CORRECT: Commit includes archival files
$ git show --stat
  Parser.java   | 10 ++++
  Test.java     | 50 +++++++++++
  todo.md       |  2 +-
  changelog.md  |  3 +++
  4 files changed, 63 insertions(+), 1 deletion(-)

Why This Matters: The merge commit MUST be atomic - including both implementation AND archival. Presenting without archival requires rework after user approval.

Workflow Integration

[VALIDATION state: All tests pass]
        ↓
[Transition to AWAITING_USER_APPROVAL]
        ↓
[Invoke pre-presentation-cleanup skill] ← THIS SKILL
        ↓
Step 1: Remove agent worktrees
Step 2: Delete agent branches
Step 3: Update archival files (todo.md + changelog.md) ← CRITICAL
Step 4: Squash into two commits:
        4a. Config commit (if .claude/docs changes exist)
        4b. Implementation commit (source, tests, archival)
Step 5: Verify only task branch
Step 6: Verify commit structure (1 or 2 commits)
        ↓
[Present clean commits to user]
        ↓
[Wait for user approval]

Related Skills

• git-squash: Used in Step 4 to squash commits
• archive-task: Alternative skill for archival (updates todo.md + changelog.md atomically)
• task-cleanup: Used AFTER merge to main (removes task branch and worktree)
• state-transition: Manages state machine transitions

Verification Checklist

Before presenting to user, confirm:

• All agent worktrees removed
• All agent branches deleted
• todo.md updated (task entry DELETED, not marked with [x])
• changelog.md updated (task completion entry added)
• Config files (if any) squashed into FIRST commit
• Implementation files squashed into LAST commit (including archival)
• git branch | grep {task} shows ONLY task branch
• git rev-list --count main..{task} returns 1 or 2
• git show --stat HEAD shows todo.md AND changelog.md in implementation commit
• If 2 commits: git show --stat HEAD~1 shows ONLY config files (.claude/, docs/project/, CLAUDE.md)