# bradygaster/squad architecture

> Architecture diagram of the GitHub repository bradygaster/squad, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bradygaster/squad
- Repository: https://github.com/bradygaster/squad

## Overview

Squad is a human-led multi-agent development product for GitHub Copilot. The documented path is to initialize a project team, propose and confirm agents, then direct work through Copilot, where requests are routed to specialists whose knowledge and decisions persist in project state. The repository also includes issue triage, platform integrations, plugins, team sharing, remote control, and a .NET adapter. The README establishes the user workflow; sampled source confirms casting and storage behavior, but does not expose enough call sites to assert all subsystem wiring.

Main entry points: [`packages/squad-cli/src/cli-entry.ts`](https://github.com/bradygaster/squad/blob/dev/packages/squad-cli/src/cli-entry.ts) (Squad CLI), [`packages/squad-sdk/src/coordinator/coordinator.ts`](https://github.com/bradygaster/squad/blob/dev/packages/squad-sdk/src/coordinator/coordinator.ts) (Request coordinator), [`packages/squad-sdk/src/agents/lifecycle.ts`](https://github.com/bradygaster/squad/blob/dev/packages/squad-sdk/src/agents/lifecycle.ts) (Agent lifecycle), [`packages/squad-cli/src/cli/commands/watch/index.ts`](https://github.com/bradygaster/squad/blob/dev/packages/squad-cli/src/cli/commands/watch/index.ts) (Issue watch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Team setup"]
  node_cli["Squad CLI<br/>[cli-entry.ts]"]
  node_commands["CLI commands"]
  node_initialization["Team initialization<br/>[init.ts]"]
  node_casting["Agent casting<br/>[casting-engine.ts]"]
  node_roles["Role catalog<br/>[catalog.ts]"]
  node_configuration["Team configuration<br/>[routing.ts]"]
end

subgraph group_runtime["Agent runtime"]
  node_coordinator["Request coordinator<br/>[coordinator.ts]"]
  node_agents["Agent lifecycle<br/>[lifecycle.ts]"]
  node_memory["Agent memory<br/>[index.ts]"]
  node_state["Squad state<br/>[squad-state.ts]"]
  node_storage["Storage providers"]
end

subgraph group_operations["Operations"]
  node_watch["Issue watch<br/>[index.ts]"]
  node_ralph["Triage capabilities<br/>[capabilities.ts]"]
end

subgraph group_integrations["Integrations"]
  node_platforms["Platform connectors<br/>[index.ts]"]
  node_marketplace["Plugin marketplace<br/>[index.ts]"]
  node_sharing["Team sharing<br/>[index.ts]"]
  node_remote["Remote control<br/>[index.ts]"]
  node_dotnet[".NET agent adapter"]
end

node_human(("Human operator"))
node_copilot["GitHub Copilot"]
node_github["GitHub services"]
node_projectstate[("Project team files")]

node_human -->|"runs commands"| node_cli
node_cli -->|"dispatches"| node_commands
node_commands -->|"initializes team"| node_initialization
node_initialization -->|"creates team files"| node_projectstate
node_human -->|"directs work"| node_copilot
node_copilot -->|"submits requests"| node_coordinator
node_coordinator -->|"routes requests"| node_configuration
node_coordinator -->|"coordinates agents"| node_agents
node_agents -->|"uses knowledge"| node_memory
node_agents -->|"persists learnings"| node_state
node_state -->|"stores state"| node_storage
node_cli -->|"starts triage"| node_watch
node_watch -->|"loads capabilities"| node_ralph
node_watch -->|"checks work items"| node_platforms
node_platforms -.->|"integrates with"| node_github
node_cli -->|"manages plugins"| node_marketplace
node_cli -->|"exports or imports"| node_sharing
node_copilot -.->|"remote access"| node_remote
node_dotnet -->|"reads squad folder"| node_projectstate

click node_cli "https://github.com/bradygaster/squad/blob/dev/packages/squad-cli/src/cli-entry.ts"
click node_commands "https://github.com/bradygaster/squad/tree/dev/packages/squad-cli/src/cli/commands"
click node_initialization "https://github.com/bradygaster/squad/blob/dev/packages/squad-sdk/src/config/init.ts"
click node_casting "https://github.com/bradygaster/squad/blob/dev/packages/squad-sdk/src/casting/casting-engine.ts"
click node_roles "https://github.com/bradygaster/squad/blob/dev/packages/squad-sdk/src/roles/catalog.ts"
click node_configuration "https://github.com/bradygaster/squad/blob/dev/packages/squad-sdk/src/config/routing.ts"
click node_coordinator "https://github.com/bradygaster/squad/blob/dev/packages/squad-sdk/src/coordinator/coordinator.ts"
click node_agents "https://github.com/bradygaster/squad/blob/dev/packages/squad-sdk/src/agents/lifecycle.ts"
click node_memory "https://github.com/bradygaster/squad/blob/dev/packages/squad-sdk/src/memory/index.ts"
click node_state "https://github.com/bradygaster/squad/blob/dev/packages/squad-sdk/src/state/squad-state.ts"
click node_storage "https://github.com/bradygaster/squad/blob/dev/packages/squad-sdk/src/storage/storage-provider.ts"
click node_watch "https://github.com/bradygaster/squad/blob/dev/packages/squad-cli/src/cli/commands/watch/index.ts"
click node_ralph "https://github.com/bradygaster/squad/blob/dev/packages/squad-sdk/src/ralph/capabilities.ts"
click node_platforms "https://github.com/bradygaster/squad/blob/dev/packages/squad-sdk/src/platform/index.ts"
click node_marketplace "https://github.com/bradygaster/squad/blob/dev/packages/squad-sdk/src/marketplace/index.ts"
click node_sharing "https://github.com/bradygaster/squad/blob/dev/packages/squad-sdk/src/sharing/index.ts"
click node_remote "https://github.com/bradygaster/squad/blob/dev/packages/squad-sdk/src/remote/index.ts"
click node_dotnet "https://github.com/bradygaster/squad/blob/dev/src/Squad.Agents.AI/SquadServiceCollectionExtensions.cs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_commands,node_initialization,node_casting,node_roles,node_configuration toneBlue
class node_coordinator,node_agents,node_memory,node_state,node_storage,node_projectstate toneAmber
class node_watch,node_ralph toneMint
class node_platforms,node_marketplace,node_sharing,node_remote,node_dotnet toneRose
class node_human,node_copilot,node_github toneIndigo
```

## Components

### Team setup

- [Squad CLI](https://github.com/bradygaster/squad/blob/dev/packages/squad-cli/src/cli-entry.ts): `packages/squad-cli/src/cli-entry.ts`
- [CLI commands](https://github.com/bradygaster/squad/tree/dev/packages/squad-cli/src/cli/commands): `packages/squad-cli/src/cli/commands`
- [Team initialization](https://github.com/bradygaster/squad/blob/dev/packages/squad-sdk/src/config/init.ts): `packages/squad-sdk/src/config/init.ts`
- [Agent casting](https://github.com/bradygaster/squad/blob/dev/packages/squad-sdk/src/casting/casting-engine.ts): `packages/squad-sdk/src/casting/casting-engine.ts`
- [Role catalog](https://github.com/bradygaster/squad/blob/dev/packages/squad-sdk/src/roles/catalog.ts): `packages/squad-sdk/src/roles/catalog.ts`
- [Team configuration](https://github.com/bradygaster/squad/blob/dev/packages/squad-sdk/src/config/routing.ts): `packages/squad-sdk/src/config/routing.ts`

### Agent runtime

- [Request coordinator](https://github.com/bradygaster/squad/blob/dev/packages/squad-sdk/src/coordinator/coordinator.ts): `packages/squad-sdk/src/coordinator/coordinator.ts`
- [Agent lifecycle](https://github.com/bradygaster/squad/blob/dev/packages/squad-sdk/src/agents/lifecycle.ts): `packages/squad-sdk/src/agents/lifecycle.ts`
- [Agent memory](https://github.com/bradygaster/squad/blob/dev/packages/squad-sdk/src/memory/index.ts): `packages/squad-sdk/src/memory/index.ts`
- [Squad state](https://github.com/bradygaster/squad/blob/dev/packages/squad-sdk/src/state/squad-state.ts): `packages/squad-sdk/src/state/squad-state.ts`
- [Storage providers](https://github.com/bradygaster/squad/blob/dev/packages/squad-sdk/src/storage/storage-provider.ts): `packages/squad-sdk/src/storage/storage-provider.ts`

### Operations

- [Issue watch](https://github.com/bradygaster/squad/blob/dev/packages/squad-cli/src/cli/commands/watch/index.ts): `packages/squad-cli/src/cli/commands/watch/index.ts`
- [Triage capabilities](https://github.com/bradygaster/squad/blob/dev/packages/squad-sdk/src/ralph/capabilities.ts): `packages/squad-sdk/src/ralph/capabilities.ts`

### Integrations

- [Platform connectors](https://github.com/bradygaster/squad/blob/dev/packages/squad-sdk/src/platform/index.ts): `packages/squad-sdk/src/platform/index.ts`
- [Plugin marketplace](https://github.com/bradygaster/squad/blob/dev/packages/squad-sdk/src/marketplace/index.ts): `packages/squad-sdk/src/marketplace/index.ts`
- [Team sharing](https://github.com/bradygaster/squad/blob/dev/packages/squad-sdk/src/sharing/index.ts): `packages/squad-sdk/src/sharing/index.ts`
- [Remote control](https://github.com/bradygaster/squad/blob/dev/packages/squad-sdk/src/remote/index.ts): `packages/squad-sdk/src/remote/index.ts`
- [.NET agent adapter](https://github.com/bradygaster/squad/blob/dev/src/Squad.Agents.AI/SquadServiceCollectionExtensions.cs): `src/Squad.Agents.AI/SquadServiceCollectionExtensions.cs`

### Other components

- **Human operator**
- **GitHub Copilot**
- **GitHub services**
- **Project team files**

## Connections

- Human operator → Squad CLI: runs commands
- Squad CLI → CLI commands: dispatches
- CLI commands → Team initialization: initializes team
- Team initialization → Project team files: creates team files
- Human operator → GitHub Copilot: directs work
- GitHub Copilot → Request coordinator: submits requests
- Request coordinator → Team configuration: routes requests
- Request coordinator → Agent lifecycle: coordinates agents
- Agent lifecycle → Agent memory: uses knowledge
- Agent lifecycle → Squad state: persists learnings
- Squad state → Storage providers: stores state
- Squad CLI → Issue watch: starts triage
- Issue watch → Triage capabilities: loads capabilities
- Issue watch → Platform connectors: checks work items
- Platform connectors → GitHub services: integrates with
- Squad CLI → Plugin marketplace: manages plugins
- Squad CLI → Team sharing: exports or imports
- GitHub Copilot → Remote control: remote access
- .NET agent adapter → Project team files: reads squad folder