agentleFS
OKHP3OKHP3/skillz/.agents/skills/okhp3-replit-repl-janitor/SKILL.md

okhp3-replit-repl-janitor

Skill3 starsChanged 2 months agoMITView on GitHub

OverKill Hill P³ one-Repl repository cleanup workflow for safely auditing and tidying a single Replit workspace's Git checkout. Use when a user asks to clean up merged or abandoned branches and pull requests, purge stale subrepl-* or agent/* branches, normalize file and folder names, or remove repository detritus. Also activate for "decrapify this Repl", "tidy this repo", "prune dead branches", or "fix inconsistent filenames". This is the authoritative one-time cleanup workflow for one Replit checkout; use okhp3-repository-janitor for recurring maintenance and multiple local clones, and okhp3-repository-organizer for structural reorganization.

  • Commits and pushes

The file

Show its rules and text

We split this skill into the rules it gives an agent

13 rules. About 0 are common, 10 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈10

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Very specific:

    Start read-only: Run the bundled audit without --fetch.

    line 61
  2. Distinctive:

    Protect recovery paths: Never rewrite main, force-push, or delete stashes or archive refs under this skill.

    line 77
  3. Very specific:

    If remote-tracking refs may be stale, run git fetch --all separately and inspect its result.

    line 95
  4. Distinctive:

    Run the deterministic local audit:

    line 103
  5. Very specific:

    Do not infer "no PR" from a failed network call.

    line 124
  6. Distinctive:

    Every non-current, non-main branch belongs in exactly one bucket:

    line 129
  7. Distinctive:

    Use this exact report shape:

    line 158
  8. Distinctive:

    Stop. General approval of "the cleanup" is not approval of every destructive line.

    line 180
  9. Distinctive:

    Before each branch operation, run the bundled pre-delete check with the exact branch and SHA recorded in the approved plan:

    line 185
  10. Distinctive:

    Delete the exact remote branch first.

    line 210
  11. Distinctive:

    Delete its local tracking branch second.

    line 211
  12. Distinctive:

    After every approved batch:

    line 218
  13. Distinctive:

    If a tracked source file moved or was renamed, run the relevant validation and restart the affected workflow, then inspect its logs and …

    line 227

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

okhp3-replit-repl-janitor

OverKill Hill P³ · overkillhill.com · github.com/OKHP3

Safely clean one Replit workspace's Git checkout without confusing generated branch names with proof, a closed pull request with a merged one, or an untidy filename with permission to rename it. The workflow is read-only first, evidence-led, and destructive only after the owner approves exact line items.


Scope

In scopeOut of scope
One-time cleanup of one Replit checkoutRecurring maintenance; use okhp3-repository-janitor
Branch and PR classification against a verified baseMulti-clone reconciliation; use okhp3-repository-janitor
Naming and detritus auditStructural redesign; use okhp3-repository-organizer
Exact, owner-approved cleanup executionAutonomous deletion, merging, renaming, or publishing

