Context

The CLI (squad-cli) has bootstrap utilities that run before the Squad SDK is loaded. If these files import SDK code (e.g., FSStorageProvider, anything from squad-sdk), the CLI breaks at startup — no helpful error, just a crash.

This skill applies when:

• Touching any file in packages/squad-cli/src/cli/core/
• Running sweeping refactors (e.g., "convert all fs calls to StorageProvider")
• Adding new bootstrap utilities

Protected File List

Rules

• ❌ NEVER convert these files to use FSStorageProvider, StorageProvider, or any SDK abstraction
• ❌ NEVER add import or require statements referencing packages outside node:* built-ins
• ✅ ONLY use node:fs, node:path, node:child_process, node:util, and other Node.js built-in modules
• ✅ DO check this list before sweeping refactors
• ✅ LOOK for — zero dependencies markers in file headers as a signal

SDK/CLI Package Boundary

The packages/squad-cli/src/cli/core/ directory contains a mix of early-startup bootstrap utilities and later SDK-dependent modules. The protected list above is the authoritative set of zero-dependency bootstrap files. If you need to add SDK imports to another core/ file, verify it is not in the protected list and confirm the SDK is loaded at that point in the startup sequence.

Anti-Patterns

• Converting all fs calls to StorageProvider without checking this list first
• Adding import { X } from '@bradygaster/squad-sdk' to a bootstrap file
• Assuming every file in core/ can safely import SDK code

Adding New Bootstrap Utilities

When adding a new file that runs before SDK init:

1. Add it to the Protected File List table above
2. Write a matching zero-dependency regression test (see detect-squad-dir-zero-deps.test.ts for the pattern)
3. Add — zero dependencies marker in the file header

Regression tests guard these files, but prevention is better than detection.