# Protected Files

> Zero-dependency bootstrap files that must never import npm packages or SDK code

- Skill: `bradygaster/protected-files` (Agent Skill)
- Install (CLI): `npx skillmds@latest add bradygaster/protected-files`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bradygaster/protected-files/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: bradygaster (https://skillmd.com/u/bradygaster)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bradygaster/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**.