SDK-First Mode: Define Your Team in TypeScript

SDK-first mode lets you define your entire Squad team in TypeScript using strongly-typed builder functions. Run squad build to generate all the .squad/ markdown files automatically — perfect for teams that prefer code over prose configuration, or that want to version-control their team shape as structured data and derive the markdown from it.

SDK-first mode is experimental. The builder API is stable enough for everyday use, but the generated markdown format may change between minor versions. For production teams that require long-term stability, consider using markdown-first authoring and treating squad.config.ts as a secondary representation.

The squad.config.ts file

Place a squad.config.ts file at the root of your repository. The file must export a defineSquad(…) call as its default export. Here is the real configuration from the Squad SDK repository itself, trimmed to show the first five agents:

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

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\n' +
      '- **Distribution:** npm (`@bradygaster/squad-cli` for CLI, `@bradygaster/squad-sdk` for SDK)\n' +
      '- **Created:** 2026-02-21',
    members: [
      'keaton', 'verbal', 'fenster', 'hockney', 'mcmanus',
      // … more members
    ],
  }),

  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' }),
    // … more agents
  ],

  routing: defineRouting({
    rules: [
      { pattern: 'core-runtime',    agents: ['@fenster'],    description: 'CopilotClient, adapter, session pool, tools module' },
      { pattern: 'prompt-architecture', agents: ['@verbal'], description: 'Agent charters, spawn templates, coordinator logic' },
      { pattern: 'type-system',     agents: ['@edie'],       description: 'Discriminated unions, generics, tsconfig, strict mode' },
      { pattern: 'testing',         agents: ['@hockney'],    description: 'Test coverage, Vitest, edge cases, CI/CD' },
      { pattern: 'documentation',   agents: ['@mcmanus'],    description: 'README, API docs, getting-started, demos' },
    ],
    defaultAgent: '@keaton',
    fallback: 'coordinator',
  }),

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

The top-level structure is always: defineSquad({ team, agents, routing, … }). Each section is validated at startup — if you pass a warnAt outside [0, 1] or forget a required name, you get a BuilderValidationError with a clear message before any agent runs.

Builder functions reference

`defineSquad(config)`

The top-level composition function. Accepts the full SquadSDKConfig object and validates all nested sections by delegating to their respective builders. Your squad.config.ts default export must be the return value of this call.

version

string

A semantic version string for the config itself (e.g. "1.0.0"). Used for future migration tooling.

team

TeamDefinition

required

Team metadata. Pass the return value of defineTeam(…).

agents

AgentDefinition[]

required

Array of agent definitions. Each element must be the return value of defineAgent(…).

routing

RoutingDefinition

Typed routing rules. Pass the return value of defineRouting(…).

casting

CastingDefinition

Casting configuration. Pass the return value of defineCasting(…).

hooks

HooksDefinition

Governance hook pipeline. Pass the return value of defineHooks(…).

telemetry

TelemetryDefinition

OpenTelemetry configuration. Pass the return value of defineTelemetry(…).

defaults

DefaultsDefinition

Squad-level defaults applied to all agents unless overridden. Pass the return value of defineDefaults(…).

skills

SkillDefinition[]

Array of reusable skill definitions. Each element must be the return value of defineSkill(…).

`defineTeam(config)`

Define team metadata, project context, and the member roster.

name

string

required

Human-readable team name shown in the Squad UI and coordinator prompts.

description

string

One-sentence description of the team’s purpose.

projectContext

string

Markdown string injected into coordinator context at session start. Use it to describe the stack, owner, and key conventions. Multiline strings are supported.

members

string[]

required

Array of agent name strings (without @ prefix) that make up the team roster.

`defineAgent(config)`

Define a single agent with its role, charter path, model preference, tools, and capability profile.

defineAgent({
  name: 'edie',
  role: 'TypeScript Engineer',
  description: 'Precise, type-obsessed. Types are contracts.',
  charter: '.squad/agents/edie/charter.md',
  model: 'claude-sonnet-4',
  tools: ['grep', 'edit', 'powershell'],
  capabilities: [{ name: 'type-system', level: 'expert' }],
  status: 'active',
})

name

string

required

Unique agent identifier used for routing, casting, and @mentions.

role

string

required

Short role title shown in the coordinator dashboard and cast display.

description

string

One-sentence description of the agent’s personality and focus area.

charter

string

Path to the agent’s markdown charter file. When set, squad build copies the charter content into the generated .squad/agents/{name}/charter.md.

model

string | ModelPreference

