nightly-tidy
Skill3 starsChanged 3 months agoMITView on GitHub
Run AgentHub's recurring simplification pass to reduce accidental complexity, improve code shape, and reconcile documentation with behavior. Use for a nightly tidy or a focused cleanup slice.
In this repository6 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- new-featureSkill
- releaseSkill
- security-auditSkill
- agenthubSkill
The file
We split this skill into the rules it gives an agent
10 rules. About 0 are common, 8 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈8
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 45
Prefer, in order: what changed recently (a simplification is still cheap and the docs are most likely left behind).
- Very specific: line 58
Read the slice's docs/subsystems/ file before the code.
- Distinctive: line 63
Read for what can be removed or collapsed, not for what could be rewritten to taste.
- Distinctive: line 88
Only when Pass A left the slice genuinely hard to change.
- Distinctive: line 91
Before moving anything, check it is allowed to move:
- Very specific: line 99
If a refactor would be *nicer* but touches any row above, it does not happen here — write it down in the docs/subsystems/ file and leave.
- Distinctive: line 124
A sentence that restates the code: Delete it — it carries no reason and is the sentence most likely to be wrong after the next change.
- Distinctive: line 129
Follow the new-feature skill steps 4–5, unabbreviated — including the worktree and branch teardown.
- Distinctive: line 140
Per slice: stop when a pass produces nothing that clears the bar.
- Distinctive: line 151
Not because they are perfect, but because a scheduled pass is the wrong place to decide them:
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 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.
Files
Nightly tidy
A recurring pass over one slice of the tree, in three concerns — simplify the logic, refactor the
shape, make docs and code agree. It runs against a main nobody is mid-way through and lands by
the new-feature skill.
One rule governs the loop: every change must name the failure it prevents or the reader it helps.
A diff that cannot answer "who is better off" is churn, and churn is not free — main is linear and
several worktrees are usually in flight, so every landed commit is a rebase for everyone else. A
quiet night is a correct outcome. Landing nothing is a correct outcome.
It does not hunt for bugs (the security-audit skill does) and it does not change
behaviour. A behaviour change discovered here becomes a note in the owning docs/subsystems/ file and
then a normal feature branch.
0. Preconditions
git fetch origin
git status --short # must print nothing
git log --oneline -1 origin/main # must equal local main
git worktree list # note what is in flightSkip any package an open worktree is touching. Tidying underneath live work turns one rebase into a conflict, and the branch's author pays for it. If the tree is dirty, stop — a background agent may still be writing.
1. Pick tonight's slice
One package, or one narrow theme across a few. Not the whole tree: a diff nobody can review in one sitting gets landed on trust.
git log --since="2 weeks ago" --name-only --pretty=format: | sort | uniq -c | sort -rn | head -20Prefer, in order: what changed recently (a simplification is still cheap and the docs are most
likely left behind); what carries a recorded gap (grep -rn "Current assembly status"
docs/subsystems/ — one heading, spelled the same in every file, so this finds all of them); then what
nothing has touched in months — least likely to conflict, also least likely to matter.
git worktree add ../agent-hub-tidy-<slice> -b tidy-<slice> origin/mainThe three passes are the subtask list; the draft PR opens on the first commit as usual. Title it
tidy-<slice>: <what was collapsed> — "tidy" alone tells a reader nothing about whether it touches
theirs.
Read the slice's docs/subsystems/ file before the code. Its invariants are what tells a
simplification apart from a regression.
2. Pass A — simplify the logic
Read for what can be removed or collapsed, not for what could be rewritten to taste.
| Worth a commit | Why it clears the bar |
| A branch that cannot be reached | A reader spends time deciding when it fires; the answer is never |
| A helper with one caller, inlined there | The indirection cost a lookup and bought nothing |
| Duplicated logic where one copy has drifted | The drift is the finding; the dedup is the fix |
| An error wrapped twice, or swallowed and re-derived | The message a user sees is assembled twice from one fact |
| A parameter every caller passes the same value for | It reads as a choice that exists, and it does not |
| Dead exported surface with no caller in or out of the tree | Confirm the "out of tree" half before removing |
Not worth a commit: renames for taste, reordering that changes no meaning, comment rewording, splitting a long function that reads fine top to bottom, or a standard-library call that is neither shorter nor clearer.
Never simplify away a fail-closed path. A check that looks redundant with the one above it is usually the second of two independent gates; collapsing them turns two failures into one.
make fmt && make ci
git commit # one commit per finding, naming what it buys3. Pass B — refactor the shape
Only when Pass A left the slice genuinely hard to change. The bar is higher: a refactor must remove a constraint that is blocking work, or delete a whole category of mistake.
Before moving anything, check it is allowed to move:
| About to move | Check |
| A package, command, or identifier name | docs/conventions.md#frozen-identifiers — they do not move on a tidy night |
| An import across a package boundary | AGENTS.md's four hard constraints |
| The gate chain, the call path, provenance for an exposed name, or a tool selector | AGENTS.md's easiest things to get wrong — each of those is frozen, and none of them move on a tidy night |
If a refactor would be nicer but touches any row above, it does not happen here — write it down in
the docs/subsystems/ file and leave. A refactor that does change an invariant or a failure direction
updates that file in the same commit: the next reader's only defence against a silently changed
invariant is that file.
4. Pass C — docs and code agree again
make ci already fails on the mechanical half — dead backticked paths, comments crediting a deleted
test, unresolvable docs/conventions.md citations, prose teaching a retired command, a fuzz target missing
from the Makefile or AGENTS.md, an untranslated English
doc. Do not repeat the machine.
What a human has to read for:
- A documented invariant the code has stopped enforcing. The dangerous one, and it does not get fixed by editing the sentence — restore the enforcement, or, if it was deliberately dropped, say so there and record what now holds instead. A rule that quietly became a suggestion reads exactly like a rule.
- "Capability exists ≠ wired up" gone stale in either direction. A fixed gap that still reads as a gap costs a redundant investigation; an unfixed one that no longer reads as a gap is how "I thought that was in effect" happens.
- A
docs/subsystems/file describing a shape the package no longer has — types renamed, a responsibility moved, a failure direction inverted. - Within-section translation drift.
docs/zh-CN/is checked for its heading skeleton and nothing below it, so a dropped bullet survives. Compare side by side for the sections the slice touched. - A sentence that restates the code. Delete it — it carries no reason and is the sentence most likely to be wrong after the next change.
5. Land it
Follow the new-feature skill steps 4–5, unabbreviated — including the worktree and branch teardown. A tidy branch gets no shortcut; it is the branch most likely to have touched something whose test lives somewhere else. If the slice touched a parser reading untrusted input, this is a fuzz night too:
make fuzz FUZZ=<target> # make ci runs only the seed corporaStop condition
Per slice: stop when a pass produces nothing that clears the bar. Do not lower the bar to fill the night — the bar is the only thing separating this loop from churn.
Per night: one slice, one branch, landed or discarded before you finish. A tidy branch left open overnight conflicts with real work and nobody remembers what it was for.
Across nights: what was found and left alone goes in that package's docs/subsystems/ file; what
was fixed is in git log. A separate ledger is the thing that goes stale first.
Never touch on a tidy night
Not because they are perfect, but because a scheduled pass is the wrong place to decide them:
- The four hard constraints and their proofs in
internal/depguardtest - The gate chain, its order, and any predicate's failure direction
- Frozen identifiers (docs/conventions.md#frozen-identifiers)
VERSIONand.github/workflows/— those belong to the release skill- Any file an open worktree has claimed
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
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.

