Contributing to Squad

Welcome to Squad development. This guide explains how to build, test, and contribute.

Prerequisites

Node.js ≥20.0.0
npm ≥10.0.0 (for workspace support)
Git with SSH agent (for package resolution)
gh CLI (for GitHub integration testing)

Community Guidelines & Spam Protection

Our repository uses automated spam detection to maintain a safe, productive community. Here's what you need to know:

Spam Detection Guidelines

Comment screening — Malicious links (shortened URLs, file-sharing services) and mass-mentions are monitored
Issue evaluation — New issues are reviewed for spam patterns; suspected spam may be auto-closed
Auto-lock stale content — Issues and PRs inactive for 30+ days are locked to prevent spam on old threads

What Gets Flagged

Shortened URLs (bit.ly, tinyurl, t.co, goo.gl, rb.gy)
File-sharing links (Dropbox, Google Drive, Mega, MediaFire)
Crypto/investment scams ("free bitcoin", "guaranteed profit", etc.)
Adult content patterns
Mass-mentions (4+ @-mentions in one comment)
New accounts (< 30 days old) with 0 repos, 0 followers + suspicious content

If Your Content Is Flagged

Comment not posted — If your comment contains flagged patterns, it may be held for review
Issue closed as spam (clear violation) — Likely closed with explanation; contact maintainers if you believe this is a mistake
Issue labeled "suspicious" — Flagged for maintainer review but remains open
Issue locked — If inactive for 30+ days, locked to prevent spam replies

If your legitimate issue/comment is caught by spam detection, please contact a maintainer. We're here to help.

Monorepo Structure

Squad is an npm workspace monorepo with two packages:

squad/
├── packages/squad-cli/       # CLI tool (@bradygaster/squad-cli)
├── packages/squad-sdk/       # Runtime SDK (@bradygaster/squad-sdk)
├── src/                      # Legacy CLI code (migrating to packages/)
├── dist/                     # Compiled output
├── .squad/                   # Team state and agent history
├── docs/                     # Documentation and proposals
└── test-fixtures/            # Test data

Package Independence

squad-sdk: Core runtime, agent orchestration, tool registry. No CLI dependencies.
squad-cli: Command-line interface. Depends on squad-sdk.

Each package has independent versioning via changesets. A change to squad-sdk may bump only squad-sdk; a change to CLI bumps only squad-cli.

Getting Started

1. Clone and Install

Step 1: Fork the repo on GitHub

Go to https://github.com/bradygaster/squad and click "Fork" to create your own copy.

Step 2: Clone your fork

git clone git@github.com:{yourusername}/squad.git
cd squad

Step 3: Add upstream remote

git remote add upstream git@github.com:bradygaster/squad.git

Step 4: Fetch the dev branch

git fetch upstream dev

Step 5: Install dependencies

npm install

npm workspaces automatically links local packages. @bradygaster/squad-cli can import from @bradygaster/squad-sdk without publishing.

2. Build

# Compile TypeScript to dist/
npm run build

# Build + bundle CLI (includes esbuild)
npm run build:cli

# Watch mode (auto-recompile on changes)
npm run dev

3. Test

# Run all tests (Vitest)
npm test

# Watch mode
npm run test:watch

4. Lint

# Type check only (no emit)
npm run lint

5. Keeping Your Fork in Sync

Before opening or updating a PR, rebase your branch on the latest upstream dev:

git fetch upstream
git rebase upstream/dev
git push origin your-branch --force-with-lease

Always rebase before opening or updating a PR to ensure your changes are based on the latest integration branch.

Development Workflow

Creating a Feature Branch

Follow the branch naming convention from .squad/decisions.md:

# For user-facing work, use user_name/issue-number-slug format
git checkout -b bradygaster/217-readme-help-update
# or
git checkout -b keaton/210-resolution-api

# For team-internal work, use agent_name/issue-number-slug
git checkout -b mcmanus/documentation
git checkout -b edie/refactor-router

