SquadAI

Standardize AI coding agent environments.

Why squadai

Modern teams use multiple AI coding agents — OpenCode, Claude Code, Cursor, Windsurf, Copilot — and every developer configures their own differently. The result: inconsistent code quality, no shared methodology, drifting team standards, and no policy enforcement on what each agent is allowed to do.

squadai treats AI agent setup as infrastructure: a single declarative config (.squadai/project.json), a three-layer merge with locked policy fields, and an idempotent apply pipeline that writes the right files for each agent in its native format. Run it once per machine and every developer is on the same setup, regardless of which editor they prefer.

What It Does

One command configures every AI coding agent on your team to use the same methodology, team structure, MCP servers, and coding standards.

squadai init --methodology tdd
squadai apply

That's it. Every developer on the team gets identical agent configurations, regardless of which editor they use.

5 supported agents. OpenCode, Claude Code, VS Code Copilot, Cursor, Windsurf.

9 components. Memory protocols, team rules, editor settings, MCP servers, team agents, methodology skills, commands, plugins, workflows.

3 methodologies. TDD (6 roles), SDD (8 roles), Conventional (4 roles) — each with an orchestrator that delegates to specialized sub-agents.

3 delegation strategies. Native sub-agent files (OpenCode, Cursor), prompt-based Task tool injection (Claude Code), solo all-in-one prompts (VS Code, Windsurf).

MCP integration. Context7 enabled by default. Each agent gets MCP config in its native format.

Community skills. Vercel skills ecosystem integration via the find-skills shared skill.

Quick Start

# Install (macOS / Linux)
brew install PedroMosquera/tap/squadai

# Launch the interactive wizard — recommended for first-time setup.
# It guides you through methodology, MCP servers, plugins, and applies the config.
squadai

# Need help at any time
squadai --help            # global help and command list
squadai <command> --help  # detailed help for a specific command

Prefer scripting? Skip the wizard and run the steps directly:

squadai init --methodology tdd   # initialize project config
squadai plan --dry-run           # preview changes
squadai apply                    # apply configuration
squadai verify                   # check compliance

Other install methods (curl, deb/rpm, go install, AI agent) are documented in the Installation section.

Run squadai with no arguments to launch the interactive TUI wizard (methodology, MCP servers, plugins, summary).

Supported Agents

All detected agents are auto-enabled during init. The planner generates actions only for agents actually installed on each developer's machine.

Supported Languages

Monorepo support: when multiple languages are detected, all language standards are combined.

Components

squadai apply installs up to 9 components per agent:

Not every agent supports every component. Each adapter declares which components it handles; the planner skips unsupported combinations.

Methodologies

Each methodology defines a team of roles with an orchestrator that delegates work to specialized sub-agents.

TDD (6 roles)

SDD (8 roles)

Conventional (4 roles)

Configuration

Three-Layer Merge

Configuration follows strict precedence:

Policy (locked fields)  >  Project config  >  User defaults

Example project.json

{
  "version": 1,
  "methodology": "tdd",
  "adapters": {
    "opencode": { "enabled": true },
    "claude-code": { "enabled": true },
    "vscode-copilot": { "enabled": true },
    "cursor": { "enabled": true },
    "windsurf": { "enabled": true }
  },
  "components": {
    "memory": { "enabled": true },
    "rules": { "enabled": true },
    "settings": { "enabled": true },
    "mcp": { "enabled": true },
    "agents": { "enabled": true },
    "skills": { "enabled": true },
    "commands": { "enabled": true },
    "plugins": { "enabled": true },
    "workflows": { "enabled": true }
  },
  "copilot": {
    "instructions_template": "standard"
  },
  "mcp": {
    "context7": {
      "type": "local",
      "command": ["npx", "-y", "@upstash/context7-mcp@latest"],
      "enabled": true
    }
  },
  "team": {
    "orchestrator": { "description": "TDD orchestrator", "mode": "subagent" },
    "brainstormer": { "description": "Requirements exploration", "mode": "subagent", "skill_ref": "tdd/brainstorming" },
    "planner": { "description": "Test plan creation", "mode": "subagent", "skill_ref": "tdd/writing-plans" },
    "implementer": { "description": "Red-green-refactor cycles", "mode": "subagent", "skill_ref": "tdd/test-driven-development" },
    "reviewer": { "description": "Two-stage code review", "mode": "subagent", "skill_ref": "shared/code-review" },
    "debugger": { "description": "Systematic debugging", "mode": "subagent", "skill_ref": "tdd/systematic-debugging" }
  },
  "meta": {
    "name": "my-project",
    "language": "go",
    "test_command": "go test -race ./...",
    "build_command": "go build ./..."
  }
}

Operational Modes

Commands

Flags

Interactive TUI

Run squadai with no arguments for a guided wizard:

1. Intro screen with detected agents and mode
2. Methodology selection (TDD / SDD / Conventional)
3. MCP server configuration
4. Plugin selection (filtered by methodology and detected agents)
5. Summary and confirmation
6. Menu: Plan, Apply, Verify, Restore, Quit

Review Screen (pre-apply safety)

Interactive squadai apply (and the TUI Apply menu entry) open a review
screen before any file is written. For each planned change you see the
unified diff, the target path, and — when a JSON config already contains a
top-level key SquadAI would write and that key is not recorded in the
sidecar as SquadAI-managed — a conflict row.

Per-conflict keybindings:

Defaults to keep — the user-edited value wins. Only keys you explicitly
flipped to [OVERWRITE] are replaced, and once applied they are recorded in
.squadai/managed.json so future runs treat them as SquadAI-owned (no
conflict on the next apply).

