Configuring Squad: squad.config.ts and .squad/

Squad has two configuration surfaces. The default — and recommended — approach is markdown-first mode, where your team’s configuration lives in .squad/*.md files that are committed alongside your code. For teams who prefer TypeScript, SDK-first mode lets you define everything in a squad.config.ts file using builder functions, then generate the markdown with squad build. Both approaches produce the same runtime artifacts and support the same features.

Node.js Version Requirement

Squad requires Node.js ≥ 22.5.0. The node:sqlite module — used by the GitHub Copilot SDK for session storage — was introduced in Node 22.5.0. Squad will fail fast with a clear error message if you run it on an older version rather than producing a cryptic ERR_UNKNOWN_BUILTIN_MODULE crash.Upgrade at: nodejs.org/en/download

Markdown-First Configuration

After running squad init, Squad creates a .squad/ directory in your project. All configuration lives in plain markdown and JSON files that you can read, edit, and commit with git. This is the default mode and the most stable configuration surface.

Directory Structure

.squad/
├── team.md                    # Team roster — who is on the team
├── routing.md                 # Routing rules — who handles what type of work
├── decisions/
│   └── inbox/                 # Shared decision log and incoming decisions
├── ceremonies.md              # Sprint ceremony configuration
├── casting/
│   ├── policy.json            # Casting configuration
│   ├── registry.json          # Persistent name registry (do not edit manually)
│   └── history.json           # Universe usage history
├── agents/
│   └── {name}/
│       ├── charter.md         # Agent identity, expertise, and voice
│       └── history.md         # What this agent has learned about YOUR project
├── skills/                    # Compressed learnings extracted from sessions
├── identity/
│   ├── now.md                 # Current team focus
│   └── wisdom.md              # Reusable patterns and team conventions
└── log/                       # Full session history (searchable archive)

Key Files

team.md — Team roster

Lists all active team members and their roles. The coordinator reads this file to understand who is available to take on work. Add a member by appending a new entry; the casting engine will resolve their persistent name from casting/registry.json.

routing.md — Routing rules

Defines which agent handles which type of work. Routing rules are pattern-matched against incoming task descriptions. The defaultAgent handles anything that doesn’t match a specific rule.Example entry:

- Pattern: `testing`
  Agent: @hockney
  Description: Test coverage, Vitest, edge cases, CI quality gates

decisions.md / decisions/inbox/ — Decision log

Every decision any agent makes is recorded here. The decision log is shared across all agents — it is the squad’s collective memory. The inbox/ subdirectory holds incoming decisions awaiting merge into the main log.Do not delete old entries. The cumulative decision history is what allows agents to stay consistent across sessions.

ceremonies.md — Sprint configuration

Configures sprint ceremonies: standup frequency, retro cadence, planning triggers, and any custom ceremony types your team has defined.

agents/{name}/charter.md — Agent identity

Defines an individual agent’s identity, expertise areas, communication style, and behavioral constraints. The charter is the agent’s “personality” — it is the first thing the agent reads at the start of every session.

agents/{name}/history.md — Agent learnings

Persistent learnings that the agent has accumulated about your specific project: your conventions, architecture decisions, testing standards, preferences. Updated after each session. This is what makes Squad agents get smarter over time without re-reading the whole codebase every session.

Do not manually edit casting/registry.json. The casting engine manages the persistent name registry. Manual edits can corrupt the registry and cause agents to lose their persistent identities across sessions. Use squad init or squad preset apply to add agents.

SDK-First Configuration

Experimental. SDK-first mode is under active development and has known bugs. Use markdown-first mode (the default) for production teams. See the SDK-First Mode guide for the current status and known limitations.

Prefer TypeScript over markdown? You can define your entire squad in a squad.config.ts file using builder functions from @bradygaster/squad-sdk. Run squad build to generate all the .squad/*.md files automatically.

Example: squad.config.ts

Here is the real squad.config.ts from the Squad project itself:

import {
  defineSquad,
  defineTeam,
  defineAgent,
  defineRouting,
  defineCasting,
} from '@bradygaster/squad-sdk';

/**
 * Squad Configuration — squad-sdk
 *
 * Converted from .squad/ markdown to SDK-first builder syntax.
 * Run `squad build` to regenerate .squad/*.md from this file.
 */
