Squad Conventions
Core conventions and patterns used in the Squad codebase
Install
npx skills add microsoft/waza --skill squad-conventions -g -a claude-code -y- Repository
- microsoft/waza1.5k
- Category
- Engineering
- Updated
- 4d ago
- License
- MIT
- Context cost
- Lightabout 807 tokens
- Runs scripts
- No, instructions only
What it does
Core conventions and patterns used in the Squad codebase
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.squad/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.
