# Squad Conventions

Core conventions and patterns used in the Squad codebase

- Repository: https://github.com/microsoft/waza (1496 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-10-31
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add microsoft/waza --skill squad-conventions -g -a claude-code -y`
Codex: `npx skills add microsoft/waza --skill squad-conventions -g -a codex -y`
Cursor: `npx skills add microsoft/waza --skill squad-conventions -g -a cursor -y`
Gemini CLI: `npx skills add microsoft/waza --skill squad-conventions -g -a gemini-cli -y`

## Description

Core conventions and patterns used in the Squad codebase

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

## 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 from `templates/` (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.

The rest: https://github.com/microsoft/waza/blob/HEAD/.github/skills/squad-conventions/SKILL.md