OpenParable
Skip to content
← Back to skills

Protected Files

Development
protected-files

Protected 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

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
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 fs calls to StorageProvider")
  • Adding new bootstrap utilities

Protected File List

FilePurpose
packages/squad-cli/src/cli/core/detect-squad-dir.tsFinds .squad/ directory at startup — runs before SDK init
packages/squad-cli/src/cli/core/errors.tsError classes (SquadError, fatal()) — used by all CLI entry points
packages/squad-cli/src/cli/core/gh-cli.tsGitHub CLI wrapper — uses only node:child_process and node:util
packages/squad-cli/src/cli/core/output.tsColor/emoji console output — pure ANSI codes, zero imports
packages/squad-cli/src/cli/core/history-split.tsSeparates 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.