Non-interactive flows

• --no-review skips the TUI. With no override and a conflict present,
  apply returns an error wrapping ErrMergeConflict and leaves the file +
  sidecar untouched.
• --overwrite-unmanaged grants blanket consent — SquadAI will overwrite any
  user-owned top-level key it needs to write. Combine with --no-review in
  CI when you've already decided to claim the config.
• squadai diff --json emits a conflicts array per entry so CI pipelines
  can detect drift without the TUI.

Architecture

Six-layer architecture with strict dependency direction:

Layer 1: Domain       Types, interfaces, errors (no side effects)
Layer 2: Config       Three-layer merge with policy enforcement
Layer 3: Planner      Compute actions from merged config + detected adapters
Layer 4: Pipeline     Execute actions with backup/rollback safety
Layer 5: Verifier     Post-apply compliance assertions
Layer 6: Interfaces   CLI commands, TUI wizard

Key design principles:

• Adapters own all paths. No hardcoded agent paths outside adapter packages.
• Marker blocks for managed content. User content outside <!-- squadai:SECTION --> markers is never modified.
• Atomic writes. Temp file + rename via fileutil.WriteAtomic for crash safety.
• Idempotent by default. Planner returns ActionSkip when state matches; writer skips when bytes are identical.
• Fail loudly. Errors are always surfaced, never silently swallowed.

Full architecture details: docs/architecture.md

Safety

Every apply operation:

1. Snapshots all target files to a backup manifest
2. Executes steps in deterministic order with step-level logging
3. On failure, rolls back all completed steps from the manifest
4. Emits a failure summary with the backup ID for manual recovery

Installation

Homebrew (macOS / Linux) — recommended

brew install PedroMosquera/tap/squadai

To upgrade:

brew upgrade squadai

The formula is published to PedroMosquera/homebrew-tap automatically by every release.

Linux native packages (deb / rpm)

Every release publishes .deb and .rpm packages alongside the tarballs. Download the matching package from Releases:

# Debian / Ubuntu
sudo dpkg -i squadai_<version>_linux_<arch>.deb

# Fedora / RHEL / openSUSE
sudo rpm -i squadai_<version>_linux_<arch>.rpm

The binary lands at /usr/bin/squadai.

Shell script (macOS / Linux)

curl -sSL https://raw.githubusercontent.com/PedroMosquera/squadai/main/scripts/install.sh | sh

From source (requires Go 1.24+)

go install github.com/PedroMosquera/squadai/cmd/squadai@latest

GitHub Releases

Download the binary for your architecture from Releases.

Install via your AI agent

If you use Claude Code, OpenCode, Cursor, Windsurf, or VS Code Copilot, paste this prompt into your agent and let it install squadai for you:

Install squadai on this machine following the numbered steps in the "Agent install protocol" section of https://github.com/PedroMosquera/squadai/blob/main/README.md. After install, run squadai doctor and report back any failed checks.

Agent install protocol

Agents: follow these steps in order. Stop at the first method that succeeds.

1. Detect the OS and architecture with uname -sm.
2. Pick the best install method available, in this order:
   1. If brew is on PATH (macOS or Linux): brew install PedroMosquera/tap/squadai.
   2. Else if apt is available (Debian/Ubuntu) and the user can sudo: download the matching .deb from the latest GitHub release and sudo dpkg -i.
   3. Else if dnf or rpm is available (Fedora/RHEL): download the matching .rpm and sudo rpm -i.
   4. Else if curl is available (macOS / Linux): curl -sSL https://raw.githubusercontent.com/PedroMosquera/squadai/main/scripts/install.sh | sh.
   5. Else if go (>= 1.24) is on PATH: go install github.com/PedroMosquera/squadai/cmd/squadai@latest.
   6. Else: stop and tell the user to install one of brew, curl, or go first.
3. Verify the install: squadai version must print a non-empty version string.
4. Run health checks: squadai doctor. If any checks fail, run squadai doctor --fix and re-run squadai doctor.
5. Offer to initialize the workspace: ask the user if they want to run squadai init in the current directory before doing it. Do not run init without confirmation.

Do not modify shell rc files, do not install with sudo unless step 2 explicitly requires it, and do not edit any project files outside the squadai install itself.

Self-update (built-in)

Once installed, squadai can check for and apply its own updates:

squadai update --enable-checks   # opt in to once-per-day background checks
squadai update --check           # see if a newer release exists
squadai update                   # download + stage the latest; applies on next launch

Updates are disabled by default to avoid background network activity. The self-updater skips the swap if the binary lives in a system-managed path (e.g. installed via Homebrew) — use brew upgrade squadai instead.

Windows

Windows binaries (squadai_<version>_windows_<arch>.zip) are published to every release. Native installer support (Scoop / WinGet) is coming soon. For now:

# Option 1: from source (requires Go 1.24+)
go install github.com/PedroMosquera/squadai/cmd/squadai@latest

# Option 2: download the .zip from https://github.com/PedroMosquera/squadai/releases/latest
# and extract squadai.exe to a directory on your PATH.

Platform Support

Development Process

SquadAI uses Spec-Driven Development for its own changes. The openspec/ directory tracks
in-flight specs (changes/), living specs (specs/), and completed work (archive/).
See openspec/config.yaml for workflow rules and testing conventions.

Author

Built by Pedro Mosquera — software engineer focused on developer tooling, clean architecture, and AI-assisted workflows.

• GitHub: @PedroMosquera

Feedback, issues, and pull requests are welcome.

License

MIT