@acme-skunkworks/agent-skills 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rob Easthope
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,52 @@
+# agent-skills
+
+Shared agent skills for Claude Code and Cursor, distributed as [skills.sh](https://skills.sh)-compatible bundles. Each skill lives under `skills/<name>/` with a `SKILL.md` manifest at its root.
+
+## Installing a skill
+
+From any consumer repo:
+
+```bash
+npx skills add https://github.com/acme-skunkworks/agent-skills --skill <name> --agent claude-code --agent cursor --copy
+```
+
+`--copy` writes real files (not symlinks) so the skill is portable across machines. Don't use `-g` / `--global` — installs should live in the consumer repo.
+
+## Repo layout
+
+```
+.
+├── .changeset/              # pending changesets + config
+├── .claude/commands/
+│   └── send-it.md           # all-in-one finisher (stopgap until the send-it skill ships)
+├── .github/
+│   ├── actions/
+│   │   └── load-repo-config/ # infrastructure/repo-config.yaml → step outputs
+│   └── workflows/
+│       ├── release.yml       # publish-only: build → npm (OIDC) → GitHub Packages (dormant)
+│       └── validate.yml      # PR gate: build & lint, changelog validation, infra tests
+├── .husky/                  # git hooks (block main pushes; lint-staged; strip Claude trailer)
+├── architecture/            # ADRs (sequentially numbered, immutable)
+├── changelog/               # dated per-change release-note entries (companion to CHANGELOG.md)
+├── infrastructure/
+│   ├── repo-config.yaml      # non-secret CI/release knobs
+│   ├── scripts/              # changelog .ts helpers + ensure-*.sh tool bootstraps
+│   ├── send-it/              # deterministic helpers for /send-it
+│   └── tests/                # bats (publish scripts) + vitest (changelog)
+├── scripts/                 # publish wrappers (npm OIDC + GitHub Packages)
+├── skills/                  # one folder per skill
+├── CLAUDE.md
+├── LICENSE
+├── README.md
+└── package.json
+```
+
+The `skills/<name>/` convention may be refined by ADR-0001 (tracked in [ASW-133](https://linear.app/goose-and-hobbes/issue/ASW-133)) once skills.sh's expected layout is double-checked.
+
+## Architecture decisions
+
+ADRs land under `architecture/` as `NNNN-<slug>.md`. ADR-0001 — the foundational decision record for skill layout, distribution conventions, and semver discipline — is forthcoming.
+
+## Contributing
+
+See [CLAUDE.md](./CLAUDE.md) for the conventions (Conventional Commits, draft PRs, Changesets per behavioural change).

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@acme-skunkworks/agent-skills",
+  "version": "1.0.0",
+  "private": false,
+  "description": "Shared agent skills (Claude Code, Cursor) distributed as skills.sh-compatible bundles.",
+  "keywords": [
+    "agent-skills",
+    "claude-code",
+    "cursor",
+    "skills",
+    "skills.sh"
+  ],
+  "homepage": "https://github.com/acme-skunkworks/agent-skills#readme",
+  "bugs": {
+    "url": "https://github.com/acme-skunkworks/agent-skills/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/acme-skunkworks/agent-skills.git"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Rob Easthope",
+    "url": "https://github.com/RobEasthope"
+  },
+  "files": [
+    "skills/"
+  ],
+  "scripts": {
+    "changelog:finalise": "tsx infrastructure/scripts/finalise-changelog.ts",
+    "changeset": "changeset",
+    "changeset:version": "changeset version && pnpm changelog:finalise",
+    "lint:sh": "bash -c 'if command -v shellcheck >/dev/null 2>&1; then shellcheck scripts/*.sh infrastructure/scripts/*.sh .husky/pre-commit .husky/pre-push .husky/commit-msg; elif [ \"$(uname -s)\" = \"Darwin\" ]; then echo \"⚠️  shellcheck not installed — skipping. Install: brew install shellcheck\"; else echo \"⚠️  shellcheck not installed — skipping. Install: apt-get install shellcheck\"; fi'",
+    "lint:workflows": "actionlint",
+    "lint:yaml": "yamllint .",
+    "prepare": "husky",
+    "release": "changeset publish",
+    "release:manual": "npm publish --access public --provenance=false",
+    "release:manual:dry": "npm publish --access public --provenance=false --dry-run",
+    "test": "vitest run",
+    "test:sh": "bash -c 'if command -v bats >/dev/null 2>&1; then bats infrastructure/tests/*.bats; elif [ \"$(uname -s)\" = \"Darwin\" ]; then echo \"⚠️  bats not installed — skipping. Install: brew install bats-core\"; else echo \"⚠️  bats not installed — skipping. Install: apt-get install bats\"; fi'",
+    "test:watch": "vitest",
+    "validate:changelog": "tsx infrastructure/scripts/validate-changelog.ts",
+    "version": "changeset version"
+  },
+  "lint-staged": {
+    "**/*.sh": [
+      "bash -c 'if command -v shellcheck >/dev/null 2>&1; then shellcheck \"$@\"; elif [ \"$(uname -s)\" = \"Darwin\" ]; then echo \"⚠️  shellcheck not installed — skipping. Install: brew install shellcheck\"; else echo \"⚠️  shellcheck not installed — skipping. Install: apt-get install shellcheck\"; fi' --"
+    ],
+    "**/*.{yml,yaml}": [
+      "bash -c 'if command -v yamllint >/dev/null 2>&1; then yamllint \"$@\"; elif [ \"$(uname -s)\" = \"Darwin\" ]; then echo \"⚠️  yamllint not installed — skipping. Install: brew install yamllint\"; else echo \"⚠️  yamllint not installed — skipping. Install: pip install --user yamllint==1.37.1\"; fi' --"
+    ],
+    ".github/workflows/*.{yml,yaml}": [
+      "bash -c 'if command -v actionlint >/dev/null 2>&1; then actionlint \"$@\"; elif [ \"$(uname -s)\" = \"Darwin\" ]; then echo \"⚠️  actionlint not installed — skipping. Install: brew install actionlint\"; else echo \"⚠️  actionlint not installed — skipping. Install via the pinned bootstrap in infrastructure/scripts/ensure-actionlint.sh\"; fi' --"
+    ],
+    "changelog/*.md": [
+      "bash -c 'pnpm validate:changelog' --"
+    ]
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.31.0",
+    "@types/node": "^25.6.0",
+    "gray-matter": "^4.0.3",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.3.2",
+    "tsx": "^4.21.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.6"
+  },
+  "packageManager": "pnpm@10.33.0",
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "registry": "https://registry.npmjs.org"
+  }
+}

package/skills/README.md

@@ -0,0 +1,11 @@
+# Skills
+
+Each skill lives in `skills/<name>/` as a [skills.sh](https://skills.sh)-compatible bundle with a `SKILL.md` manifest at its root.
+
+Consumers install a skill from this repo with:
+
+```bash
+npx skills add https://github.com/acme-skunkworks/agent-skills --skill <name> --agent claude-code --agent cursor --copy
+```
+
+No skills here yet — the first one (`cleanup-repo`) is tracked under [ASW-134](https://linear.app/goose-and-hobbes/issue/ASW-134). The exact bundle layout may be refined by ADR-0001 (ASW-133) once skills.sh's expected structure is double-checked.

package/skills/cleanup-repo/README.md

@@ -0,0 +1,73 @@
+# cleanup-repo
+
+Clean up a Git repository's merged branches and worktrees, then prune filesystem
+cruft (recursively-empty directories and orphaned `node_modules/`) — behind a
+single confirmation gate, with a `--dry-run` preview.
+
+## Install
+
+From any consumer repo:
+
+```bash
+npx skills add https://github.com/acme-skunkworks/agent-skills --skill cleanup-repo --agent claude-code --agent cursor --copy
+```
+
+`--copy` writes real files so the bundle is portable. Don't use `-g` / `--global`
+— the install should live in the consumer repo.
+
+## Configure
+
+The shipped [`config.json`](config.json) carries **ACME Skunkworks defaults**
+(`linearTeamName` and `issueKeys`) — update them for your organisation on install,
+or the Linear lookups will target the wrong team and branch issue-IDs won't match.
+A neutral [`config.example.json`](config.example.json) ships alongside it as a
+template — copy it over `config.json` and fill in your values, or edit
+`config.json` directly.
+
+| Key | Meaning | Default |
+| --- | --- | --- |
+| `linearTeamName` | Linear team **name** used to resolve the live `Done` state. Stable across team-key renames. | `"ACME Skunkworks"` |
+| `issueKeys` | Team-key prefixes that may appear in branch names; the issue-ID regex is built from these. Keep legacy keys so old branches still match. | `["ASW", "AKW", "SKW"]` |
+| `protectedBranches` | Branches never deleted, locally or remotely. | `["main"]` |
+
+> **Base branch.** v1 assumes the trunk is `origin/main` — merge detection
+> (`git branch --merged origin/main`) is hard-coded to it. Repositories on
+> `master` / `develop` aren't supported yet; a `mainBranch` config key is noted
+> in [`references/design-notes.md`](references/design-notes.md) as a future
+> extension.
+
+## Requirements
+
+- `git` and `gh` CLIs (`gh` authenticated for the squash-merge detection pass).
+- Node.js ≥22 (per the package's `engines`), for the bundled filesystem-hygiene script.
+- The Linear MCP server is **optional**: the issue-status check and the `Done`
+  writeback are skipped silently when it is unavailable.
+
+## What it does
+
+Two passes, one confirmation:
+
+1. **Branch/worktree pass** — fetches and prunes, removes merged worktrees
+   (guarding ones with uncommitted changes), deletes merged local and remote
+   branches using two-pass detection (`git branch --merged origin/main` plus
+   `gh pr list … --state merged` for squash-merges), optionally writes linked
+   Linear issues back to `Done` (default no).
+2. **Filesystem-hygiene pass** — removes top-most recursively-empty directories
+   (placeholder-only `.gitkeep` / `.gitignore` directories are left alone; `.git/`
+   is hard-protected) and orphaned `node_modules/` directories (those whose parent
+   has no `package.json`). The two filesystem groups are surfaced separately.
+
+## Behaviour parity
+
+The **branch/worktree pass** is a faithful port of the `/cleanup-branches` slash
+command (canonical reference: Octavo's `.claude/commands/cleanup-branches.md`):
+the same two-pass merge detection, the same uncommitted-changes worktree guard,
+the same protected-branch handling, and the same opt-in, default-no Linear `Done`
+transition.
+
+The **filesystem-hygiene pass is new** to this skill — it has no equivalent in
+`/cleanup-branches`. A single bundled script computes the removal set once, so the
+`--dry-run` preview lists exactly what a real run removes.
+
+See [`references/design-notes.md`](references/design-notes.md) for the `cleanup-repo`
+naming rationale and the future extensions the name deliberately leaves room for.

package/skills/cleanup-repo/SKILL.md

@@ -0,0 +1,289 @@
+---
+name: cleanup-repo
+description: >-
+  Clean up a Git repository's merged branches and worktrees, then prune
+  filesystem cruft (recursively-empty directories and orphaned node_modules).
+  Use when asked to clean up / tidy / prune merged branches, remove stale or
+  finished worktrees, delete branches whose PRs have already merged (including
+  squash-merges), or sweep empty directories and leftover node_modules. Two-pass
+  merge detection (git ancestry plus merged GitHub PRs), an uncommitted-changes
+  guard on worktrees, an optional Linear "Done" writeback, a single confirmation
+  gate, and a --dry-run preview. Protected branches are never touched.
+license: MIT
+compatibility: >-
+  Requires the `git` and `gh` CLIs. The optional Linear status check needs the
+  Linear MCP server; if it is unavailable, skip that step silently. The
+  filesystem pass needs Node.js ≥22.
+metadata:
+  version: 0.1.0
+allowed-tools: Bash(git:*), Bash(gh:*), Bash(node:*), mcp__linear-server__get_issue, mcp__linear-server__save_issue, mcp__linear-server__list_issue_statuses
+---
+
+# cleanup-repo
+
+Remove merged Git worktrees and branches, then run a filesystem-hygiene pass —
+all behind a single confirmation gate, with a `--dry-run` preview.
+
+The branch/worktree pass mirrors the behaviour of the `/cleanup-branches`
+slash command it was extracted from. The filesystem-hygiene pass (recursively-empty
+directories and orphan `node_modules/`) is new to this skill. See
+[`references/design-notes.md`](references/design-notes.md) for the naming
+rationale and the deliberately-deferred future extensions.
+
+## Configuration
+
+Three knobs live in [`config.json`](config.json) beside this file. Read it at the
+start of a run and use its values throughout. Edit your copied `config.json` to
+match the consuming repo:
+
+| Key | Meaning | Default |
+| --- | --- | --- |
+| `linearTeamName` | Linear team **name** used to resolve the live `Done` state. Use the name, not the key — the key is renamed over time but the name is stable. | `"ACME Skunkworks"` |
+| `issueKeys` | Team-key prefixes that may appear in branch names. The issue-ID regex is built from these. Keep legacy keys so old branches still match. | `["ASW", "AKW", "SKW"]` |
+| `protectedBranches` | Branches that are **never** deleted, locally or remotely. | `["main"]` |
+
+Build the issue-ID regex by joining `issueKeys` with `|`:
+`\b((?:ASW|AKW|SKW)-\d+)\b` for the defaults above. Match it against the
+**upper-cased** branch name (branches like `asw-7-as-acquired` carry the key in
+lower case).
+
+If the Linear MCP server is not available, skip the Linear status check and the
+optional `Done` writeback silently — they are not required for branch cleanup.
+
+## Usage modes
+
+**Dry run** — preview everything, change nothing:
+
+```bash
+cleanup-repo --dry-run
+```
+
+**Normal** — preview, then delete after a single confirmation:
+
+```bash
+cleanup-repo
+```
+
+There is one bulk confirmation gate (Step 8) covering both the branch/worktree
+pass and the filesystem pass. `--dry-run` short-circuits before that gate.
+
+## Process
+
+### Step 1 — Fetch latest from remote
+
+```bash
+git fetch --prune origin
+```
+
+### Step 2 — Identify worktrees to remove
+
+```bash
+git worktree list
+```
+
+- List all worktrees except the main repository directory (the primary working
+  directory is never removed).
+- Identify worktrees whose branch is fully merged into `main`.
+- Identify worktrees in detached-HEAD state — treat as abandoned, safe to remove.
+- Identify worktrees with uncommitted changes: `git -C <path> status --porcelain`
+  non-empty. These are surfaced separately in Step 6 and **never removed
+  automatically** — the user handles them manually (`git worktree remove --force
+  <path>` once they have moved or discarded the work).
+- Worktree location is irrelevant to detection; `git worktree list` enumerates
+  them wherever they live (e.g. a gitignored `.claude/worktrees/<branch>/`).
+
+### Step 3 — Identify merged branches (two-pass)
+
+**Pass 1 — Git-merged branches:**
+
+- Find local branches merged into `main`: `git branch --merged origin/main`.
+- Exclude every branch in `protectedBranches`.
+- Determine which of those branches also still exist on the remote.
+
+**Pass 2 — Squash-merged branches:**
+
+A squash merge lands a single new commit on `main`, so the branch's own commits
+are never ancestors of `main` and `git branch --merged` misses it. For each local
+branch **not** caught in Pass 1 (and not protected):
+
+```bash
+gh pr list --head <branch-name> --state merged --json number,title --limit 1
+```
+
+`gh` auto-detects the repository from the current directory's remote, so no
+`--repo` flag is needed.
+
+- A non-empty result means the branch has a merged PR — treat it as merged and
+  add it to the cleanup list.
+- An empty result means the branch is genuinely unmerged — leave it alone.
+- Record the PR number and title for the summary so the user can verify.
+
+### Step 4 — Check Linear issue status for merged branches
+
+For each merged branch whose name contains an issue ID (extract with the regex
+built from `issueKeys`, matched against the upper-cased branch name):
+
+- Fetch the issue via `mcp__linear-server__get_issue`.
+- Track any issue that is **not** in `Done` status.
+
+Skip this step silently if the Linear MCP server is unavailable.
+
+### Step 5 — Run the filesystem-hygiene detection
+
+Run the bundled script against the repository root to get the candidate list.
+It is read-only without `--apply`:
+
+```bash
+node scripts/filesystem-hygiene.mjs <repo-root> --json
+```
+
+It prints `{ "emptyDirs": [...], "orphanNodeModules": [...] }`:
+
+- **`emptyDirs`** — top-most recursively-empty directories (no files anywhere in
+  the subtree). Directories holding any file — including a `.gitkeep` /
+  `.gitignore` placeholder — are left alone. `.git/` is never traversed.
+- **`orphanNodeModules`** — `node_modules/` directories whose immediate parent has
+  no `package.json` (strict; no workspace inference). Removing one re-installs is
+  needed if the parent was not actually meant to be gone — which is why these are
+  surfaced **separately**.
+
+This detection is read-only and feeds the Step 6 preview. One subtlety: Step 9
+removes worktrees **before** re-running the detection with `--apply`, so the apply
+pass can additionally sweep a parent that becomes empty only once its worktrees are
+gone (e.g. `.claude/worktrees/`). Such a directory won't appear in this pre-removal
+detect output — predict it from the worktree-removal list and label it as a
+post-removal sweep in the preview, so the user isn't surprised when `--apply`
+removes it.
+
+### Step 6 — Display everything to be deleted
+
+Show clear, counted lists. Keep the filesystem groups separate so the user can
+eyeball them:
+
+```text
+## Worktrees to Remove (3)
+- /path/.claude/worktrees/ASW-7-as-acquired (merged)
+- /path/.claude/worktrees/ASW-9-button-styling (squash-merged, PR #42)
+- /path/.claude/worktrees/orphan-detached (detached HEAD)
+
+## Worktrees Skipped — Uncommitted Changes (1)
+- /path/.claude/worktrees/ASW-12-wip (merged, but `git status` is non-empty;
+  remove manually with `git worktree remove --force <path>`)
+
+## Local Branches to Delete (3)
+- ASW-7-as-acquired (merged)
+- ASW-9-button-styling (squash-merged, PR #42 "Fix button styling")
+- chore-update-deps (merged)
+
+## Remote Branches to Delete (2)
+- ASW-7-as-acquired
+- ASW-9-button-styling
+
+## Linear Issues Still Open (1)
+- ASW-9 "Button styling" — currently In Review (branch: ASW-9-button-styling)
+
+## Empty Directories to Remove (1)
+- /path/.claude/worktrees   (predicted: empty once the worktrees above are removed)
+
+## Orphan node_modules to Remove (1)
+- /path/old-package/node_modules   (no sibling package.json)
+```
+
+### Step 7 — Dry-run handling
+
+If `--dry-run` is set, STOP here. Print `DRY RUN MODE - No changes were made` and
+exit without changing anything.
+
+### Step 8 — Confirmation (normal mode only)
+
+Ask once: `Do you want to delete these worktrees, branches, and files? (yes/no)`.
+Proceed only if the user answers `yes`; otherwise exit without deleting.
+
+### Step 9 — Execute, in order
+
+Order matters. Worktrees must go before their branches, and the filesystem pass
+runs **after** worktree removal so a just-emptied worktree parent (e.g.
+`.claude/worktrees/`) is swept in the same run.
+
+1. **Remove worktrees** (skip the uncommitted-changes group from Step 6):
+
+   ```bash
+   git worktree remove <path>
+   ```
+
+2. **Prune stale worktree references:**
+
+   ```bash
+   git worktree prune
+   ```
+
+3. **Delete local branches:**
+
+   ```bash
+   git branch -d <branch-name>   # Pass 1 (git-merged) — safe delete
+   git branch -D <branch-name>   # Pass 2 (squash-merged) — force is safe: a
+                                 # merged PR was confirmed via the GitHub API
+   ```
+
+4. **Delete remote branches** that still exist:
+
+   ```bash
+   git push origin --delete <branch-name>
+   ```
+
+5. **Filesystem-hygiene removal** — re-run the bundled script with `--apply`. It
+   removes exactly the same set it detects and prints what it removed:
+
+   ```bash
+   node scripts/filesystem-hygiene.mjs <repo-root> --apply
+   ```
+
+   Removing an orphan `node_modules/` can leave its parent empty; that parent is
+   intentionally left for a follow-up run rather than swept in this snapshot.
+
+### Step 10 — Optional Linear `Done` writeback
+
+If any Linear issues from Step 4 are not `Done`:
+
+- Ask: `These Linear issues are linked to merged branches but aren't Done. Set
+  them to Done? (yes/no)`. **Default no** — Linear's GitHub integration normally
+  handles this on PR merge, so this exists only for the rare case where it didn't
+  fire (e.g. the issue ID was added after the merge).
+- If yes:
+  - Resolve the live `Done` state ID **once** via
+    `mcp__linear-server__list_issue_statuses` with `team: <linearTeamName>` —
+    state IDs are per-team and the team key changes over time, so pass the team
+    *name*.
+  - For each open issue, call `mcp__linear-server__save_issue` with
+    `state: <Done state ID>`.
+- If no, skip without changes.
+
+### Step 11 — Summary
+
+Report counts: worktrees removed, local branches deleted, remote branches
+deleted, empty directories removed, orphan `node_modules/` removed, Linear issues
+set to `Done` (if any). List the names of deleted items.
+
+## Important rules
+
+- **Dry-run** previews without deleting (`--dry-run`).
+- **Confirmation required** before any deletion (single bulk gate).
+- **Protected branches** (`protectedBranches`) are never touched.
+- **Merged only**: a branch is deleted only if merged into `main` via git
+  ancestry **or** a merged GitHub PR (squash merges).
+- **Worktrees first**, then branches; filesystem pass last.
+- **Uncommitted worktrees** are never force-removed automatically.
+- **`.git/` and the main worktree** are never touched.
+
+## Error handling
+
+- Skip (and report) any worktree or branch that fails to remove; continue with
+  the rest.
+- Skip remote branches that no longer exist (already deleted).
+- If `gh pr list` fails for a branch (network, rate limit, auth), log a warning
+  and continue — do not treat the branch as merged.
+- If the Linear MCP server is unavailable, skip the Linear steps silently.
+
+## Arguments
+
+$ARGUMENTS

package/skills/cleanup-repo/config.example.json

@@ -0,0 +1,5 @@
+{
+  "linearTeamName": "Your Linear Team",
+  "issueKeys": ["ABC", "XYZ"],
+  "protectedBranches": ["main"]
+}

package/skills/cleanup-repo/config.json

@@ -0,0 +1,5 @@
+{
+  "linearTeamName": "ACME Skunkworks",
+  "issueKeys": ["ASW", "AKW", "SKW"],
+  "protectedBranches": ["main"]
+}

package/skills/cleanup-repo/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@acme-skunkworks/skill-cleanup-repo",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Agent skill: clean up merged Git branches and worktrees, plus a filesystem-hygiene pass (empty directories and orphan node_modules).",
+  "keywords": [
+    "agent-skill",
+    "claude-code",
+    "cursor",
+    "git",
+    "cleanup",
+    "worktree"
+  ],
+  "homepage": "https://github.com/acme-skunkworks/agent-skills/tree/main/skills/cleanup-repo#readme",
+  "bugs": {
+    "url": "https://github.com/acme-skunkworks/agent-skills/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/acme-skunkworks/agent-skills.git",
+    "directory": "skills/cleanup-repo"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Rob Easthope",
+    "url": "https://github.com/RobEasthope"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/skills/cleanup-repo/references/design-notes.md

@@ -0,0 +1,56 @@
+# cleanup-repo — design notes
+
+## Why `cleanup-repo`, not `cleanup-branches`
+
+The skill lifts an existing slash command called `/cleanup-branches`, but it is
+named `cleanup-repo` deliberately:
+
+- It already does more than branches — it removes **worktrees** (with an
+  uncommitted-changes guard and detached-HEAD handling) and runs a
+  **filesystem-hygiene** pass.
+- The broader name leaves room for further repo-hygiene extensions without
+  another rename.
+
+Per-repo slash-command names are a consumer choice. A consumer can expose this as
+`/cleanup-repo`, or keep `/cleanup-branches` as a friendlier alias.
+
+## Initial scope
+
+- Merged-worktree and merged-branch cleanup (two-pass detection), an opt-in Linear
+  `Done` writeback, a single confirmation gate, and a `--dry-run` preview — at
+  parity with `/cleanup-branches`.
+- **New:** a filesystem-hygiene pass — recursively-empty directory pruning and
+  orphan `node_modules/` pruning.
+
+## Deliberate non-goals (v1)
+
+- **The filesystem pass is not parameterised.** The placeholder allowlist
+  (`.gitkeep`, `.gitignore`) is fixed, and the orphan-`node_modules` rule is fixed
+  at the strict "no sibling `package.json`" check. Either can become a config knob
+  in a future minor bump if a real consumer case demands it.
+- **No workspace-membership inference** for orphan `node_modules/` — strict
+  parent-`package.json` check only.
+- **Single-snapshot removal within `apply()`.** `apply()` detects once and removes
+  that snapshot; removing an orphan `node_modules/` can leave its parent empty, but
+  that parent is left for a follow-up run rather than swept in the same snapshot.
+  Note the skill runs the filesystem detection twice — a read-only pass for the
+  preview, then `apply()` **after** worktree removal — so the apply pass may sweep a
+  worktree parent (e.g. `.claude/worktrees/`) that the pre-removal preview could not
+  yet see. The skill predicts these in the preview from the worktree-removal list.
+- **Merge-detection base branch is hardcoded to `origin/main`.** Both passes (git
+  ancestry and merged-PR lookup) assume `main`; a consumer defaulting to `master` or
+  `develop` must edit the skill. A future minor bump should add a `mainBranch` config
+  key alongside `protectedBranches`.
+
+## Future extensions (out of scope, enabled by the name)
+
+Each would be a follow-up issue and a Changeset minor bump:
+
+- Pruning stale local tags (`git tag --merged main` style).
+- An optional reflog / garbage-collection trigger after large cleanups.
+- Surfacing local branches with no upstream that have been stale for N days.
+- Build-artifact cleanup (`dist/`, `build/`, `.next/`, `coverage/`, …) — only if a
+  generalisable heuristic emerges; tool-specific cleanup stays the user's job.
+
+Explicitly **not** planned: lockfile / package-manager cache cleanup
+(`pnpm store prune`, npm/yarn caches) — a different concern on a different cadence.

package/skills/cleanup-repo/scripts/filesystem-hygiene.mjs

@@ -0,0 +1,316 @@
+#!/usr/bin/env node
+// Filesystem-hygiene pass for the cleanup-repo skill.
+//
+// Detects two kinds of cruft and (optionally) removes them:
+//   - emptyDirs          : recursively-empty directories — a directory whose
+//                          entire subtree contains no files at all. The top-most
+//                          such directory is reported (removing it takes its
+//                          empty descendants with it). A directory holding any
+//                          file — including a `.gitkeep` / `.gitignore`
+//                          placeholder — is NOT empty and is left alone.
+//   - orphanNodeModules  : `node_modules/` directories whose immediate parent has
+//                          no `package.json` (strict; no workspace inference).
+//
+// `.git/` is hard-protected: never traversed, and its presence marks the
+// containing directory as non-empty (so a nested working tree is never swept).
+// `node_modules/` is never traversed (huge, and handled by the orphan check).
+//
+// For a given filesystem state the SAME detection drives both the report and
+// the removal, so `--apply` removes exactly what a plain run lists. (The skill
+// runs detection twice — before and after worktree removal — so its end-to-end
+// preview can still pick up parents emptied by that removal; see SKILL.md.)
+//
+// Usage:
+//   node filesystem-hygiene.mjs [root]            # print detection JSON (default cwd)
+//   node filesystem-hygiene.mjs [root] --json     # same, explicit
+//   node filesystem-hygiene.mjs [root] --apply    # remove the detected set, print JSON
+//   node filesystem-hygiene.mjs --self-test       # run built-in fixtures
+
+import {
+  readdirSync,
+  existsSync,
+  statSync,
+  rmSync,
+  mkdtempSync,
+  mkdirSync,
+  writeFileSync,
+} from "node:fs";
+import { join, dirname, resolve, sep } from "node:path";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+
+// Recurse a directory. Returns true when the directory is recursively empty
+// (its subtree contains no files). Side effects: pushes top-most empty
+// directories into `emptyDirs` and every node_modules path into `nodeModulesDirs`.
+function scan(dir, emptyDirs, nodeModulesDirs) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    // Unreadable directory — treat as content so we never remove it.
+    return false;
+  }
+
+  let hasContent = false;
+  const emptyChildDirs = [];
+
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+
+    if (entry.isSymbolicLink()) {
+      // Never follow or remove through symlinks.
+      hasContent = true;
+      continue;
+    }
+    if (entry.isFile()) {
+      // Any file — placeholders included — counts as content.
+      hasContent = true;
+      continue;
+    }
+    if (entry.isDirectory()) {
+      if (entry.name === ".git") {
+        hasContent = true; // protect working trees / nested repos
+        continue;
+      }
+      if (entry.name === "node_modules") {
+        nodeModulesDirs.push(full);
+        hasContent = true; // not traversed; handled by the orphan check
+        continue;
+      }
+      const childEmpty = scan(full, emptyDirs, nodeModulesDirs);
+      if (childEmpty) {
+        emptyChildDirs.push(full);
+      } else {
+        hasContent = true;
+      }
+      continue;
+    }
+    // Sockets, FIFOs, devices — treat as content.
+    hasContent = true;
+  }
+
+  if (hasContent) {
+    // This directory stays; its recursively-empty children are the top-most
+    // empties (their parent has content), so they are the ones to remove.
+    for (const child of emptyChildDirs) emptyDirs.push(child);
+    return false;
+  }
+  // No content anywhere in this subtree: this whole directory is removable.
+  // Don't record its children — the parent records this directory instead.
+  return true;
+}
+
+export function detect(root) {
+  if (!existsSync(root)) {
+    throw new Error(`Root path does not exist: ${root}`);
+  }
+  if (!statSync(root).isDirectory()) {
+    throw new Error(`Root path is not a directory: ${root}`);
+  }
+  const emptyDirs = [];
+  const nodeModulesDirs = [];
+  // The root itself is never a removal candidate.
+  scan(root, emptyDirs, nodeModulesDirs);
+
+  const orphanNodeModules = nodeModulesDirs.filter(
+    (nm) => !existsSync(join(dirname(nm), "package.json")),
+  );
+
+  return {
+    emptyDirs: emptyDirs.sort(),
+    orphanNodeModules: orphanNodeModules.sort(),
+  };
+}
+
+export function apply(root) {
+  const result = detect(root);
+  const removed = [];
+  const failed = [];
+  // Isolate per-path failures: one un-removable entry (permissions, a race)
+  // must not abort the rest. Report what was removed and what wasn't.
+  for (const path of [...result.orphanNodeModules, ...result.emptyDirs]) {
+    try {
+      rmSync(path, { recursive: true, force: true });
+      removed.push(path);
+    } catch (err) {
+      failed.push({ path, error: err.message });
+    }
+  }
+  return { ...result, removed, failed };
+}
+
+function parseArgs(argv) {
+  const flags = new Set(argv.filter((a) => a.startsWith("--")));
+  const positional = argv.filter((a) => !a.startsWith("--"));
+  return { flags, root: positional[0] ?? process.cwd() };
+}
+
+// ---- self-test ----------------------------------------------------------
+
+function buildFixture() {
+  const root = mkdtempSync(join(tmpdir(), "cleanup-repo-fs-"));
+  const d = (...p) => {
+    const full = join(root, ...p);
+    mkdirSync(full, { recursive: true });
+    return full;
+  };
+  const f = (rel, body = "") => writeFileSync(join(root, rel), body);
+
+  // A repo-like root marker so the root always has content.
+  d(".git");
+  f(".git/HEAD", "ref: refs/heads/main\n");
+
+  // 1. A recursively-empty directory (nested, no files) → top-most reported.
+  d("empty-top", "a", "b");
+
+  // 2. A directory whose subtree holds only a placeholder → left alone.
+  d("placeholder-only");
+  f("placeholder-only/.gitkeep");
+
+  // 3. A directory with a real file → left alone.
+  d("has-file");
+  f("has-file/index.ts", "export {};\n");
+
+  // 4. Orphan node_modules (parent has no package.json).
+  d("orphan-pkg", "node_modules", "left-pad");
+
+  // 5. Legitimate node_modules (parent has package.json) → not orphan.
+  d("real-pkg", "node_modules", "left-pad");
+  f("real-pkg/package.json", "{}\n");
+
+  // 6. A nested .git (sub working tree) inside an otherwise file-free dir →
+  //    must NOT be reported as empty.
+  d("nested-repo", ".git");
+
+  return root;
+}
+
+function selfTest() {
+  const cases = [];
+  const root = buildFixture();
+  let result;
+  try {
+    result = detect(root);
+  } catch (e) {
+    console.log(`  FAIL  detect threw (${e.message})`);
+    process.exit(1);
+  }
+
+  const rel = (p) => p.slice(root.length).split(sep).filter(Boolean).join("/");
+  const empties = result.emptyDirs.map(rel);
+  const orphans = result.orphanNodeModules.map(rel);
+
+  cases.push({
+    name: "top-most empty directory is reported",
+    ok: empties.includes("empty-top"),
+  });
+  cases.push({
+    name: "empty descendants are not reported individually",
+    ok: !empties.includes("empty-top/a") && !empties.includes("empty-top/a/b"),
+  });
+  cases.push({
+    name: "placeholder-only directory is left alone",
+    ok: !empties.includes("placeholder-only"),
+  });
+  cases.push({
+    name: "directory with a real file is left alone",
+    ok: !empties.includes("has-file"),
+  });
+  cases.push({
+    name: "orphan node_modules (no sibling package.json) is reported",
+    ok: orphans.includes("orphan-pkg/node_modules"),
+  });
+  cases.push({
+    name: "node_modules with a sibling package.json is NOT an orphan",
+    ok: !orphans.includes("real-pkg/node_modules"),
+  });
+  cases.push({
+    name: "node_modules never appears in emptyDirs",
+    ok: !empties.some((p) => p.split("/").includes("node_modules")),
+  });
+  cases.push({
+    name: "directory holding a nested .git is not reported empty",
+    ok: !empties.includes("nested-repo"),
+  });
+  cases.push({
+    name: ".git is never reported or traversed",
+    ok:
+      !empties.some((p) => p.split("/").includes(".git")) &&
+      !orphans.some((p) => p.split("/").includes(".git")),
+  });
+
+  // apply() removes exactly the detected snapshot and nothing else.
+  const before = detect(root);
+  const applied = apply(root);
+  const after = detect(root);
+  cases.push({
+    name: "apply removed the originally detected paths",
+    ok:
+      before.emptyDirs.every((p) => !existsSync(p)) &&
+      before.orphanNodeModules.every((p) => !existsSync(p)),
+  });
+  cases.push({
+    name: "apply reports every removed path and no failures on a clean run",
+    ok:
+      applied.failed.length === 0 &&
+      applied.removed.length ===
+        before.emptyDirs.length + before.orphanNodeModules.length,
+  });
+  cases.push({
+    name: "apply preserves placeholder-only and file-bearing directories",
+    ok: existsSync(join(root, "placeholder-only")) && existsSync(join(root, "has-file")),
+  });
+  // Removing orphan-pkg/node_modules empties its parent — a deliberate cascade
+  // that a *subsequent* run sweeps, never the same snapshot.
+  cases.push({
+    name: "removing an orphan node_modules leaves its parent for the next run",
+    ok:
+      after.emptyDirs.map(rel).join(",") === "orphan-pkg" &&
+      after.orphanNodeModules.length === 0,
+  });
+
+  // detect() fails fast on a root that exists but is not a directory, rather
+  // than silently reporting nothing (readdirSync would throw ENOTDIR in scan).
+  const fileRoot = join(tmpdir(), `cleanup-repo-fs-not-a-dir-${process.pid}`);
+  writeFileSync(fileRoot, "");
+  let threwOnFileRoot = false;
+  try {
+    detect(fileRoot);
+  } catch {
+    threwOnFileRoot = true;
+  }
+  rmSync(fileRoot, { force: true });
+  cases.push({
+    name: "detect throws on a non-directory root",
+    ok: threwOnFileRoot,
+  });
+
+  rmSync(root, { recursive: true, force: true });
+
+  let failed = 0;
+  for (const { name, ok } of cases) {
+    if (ok) {
+      console.log(`  ok    ${name}`);
+    } else {
+      failed += 1;
+      console.log(`  FAIL  ${name}`);
+    }
+  }
+  console.log(`\n${cases.length - failed}/${cases.length} passed`);
+  process.exit(failed === 0 ? 0 : 1);
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  if (argv.includes("--self-test")) {
+    selfTest();
+    return;
+  }
+  const { flags, root } = parseArgs(argv);
+  const result = flags.has("--apply") ? apply(root) : detect(root);
+  console.log(JSON.stringify(result, null, 2));
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1])) {
+  main();
+}