Safety contract

  1. Start read-only. Run the bundled audit without --fetch; it reads the current checkout and prints JSON. Fetch separately only when network access is appropriate. Never prune during discovery.
  2. Fail visibly. A missing base ref, failed Git command, detached HEAD, or non-repository path is evidence, not an empty result. Stop and report it.
  3. Separate three facts. "Merged into origin/main", "closed pull request", and "abandoned with no PR" are different states. Never substitute one for another.
  4. Names are hints, not verdicts. subrepl-*, replit-agent, and agent/* suggest generated work but do not prove it is safe to delete. The current branch is never a deletion candidate.
  5. Plan before touching. Return the exact keep, merge, delete, and review branch buckets plus file actions. Wait for explicit approval of individual destructive lines.
  6. Rename atomically. A file rename must update every importer and link in the same change. A public URL needs a redirect or transition plan.
  7. Protect recovery paths. Never rewrite main, force-push, or delete stashes or archive refs under this skill.

Workflow

1. Establish a trustworthy baseline

Record the repository root, current branch, configured remotes, base ref, and working-tree status before making recommendations:

git status --short --branch
git remote -v
git rev-parse --verify origin/main

If remote-tracking refs may be stale, run git fetch --all separately and inspect its result. Do not add --prune: pruning before classification destroys evidence about stale remote branches.

NON-NEGOTIABLE — NO EARLY PRUNING: Never run git fetch --all --prune, git fetch --prune, or git remote prune until every stale remote branch has been classified. Refresh refs without pruning during discovery.

Run the deterministic local audit:

python3 .agents/skills/okhp3-replit-repl-janitor/scripts/audit-repo.py \
  --root . \
  --base origin/main

The script is read-only by default. --fetch is available only as an explicit opt-in and still never prunes.

2. Resolve pull-request state

The audit reports Git facts; it does not infer hosted pull-request state. For every unmerged branch, use the git-remote skill or GitHub CLI:

gh pr list --head '<branch>' --state all
gh pr view <number> --json state,mergeStateStatus,reviewDecision,statusCheckRollup,headRefOid

Do not infer "no PR" from a failed network call. Record the lookup as unknown and place the branch in review.

3. Classify every branch

Every non-current, non-main branch belongs in exactly one bucket:

BucketEvidence rule
keepActive work, an open wanted PR, or deliberately retained history
mergeApproved PR, required checks passing, exact head verified
deleteVerified merged into the base, or owner-confirmed abandoned with no wanted PR
reviewUnique commits, unknown PR state, failed lookup, or unclear intent

Generated naming affects the explanation, never the bucket by itself.

4. Audit naming and detritus

Apply references/naming-conventions.md:

  • default to kebab-case;
  • preserve PascalCase .tsx/.jsx components;
  • preserve camelCase useFoo.ts hooks;
  • preserve root governance, tool-required, and web-standard filenames;
  • flag spaces, mixed case, underscores, and uppercase extensions when no exception applies.

For detritus folders such as attached_assets/, _unused/, _drafts/, _scratch/, _old/, tmp/, temp/, and unused/, inspect contents before choosing delete or gitignore-and-untrack. A folder name is evidence for triage, not permission to discard its contents.

5. Present the plan and stop

Use this exact report shape:

## Branches & PRs
- KEEP: <branch> — <evidence>
- MERGE: <branch> — <PR and check evidence>
- DELETE: <branch> — <merged or owner-confirmed abandonment evidence>
- REVIEW: <branch> — <unknown fact and smallest next check>

## A. DELETE
- <path> — <why it is verified disposable>

## B. GITIGNORE-AND-UNTRACK
- <path> — <why it is generated but currently tracked>

## C. TRIAGE-THEN-DELETE
- <path> — <what must be inspected first>

## D. RENAME
- <old> → <new> — <rule, import/link impact, validation>

Stop. General approval of "the cleanup" is not approval of every destructive line; obtain an exact go/no-go for each merge, delete, and rename.

6. Execute approved items in small batches

Before each branch operation, run the bundled pre-delete check with the exact branch and SHA recorded in the approved plan:

python3 .agents/skills/okhp3-replit-repl-janitor/scripts/audit-repo.py \
  --root . \
  --check-delete \
  --branch '<branch>' \
  --reviewed-head '<reviewed SHA>'

The JSON result records both reviewed_head and the freshly read current_head. If the bucket is review, stop, record the hold, and run no deletion command. Only a delete result may be executed, and its deletion_commands must be run in the emitted order. The sequence is remote-first (git push origin --delete <branch>) and local second (git branch -d <branch>). The check is read-only and never executes either command.

For an approved merge:

  1. Confirm PR approval and required checks.
  2. Confirm the PR head SHA matches the reviewed branch head.
  3. Squash-merge through the pull request.
  4. Fetch and verify the merged result is reachable from the base.
  5. Delete the exact remote branch first.
  6. Delete its local tracking branch second.

For approved files, use git rm and git mv so the change is explicit. Plain rm is acceptable only for an untracked or gitignored working file.

7. Verify and report

After every approved batch:

python3 .agents/skills/okhp3-replit-repl-janitor/scripts/audit-repo.py \
  --root . \
  --base origin/main
git status --short

If a tracked source file moved or was renamed, run the relevant validation and restart the affected workflow, then inspect its logs and preview. Report what changed, what remains, and which recovery path is still available.


Output contract

Return:

  • repository root, current branch, base ref, and whether refs were fetched;
  • the four branch buckets with evidence for every item;
  • the four file-action sections;
  • unresolved unknowns and the smallest safe next check;
  • exact writes performed, or an explicit statement that discovery was read-only;
  • post-change audit, Git status, and workflow validation results when execution was authorized.

Failure handling

ConditionResult
Base ref missingStop; ask which verified base ref to use
Git command or fetch failsStop; show the failed command and stderr
Detached HEADAudit may continue, but no branch deletion may be recommended until the active work is identified
PR lookup unavailablePut affected branches in review; never infer abandonment
Unique unmerged commitsPreserve in review unless the owner explicitly abandons them
Rename affects public URLRequire redirect or transition plan before execution
Approval is broad or ambiguousAsk for exact approved line items

Resources

  • scripts/audit-repo.py — deterministic, no-fetch-by-default JSON audit of branches, naming violations, and nested detritus.
  • references/naming-conventions.md — portable kebab-case policy and structural exceptions.
  • references/foundry-architecture.md — Phase 1 intent, scope, and brand decision for this renamed skill.
  • evals/evals.json — three live-evaluation prompts with four anchored expectations each.
  • benchmarks/benchmark.json — version-matched Foundry evidence after live execution.

About

Built by Jamie Hill · OverKill Hill P³ Published at github.com/OKHP3 Part of the OKHP3/skillz Agent Skill library. MIT License -- free to use, fork, and adapt. A nod to the source is appreciated.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.