export default defineSquad({
  version: '1.0.0',

  team: defineTeam({
    name: 'squad-sdk',
    description: 'The programmable multi-agent runtime for GitHub Copilot.',
    projectContext:
      '- **Owner:** Brady\n' +
      '- **Stack:** TypeScript (strict mode, ESM-only), Node.js ≥20, @github/copilot-sdk, Vitest, esbuild\n' +
      '- **Description:** The programmable multi-agent runtime for GitHub Copilot — v1 replatform of Squad beta\n' +
      '- **Distribution:** npm (`npm install -g @bradygaster/squad-cli` for CLI, `npm install @bradygaster/squad-sdk` for SDK)\n' +
      '- **Created:** 2026-02-21',
    members: [
      'keaton', 'verbal', 'fenster', 'hockney', 'mcmanus', 'kujan',
      'edie', 'kobayashi', 'fortier', 'rabin', 'baer', 'redfoot',
      'strausz', 'saul', 'kovash', 'marquez', 'cheritto', 'breedan',
      'nate', 'waingro',
    ],
  }),

  agents: [
    defineAgent({ name: 'keaton', role: 'Lead', description: 'Architect, scope-holder, the one who sees the whole board.', status: 'active' }),
    defineAgent({ name: 'verbal', role: 'Prompt Engineer', description: 'Crafts prompts, charters, and coordinator logic.', status: 'active' }),
    defineAgent({ name: 'fenster', role: 'Core Dev', description: 'Practical, thorough, makes it work then makes it right.', status: 'active' }),
    defineAgent({ name: 'hockney', role: 'Tester', description: 'If it is not tested, it does not work.', status: 'active' }),
    defineAgent({ name: 'mcmanus', role: 'DevRel', description: 'Docs, messaging, developer experience.', status: 'active' }),
    defineAgent({ name: 'kujan', role: 'SDK Expert', description: 'The one who understands the Copilot SDK inside and out.', status: 'active' }),
    defineAgent({ name: 'edie', role: 'TypeScript Engineer', description: 'Precise, type-obsessed. Types are contracts. If it compiles, it works.', status: 'active' }),
    defineAgent({ name: 'kobayashi', role: 'Git & Release', description: 'Semantic versioning, releases, branch protection.', status: 'active' }),
    defineAgent({ name: 'fortier', role: 'Node.js Runtime', description: 'Streaming, event loop health, async iterators, memory profiling.', status: 'active' }),
    defineAgent({ name: 'rabin', role: 'Distribution', description: 'npm packaging, esbuild config, global install, marketplace.', status: 'active' }),
    defineAgent({ name: 'baer', role: 'Security', description: 'Hook design, PII filters, file-write guards, compliance.', status: 'active' }),
    defineAgent({ name: 'redfoot', role: 'Graphic Designer', description: 'Logo, icons, brand assets, design system.', status: 'active' }),
    defineAgent({ name: 'strausz', role: 'VS Code Extension', description: 'VS Code Extension API, runSubagent, editor integration.', status: 'active' }),
    defineAgent({ name: 'saul', role: 'Aspire & Observability', description: 'Aspire dashboard, OTLP integration, Docker telemetry.', status: 'active' }),
    defineAgent({ name: 'kovash', role: 'REPL & Interactive Shell', description: 'Interactive shell, Ink components, session dispatch.', status: 'active' }),
    defineAgent({ name: 'marquez', role: 'CLI UX Designer', description: 'Interaction design, copy, spacing, affordances, UX gates.', status: 'active' }),
    defineAgent({ name: 'cheritto', role: 'TUI Engineer', description: 'Ink components, layout, input handling, rendering perf.', status: 'active' }),
    defineAgent({ name: 'breedan', role: 'E2E Test Engineer', description: 'node-pty harness, Gherkin features, frame snapshots.', status: 'active' }),
    defineAgent({ name: 'nate', role: 'Accessibility Reviewer', description: 'Keyboard nav, color contrast, error guidance, shortcut discoverability.', status: 'active' }),
    defineAgent({ name: 'waingro', role: 'Product Dogfooder', description: 'Adversarial testing, edge cases, regression scenarios.', status: 'active' }),
  ],

  routing: defineRouting({
    rules: [
      { pattern: 'core-runtime', agents: ['@fenster'], description: 'CopilotClient, adapter, session pool, tools module, spawn orchestration' },
      { pattern: 'prompt-architecture', agents: ['@verbal'], description: 'Agent charters, spawn templates, coordinator logic, response tier selection' },
      { pattern: 'type-system', agents: ['@edie'], description: 'Discriminated unions, generics, tsconfig, strict mode, declaration files' },
      { pattern: 'sdk-integration', agents: ['@kujan'], description: '@github/copilot-sdk usage, CopilotSession lifecycle, event handling' },
      { pattern: 'runtime-performance', agents: ['@fortier'], description: 'Streaming, event loop health, session management, async iterators' },
      { pattern: 'testing', agents: ['@hockney'], description: 'Test coverage, Vitest, edge cases, CI/CD, quality gates' },
      { pattern: 'documentation', agents: ['@mcmanus'], description: 'README, API docs, getting-started, demos, tone review' },
      { pattern: 'architecture', agents: ['@keaton'], description: 'Product direction, architectural decisions, code review, scope' },
      { pattern: 'distribution', agents: ['@rabin'], description: 'npm packaging, esbuild config, global install, marketplace prep' },
      { pattern: 'git-releases', agents: ['@kobayashi'], description: 'Semantic versioning, GitHub Releases, CI/CD, branch protection' },
      { pattern: 'security', agents: ['@baer'], description: 'Hook design, PII filters, security review, compliance' },
      { pattern: 'visual-identity', agents: ['@redfoot'], description: 'Logo, icons, brand assets, design system' },
      { pattern: 'observability', agents: ['@saul'], description: 'Aspire dashboard, OTLP integration, Playwright E2E, Docker telemetry' },
      { pattern: 'vscode-integration', agents: ['@strausz'], description: 'VS Code Extension API, runSubagent compatibility' },
      { pattern: 'repl-shell', agents: ['@kovash'], description: 'Interactive shell, Ink components, session dispatch' },
      { pattern: 'cli-ux', agents: ['@marquez'], description: 'Interaction design, copy, spacing, affordances, UX gates' },
      { pattern: 'tui', agents: ['@cheritto'], description: 'Ink components, layout, input handling, focus management' },
      { pattern: 'e2e-tests', agents: ['@breedan'], description: 'node-pty harness, Gherkin features, frame snapshots' },
      { pattern: 'accessibility', agents: ['@nate'], description: 'Keyboard nav, color contrast, error guidance' },
      { pattern: 'hostile-qa', agents: ['@waingro'], description: 'Adversarial testing, edge cases, regression scenarios' },
    ],
    defaultAgent: '@keaton',
    fallback: 'coordinator',
  }),

  casting: defineCasting({
    allowlistUniverses: ['The Usual Suspects', 'Breaking Bad', 'The Wire', 'Firefly'],
    overflowStrategy: 'generic',
  }),
});

