Protected Files
Developmentprotected-filesProtected Files is an Agent Skill for development published in the bradygaster/squad repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Zero-dependency bootstrap files that must never import npm packages or SDK code
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/bradygaster/squad/blob/HEAD/.copilot/skills/protected-files/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/protected-files, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
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
fscalls toStorageProvider") - 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
importorrequirestatements referencing packages outsidenode:*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 dependenciesmarkers 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
fscalls toStorageProviderwithout 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.tsfor the pattern) - Add
— zero dependenciesmarker in the file header
Regression tests guard these files, but prevention is better than detection.