v0.3.1 — Conversation Protocol

What's in this release

v0.3.1 ships the conversation protocol — the foundation for how squads work as teams. Agents no longer run in isolation; they share context, brief each other, challenge outputs, and converge on a result before stopping.

This is the first stable release on npm @latest, promoted from v0.3.0-rc.1 after burn-in on @next.

v0.3.0 was skipped — that version slot is reserved by a historical pre-release; npm enforces version immutability.

---

Conversation Protocol

squads run <squad> now drives a structured multi-agent conversation:

1. Lead reads goals, priorities, and recent state — then briefs workers
2. Workers execute tasks, use tools, and report progress mid-conversation
3. Lead reviews outputs and requests corrections if needed
4. Verifier confirms the work meets exit criteria

Agents share a live transcript and can hand off context to each other. The conversation continues until it converges or reaches a configured limit.

Org Cycle

squads run with no target now runs the full organization:

• Squads execute in waves based on dependencies
• Smart-skip: squads with unchanged goals and priorities are skipped automatically
• Interrupted runs resume from where they left off — completed squads are not re-run
• --force re-runs everything regardless of state

Role-Based Timeouts

Workers, leads, and verifiers each have appropriate time limits per role — replacing the old hardcoded ceiling that was simultaneously too tight for leads and too loose for scanners.

New Commands

Command	What it does
squads review	Trigger a review pass from the squad lead
squads credentials	Add, rotate, and validate API keys
squads goals	Read and update squad goals
squads log	Browse agent conversation history

Existing commands (init, status, run) also received refinements in this release.

Project Configuration

.squads/config.yml lets you set per-project defaults without environment variables. Resolution order: env var → config file → built-in defaults.

Safety Hooks

Agents now support PreToolUse hooks — shell commands that run before any agent action executes. Return a non-zero exit code to block the action. Use this for approval gates, audit logs, or environment guards.

Better squads init

The init command now scaffolds starter agents with working definitions, an example squad, and step-by-step guidance for what to do next. A growth squad template is also included in the seed templates.

---

Install

```bash
npm install -g squads-cli
squads --version # 0.3.1
```

Pre-release channel: npm install -g squads-cli@next
Changelog: https://github.com/agents-squads/squads-cli/blob/main/CHANGELOG.md

v0.3.0-rc.1 — pre-release burn-in

Pre-release candidate published to npm @next for burn-in. Promoted to @latest as v0.3.1.

```bash
npm install -g squads-cli@next
```

See v0.3.1 release notes for the full changelog.

v0.2.2 — Observability & IDP

What's in this release

v0.2.2 adds two major layers: observability (what did your agents do, and what did it cost?) and an internal developer platform (how do you manage them as a proper system?).

---

Observability

Track every agent execution — cost, tokens, duration — without manual instrumentation.

squads obs history
View execution history for any squad. Shows token usage, cost, model, and duration per run.

squads obs cost
Spend summary broken down by squad and model. Identify which squads are expensive and why.

squads obs sync
Push local execution logs to Postgres for long-term storage and cross-device access.

Executions are logged to .agents/observability/executions.jsonl — a structured append-only log that other tools can consume directly.

---

Internal Developer Platform (IDP)

Manage your agent system as a first-class software platform.

squads catalog
Service catalog for your agents and squads. Browse what exists, inspect definitions, and validate structure against the schema.

squads release
Pre-release scorecard checks. Before promoting a squad, verify it meets your defined criteria (has goals, a lead, defined roles, etc.).

Structured frontmatter
Agents now support spec.type, spec.squad, and spec.role in their YAML frontmatter. The catalog and release commands use these fields for validation.

---

Architecture Tiers

squads tier shows which tier your current setup is running at:

Tier	What it means
Tier 1	Local only — no external services required
Tier 2	Local services running (Postgres, Bridge)
Tier 3	Cloud execution

squads services starts, stops, and checks the status of local services.

---

Org Cycle Improvements

• Smart-skip: squads re-run only when their goals or priorities changed since the last execution
• --force flag to override and re-run everything
• Improved quota handling: waits and retries instead of failing on rate limits

---

Install

```bash
npm install -g squads-cli
```

Full changelog: v0.2.1...v0.2.2

v0.2.1 — First-Run Experience

What's in this release

v0.2.1 is a complete reset of the first-run experience. A new user with no existing project can install, init, and run a real AI agent in under 5 minutes:

