Repo Housekeep

Degree of freedom: MIXED. What is dead vs still referenced [HIGH freedom]; delete-only-after-proof and dependency bump commands [LOW freedom — run exactly].

How to reason

1. Observe — README drift, unused files, outdated deps
2. Interpret — unused by search, or only unused in this package?
3. Classify — sync docs / delete / bump / leave
4. Severity — deleting a file still imported is a break

Worked example

Observe: OldButton.tsx has zero imports; README still lists a removed script; patch bump available.
Interpret: file is dead; README is stale; bump is safe if tests pass.
Classify: delete the file after rg + import check; sync README; bump patch.
Do not delete housekeep-design token work — that is another skill.

Self-critique before reporting

• Proven unused — imports, refs, config, git history checked
• README matches — scripts and paths in the README actually exist
• Tests after bump — dependency update was not a silent break
• Right owner — parked work → housekeep-backlog; token SSOT → housekeep-design; CI gates → housekeep-gates

Full-cycle repository maintenance: documentation sync, dead file removal, dependency updates, and research-driven cleanup. Works with any project — auto-detects tech stack, package manager, and structure.

Critical Rules [LOW freedom — do not skip]

NEVER delete files without confirming they are truly unused.
Check imports, references, git blame, and config entries before removing anything.

NEVER blindly upgrade a major version.
Major bumps may have breaking changes. Research the changelog before upgrading.

README must reflect reality, not aspiration.
Only document what currently exists in the codebase.

Commit each phase separately.
Documentation, cleanup, and dependency updates are independent concerns.

Parked-work register is a different skill.
Unfinished plans, TODOs, skipped tests → housekeep-backlog. This skill
does README / dead files / deps. A housekeep pass may schedule a
backlog regeneration; it does not invent the register.

Step 0: Auto-Detect Project Configuration [LOW freedom — run exactly]

0a. Detect Tech Stack

Read the dependency manifest to determine the ecosystem:

0b. Detect Project Structure

Glob("README*")
Glob("**/*readme*")
Glob("**/CHANGELOG*")
Glob("**/.env*")
Glob("**/*.log")
Glob("**/dist/**")
Glob("**/build/**")
Glob("**/*.screenshot*")
Glob("**/*.png", in test/debug/temp folders)

0c. Record Configuration

ECOSYSTEM: [Node.js / Python / Rust / Go / etc.]
PKG_MANAGER: [npm / pnpm / yarn / bun / pip / poetry / cargo / etc.]
MANIFEST: [package.json / requirements.txt / Cargo.toml / etc.]
LOCKFILE: [package-lock.json / yarn.lock / etc.]
README_PATH: [README.md or detected path]
SRC_DIR: [src/ / app/ / lib/ / etc.]
BUILD_DIR: [dist/ / build/ / .next/ / out/ / etc.]
FRAMEWORK: [Next.js / React / Vue / Django / FastAPI / etc.]

Phase 1: README Sync [HIGH freedom]

Update the root README (and any folder-level READMEs) to reflect the current architecture.

1a. Discover Current Architecture

Read these files to understand what actually exists:

