Repo Housekeep

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

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.

Step 0: Auto-Detect Project Configuration

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

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)

# Project Name

Brief description from package manifest + actual functionality.

## Tech Stack

[List ONLY what's in the dependency manifest — framework, UI lib, DB, auth, etc.]

## Getting Started

### Prerequisites
[Node version from .nvmrc/engines, other requirements]

### Installation
[Exact commands from package.json scripts]

### Environment Variables
[List from .env.example with descriptions]

### Development
[Dev server command, test command, lint command]

## Project Structure
[Actual directory tree, 2 levels deep]

## Deployment
[From CI/CD config — where it deploys, how]

## Scripts
[All scripts from package.json with descriptions]

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

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

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:

CallMcpTool(server: "user-firecrawl", toolName: "firecrawl_search", arguments: {
 "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

4a. .gitignore Best Practices

Research the recommended .gitignore for the detected ecosystem:

CallMcpTool(server: "user-firecrawl", toolName: "firecrawl_search", arguments: {
 "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

## Housekeep Report — [Project Name]

### Configuration
- Ecosystem: [Node.js / Python / etc.]
- Package Manager: [npm / pnpm / yarn / etc.]
- Framework: [Next.js / React / Django / etc.]

### Phase 1: README Sync
- [x] Root README updated: [list of sections changed]
- [x] Folder READMEs updated: [list]
- Stale sections removed: [list]
- New sections added: [list]

### Phase 2: Dead File Cleanup
| File | Category | Action |
|------|----------|--------|
| path/to/file.log | Log | Deleted |
| path/to/screenshot.png | Screenshot | Deleted |

- .gitignore updated: [patterns added]
- Dead exports found: [list or "none"]

### Phase 3: Dependency Updates
- Vulnerabilities fixed: [count] ([critical/high/moderate])
- Packages updated: [count]
 - Patch: [list]
 - Minor: [list]
 - Major: [list with migration notes]
- Build verified: [pass/fail]
- Tests verified: [pass/fail/no tests]

### Phase 4: General Cleanup
- Config files updated: [list]
- Scripts cleaned: [list]
- .gitignore modernized: [yes/no]
- Env vars audited: [findings]

### Files Modified
- [path] — [description]

### Files Deleted
- [path] — [reason]

### Requires Manual Follow-Up
- [item] — [why it cannot be automated]

Quick Reference: Common Cleanup Commands