clean

Files (2)

• SKILL.md
• check-dirty-beads.sh · scripts/

SKILL.md (first lines)

# /clean — repo hygiene sweep

A five-phase end-of-work sweep. Each phase is a checkpoint: run it, report, move on.
`/clean` is the wrapper — the heavy lifting is delegated to focused skills.

## Before you start

- Identify the repo's integration branch (`dev` / `main`) from the contributor docs
  (CLAUDE.md, AGENTS.md).
- **Shared-checkout check.** Are other Claude sessions sharing this working tree? This
  changes Phase 1's path.

  ```bash
  pgrep -fa claude | awk '{print $1}' | sort -u | while read pid; do
    lsof -p "$pid" 2>/dev/null | awk '/cwd/{print $NF}' | grep -qx "$(pwd)" \
      && echo "sister Claude shares this checkout: PID $pid"
  done
  ```

  If sisters are present, never move a shared branch pointer and never run
  `checkout` / `reset` / `rebase` in the canonical checkout — do branch-mutating
  work in a `git worktree`.

- Register with Agent Mail if the repo uses it — mutating ops follow.

## Phase 0 — Bead state, in every repo this session touched

A `br close` reaches origin only if the resulting `.beads/issues.jsonl` change is both
committed and pushed. Two ways it silently is not (bd-1x5s, 3+ occurrences): it is never
committed — sitting in `git status` beside foreign modified files while closeout attention
goes to a different repo — or it is committed onto a local integration branch that has
diverged from its upstream and never leaves the machine.

```bash
bash ~/.claude/skills/clean/scripts/check-dirty-beads.sh <repo> [<repo> ...]
```

Pass every repo the session touched, not only the current one — the 2026-08-05 loss was in
the second repo. Non-zero exit names the repo and the reason. **Never `br close` and commit
onto a stale local `dev`** — close in a fresh worktree off the integration branch instead:

```bash
git worktree add .ntm/worktrees/close-beads -b chore/close-beads origin/dev
cd .ntm/worktrees/close-beads && br close <ids> && br sync --flush-only
git diff -- .beads/            # ONLY the intended beads
git add .beads/ && git commit -m 'chore(beads): close <ids>'
git push -u origin HEAD && gh pr create --base dev   # then merge
```

## Phase 1 — Land genuine unpushed work

The path depends on the shared-checkout check above.

### Single-agent repo (no sisters)

A dirty working tree IS unlanded work; an "ahead" branch IS your unpushed commits.
Stage, commit, and `git push`. Skip the classifier below — it is just friction here.

### Multi-agent shared checkout (sisters present)

Do **not** assume a dirty working tree or an "ahead" branch is unlanded work. A sister
may have already committed your "modification" and pushed it; your "ahead" commits may
be content-equivalent duplicates of commits already on `origin`. Classify first:

1. **Working-tree changes.** For each modified file, compare its blob to the integration
   branch on the remote:

   ```bash
   git fetch origin <branch> --quiet
   git hash-object <file>                  # working-tree blob
   git rev-parse origin/<branch>:<file>    # remote blob
   ```

   A file whose blob equals `origin/<branch>`'s is already shipped — a sister committed
   it. It is stale residue, not new work. Do not re-commit it.

2. **"Ahead" commits.** For each commit in `origin/<branch>..<branch>`, classify:
   - **Duplicate** — same `git patch-id` as a commit already on `origin`. Drop it.
   - **Already-shipped** — `git cherry origin/<branch> <commit>` prints a `-` prefix,
     meaning its patch-id matches one on the upstream. Drop it.
   - **Genuinely unpushed** — real work not on `origin`. Land it.

3. **Land genuine commits without disturbing a shared branch.** Create an isolated
   worktree at the remote tip, cherry-pick the genuine commits oldest-first, and
   fast-forward push. Never force-push a shared branch; never move the local branch
   pointer that sister sessions share:

   ```bash
   git worktree add --detach <tmp-worktree> origin/<branch>
   git -C <tmp-worktree> cherry-pick <genuine-commit> ...
   git -C <tmp-worktree> push origin HEAD:<branch>
   git worktree remove <tmp-worktree>
   ```

   Resolve `.beads/issues.jsonl` conflicts as positional only — keep both sides' beads,
   never drop a bead another commit added.

If there is genuinely nothing to land, say so and move on — do not manufacture a commit.

## Phase 2 — Squash open PRs

Invoke the **`squash-pr`** skill. It lists open PRs, presents them for triage, and
squash-merges the approved ones through GitHub's merge path. No open PRs → no-op; report
and continue.

## Phase 3 — Prune branches and worktrees

Two passes — remote first, then local. They use different tools because their skills do.

### Remote branches

Invoke the **`prune-branches`** skill. It cross-references GitHub PR state to find
merged and squash-merged branches on `origin`, categorizes the rest, and proposes an
explicit delete command for approval. `prune-branches` is remote-only — it does not
touch local refs.

### Local branches and worktrees

`prune-branches` does not handle these; inline the logic here. Enumerate candidates:

From thunter009/skills, MIT.

More from thunter009/skills