Session Cleanup
npx machina-cli add skill smith-horn/product-builder-starter/session-cleanup --openclawSession Cleanup
Structured end-of-session housekeeping: doc review, branch audit, worktree removal, and remote sync.
Behavioral Classification
Type: Guided Decision
Directive: ASK, THEN EXECUTE
Audits each category and presents findings before taking any destructive action. Deletions always follow an explicit audit phase.
Execution Context Requirements
This skill spawns a general-purpose subagent that performs git operations and file edits.
Foreground execution required: Yes
Required tools: Read, Write, Edit, Bash, Grep, Glob
Fallback: If tools are denied, the subagent returns a checklist of recommended actions for the coordinator to apply manually.
Usage
Invoke at the end of a working session:
/session-cleanup
Or trigger via phrases: "end of session", "clean up branches", "clean up worktrees", "session cleanup"
Out of scope: PR creation/merge (/ship), production deploys, Linear issue updates (/linear), resolving merge conflicts.
Five Phases
- Doc Review — CLAUDE.md staleness, MEMORY.md updates, submodule dirty state
- Branch Audit — PR status check, unpushed commit detection, squash-merge artifact filtering
- Branch Cleanup — Push unreleased content, cherry-pick docs to main, delete merged branches
- Worktree Cleanup — Remove stale worktrees via project script or
git worktree remove - Final State — Sync main, confirm clean working tree, report summary
Pre-Dispatch Check (REQUIRED — run before spawning agent)
Before launching the cleanup agent, run these two commands via Bash:
git status --porcelain
git branch --list | grep -v "^\* main$"
If both return empty (working tree clean AND only main branch exists locally), cleanup has almost certainly already run this session. Do NOT spawn the agent. Instead, tell the user:
"The repo looks clean already — only
main, nothing uncommitted. Cleanup appears to have already run this session. Run it again anyway?"
Only proceed to Dispatch if the user confirms, or if either check returns output (there is real work to do).
Dispatch
Use the Task tool with subagent_type="general-purpose" and pass the full contents
of ./agent-prompt.md as the prompt.
Changelog
v1.2.0 (2026-02)
- New: Pre-dispatch check — skip agent spawn when repo is already clean
- New: Two-dot diff gate for unreleased content detection
- New:
--no-verifyconsent rule — never bypass hooks without explicit user approval - New: Abort-gracefully rule — clean state report when user cancels mid-run
v1.1.0 (2026-01)
- New: Thin dispatcher pattern — full workflow extracted to
agent-prompt.md - New: Cherry-pick to main for docs-only commits on merged branches
- New: Worktree cleanup phase using project
remove-worktree.shscript - New: Squash-merge artifact filtering in branch audit
v1.0.0 (2025-12)
- Initial release
- Five-phase workflow: Doc Review, Branch Audit, Branch Cleanup, Worktree Cleanup, Final State
- Guided decision pattern — audit first, delete only with user approval
- Remote sync and main branch verification
Source
git clone https://github.com/smith-horn/product-builder-starter/blob/main/skills/session-cleanup/SKILL.mdView on GitHub Overview
Session Cleanup performs a structured end-of-session audit of git repos, covering docs, branches, worktrees, and remote state. It guides you through auditing findings before any deletions, then cleans up and syncs to a clean final state.
How This Skill Works
Technically, it uses a guided decision workflow that audits Doc Review, Branch Audit, Branch Cleanup, Worktree Cleanup, and Final State, surfacing findings before any destructive actions. Deletions occur only after explicit user approval. If the repository is already clean (per pre-dispatch checks), the agent is not spawned; otherwise, it dispatches a general-purpose subagent with the contents of ./agent-prompt.md via the Task tool.
When to Use It
- You’ve just finished a coding session and want to tidy local branches and worktrees before leaving.
- Before handing off the repo or triggering CI, audit and prune merged branches and remote references.
- Git status shows uncommitted changes or unpushed commits that you want to resolve in one go.
- You want to remove stale worktrees and squash-merge artifacts to simplify the working directory.
- You need a final, auditable state report confirming a clean main branch and synchronized remote.
Quick Start
- Step 1: Run the command /session-cleanup at the end of your session.
- Step 2: Review the audit findings and confirm any deletions to proceed.
- Step 3: Review the final state report and confirm the repo is clean and in sync.
Best Practices
- Always run the Doc Review and Branch Audit before any deletions.
- Only delete after an explicit audit and user confirmation.
- Use the pre-dispatch checks to determine if there’s any work to do; skip spawning if clean.
- Keep the main branch up-to-date and verify a clean working tree after cleanup.
- Provide a concise summary report of changes for accountability.
Example Use Cases
- Finish a feature, run /session-cleanup to prune local branches and remove merged branches.
- Clean up remote branches after PRs are merged to keep the remote repo tidy.
- Detect unpushed commits; run the audit and decide on push, rebase, or discard actions.
- Remove stale worktrees using the project script or git worktree remove.
- Generate and review a final state report showing main in sync with remote and a clean working tree.
