squad-conventions
Core conventions and patterns used in the Squad codebase
- License 许可
- MIT
- 所属仓库
- github/squad
- 最近更新
- 2026-11-15
- Stars
- ★ 3.4k
- Forks
- 520
01 前言 Front Matter
- name
- squad-conventions
- domain
- project-conventions
- source
- manual
- confidence
- high
- description
- Core conventions and patterns used in the Squad codebase
03 SKILL.md 正文
Context
These conventions apply to all work on the Squad CLI tool (create-squad). Squad is a zero-dependency Node.js package that adds AI agent teams to any project. Understanding these patterns is essential before modifying any Squad source code.
Patterns
Zero Dependencies
Squad has zero runtime dependencies. Everything uses Node.js built-ins (fs, path, os, child_process). Do not add packages to dependencies in package.json. This is a hard constraint, not a preference.
Node.js Built-in Test Runner
Tests use node:test and node:assert/strict — no test frameworks. Run with npm test. Test files live in test/. The test command is node --test test/.
Error Handling — fatal() Pattern
All user-facing errors use the fatal(msg) function which prints a red ✗ prefix and exits with code 1. Never throw unhandled exceptions or print raw stack traces. The global uncaughtException handler calls fatal() as a safety net.
ANSI Color Constants
Colors are defined as constants at the top of index.js: GREEN, RED, DIM, BOLD, RESET. Use these constants — do not inline ANSI escape codes.
File Structure
.squad/— Team state (user-owned, never overwritten by upgrades).squad/templates/— Template files copied fromtemplates/(Squad-owned, overwritten on upgrade).github/agents/squad.agent.md— Coordinator prompt (Squad-owned, overwritten on upgrade)templates/— Source templates shipped with the npm package.copilot/skills/— Team skills in SKILL.md format (user-owned).squad/decisions/inbox/— Drop-box for parallel decision writes
Windows Compatibility
Always use path.join() for file paths — never hardcode / or \ separators. Squad must work on Windows, macOS, and Linux. All tests must pass on all platforms.
Init Idempotency
The init flow uses a skip-if-exists pattern: if a file or directory already exists, skip it and report "already exists." Never overwrite user state during init. The upgrade flow overwrites only Squad-owned files.
Copy Pattern
copyRecursive(src, target) handles both files and directories. It creates parent directories with { recursive: true } and uses fs.copyFileSync for files.
Examples
// Error handling
function fatal(msg) {
console.error(`${RED}✗${RESET} ${msg}`);
process.exit(1);
}
// File path construction (Windows-safe)
const agentDest = path.join(dest, '.github', 'agents', 'squad.agent.md');
// Skip-if-exists pattern
if (!fs.existsSync(ceremoniesDest)) {
fs.copyFileSync(ceremoniesSrc, ceremoniesDest);
console.log(`${GREEN}✓${RESET} .squad/ceremonies.md`);
} else {
console.log(`${DIM}ceremonies.md already exists — skipping${RESET}`);
}
Anti-Patterns
- Adding npm dependencies — Squad is zero-dep. Use Node.js built-ins only.
- Hardcoded path separators — Never use
/or\directly. Alwayspath.join(). - Overwriting user state on init — Init skips existing files. Only upgrade overwrites Squad-owned files.
- Raw stack traces — All errors go through
fatal(). Users see clean messages, not stack traces. - Inline ANSI codes — Use the color constants (
GREEN,RED,DIM,BOLD,RESET).
04 同仓库更多 Skills
windows-compatibility
Cross-platform path handling and command patterns
versioning-policy
SemVer rules for Squad's stable, preview, insider, and local package versions
tiered-memory
Three-tier agent memory model (hot/cold/wiki) for context reduction per spawn
test-discipline
Design assertions that prove the actual contract and fail on realistic regressions
squad
Squad's command catalog and interactive menu. Invoke via /squad (slash command) or natural language ("squad commands", "what can squad do", "show me squad options"). Presents categorized operations (Install & Upgrade, Team Management, Issues & PRs, Plugins & Skills, Model & Cost, Sessions & State) as an interactive picker. Routes to the right squad CLI command or the Squad coordinator agent.
squad-version-check
Internals of how @bradygaster/squad-cli stamps its version, how `squad upgrade` works (what it preserves vs overwrites), and how to probe the npm registry for the latest version from a coordinator prompt.