v0.8.21

Changelog

All notable changes to this project will be documented in this file.

[0.8.21] - 2026-03-11

Added — SDK-First Mode (Phase 1)

• Builder functions — Type-safe team configuration with runtime validation
  • defineTeam() — Team metadata, project context, member roster
  • defineAgent() — Agent definition with role, model, tools, capabilities
  • defineRouting() — Routing rules with pattern matching and priority
  • defineCeremony() — Ceremony scheduling (standups, retros, etc.)
  • defineHooks() — Governance hooks (write paths, blocked commands, PII scrubbing)
  • defineCasting() — Casting configuration (universe allowlists, overflow strategy)
  • defineTelemetry() — OpenTelemetry configuration
  • defineSquad() — Top-level composition builder
• squad build command — Compile TypeScript definitions to .squad/ markdown
  • Generates .squad/team.md, .squad/routing.md, agent charters, ceremonies
  • Supports --check (validation), --dry-run (preview), --watch (file monitoring stub)
  • Protected files (decisions.md, history.md) never overwritten
• SDK Mode Detection — Coordinator prompt includes SDK-First mode awareness
• Documentation
  • New guide: SDK-First Mode — concepts, builder reference, examples
  • Updated SDK Reference — builder function signatures and types
  • README quick reference for SDK-First teams

