Agent Skills: 🧹 Skill: artifact-janitor (v1.1.0)

🧹 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