🧹 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

1. Core Capabilities
2. The "Do Not" List (Anti-Patterns)
3. Quick Start: Simple Cleanup
4. Standard Production Patterns
5. Monorepo Deep Cleaning
6. Safety & Verification Protocols
7. Automation with deep-clean.sh
8. Troubleshooting Build Corruption
9. Reference Library

---

🚀 Core Capabilities

• Artifact Discovery: Identifying multi-gigabyte build caches and redundant dependencies.
• Deep Cleanup: Removing recursive node_modules and 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 build

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

Bun Workspace Cleanup

# Bun is fast, but its cache can grow
bun pm cache rm

---

🛡 Safety & Verification Protocols

1. Dry Run First: Always visualize the deletion path.
2. Size Check: du -sh is your best friend.
3. Process Check: Ensure no node, bun, or vite processes are locking the files.
4. Verification: After cleaning, run bun x tsc --noEmit to 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-run mode.

# 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