Workflow housekeep

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:

File	Ecosystem	Package Manager
package.json + package-lock.json	Node.js	npm
package.json + pnpm-lock.yaml	Node.js	pnpm
package.json + yarn.lock	Node.js	yarn
package.json + bun.lockb	Node.js	bun
requirements.txt / pyproject.toml	Python	pip / poetry / uv
Cargo.toml	Rust	cargo
go.mod	Go	go mod
Gemfile	Ruby	bundler
build.gradle / pom.xml	Java/Kotlin	gradle / maven
pubspec.yaml	Dart/Flutter	pub
composer.json	PHP	composer

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:

README Section	Verify Against
Project description	package.json name/description, actual functionality
Tech stack	Installed dependencies in manifest
Getting started / Setup	Actual scripts in package.json, required env vars
Folder structure	Real directory listing
API endpoints	Route files, API handlers
Features list	Actual implemented features (not planned/removed)
Environment variables	.env.example or config files
Deployment	CI/CD config, hosting config
Contributing	Linter config, test setup, pre-commit hooks

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 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

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

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

Classification:

Category	Action
Log files	Delete + add to .gitignore
Screenshots in non-asset dirs	Delete (or move to docs/ if referenced)
Build artifacts	Delete + verify in .gitignore
.bak / .old / .orig files	Delete (git has history)
IDE/OS artifacts	Delete + add to .gitignore
Secret files committed	Delete + rotate secrets + add to .gitignore
Deprecated code files	Verify unused → delete

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

Update Type	Risk	Action
Patch (1.2.3 → 1.2.4)	Low	Auto-update
Minor (1.2.3 → 1.3.0)	Low-Medium	Auto-update, verify build
Major (1.2.3 → 2.0.0)	High	Research changelog first
Security fix (any)	Critical	Update immediately

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

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:

Config	Check
tsconfig.json	Target and lib match Node/browser version in use
eslint config	Not using deprecated rules or legacy config format
prettier config	Exists and is consistent with eslint
.nvmrc / engines	Matches current LTS or team's Node version
browserslist	Not targeting dead browsers
CI/CD config	Not using deprecated actions or outdated Node versions

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

Produce a summary using the Housekeep Report template in 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.