protected-files

## 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: 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**.