- Package manifest (package.json, etc.) — dependencies, scripts, name, description
- Entry point (src/index.ts, app/layout.tsx, main.py, etc.)
- Config files (next.config.*, vite.config.*, tsconfig.json, etc.)
- CI/CD (.github/workflows/*, vercel.json, netlify.toml, Dockerfile, etc.)
- Environment files (.env.example, .env.local) — list expected env vars
- Folder structure (top-level ls, then 2-level deep ls of src/)

1b. Cross-Check README Against Reality

For each section in the existing README, verify:

1c. Rewrite Stale Sections

For each discrepancy found:

• Missing feature in README: Add it with accurate description
• Removed feature still in README: Delete the section
• Outdated instructions: Update to match current setup
• Missing sections: Add standard sections (see template below)

1d. README Template (adapt to project)

Use the README skeleton in [references/templates.md](references/templates.md) and adapt each section to the detected stack.

1e. Folder READMEs

Check for any *_readme.md or README.md files in subdirectories. Update them if the folder contents have changed.

Phase 2: Dead File Cleanup [LOW freedom — run exactly]

Remove files that serve no purpose in the repository.

2a. Scan for Candidates

Search for these categories of dead files:

Logs and debug output:

Glob("**/*.log")
Glob("**/npm-debug.log*")
Glob("**/yarn-debug.log*")
Glob("**/yarn-error.log*")
Glob("**/debug.log")
Glob("**/.pnpm-debug.log*")

Screenshots and temp images:

Glob("**/screenshot*")
Glob("**/Screenshot*")
Glob("**/*.png", in root or non-asset directories)
Glob("**/*.jpg", in root or non-asset directories)
Glob("**/temp/**")
Glob("**/tmp/**")

Build artifacts committed by mistake:

Glob("**/dist/**")
Glob("**/build/**")
Glob("**/.next/**")
Glob("**/node_modules/**")
Glob("**/__pycache__/**")
Glob("**/*.pyc")
Glob("**/target/debug/**") (Rust)

Deprecated / dead code:

Glob("**/*.bak")
Glob("**/*.old")
Glob("**/*.orig")
Glob("**/*deprecated*")
Glob("**/*DEPRECATED*")
Glob("**/*.backup")
Glob("**/*_old.*")
Glob("**/*_backup.*")
Glob("**/*.tmp")

IDE and OS artifacts:

Glob("**/.DS_Store")
Glob("**/Thumbs.db")
Glob("**/*.swp")
Glob("**/*.swo")

Stale config files:

Glob("**/.env.local") (should not be committed)
Glob("**/.env.production") (check if contains secrets)

2b. Validate Before Deleting

For each candidate file:

1. Check git blame: When was it last modified? By whom?
2. Check imports/references: Is any code importing or referencing this file?

`` Grep for the filename across the codebase ``

1. Check .gitignore: Should this file type already be ignored?
2. Check CI/CD: Does any workflow reference this file?

Classification:

2c. Update .gitignore

After cleanup, ensure .gitignore prevents reoccurrence:

Check existing .gitignore covers:
- logs/ *.log
- build output dist/ build/ .next/ out/
- env files .env.local .env.production
- OS files .DS_Store Thumbs.db
- IDE files .idea/ .vscode/ (unless project uses shared settings)
- temp files *.tmp *.bak *.swp
- dependencies node_modules/ __pycache__/ target/

2d. Find Dead Exports / Unused Code

For TypeScript/JavaScript projects:

Run: npx knip (if available) or npx ts-prune

For Python:

Run: vulture . (if available)

If these tools aren't available, do a manual check:

• Find all exported functions/components
• Check if each has at least one import elsewhere
• Flag unused exports for review

Phase 3: Dependency Updates [HIGH freedom]

3a. Audit Current State

Node.js:

npm outdated # see what's behind
npm audit # check vulnerabilities

Python:

pip list --outdated
pip-audit # or safety check

Rust:

cargo outdated
cargo audit

Go:

go list -m -u all
govulncheck ./...

3b. Classify Updates

3c. Update Strategy

Step 1: Fix vulnerabilities first

npm audit fix # safe fixes only
npm audit fix --force # ONLY if safe fixes insufficient, review changes

Step 2: Update patch + minor

npm update # updates within semver range

Or for more control:

npx npm-check-updates -u -t minor # update package.json to latest minor
npm install # install updated versions

Step 3: Research major updates

For each major version bump available:

firecrawl:firecrawl_search
{
 "query": "<package-name> v<new-major> migration guide changelog breaking changes",
 "limit": 3,
 "sources": [{ "type": "web" }]
}

Only apply major updates if:

• The migration is straightforward (no breaking API changes affecting this project)
• The current major version is EOL or has known security issues
• The project has tests to verify nothing breaks

Step 4: Verify after updates

npm run build # or equivalent
npm run lint # or equivalent
npm test # if tests exist

3d. Lock File Hygiene

• Ensure lock file is committed and up to date
• If lock file has conflicts or corruption: delete and regenerate
• Verify lock file matches the package manager in use

Phase 4: Research-Driven General Cleanup [HIGH freedom]

4a. .gitignore Best Practices

Research the recommended .gitignore for the detected ecosystem:

firecrawl:firecrawl_search
{
 "query": "<framework> gitignore best practices <current year>",
 "limit": 3,
 "sources": [{ "type": "web" }]
}

Cross-check with https://github.com/github/gitignore templates.

4b. Config File Audit

Check for stale or redundant config:

4c. Script Audit

Review all scripts in package.json (or equivalent):

• Remove scripts that reference deleted files or tools
• Verify all scripts actually work
• Add missing standard scripts (dev, build, lint, test, typecheck)

4d. Environment Variable Audit

• Verify .env.example lists all required vars
• Check no .env files with real secrets are committed
• Ensure env var names are consistent with usage in code

4e. TypeScript / Lint Config Modernization

If the project uses TypeScript:

• Check for any type usage that could be tightened
• Verify strict mode settings
• Check for unused @ts-ignore or @ts-expect-error comments

4f. License and Metadata

• package.json: verify name, version, description, license, repository are accurate
• LICENSE file: exists and matches package.json license field
• CONTRIBUTING.md: exists if the project accepts contributions

Phase 5: Summary Report [LOW freedom — do not skip]

Produce a summary using the Housekeep Report template in [references/templates.md](references/templates.md), filling in real values for each phase.

Quick Reference: Common Cleanup Commands

See the per-ecosystem command cheatsheet (outdated / audit / update / build verify for npm, pnpm, yarn, pip, cargo, go) in [references/templates.md](references/templates.md).