| name | protected-files |
| description | Zero-dependency bootstrap files that must never import npm packages or SDK code |
| domain | dependency-safety |
| confidence | high |
| source | earned — CLI startup crashes when bootstrap files import SDK code |
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
| File | Purpose |
|---|
packages/squad-cli/src/cli/core/detect-squad-dir.ts | Finds .squad/ directory at startup — runs before SDK init |
packages/squad-cli/src/cli/core/errors.ts | Error classes (SquadError, fatal()) — used by all CLI entry points |
packages/squad-cli/src/cli/core/gh-cli.ts | GitHub CLI wrapper — uses only node:child_process and node:util |
packages/squad-cli/src/cli/core/output.ts | Color/emoji console output — pure ANSI codes, zero imports |
packages/squad-cli/src/cli/core/history-split.ts | Separates portable knowledge from project data — pure string logic |
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:
- Add it to the Protected File List table above
- Write a matching zero-dependency regression test (see
detect-squad-dir-zero-deps.test.ts for the pattern)
- Add
— zero dependencies marker in the file header
Regression tests guard these files, but prevention is better than detection.
