🧹 Skill: artifact-janitor (v1.1.0)
Executive Summary
The artifact-janitor is a tactical skill designed to maintain a clean, efficient, and healthy development environment. In 2026, where monorepos can easily exceed 5GB in dependencies and build caches (Turborepo, Next.js), proactive management of build artifacts is no longer optional—it is a performance requirement.
📋 Table of Contents
- Core Capabilities
- The "Do Not" List (Anti-Patterns)
- Quick Start: Simple Cleanup
- Standard Production Patterns
- Monorepo Deep Cleaning
- Safety & Verification Protocols
- Automation with deep-clean.sh
- Troubleshooting Build Corruption
- Reference Library
🚀 Core Capabilities
- Artifact Discovery: Identifying multi-gigabyte build caches and redundant dependencies.
- Deep Cleanup: Removing recursive
node_modulesand hidden cache directories (.next,.turbo). - Build Health Restoration: Resolving "ghost errors" caused by corrupted build artifacts or stale TS build info.
- Space Optimization: Drastically reducing project size for archiving or sharing.
🚫 The "Do Not" List (Anti-Patterns)
| Anti-Pattern | Why it fails in 2026 | Modern Alternative |
|---|---|---|
Manual rm -rf | Prone to typos (e.g., rm -rf / node_modules). | Use the deep-clean.sh script or specific tool commands. |
Deleting .git | Destroys repository history and identity. | NEVER delete .git unless detaching a repo. |
Deleting .env | Loss of critical local secrets/keys. | Add .env to a "Protected" list. |
| Blind Deletion in CI | Can break incremental build performance. | Use targeted cache invalidation rather than total wipes. |
Ignoring .cache | Many modern tools store GBs in hidden user-level caches. | Include ~/.cache and framework-specific caches in discovery. |
⚡ Quick Start: Simple Cleanup
If you just need to free up some quick space or fix a minor build glitch:
# 1. Analyze space
du -sh node_modules .next
# 2. Targeted removal
rm -rf .next/
rm -rf node_modules/
# 3. Restore
bun install🛠 Standard Production Patterns
Pattern A: The "Ghost in the Machine" Fix
Use this when your code is correct but the build is failing with strange errors.
# Clean all caches and build info
rm -rf .next tsconfig.tsbuildinfo .turbo
# Re-generate everything
bun run buildPattern B: The Pre-Archive Scrub
Use this before zipping a project or pushing a massive refactor to ensure no local artifacts interfere.
# Using the janitor script in dry-run first
./skills/artifact-janitor/scripts/deep-clean.sh --dry-run
# Execute if safe
./skills/artifact-janitor/scripts/deep-clean.sh📦 Monorepo Deep Cleaning
In 2026, monorepos are the norm. Standard rm doesn't scale.
pnpm Workspace Cleanup
# Remove all node_modules in every package
pnpm -r exec rm -rf node_modules
# Clean pnpm global store (use with caution)
pnpm store pruneBun Workspace Cleanup
# Bun is fast, but its cache can grow
bun pm cache rm🛡 Safety & Verification Protocols
- Dry Run First: Always visualize the deletion path.
- Size Check:
du -shis your best friend. - Process Check: Ensure no
node,bun, orviteprocesses are locking the files. - Verification: After cleaning, run
bun x tsc --noEmitto ensure the project structure is still valid.
*See References: Safety Protocols for more.*
🤖 Automation with deep-clean.sh
We provide a robust script in skills/artifact-janitor/scripts/deep-clean.sh.
Features:
- Recursive discovery of 20+ artifact types.
- Automatic sizing of reclaimed space.
- Safety-first
--dry-runmode.
# Usage
./skills/artifact-janitor/scripts/deep-clean.sh [options]
# Options:
# --dry-run : Only show what would be deleted.
# --force : Skip confirmation (use with caution).🔍 Troubleshooting Build Corruption
"Property X does not exist on type Y" (but it does)
Cause: Stale tsconfig.tsbuildinfo or .next/types. Fix: rm tsconfig.tsbuildinfo && rm -rf.next.
"Module not found" (after changing branches)
Cause: Stale node_modules or symlink breakage. Fix: rm -rf node_modules && bun install.
📖 Reference Library
Detailed deep-dives into artifact management:
- Target Discovery Guide: How to find what's eating your disk.
- Safety Protocols: Protecting your data during cleanup.
- CI/CD Optimization: Best practices for automated pipelines.
*Updated: January 22, 2026 - 16:50*