cleanup

Audit and retire stale git branches, worktrees, jj workspaces, and centralized work state.

4|1|Updated Jul 31, 2025
One-click install
npx skills add https://github.com/alvis/.agents --skill cleanup-alvis
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: cleanup
Source: https://github.com/alvis/.agents/tree/main/plugins/coding/skills/cleanup
Command: npx skills add https://github.com/alvis/.agents --skill cleanup-alvis

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Long-running development accumulates stale branches, abandoned worktrees, divergent jj workspaces, and orphaned state directories that clutter repositories and obscure what work is actually live. This Skill performs an evidence-first audit and safely retires only verified, approved targets. ## Core Features & Use Cases - Full inventory without deletion: Enumerates git branches, remotes, registered worktrees, jj workspaces, PRs, and centralized .state/works/ directories before recommending anything. - Lifecycle classification: Classifies each work stream as active, interrupted, completed, or ambiguous based on direct reads of state.md, reviews, and promotion receipts. - Gated retirement: Archives completed work only after all retirement gates pass, a three-day landing window elapses, per-target approval is granted, and a verified recoverable backup exists. - Use Case: Run /cleanup after a release cycle to identify merged branches and completed work streams, review the evidence-backed recommendations, and approve archival of each target individually. ## Quick Start Ask the assistant to run /cleanup on the current repository to audit stale branches, worktrees, and work state with evidence-backed recommendations.

Frequently Asked Questions about cleanup

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I clean up stale git branches and worktrees safely?

Run the cleanup audit to inventory branches, worktrees, and jj workspaces with merged status, unpushed commits, and dirty-state checks. It recommends removal only for merged or content-equivalent targets and requires explicit per-target approval plus a verified backup before deleting anything.

How to archive completed work state without losing history?

Completed work directories under the resolved state root are moved to a permanent `.state/archive/` location rather than deleted, after all retirement gates pass. A timestamped backup with restoration metadata is created first, and the archive prevents retired work IDs from being reused.

Does the cleanup audit work without network or GitHub access?

Yes, missing gh CLI, network, or credentials does not abort the local inventory. Remote evidence is marked partial or stale, affected recommendations are downgraded, and the --exclude-remote flag skips remote fetches and PR checks entirely.

When will cleanup refuse to archive a completed work stream?

Archival is refused when required tasks are unfinished, reviews have outstanding findings, promotion receipts are missing, a named blocker or open question remains, or fewer than three days have passed since landing evidence. Ambiguous or contradictory state is always preserved.

What are the limitations of automated repository cleanup?

The audit never scans unregistered directories, never infers approval from the /cleanup invocation, and never performs history rewriting or dead-code removal. Age alone or a merged branch never authorizes state archival; every destructive action needs separate explicit approval.