Model override for this agent. Pass a string model ID or a { preferred, rationale?, fallback? } object for preference-ranked selection. When omitted the team defaults.model applies.

tools

string[]

List of Copilot tool names this agent is allowed to use. Omit to inherit the default tool set.

capabilities

AgentCapability[]

Structured capability declarations. Each entry is { name: string, level: 'expert' | 'proficient' | 'basic' }. Used by the casting engine and skill matcher.

status

'active' | 'inactive' | 'retired'

Lifecycle status. Inactive and retired agents are excluded from automatic casting. Defaults to 'active'.

`defineRouting(config)`

Define typed routing rules that direct incoming requests to the right agent.

defineRouting({
  rules: [
    { pattern: 'feature-*',   agents: ['@edie'],    tier: 'standard',     priority: 1 },
    { pattern: 'docs-*',      agents: ['@mcmanus'], tier: 'lightweight'              },
    { pattern: 'arch-review', agents: ['@keaton'],  description: 'Senior arch review' },
  ],
  defaultAgent: '@keaton',
  fallback: 'coordinator',
})

rules

RoutingRule[]

required

Ordered array of routing rules. Rules are matched top-to-bottom; the first match wins.

rules[].pattern

string

required

Keyword or pattern used to match incoming task descriptions or labels.

rules[].agents

string[]

required

Agents (with @ prefix) to route matching tasks to.

rules[].tier

'direct' | 'lightweight' | 'standard' | 'full'

Response tier override for tasks matching this rule. Affects model selection and timeout budgets.

rules[].priority

number

Numeric priority for tie-breaking when multiple rules match. Lower values win.

rules[].description

string

Human-readable description shown in routing debug output.

defaultAgent

string

Agent that receives tasks when no rule matches. Typically the team lead or coordinator.

fallback

'ask' | 'default-agent' | 'coordinator'

Behavior when the default agent is unavailable. 'ask' prompts the user, 'default-agent' tries the registered default, 'coordinator' escalates to the team coordinator.

`defineCasting(config)`

Configure which character universes the casting engine may draw from, and how to handle overflow when the preferred universe is exhausted.

defineCasting({
  allowlistUniverses: ['The Usual Suspects', 'Breaking Bad', 'The Wire'],
  overflowStrategy: 'generic',
  capacity: { 'The Usual Suspects': 8 },
})

allowlistUniverses

string[]

Universe names that the casting engine is permitted to draw from. If omitted, all built-in universes are available.

overflowStrategy

'reject' | 'generic' | 'rotate'

How to handle a request when all slots in a universe are filled. 'reject' returns an error, 'generic' assigns a generic persona, 'rotate' wraps around the roster.

capacity

Record<string, number>

Per-universe capacity override. Keys are universe names; values are the maximum number of cast members drawn from that universe.

`defineHooks(config)`

Define the governance hook pipeline. See Hooks & Tools for full documentation.

defineHooks({
  allowedWritePaths: ['src/**', 'test/**', '.squad/**'],
  blockedCommands:   ['rm -rf /', 'DROP TABLE'],
  maxAskUser:        3,
  scrubPii:          true,
  reviewerLockout:   true,
})

`defineTelemetry(config)`

Configure OpenTelemetry export for the Squad runtime.

defineTelemetry({
  enabled:       true,
  endpoint:      'http://localhost:4317',
  serviceName:   'squad',
  sampleRate:    1.0,
  aspireDefaults: true,
})

enabled

boolean

Master switch for OTel export. Defaults to false.

endpoint

string