Before Committing

Compile: npm run build (or npm run dev watch mode)
Test: npm test
Type check: npm run lint

All checks must pass before commit.

Commit Message Format

Keep messages clear and concise. Reference the issue number:

Brief description of change

Longer explanation if needed. Reference #210, #217, etc.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

The Co-authored-by trailer is required for all commits (added by Copilot CLI).

Pull Request Process

Add a changeset: npx changeset add (required before PR — see Changesets section)
Push your branch: git push origin {yourusername}/217-readme-help-update
Create a PR as a draft: gh pr create --draft --base dev --repo bradygaster/squad --head {yourusername}:your-branch
Link the issue: Add Closes #217 to PR description
Work on your changes until CI passes and you're satisfied
Mark as "Ready for review" — this is the handoff signal to the core team (see below)

Handoff: Contributor → Core Team

External contributors don't have write access, so the review-to-merge flow has a handoff point. Here's exactly what happens:

Your side (contributor):

✅ All required CI checks are green (build, test, lint; changeset/CHANGELOG gate only applies when packages/squad-cli/src/ or packages/squad-sdk/src/ files change)
✅ PR is no longer a draft — mark as "Ready for review"
✅ Copilot reviewer bot posts its review automatically
✅ Review Copilot's suggestions and manually apply any you agree with in your fork
✅ Push updates to your branch to address Copilot's feedback
✅ If Copilot flags issues you can't resolve, note them in a PR comment

Note: Copilot review suggestions appear as comments, but the "Commit suggestion" and "Fix with Copilot" buttons require repo write access and won't work for external contributors. Review the suggestions, apply them manually in your fork, and push your changes.

Core team side (after you undraft):

Look for CI-green, undrafted PRs from contributors
Address any remaining Copilot review issues (using "Fix with Copilot" or manual fixes)
Human review, resolve threads, and merge

TL;DR: Your job is done when the PR is undrafted, CI is green, and you've responded to Copilot suggestions. The core team takes it from there.

PR Readiness Checklist

An automated readiness check runs on every PR and posts a checklist comment. Address all items before requesting review:

Check	What it means
Single commit	Squash your commits into one clean commit, or the repo will squash on merge
Not in draft	Mark your PR as "Ready for review" when it's done
Branch up to date	Rebase on latest `dev` (`git fetch upstream && git rebase upstream/dev`)
Copilot review	Wait for the Copilot reviewer bot to post its review
Changeset present	Run `npx changeset add` if you changed files in `packages/squad-sdk/src/` or `packages/squad-cli/src/`
No merge conflicts	Resolve any conflicts with the target branch
CI passing	All CI checks (build, test, lint) must be green

The readiness check is informational — it helps you self-serve before a human reviewer looks at your PR. It automatically re-runs after Squad CI completes, so the checklist stays up to date without manual intervention. See .github/PR_REQUIREMENTS.md for the full requirements spec.

Code Style & Conventions

Squad follows strict TypeScript conventions:

Type Safety: strict: true, noUncheckedIndexedAccess: true
No @ts-ignore — if a type error exists, fix the code
ESM-only — no CommonJS, no dual-package
Async/await — use async iterators for streaming
Error handling: Structured errors with fatal(), error(), warn(), info()
No hype in docs — factual, substantiated claims only (tone ceiling)

Documentation

README.md — User-facing guide, quick start, architecture overview
CONTRIBUTING.md — This file
docs/proposals/ — Design docs for significant changes (required before code)
.squad/agents/[name]/history.md — Agent learnings and project context

All docs in v1 are internal only. No public docs site until v2.

Local Development Versioning

When developing Squad locally, set the package version to {next-version}-preview. For example, if the last published version is 0.8.5.1, the local dev version should be 0.8.6-preview.

This convention makes squad version show the preview tag locally, clearly indicating you're running unreleased source code, not the published npm package. The release agent will bump this to the final version at publish time, then immediately back to the next preview version for continued development.