```bash
npm install -g squads-cli
mkdir my-project && cd my-project && git init
squads init --yes
squads run research/lead
```

---

What squads init now creates

Every new project gets 4 core squads out of the box:

Squad	Purpose
research	Market and competitive intelligence
company	Internal knowledge and documentation
intelligence	Signal monitoring and synthesis
product	Product feedback and roadmap tracking

Each squad ships with a lead agent, a default brief, and working priorities — ready to run without additional configuration. The scaffolding is auto-committed so agents can immediately use git worktrees for parallel execution.

---

Context Cascade

Agents resolve context in a defined order, from most stable to most volatile:

SYSTEM.md → SQUAD.md → priorities.md → directives.md → state.md

Earlier files set constraints; later files override specifics. Update priorities.md and agents pick it up on the next run — no need to touch squad definitions.

---

Role-Based Context Injection

Each agent role receives a different context slice, keeping agents fast and appropriately scoped:

Role	Context received
Scanner	System + squad definition + current state
Worker	+ priorities, directives, feedback
Lead / COO	Full chain including cross-squad learnings

---

Phase-Ordered Execution

SQUAD.md frontmatter now supports depends_on — declare which squads must finish before this one starts. The org cycle respects these dependencies when scheduling execution waves.

---

Other Changes

• squads run is now the single entry point, replacing the old squads auto start
• gh CLI is optional — missing GitHub CLI shows a warning instead of a hard error
• Platform-agnostic install hints (no more macOS-specific suggestions on Linux)

---

Install

```bash
npm install -g squads-cli
```

Full changelog: v0.6.2...v0.2.1

v0.1.0 — Agent Orchestration Layer

What's in this release

v0.1.0 is the orchestration layer — the engine underneath squads run. It establishes how agents are isolated from each other, how context and memory flow into every execution, and how squads schedule themselves autonomously.

These capabilities are the foundation everything else builds on.

---

Git Worktree Isolation

Each agent now gets its own isolated git worktree instead of sharing the working tree.

The problem it solves: concurrent agents running git checkout -b in the same directory cause branch collisions — last checkout wins and earlier work is lost. With worktree isolation, each agent operates in a separate directory at ../.worktrees/{squad}-{agent}-{timestamp}, commits to its own branch, and never interferes with other running agents.

All three execution modes use worktrees: foreground, watch, and background. Falls back to the project root if worktree creation fails.

Memory Injection

Every agent execution now automatically receives:

• Daily briefing — synthesized summary of recent squad activity and open priorities
• Cross-squad learnings — insights from other squads relevant to this agent's domain
• Acceptance criteria — what a successful run looks like, pulled from the agent definition

The agent doesn't need to fetch this context manually — it's injected before the prompt reaches the model.

Verification Loop

After an agent completes, a verifier checks the output against the acceptance criteria defined in the agent's frontmatter. If the criteria aren't met, the agent retries. Use --no-verify to skip this loop.

Autonomous Scheduling Daemon

squads autonomous start spawns a detached background daemon that runs squads on a cron schedule:

• Cron evaluator — zero-dependency, supports *, ranges, steps, and lists
• PID file monitoring — detects running agents, cleans up orphans, enforces timeouts
• Concurrency control — configurable MAX_CONCURRENT limit (default 5)
• Cooldown enforcement — human-readable durations (30m, 6h, 7d) prevent over-running

Agents declare their own schedule in frontmatter — the daemon reads them and dispatches accordingly.

Squad-Scoped Skills and MCP Servers

Skills and MCP tool configurations now resolve through a three-tier hierarchy:

squad-local  →  project  →  global

Place a skill in .agents/squads/<squad>/skills/ and it only loads for that squad. Add .agents/squads/<squad>/mcp.json to give a squad access to specific tools no other squad has. The squads context show command displays which tier each skill came from.

Multi-Provider Model Routing

Agents can now target different AI providers. Set model: in agent frontmatter to any supported model string — the CLI detects the provider and routes to the correct executor:

model: claude-opus-4-5        # Anthropic
model: gemini-2.5-flash       # Google

Non-Anthropic models delegate to a provider-specific executor while keeping the same run interface.

Foreground-First Execution

squads run now runs in foreground by default, giving immediate visibility into agent work. Use --background / -b for detached execution, or --watch / -w for background with live log tailing. Agent work is auto-committed after successful foreground execution.

---

Install

```bash
npm install -g squads-cli
```