Run the recurring housekeeping pass — audit the agent files for rot, the glossary against the code, the decision index, the mutation measurement, the worktrees and the diary, then scan the codebase for Ousterhout's red flags and route each finding to the skill that owns it. It never fixes what it finds; findings leave as candidate tickets. Its one write of its own is stamping the diary's Last housekeeping row, and its one delegated action is the worktree pruning it hands to the cleanup skill. Use when the docs gate's housekeeping-due advisory fires, on the cadence the gate config names, or before cutting a release.
88%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Passed
No findings from the security scan
Standing instructions rot on a calendar, not on an event. Counts drift, a
quick-reference row outlives the thing it points at, a glossary term stops
matching the code, a suite goes green for a year because nothing measured
whether it could fail. The kit's protocols are all event-triggered; this skill
is the one pass that runs because time passed. The docs gate's
housekeeping-due advisory is what sends you here, and stamping the diary's
Last housekeeping row is how you send it away.
Project context — read these first, they are the parts this file cannot know:
- The root manual
AGENTS.mdand its articles underconstitution/— the standing instructions this pass audits.- Domain language:
docs/domain-glossary.md, including its banned words and its context map.- Decision records:
docs/adr/and its index.- The engineering article:
constitution/local-engineering.md(stamped from its template) — its test tiers, its mutation decision, and its three architecture anchors.- The diary:
docs/diary.md— the Current state block this pass reads and the row it stamps.- The gate config:
scripts/docs-conformance/config.mjs—housekeepingDue.windowDaysis the cadence.- Capability tiers: the pass is
plannerwork — its findings constrain the tickets that follow.sh scripts/agents.lib.sh plannerresolves the model when you spawn the scan; nothing printed means the spawn inherits this session's model.
It finds and routes; it never fixes. A repair by the session that found
the drift destroys the only independent reading anyone had of it, and it
smuggles a behaviour change into an audit (shared invariant §10). Every
finding leaves as a candidate ticket through /to-tickets, a deepening
candidate for /improve-codebase-architecture, or a re-question for
/design-brief. The one write this pass performs itself is the diary stamp;
the one action it delegates is item 5's pruning, which /worktree-cleanup
performs on worktrees and branches already merged — nothing unmerged is
touched.
.template,
or the repo has none (a template repository is one). Item 4 then reads the
repo's own suites and records that no measurement is wired; that is itself
the finding, once the codebase has a layer worth measuring.Each item names its source, so the pass is the same every time. The full
form of each — what to look at, what counts as a finding, what to route it
to — is in CHECKLIST.md; this is the order.
none is itself a finding once the codebase has
grown past the reason it gives. Source: shared invariant §9./worktree-cleanup, then compare the diary's Active
worktrees row with what is on disk, and list the dispatch scratch left on
the host. Source: the root manual's first hard rule.housekeepingDue.windowDays still the right
window for this repo's pace? Source: the gate config's own comment./improve-codebase-architecture with the file and the flag./design-brief./to-tickets, one finding per
ticket, with the checklist item it came from and the evidence.AGENTS.md, agent trust boundary).$TMPDIR, falling back to /tmp (or %TEMP% on
Windows), write <tmpdir>/housekeeping-<YYYYMMDDTHHMMSSZ>.md: one entry
per finding with its item number, its evidence, and its route. A pass
that finds nothing says so, per item./to-tickets for the ticket
candidates, the architecture skill for the deepenings, the brief for the
re-question — and stop there: invoking them is the human's next act, and
this pass's one write stays the stamp.| **Last housekeeping** | <today, ISO, UTC> — <one line: how many findings, and the one that matters most> | in the diary's Current
state table. UTC, because the advisory that reads the row compares against
UTC midnight, and the report's own timestamp is UTC too. One local commit, docs(housekeeping): …; this skill never
pushes.Written for this kit. The agent-file audit condenses Addy Osmani's "Audit your Agent files" (2026); the red-flag list is John Ousterhout's, from A Philosophy of Software Design; the never-fix rule is the same one the optional dogfood skill keeps, for the same reason.
agranado2k/ai-report-platform
caeb0da
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.