Making the `squad` Command Use Your Local Build

To make the squad CLI command globally available and pointing to your local development build:

npm run build -w packages/squad-sdk && npm run build -w packages/squad-cli
npm link -w packages/squad-cli

After this, squad version will show 0.8.6-preview (or the current preview version). When you make code changes and rebuild, the squad command automatically picks up the changes—no need to reinstall. To verify your local build is active, the version output should include the -preview tag.

To revert back to the globally installed npm package version, run:

npm unlink -w packages/squad-cli

Changesets: Independent Versioning

Squad uses @changesets/cli for independent package versioning.

When your PR changes SDK or CLI source files (packages/squad-sdk/src/ or packages/squad-cli/src/), add a changeset file instead of editing CHANGELOG.md directly. Changesets prevent merge conflicts when multiple PRs are open simultaneously and are the preferred workflow.

Adding a Changeset

Option A — Interactive (recommended):

npx changeset add

This prompts:

Which packages changed? (squad-sdk, squad-cli, both)
What type? (patch, minor, major)
Brief summary of changes

Creates a file in .changeset/ that's merged with your PR.

Option B — Manual:

Create a file at .changeset/your-change-name.md with frontmatter specifying the package and bump type, followed by a description:

---
'@bradygaster/squad-cli': patch
---

Fix help text rendering for the status command

Changeset Format

The frontmatter lists each affected package and its semver bump type. The body is a human-readable description that will appear in the generated CHANGELOG:

---
"@bradygaster/squad-sdk": minor
"@bradygaster/squad-cli": patch
---

Add streaming support to agent orchestration. Update CLI to display stream progress.

CI Changelog Gate

The changelog-gate CI check enforces that PRs touching SDK/CLI source files include either:

A .changeset/*.md file (preferred), or
A direct CHANGELOG.md edit (backward-compatible)

If neither is present, the check fails. You can bypass it with the skip-changelog label.

Release Workflow

The team runs changesets on the dev branch (via GitHub Actions):

npx changeset publish

This:

Bumps versions in package.json
Generates CHANGELOG.md entries
Publishes to npm
Creates GitHub releases

You don't need to manually version — changesets handle it.

Branch Strategy

main — Stable, published releases. All merges include changesets.
insider — Pre-release features, edge cases. Tag releases as @insider.
bradygaster/dev — Integration branch. All PRs from forks must target this branch, not main.
user/issue-slug — Feature branches from users or agents.

Continuous Integration

GitHub Actions runs on every push:

Build: npm run build and npm run build:cli
Test: npm test
Lint: npm run lint
Changeset status: npm run changeset:check (ensures PRs include a changeset)
Diff Size Guard: Warns when a single-commit PR touches 30+ files (likely branch contamination from staging all files at once on a stale branch). Always use explicit git add <file> instead.

All checks must pass before merge.

Common Tasks

Add a CLI Command

Create the command file in src/cli/commands/[name].js
Add the route in src/index.ts (the main() function)
Update help text in the --help handler
Add tests in test/cli/commands/[name].test.ts
Document in README.md

Add an SDK Export

Implement the feature in src/[module]/
Export from src/index.ts
Add tests
Document in README.md SDK section

Migrate Legacy Code

The src/ directory contains legacy code migrating to packages/squad-cli/ and packages/squad-sdk/. When moving code:

Create the new file in the target package
Update imports in both locations
Ensure tests follow the file
Delete the old src/ file once all references are updated
Document the migration in .squad/agents/[name]/history.md

Key Files

src/index.ts — CLI entry point and routing
src/resolution.ts — Squad path resolution (repo vs. global)
.squad/decisions.md — Team decisions and conventions
.squad/agents/[name]/charter.md — Agent identity and expertise
package.json — Workspace and script definitions

Questions?

Open an issue or ask in .squad/ discussion channels. The team is here to help.

License

All contributions are MIT-licensed. By submitting a PR, you agree to this license.

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History