bradygaster/squad

Squad – Human‑directed AI development teams (alpha)

What it is – Squad is a productivity tool that lets a single developer create and manage a team of AI agents (frontend, backend, tester, lead, etc.) that live inside a Git repository. The agents are powered by GitHub Copilot and are coordinated through a CLI (@bradygaster/squad-cli). The team persists as markdown files under a .squad/ folder, so the “knowledge” they accumulate travels with the code.

Key concepts

• Team definition – squad init scaffolds a .squad/ directory containing team.md, routing.md, decisions.md, and per‑agent folders with a charter and history.
• Human‑in‑the‑loop – The human stays the decision‑maker; agents only automate coordination, repetitive coding, triage, and testing. All actions are logged and reviewable.
• Watch mode (Ralph) – An optional daemon polls GitHub issues/PRs, auto‑triages them, and can spawn Copilot agents to work on the issue automatically. It supports configurable state back‑ends (in‑memory, git‑notes, orphan branch) and a tiered error‑recovery strategy.
• CLI commands – 17 first‑class commands (init, upgrade, triage, copilot, nap, aspire, etc.) cover setup, upgrades, health checks, externalizing state, exporting/importing squads, and plugin/marketplace management.
• SDK‑first mode – Besides the default markdown‑driven configuration, developers can define the squad in TypeScript (squad.config.ts) using @bradygaster/squad-sdk, then generate the markdown files with squad build.
• GitHub Agentic Workflows – Squad can be installed as a reusable GitHub Agentic Workflow, enabling slash‑command control from issue comments.

Typical workflow

1. mkdir my‑project && git init
2. npm install -g @bradygaster/squad-cli && squad init
3. Authenticate with gh auth login
4. In VS Code open Copilot Chat and select the Squad agent (or run copilot --agent squad --yolo).
5. Describe the project (e.g., “a recipe‑sharing app with React and Node”).
6. Squad proposes a roster of agents; confirm with yes.
7. Agents start working in parallel—frontend builds UI, backend creates APIs, tester writes tests, etc.—while the human reviews PRs and approves decisions.

Installation

• CLI (global): npm install -g @bradygaster/squad-cli
• From source: clone the repo, npm install (workspace), npm run build, then npm run dev:link to link a development version globally.
• .NET preview: a NuGet package Squad.Agents.AI is available under src/Squad.Agents.AI for Microsoft Agent Framework integration.

Status – Alpha (badge in README). APIs and CLI flags are expected to change; breaking changes are recorded in CHANGELOG.md.

Who might use it

• Solo developers who want AI‑assisted parallelism without losing oversight.
• Small teams looking to prototype an “AI‑augmented” workflow that lives in the repo.
• Researchers or hobbyists experimenting with agent orchestration, GitHub Copilot, and automated issue triage.

Where to learn more

• Full command reference is in the README (tables for each command and flag).
• SDK documentation (docs/src/content/docs/reference/sdk.md).
• Sample projects (samples/README.md).
• GitHub Agentic Workflows guide (link in the README).

---

All details above are taken directly from the repository’s README; no additional features have been inferred.