OTLP gRPC exporter endpoint (e.g. http://localhost:4317). Defaults to the standard OTLP environment variable OTEL_EXPORTER_OTLP_ENDPOINT if set.

serviceName

string

Service name tag added to all spans and metrics. Defaults to 'squad'.

sampleRate

number

Trace sample rate between 0.0 (none) and 1.0 (all). Defaults to 1.0.

aspireDefaults

boolean

When true, applies .NET Aspire-compatible defaults (OTLP endpoint from OTEL_EXPORTER_OTLP_ENDPOINT, resource attributes from OTEL_RESOURCE_ATTRIBUTES).

`defineDefaults(config)`

Define squad-level defaults that apply to every agent unless the agent explicitly overrides them.

defineDefaults({
  model: {
    preferred: 'claude-sonnet-4',
    rationale:  'Good balance of speed and quality',
    fallback:   'claude-haiku-4.5',
  },
  budget: {
    perSession: 100_000,
    warnAt:     0.8,
  },
})

model

string | ModelPreference

Default model for all agents. Accepts a plain string model ID or a ModelPreference object with preferred, optional rationale, and optional fallback fields.

budget

BudgetDefinition

Default budget applied to all agents. Individual agents may override via their own budget field.

`defineBudget(config)`

Define token and cost budgets. Can be used at the squad defaults level or per-agent.

defineBudget({
  perAgentSpawn: 50_000,   // max tokens per individual agent spawn
  perSession:    200_000,  // max tokens across the whole session
  warnAt:        0.8,      // emit a warning at 80% utilization
})

perAgentSpawn

number

Maximum tokens allowed for a single agent spawn. Must be a finite positive number.

perSession

number

Maximum tokens allowed across all agents in one session. Must be a finite positive number.

warnAt

number

Fraction of the budget at which a warning is emitted. Must be between 0.0 and 1.0 (e.g. 0.8 = warn at 80%).

Generating markdown

Once your squad.config.ts is in place, run squad build from the repository root:

# Generate .squad/ from squad.config.ts
squad build

squad build transpiles your TypeScript config through the SDK’s builder pipeline and writes all .squad/*.md files. The output is semantically identical to what squad init creates interactively — the same agent charters, routing tables, and casting configuration — but derived from code rather than typed prose.

The generated .squad/ directory should be committed to git. Team members who do not have the SDK installed can still read the markdown files directly. Regenerate after every change to squad.config.ts.

Model selection

Configure per-agent models inside defineAgent using either a string shorthand or the full ModelPreference shape:

// String shorthand — pin a specific model
defineAgent({
  name: 'edie',
  role: 'TypeScript Engineer',
  model: 'claude-sonnet-4',
})

// Preference object — fallback-aware selection
defineAgent({
  name: 'fenster',
  role: 'Core Dev',
  model: {
    preferred: 'claude-opus-4',
    rationale:  'Long-context reasoning for complex refactors',
    fallback:   'claude-sonnet-4',
  },
})

Squad applies the defaults.model to any agent that does not specify its own. That means you can set one sensible default for the team and only override where it matters.

Budget control

Use defineBudget to cap token spend at the team level, the individual agent level, or both:

export default defineSquad({
  // …
  defaults: defineDefaults({
    model: 'claude-sonnet-4',
    budget: defineBudget({
      perSession:    200_000,  // whole-session cap
      warnAt:        0.8,
    }),
  }),

  agents: [
    // Heavy analysis agent gets its own higher cap
    defineAgent({
      name: 'keaton',
      role: 'Lead',
      budget: defineBudget({
        perAgentSpawn: 100_000,
      }),
    }),
    // Lightweight agents inherit the team default
    defineAgent({ name: 'hockney', role: 'Tester' }),
  ],
})

Budget values are soft limits enforced by the SDK’s cost-tracker. Exceeding perSession causes the session to terminate gracefully rather than hard-kill an in-flight agent.

What’s next

Hooks & Tools

Learn how to register pre- and post-tool-use hooks for file-write guards, PII scrubbing, and reviewer lockout.

SDK Overview

See all SDK exports organized by category.

Get Started

CLI Reference

Guides

SDK

Samples & Examples

SDK-First Mode: Define Your Team in TypeScript

The squad.config.ts file

Builder functions reference

`defineSquad(config)`

`defineTeam(config)`

`defineAgent(config)`

`defineRouting(config)`

`defineCasting(config)`

`defineHooks(config)`

`defineTelemetry(config)`

`defineDefaults(config)`

`defineBudget(config)`

Generating markdown

Model selection

Budget control

What’s next

Hooks & Tools

SDK Overview

Build docs developers (and LLMs) love

Get Started

CLI Reference

Guides

SDK

Samples & Examples

Documentation Index

​The squad.config.ts file

​Builder functions reference

​defineSquad(config)

​defineTeam(config)

​defineAgent(config)

​defineRouting(config)

​defineCasting(config)

​defineHooks(config)

​defineTelemetry(config)

​defineDefaults(config)

​defineBudget(config)

​Generating markdown

​Model selection

​Budget control

​What’s next

Hooks & Tools

SDK Overview

Build docs developers (and LLMs) love

The squad.config.ts file

Builder functions reference

`defineSquad(config)`

`defineTeam(config)`

`defineAgent(config)`

`defineRouting(config)`

`defineCasting(config)`

`defineHooks(config)`

`defineTelemetry(config)`

`defineDefaults(config)`

`defineBudget(config)`

Generating markdown

Model selection

Budget control

What’s next