Added — Remote Squad Mode (ported from @spboyer's bradygaster/squad#131)

• resolveSquadPaths() dual-root resolver — project-local vs team identity directories
• squad doctor command — 9-check setup validation with emoji output
• squad link <path> command — link a project to a remote team root
• squad init --mode remote — initialize with remote team root config
• ensureSquadPathDual() / ensureSquadPathResolved() — dual-root write guards

Fixed — Critical Crash & Stability Issues

• Installation crash fix (#247) — npx @bradygaster/squad-cli was failing on fresh installs due to hard dependency on @opentelemetry/api that couldn't resolve in isolated npm environments. Created otel-api.ts resilient wrapper with full no-op fallbacks. Moved OTel to optional dependencies. Telemetry now gracefully degrades when absent.
• CLI command wiring (#244) — Commands rc, copilot-bridge, init-remote, rc-tunnel were implemented but never wired into CLI entry point. Now properly connected and discoverable.
• Model config round-trip (#245) — AgentDefinition.model now accepts string | ModelPreference for structured model configuration. Charter compiler updated to emit and parse the new format correctly.
• ExperimentalWarning suppression — Node's ExperimentalWarning for node:sqlite no longer leaks into terminal output. Suppressed via process.emit override in cli-entry.ts.
• Blankspace fix (#239) — Idle blank space below agent panel removed. Conditional height constraint only active during processing.
• Windows race condition (EBUSY) — fs.rm with retry logic and exponential backoff. Tests now pass reliably on Windows.
• Test hardening — Speed gate threshold adjustments for growing CLI codebase. 25 regression tests fixed (PR #221).
• CI stabilization — GitHub Actions pipeline fixed and green (PRs #232, #228).

Changed — Distribution & Versioning

• Distribution: npm-only distribution channel. No more GitHub-native distribution (npx github:bradygaster/squad). Users now install via npm install -g @bradygaster/squad-cli or npx @bradygaster/squad-cli from npm registry.
• Semantic Versioning fix (#692): Version format changed from X.Y.Z.N-preview to X.Y.Z-preview.N to comply with semantic versioning spec (prerelease identifier after patch, build metadata after prerelease). Example: 0.8.6-preview.1 instead of 0.8.6.1-preview.
• Version transition: Public repo final version was 0.8.5.1. Private repo continues at 0.8.x cadence (next publish after 0.8.17 is 0.8.18), following semver prerelease convention for development.

Community

• Thanks to Shayne Boyer (@spboyer) for the original remote mode design.
• PR #199 (migration command) received, reviewed, and feedback captured as issue #231 for future implementation.
• PR #243 (blankspace fix) — community contribution cherry-picked and credited.

By the Numbers

• 26 issues closed
• 16 PRs merged
• 3,724 tests passing (3,740 total, 13 known Windows timeout flakes, 0 logic failures)
• 8 builder functions shipped
• 4 CLI commands wired
• 1 critical crash fix (OTel dependency)
• 25 regression tests fixed

[Unreleased]

[0.8.20] - 2025-01-08

Fixed

• Template path fix (#190): Corrected all references from .squad-templates/ to .squad/templates/ to align with the project's directory structure. This ensures the CLI correctly resolves team member charters and other template resources.
• Init test templates: Updated initialization tests to reference the corrected .squad/templates/ directory path.

[0.8.18-preview] - TBD

Added — Remote Squad Mode (ported from @spboyer's bradygaster/squad#131)

• resolveSquadPaths() dual-root resolver — project-local vs team identity directories (#311)
• squad doctor command — 9-check setup validation with emoji output (#312)
• squad link <path> command — link a project to a remote team root (#313)
• squad init --mode remote — initialize with remote team root config (#313)
• ensureSquadPathDual() / ensureSquadPathResolved() — dual-root write guards (#314)

Changed — npm Distribution & Monorepo Structure

• Distribution: Migrated from GitHub-native (npx github:bradygaster/squad) to npm packages (npm install -g @bradygaster/squad-cli / npx @bradygaster/squad-cli)
• Packages: Independent versioning via @changesets/cli — @bradygaster/squad-sdk and @bradygaster/squad-cli evolve on separate cadences
• Structure: Monorepo layout with workspace packages (SDK + CLI)
• Directory: .squad/ directory structure (migration from .ai-team/)
• Semantic Versioning: All versions now comply with semver spec (prerelease format X.Y.Z-preview.N)

Fixed

• CLI entry point moved from dist/index.js to dist/cli-entry.js. If you reference the binary directly, update your path. npx and npm bin resolution is unchanged. (#187)
• CRLF normalization: All parsers now normalize line endings before parsing. Windows users with core.autocrlf=true no longer get \r-tainted values. (#220, #221)
• process.exit() removed from library-consumable functions. VS Code extensions can now safely import CLI functions without risking extension host termination. (#189)
• Removed .squad branch protection guard (squad-main-guard.yml) — no longer needed with npm workspace files field exclusions

Internal

• New utility: normalizeEol() in src/utils/normalize-eol.ts
• New entry point: src/cli-entry.ts (CLI bootstrap separated from library exports)
• Migrated to npm workspace publishing (@bradygaster/squad-sdk, @bradygaster/squad-cli)
• Changesets infrastructure for independent package versioning

v0.8.20

v0.8.20 Release

Fixes

• fix: propagate template path fix (#190) — Template directory references have been standardized from .squad-templates/ to .squad/templates/ for consistency with the project structure.
• fix(test): update references in init test — Updated initialization tests to use the new .squad/templates/ path.

Changes Since v0.8.19

This release includes critical template path corrections that ensure the CLI correctly resolves team member charters and other template resources in the .squad/templates/ directory.

v0.8.19 — Nap & Doctor Commands, Template Path Fix

What's New

New Commands

• *\squad nap* — Context hygiene engine restored. Supports --deep\ and --dry-run\ flags for managing .squad/ state cleanliness.
• *\squad doctor* — Diagnostic tool now wired into CLI entry point. Fixes issue #188.

Bug Fixes

• Template install path (PR #185 by @williamhallatt) — Corrected template resolution from .squad-templates/\ to .squad/templates/.
• Documentation improvements — Features section added to docs, broken link fixes, migration guide updated with file-safety table.

Community Contributions

• @williamhallatt — PR #185: Template path fix
• @CarlosSardo — PR #178: GitLab Issues walkthrough and feature reference docs

Documentation

• 19 feature docs synced to main branch
• Migration guide enhanced with file safety table
• Features section integrated into navigation

---

Released: | Package Versions: @bradygaster/squad-sdk@0.8.19, @bradygaster/squad-cli@0.8.19

v0.8.18 — Migration: GitHub-native → npm Distribution

🎉 Migration Complete: GitHub-native → npm Distribution

Breaking Changes

• Distribution: Moved from GitHub-native (
  px github:bradygaster/squad) to npm packages
• Directory: Configuration moved from .ai-team/ to .squad/ (format changes apply)
• Package Names:
  • Old: @bradygaster/create-squad (deprecated)
  • New: @bradygaster/squad-cli (CLI) and @bradygaster/squad-sdk (SDK)
• Monorepo Structure: Public repo now uses npm workspaces

New Installation

Install Squad CLI globally:
\\�ash
npm install -g @bradygaster/squad-cli@latest
\\

Or use with npx:
\\�ash
npx @bradygaster/squad-cli --version
\\

Upgrade Guide

See Migration Guide for detailed upgrade instructions and configuration migration steps.

Version Jump

v0.5.4 → v0.8.18 (intermediate versions consolidated for migration release)

Release Notes

• Full monorepo migration to npm distribution
• Consult mode implementation included
• .squad/ directory configuration system
• Enhanced team-based agent routing

For more details, see CHANGELOG.

v0.5.4 — Ralph heartbeat cron disabled by default

Bug Fixes

• Ralph heartbeat cron disabled by default — The 30-minute cron schedule in \squad-heartbeat.yml\ was consuming excessive GitHub Actions minutes for users with multiple Squad-enabled repos. The cron is now disabled by default. Ralph still auto-triages on issue close/label and PR close events (zero extra cost). Fixes #158.

Upgrade

Run
px github:bradygaster/squad upgrade\ to get the updated heartbeat workflow. Existing cron schedules will be replaced with the disabled-by-default version.

Details

See #158 for the full problem description and resolution.

v0.5.3

What's New in v0.5.3

Bug Fixes

• Windows EPERM fallback — \safeRename()\ catches EPERM/EACCES errors (VS Code file watchers hold handles on Windows), falls back to copy+delete. Fixes #135, PR #149.
• --version\ now shows installed version —
  px github:bradygaster/squad --version\ now shows both the installed Squad version AND the Copilot CLI version on separate lines. Fixes #137, PR #149.
• Content replacement in migrate-directory — When migrating from .ai-team/\ to .squad/, file contents (not just paths) now get .ai-team/\ references replaced with .squad/. Fixes #134, PR #151.

Behavior Change

• Guard workflow removed — The \squad-main-guard.yml\ workflow that blocked .squad/\ files from reaching main/preview has been removed. .squad/\ files now flow freely to all branches. Users who want to exclude .squad/\ can use .gitignore. Existing installations get the guard auto-deleted on next \squad upgrade\ (v0.5.4 migration). Fixes #150, PR #152.

Community

• Responded to and closed community issues #146, #145, #139
• Filed 4 port issues on squad-pr (#548-551) for cross-repo parity

Looking Ahead

The next release of Squad will be more significant than prior releases, bringing Squad to NPM for easier installation. The package will still ship from this repository, so existing users will see a transparent change. Issues or PRs filed between now and that release may be held until the next update is complete.

We appreciate the community's continued support and look forward to sharing what's coming.

Full Changelog: v0.5.2...v0.5.3

v0.5.2

Full Changelog: v0.5.1...v0.5.2

v0.5.2-insider+234b2a6

This is an insider/development build of Squad. Install with:bash\nnpx github:bradygaster/squad#v0.5.2-insider+234b2a6\n\n\nNote: Insider builds may be unstable and are intended for early adopters and testing only.

v0.5.1 — squad watch (Ralph Local Watchdog)

What's New

squad watch — Ralph Local Watchdog

Persistent background polling for squad work. Run it while you're away:

npx github:bradygaster/squad watch                    # polls every 10 minutes
npx github:bradygaster/squad watch --interval 5       # polls every 5 minutes

Ralph now has three layers:

• In-session: 'Ralph, go'
• Local watchdog: squad watch
• Cloud heartbeat: squad-heartbeat.yml

Project Type Detection + Git Safety Rules

Squad now detects your project's language and stack, and enforces git guardrails to prevent common mistakes.

Install

npx github:bradygaster/squad

v0.5.0-insider+ad8da0f

This is an insider/development build of Squad. Install with:bash\nnpx github:bradygaster/squad#v0.5.0-insider+ad8da0f\n\n\nNote: Insider builds may be unstable and are intended for early adopters and testing only.