okhp3-repl-repo-janitor
OverKill Hill P³ · overkillhill.com · github.com/OKHP3
A portable, transferable Agent Skill for one specific and common situation: a single Replit workspace's Git checkout has accumulated stale branches, merged/abandoned pull requests, and inconsistently named files, and the user wants it cleaned up safely. Copy this skill's folder into .agents/skills/ in any Repl to reuse it there.
This is a condensed, Replit-shaped descendant of two broader OverKill Hill P³ skills:
okhp3-repository-janitor (multi-repo branch/PR lifecycle across local mirrors)
okhp3-repository-organizer (deep content-first repository classification and scaffolding)
Use this skill instead of those two when the scope is "one Repl, tidy the branches and the names," not a fleet of local clones or a full repository re-architecture.
Safety contract
- Start read-only. Run the bundled audit script or equivalent
git/gh inspection before proposing any change. Never delete a branch, PR, file, or folder during discovery.
git fetch --all to refresh remote-tracking refs. Never pass --prune until every stale remote branch has been classified.
- Treat "merged into origin/main," "closed pull request," and "abandoned with no PR" as three different facts. Check the actual PR state (via the
git-remote skill or gh pr view) before recommending deletion — an old branch can still have an open, wanted PR.
- A Replit-generated name (
subrepl-*, replit-agent, agent/*) is a hint that the branch may be an ephemeral task-agent artifact, not proof it is safe to delete. Confirm it is merged or explicitly abandoned before including it in the delete list. The current/active branch (checked out, or the one the live agent session is using) is never a deletion candidate.
- For naming cleanup, apply the kebab-case default (
references/naming-conventions.md) but respect the documented exceptions: PascalCase React components, camelCase hooks, ALL-CAPS root governance files (README.md, LICENSE, CHANGELOG.md, AGENTS.md, etc.), and files whose name is dictated by a tool or a web standard (package.json, .replit, robots.txt, CNAME, ...).
- Renaming a file changes import paths and, if it is web content, deployed URLs. Update every importer in the same change, and never rename a file that is live-linked without a redirect or transition plan.
- Always produce a written plan before touching anything. Wait for the user to say "go" (or otherwise explicitly approve the exact items) before executing.
- Never rewrite
main, force-push, or delete stashes/archive refs without a separately stated and confirmed recovery plan.
Workflow
1. Inventory branches and PRs
git fetch --all
python3 .agents/skills/okhp3-repl-repo-janitor/scripts/audit-repo.py --root . --base origin/main
This prints a JSON report: every local branch with its last-commit metadata, whether it's merged into the base branch, and whether its name matches a known Replit-generated pattern. It never mutates anything.
For each unmerged branch, resolve its pull-request state before deciding: use the git-remote skill (or gh pr list --head <branch> / gh pr view if the gh CLI and a token are available) to check open/closed/merged status and CI checks. Do not assume a branch is dead just because it's old — check for an open PR first.
2. Classify each branch
Bucket every non-current, non-main branch into one of:
- keep — active work, open PR still under review, or too recent/ambiguous to judge
- merge — has an approved, checks-passing PR ready to land; squash-merge it
- delete — already merged into
origin/main, or confirmed abandoned with no open PR and no unique unmerged value
- review — needs the user's judgment (e.g., unmerged commits with unclear intent)
3. Inventory naming and detritus
The same script also reports naming violations (mixed/camel/Pascal case outside the documented exceptions, spaces in filenames) and known detritus folder names present in the tree (attached_assets/, _unused/, tmp/, temp/, etc., and their hyphen variants). Treat this as a starting point, not the full picture — also scan manually for:
- one-time handoff/plan documents at the repo root whose referenced work has already shipped and merged
- stale dated build/export archives (zips, tarballs) that duplicate what the build process would regenerate
- leftover temp files from interrupted shell commands (e.g. a
sed/mktemp scratch file committed under a random name instead of the real target file — check content, not just the name, before judging)
4. Produce the plan, wait for "go"
Present findings in this exact shape (mirrors the OverKill Hill P³ "Decrapify" format so the user gets a consistent report across every Repl):
## Branches & PRs
- MERGE: <branch> — PR #<n>, checks green, approved → squash-merge then delete
- DELETE: <branch> — merged into origin/main on <date>, safe to remove
- KEEP: <branch> — <reason>
- REVIEW: <branch> — <what's unclear, what you need from the user>
## A. DELETE
- <file/folder> — <why it's dead>
## B. GITIGNORE-AND-UNTRACK
- <path> — currently tracked but matches a build/working-artifact pattern
## C. TRIAGE-THEN-DELETE
- <path> — read first to confirm nothing is stranded, then remove
## D. RENAME
- <old-name> → <new-name> — <which naming rule it violates>, <what else must change in the same commit>
Stop here. Do not execute until the user approves specific items — approving "the plan" in general is not the same as approving each destructive line.
5. Execute in small batches, then verify
For each approved branch merge: refresh, verify the expected head, merge via the pull request (squash), refetch, then delete only that exact verified-merged branch — remote first, then the local tracking branch. For each approved file/folder action: use git rm/git mv (not raw rm) so history and diffs stay clean, unless the target was never tracked (e.g. a gitignored working file), in which case a plain rm is fine.
After executing: re-run the audit script, run git status --short, and confirm the workflow/app still starts cleanly if any tracked source file moved or was renamed.
Resources
scripts/audit-repo.py — read-only branch + naming + detritus audit for a single local checkout. Safe to run anytime; makes no changes.
references/naming-conventions.md — the kebab-case default and its structural exceptions, condensed for reuse across any Repl (not tied to a specific brand's folder taxonomy).
About
Adapted from okhp3-repository-janitor and okhp3-repository-organizer, narrowed for the one-Repl-one-checkout case.
Built by Jamie Hill · OverKill Hill P³
MIT License — free to use, fork, and adapt.
1---2name: okhp3-repl-repo-janitor-33description: Clean up a single Replit-hosted Git repository — squash-merge and delete old, merged, or abandoned branches and pull requests (including Replit-generated subrepl-*, replit-agent, and agent/* branches), and normalize file/folder names against a kebab-case default with documented exceptions. Use when a user asks to purge dead/stale branches, clean up merged PRs, decrapify or tidy the repo, fix inconsistent file naming, or wants a repeatable Replit-repo hygiene routine across multiple Repls.4license: MIT5metadata:6 source: https://skillmd.com/skills/okhp3/okhp3-repl-repo-janitor-37 author: Jamie Hill (OverKill Hill P³)8 version: "0.1.0"9 category: universal10 origin: adapted from okhp3/skillz `okhp3-repository-janitor` and `okhp3-repository-organizer` for the single-checkout Replit workspace model11 homepage: https://overkillhill.com12 author-github: https://github.com/OKHP313 maturity: draftable14 in_scope:15 - Auditing local branches in a single Replit workspace against origin/main and each branch's pull-request state16 - Recognizing Replit-specific branch patterns (subrepl-*, replit-agent, agent/*) as a hint, not a verdict17 - Squash-merging an approved, checks-passing pull request, then deleting the exact verified branch (remote first, then local)18 - Auditing file/folder names against a kebab-case default with the standard structural exceptions (React components/hooks, root governance files, tool-required filenames, web-standard filenames)19 - Identifying common repo detritus (paste-buffer/attachment dirs, stale build zips, leftover temp files, orphaned one-time handoff docs) and proposing a triage plan20 out_of_scope:21 - Multi-repository mirror estates (that is `okhp3-repository-janitor`'s job on a machine with several local clones)22 - Deep repository classification, purpose discovery, or governance scaffolding for content-first knowledge repos (that is `okhp3-repository-organizer`'s job)23 - Merging, closing, deleting, or renaming anything without an explicit "go" from the user24 - Rewriting `main`, force-pushing, or deleting stashes/archive refs25---2627# okhp3-repl-repo-janitor2829**OverKill Hill P³** · [overkillhill.com](https://overkillhill.com) · [github.com/OKHP3](https://github.com/OKHP3)3031A portable, transferable Agent Skill for one specific and common situation: **a single Replit workspace's Git checkout has accumulated stale branches, merged/abandoned pull requests, and inconsistently named files**, and the user wants it cleaned up safely. Copy this skill's folder into `.agents/skills/` in any Repl to reuse it there.3233This is a condensed, Replit-shaped descendant of two broader OverKill Hill P³ skills:34- `okhp3-repository-janitor` (multi-repo branch/PR lifecycle across local mirrors)35- `okhp3-repository-organizer` (deep content-first repository classification and scaffolding)3637Use this skill instead of those two when the scope is "one Repl, tidy the branches and the names," not a fleet of local clones or a full repository re-architecture.3839## Safety contract40411. Start read-only. Run the bundled audit script or equivalent `git`/`gh` inspection before proposing any change. Never delete a branch, PR, file, or folder during discovery.422. `git fetch --all` to refresh remote-tracking refs. Never pass `--prune` until every stale remote branch has been classified.433. Treat "merged into origin/main," "closed pull request," and "abandoned with no PR" as three different facts. Check the actual PR state (via the `git-remote` skill or `gh pr view`) before recommending deletion — an old branch can still have an open, wanted PR.444. A Replit-generated name (`subrepl-*`, `replit-agent`, `agent/*`) is a hint that the branch may be an ephemeral task-agent artifact, not proof it is safe to delete. Confirm it is merged or explicitly abandoned before including it in the delete list. The current/active branch (checked out, or the one the live agent session is using) is never a deletion candidate.455. For naming cleanup, apply the kebab-case default (`references/naming-conventions.md`) but respect the documented exceptions: PascalCase React components, camelCase hooks, ALL-CAPS root governance files (`README.md`, `LICENSE`, `CHANGELOG.md`, `AGENTS.md`, etc.), and files whose name is dictated by a tool or a web standard (`package.json`, `.replit`, `robots.txt`, `CNAME`, ...).466. Renaming a file changes import paths and, if it is web content, deployed URLs. Update every importer in the same change, and never rename a file that is live-linked without a redirect or transition plan.477. Always produce a written plan before touching anything. Wait for the user to say "go" (or otherwise explicitly approve the exact items) before executing.488. Never rewrite `main`, force-push, or delete stashes/archive refs without a separately stated and confirmed recovery plan.4950## Workflow5152### 1. Inventory branches and PRs5354```bash55git fetch --all56python3 .agents/skills/okhp3-repl-repo-janitor/scripts/audit-repo.py --root . --base origin/main57```5859This prints a JSON report: every local branch with its last-commit metadata, whether it's merged into the base branch, and whether its name matches a known Replit-generated pattern. It never mutates anything.6061For each **unmerged** branch, resolve its pull-request state before deciding: use the `git-remote` skill (or `gh pr list --head <branch>` / `gh pr view` if the `gh` CLI and a token are available) to check open/closed/merged status and CI checks. Do not assume a branch is dead just because it's old — check for an open PR first.6263### 2. Classify each branch6465Bucket every non-current, non-`main` branch into one of:66- **keep** — active work, open PR still under review, or too recent/ambiguous to judge67- **merge** — has an approved, checks-passing PR ready to land; squash-merge it68- **delete** — already merged into `origin/main`, or confirmed abandoned with no open PR and no unique unmerged value69- **review** — needs the user's judgment (e.g., unmerged commits with unclear intent)7071### 3. Inventory naming and detritus7273The same script also reports naming violations (mixed/camel/Pascal case outside the documented exceptions, spaces in filenames) and known detritus folder names present in the tree (`attached_assets/`, `_unused/`, `tmp/`, `temp/`, etc., and their hyphen variants). Treat this as a starting point, not the full picture — also scan manually for:74- one-time handoff/plan documents at the repo root whose referenced work has already shipped and merged75- stale dated build/export archives (zips, tarballs) that duplicate what the build process would regenerate76- leftover temp files from interrupted shell commands (e.g. a `sed`/`mktemp` scratch file committed under a random name instead of the real target file — check content, not just the name, before judging)7778### 4. Produce the plan, wait for "go"7980Present findings in this exact shape (mirrors the OverKill Hill P³ "Decrapify" format so the user gets a consistent report across every Repl):8182```83## Branches & PRs84- MERGE: <branch> — PR #<n>, checks green, approved → squash-merge then delete85- DELETE: <branch> — merged into origin/main on <date>, safe to remove86- KEEP: <branch> — <reason>87- REVIEW: <branch> — <what's unclear, what you need from the user>8889## A. DELETE90- <file/folder> — <why it's dead>9192## B. GITIGNORE-AND-UNTRACK93- <path> — currently tracked but matches a build/working-artifact pattern9495## C. TRIAGE-THEN-DELETE96- <path> — read first to confirm nothing is stranded, then remove9798## D. RENAME99- <old-name> → <new-name> — <which naming rule it violates>, <what else must change in the same commit>100```101102Stop here. Do not execute until the user approves specific items — approving "the plan" in general is not the same as approving each destructive line.103104### 5. Execute in small batches, then verify105106For each approved branch merge: refresh, verify the expected head, merge via the pull request (squash), refetch, then delete only that exact verified-merged branch — remote first, then the local tracking branch. For each approved file/folder action: use `git rm`/`git mv` (not raw `rm`) so history and diffs stay clean, unless the target was never tracked (e.g. a gitignored working file), in which case a plain `rm` is fine.107108After executing: re-run the audit script, run `git status --short`, and confirm the workflow/app still starts cleanly if any tracked source file moved or was renamed.109110## Resources111112- `scripts/audit-repo.py` — read-only branch + naming + detritus audit for a single local checkout. Safe to run anytime; makes no changes.113- `references/naming-conventions.md` — the kebab-case default and its structural exceptions, condensed for reuse across any Repl (not tied to a specific brand's folder taxonomy).114115## About116117Adapted from [okhp3-repository-janitor](https://github.com/OKHP3/skillz/blob/main/universal/okhp3-repository-janitor/SKILL.md) and [okhp3-repository-organizer](https://github.com/OKHP3/skillz/blob/main/universal/okhp3-repository-organizer/SKILL.md), narrowed for the one-Repl-one-checkout case.118Built by [Jamie Hill](https://overkillhill.com) · [OverKill Hill P³](https://overkillhill.com)119MIT License — free to use, fork, and adapt.