🧹 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](#core-capabilities)
2. [The "Do Not" List (Anti-Patterns)](#the-do-not-list-anti-patterns)
3. [Quick Start: Simple Cleanup](#quick-start-simple-cleanup)
4. [Standard Production Patterns](#standard-production-patterns)
5. [Monorepo Deep Cleaning](#monorepo-deep-cleaning)
6. [Safety & Verification Protocols](#safety--verification-protocols)
7. [Automation with deep-clean.sh](#automation-with-deep-cleansh)
8. [Troubleshooting Build Corruption](#troubleshooting-build-corruption)
9. [Reference Library](#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)

⚡ 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](./references/safety-protocols.md) 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 nodemodules or symlink breakage. Fix: rm -rf nodemodules && bun install.

📖 Reference Library

Detailed deep-dives into artifact management:

• [Target Discovery Guide](./references/target-discovery.md): How to find what's eating your disk.
• [Safety Protocols](./references/safety-protocols.md): Protecting your data during cleanup.
• [CI/CD Optimization](./references/cicd-cleanup.md): Best practices for automated pipelines.

Updated: January 22, 2026 - 16:50