After creating this file, run:

squad build

Squad compiles the TypeScript config and writes all the corresponding .squad/*.md files. Use squad build --watch to rebuild on every save.

Builder Functions

Function	Purpose
`defineSquad(config)`	Root config wrapper — accepts `team`, `agents`, `routing`, `casting`
`defineTeam(config)`	Team-level metadata: name, description, project context, members
`defineAgent(config)`	Single agent definition: name, role, description, status, model
`defineRouting(config)`	Routing rules, default agent, fallback strategy
`defineCasting(config)`	Casting policy: allowlisted name universes, overflow strategy

Personal Squad

Use squad init --global to create a personal squad at ~/.config/squad/ (or the platform equivalent) that persists across all projects. Personal squads are ideal for ambient agents that apply your preferences everywhere — code style helpers, personal scribe, cross-project decisions.

# Initialize your personal squad
squad init --global

# Upgrade your personal squad to the latest templates
squad upgrade --global

# Check whether a personal squad is active
squad status

When Squad resolves which team to use, it checks for a project-level .squad/ first. If none is found, it falls back to the personal squad at the global path. squad status shows you which squad is active and why.

Dual-Root Mode

Dual-root mode separates squad state from the working tree — useful for teams that want to share a single squad configuration across multiple projects, or for organizations that want to govern squad templates centrally.

# Initialize the current project pointing to an external squad repo
squad init --mode remote ../shared-team-repo

This writes a .squad/config.json in the current directory pointing to ../shared-team-repo. The actual agent charters, routing rules, and decisions live in the remote repo; the local project just references it. You can also use squad link for a post-hoc connection:

squad link ../shared-team-repo

Environment Variables

Squad respects the following environment variables:

Variable	Description
`NODE_NO_WARNINGS`	Set to `1` automatically by the CLI to suppress Node.js experimental warnings
`SQUAD_TEAM_ROOT`	Override the directory Squad uses to resolve `.squad/`. Useful for subprocesses (e.g. Copilot CLI bang commands) that run in a different working directory than the interactive shell
`SQUAD_ECONOMY_MODE`	Set to `1` to activate economy mode (cost-conscious model selection) for all agent sessions in this process

config.json Reference

Squad writes a .squad/config.json during squad init. You can edit this file directly to configure project-level settings.

{
  "projectKey": "my-project",
  "stateBackend": "local",
  "teamRoot": null,
  "capabilities": {
    "board": false,
    "self-pull": true
  }
}

Field	Description
`projectKey`	Unique key for this squad (used by externalize and state backends)
`stateBackend`	Default state backend: `local`, `orphan`, or `two-layer`
`teamRoot`	Path to an external team root (set by `squad init --mode remote` or `squad link`)
`capabilities`	Default capability flags for Watch mode (can be overridden per-run with CLI flags)

Run squad doctor any time something isn’t working as expected. It validates your .squad/ directory, checks for missing or malformed files, verifies GitHub auth, and surfaces the most common configuration problems with clear remediation steps.

Get Started

CLI Reference

Guides

SDK

Samples & Examples

Configuring Squad: squad.config.ts and .squad/

Node.js Version Requirement

Markdown-First Configuration

Directory Structure

Key Files

SDK-First Configuration

Example: squad.config.ts

Builder Functions

Personal Squad

Dual-Root Mode

Environment Variables

config.json Reference

Build docs developers (and LLMs) love

Get Started

CLI Reference

Guides

SDK

Samples & Examples

Documentation Index

​Node.js Version Requirement

​Markdown-First Configuration

​Directory Structure

​Key Files

​SDK-First Configuration

​Example: squad.config.ts

​Builder Functions

​Personal Squad

​Dual-Root Mode

​Environment Variables

​config.json Reference

Build docs developers (and LLMs) love

Node.js Version Requirement

Markdown-First Configuration

Directory Structure

Key Files

SDK-First Configuration

Example: squad.config.ts

Builder Functions

Personal Squad

Dual-Root Mode

Environment Variables

config.json Reference