Squad
A GitHub Copilot team workspace that keeps AI development work persistent, inspectable, and human-led.
Per-dimension scores and reasoning
Evidence shows: README emphasizes human oversight but lacks specific least-privilege mechanisms; user confirmation only appears in 'type yes' example, not systematic; data flow transparency partially described (decisions.md, orchestration-log) but not detailed; sensitive data handling mentions PII scrubbing but not in depth; dependency security has pinning and audit but not comprehensive; external effects include watch mode auto-execution but permission boundaries unclear; rollback has upgrade preserving state but no rollback mechanism; source attribution has maintainer info but unverified. Deductions: most security features are mentioned without implementation details.
Evidence shows: README and test files are consistent, but some inconsistencies exist (e.g., README says 17 commands but table lists more); dependency availability has package.json and lock files but unverified; failure messages have tiered recovery but no specific examples. Deductions: minor inconsistency in self-consistency, dependency availability unverified, failure messages not specific.
Evidence shows: README describes multiple scenarios (quick start, watch mode, SDK mode) with clear audience; capability boundaries described (e.g., 'not a replacement for engineers') but not detailed; trigger precision has routing rule examples but not comprehensive; environment fit has Node version requirements but not all platforms. Deductions: trigger precision and boundary descriptions not detailed enough.
Evidence shows: clear information architecture (README has TOC), detailed install notes, naming stability with aliases, rich examples, known limitations with alpha warning, clear license, versioning with changesets, maintenance responsibility with maintainer list. Deductions: naming stability may change despite aliases, known limitations only mention alpha, changelog not provided, maintenance responsibility unverified.
Evidence shows: output usability with decision logs and breadcrumbs, marginal value with parallel execution and knowledge accumulation, cost-benefit with cost tracking but no actual data. Deductions: cost-benefit lacks real data support.
Evidence shows: some claims in README are supported by tests (e.g., test files), but no cross-validation; facts and inferences not clearly separated. Deductions: limited claim traceability, insufficient cross-validation, facts and inferences not separated.
- This repository is alpha software; APIs and CLI commands may change, use with caution in production.
- Watch mode can auto-execute agents; ensure permission boundaries and approval processes are clear.
- Dependency security not fully verified; recommend security audit before use.
What does this agent do, and when should you use it?
Squad is a human-directed AI development-team system built around GitHub Copilot, delivered as a CLI and TypeScript SDK. It stores the roster, routing rules, decisions, agent histories, and session logs in a repository-local .squad/ directory so team context can persist across sessions and travel with Git. Users interact through copilot --agent squad or the Squad agent in VS Code Copilot Chat, while a coordinator routes work among team members. The CLI covers setup, upgrades, portable imports and exports, remote-team links, and Ralph polling; the SDK can generate Markdown team state from squad.config.ts. The project is explicitly alpha software, and its APIs and CLI commands may change between releases.
squad init creates repository state including .squad/team.md, routing.md, decisions.md, agents/*/charter.md, history.md, identity/, and log/. After a user gives GitHub Copilot a task, the coordinator uses routing.md to delegate work; members operate in separate contexts, read their own knowledge, and write learnings and decisions back to project files. squad upgrade updates squad.agent.md, templates, and GitHub workflows without changing .squad/ team state. squad triage, also available as watch or loop, polls issues, writes an issue-and-team context snapshot to a temporary file, and can invoke a configured agent command when --execute is enabled; its state can use git-notes or an orphan branch. In SDK-first mode, @bradygaster/squad-sdk exposes defineSquad, defineTeam, and defineAgent for a squad.config.ts file, and squad build generates the .squad/ Markdown files.
- A full-stack developer using GitHub Copilot who wants frontend, backend, and testing responsibilities recorded in the repository and retained between sessions.
- A small engineering team managing GitHub Issues that wants squad watch --execute to poll for actionable work and hand execution to Copilot sessions.
- A developer starting a React and Node project who wants squad init --preset default to create an immediately configured team, charters, and routing rules.
- A developer who switches branches often and needs to keep team state outside the working tree by using squad externalize.
- An engineer who prefers defining a team in TypeScript instead of hand-authoring Markdown, using squad.config.ts followed by squad build.
What are this agent's strengths and limitations?
- Persists roster data, routing, decisions, agent history, and searchable session logs in .squad/, allowing team context to be versioned and cloned with the repository.
- Offers CLI, Markdown-first configuration, and an SDK-first TypeScript path that generates team Markdown from squad.config.ts.
- Ralph watch includes issue polling, optional agent dispatch, health reporting, logging, selectable persistence backends, and four tiers of remediation.
- Keeps human accountability explicit: people retain control of priorities, approvals, and final changes.
- Its documented core experience depends on GitHub Copilot, making it platform-specific rather than a documented provider-neutral agent system.
- Adoption requires a recent Node.js runtime, npm, Git SSH setup, and GitHub CLI; Issues, PRs, and Ralph also require GitHub authentication through gh auth login.
- The project is labeled alpha, with documented potential CLI and API changes; SDK-first mode is experimental and has known bugs.
- watch --execute starts agent sessions, and --yolo suppresses per-tool-call approval prompts, so teams need to assess local permissions and review controls.
How do you install or deploy this agent?
Requirements are Node.js >=22.5.0, npm >=10.0.0, Git with an SSH agent, and GitHub CLI for GitHub integration. From a Git repository, run:
npm install -g @bradygaster/squad-cli
squad initAuthenticate for Issues, PRs, and Ralph:
gh auth loginVerify that .squad/team.md exists. For local source development, clone the repository, run npm install and npm run build, then run node ./packages/squad-cli/dist/cli-entry.js init.
How do you use this agent?
Start Squad through GitHub Copilot CLI:
copilot --agent squad --yoloDescribe the project or task in natural language, for example: “I'm starting a new project. Set up the team. Here's what I'm building: a recipe sharing app with React and Node.” Confirm the proposed members to begin. In VS Code, select the Squad agent in Copilot Chat instead. To monitor issues without execution, run npx @bradygaster/squad-cli watch. To dispatch agents for actionable issues, run npx @bradygaster/squad-cli watch --execute --interval 5. For SDK-first mode, create squad.config.ts using @bradygaster/squad-sdk builder functions and run squad build.
How does this agent compare with similar options?
Squad recommends GitHub Copilot CLI as its current interface and deprecates the no-argument squad interactive shell. Its default Markdown-first mode is recommended for production teams, while SDK-first uses squad.config.ts and squad build but is documented as experimental.