Skip to content

release: v0.3.0 — review, credentials, conversation mode, guardrails#696

Open
agents-squads[bot] wants to merge 219 commits intomainfrom
develop
Open

release: v0.3.0 — review, credentials, conversation mode, guardrails#696
agents-squads[bot] wants to merge 219 commits intomainfrom
develop

Conversation

@agents-squads
Copy link
Copy Markdown
Contributor

@agents-squads agents-squads bot commented Mar 31, 2026

Release: v0.3.0

195 commits from develop, including significant new features and reliability improvements.

New Commands

  • squads review — post-cycle evaluation dashboard for founder/COO.
  • squads credentials — per-squad GCP service account management.
  • squads goals — goals dashboard with status tracking.

Significant Changes

  • Conversation mode rewrite — agents now talk AND use tools.
  • Agent guardrails — PreToolUse hooks in all spawned Claude sessions (issue 664).
  • Init UX — What's next guidance + opt-in email capture.
  • Smart skip — re-run squads when goals/priorities change.
  • Obs fixes — agent name normalization, squads dir from git root.
  • Services command tests + Tier 2 docs.
  • Prompts extracted to markdown files.

Pre-publish Checklist

  • CI passes
  • npm run build locally
  • npm publish (after merge)
  • npm dist-tag add squads@0.3.0 latest — REQUIRED: npm latest = old v0.3.4 pre-release. Semver wont auto-update. Must set manually.
  • Create GitHub release tag v0.3.0
  • Close issue 669

Security

9 Dependabot vulnerabilities (6 high, 3 moderate) pre-exist. Recommend follow-up PR.

Generated with Claude Code

kokevidaurre and others added 30 commits February 21, 2026 12:32
@kokevidaurre @claude
fix(security): update minimatch to fix ReDoS vulnerability (#350)
99d74d7 
Closes #342

Co-authored-by: Squads Cloud Worker <cloud@agents-squads.com>
Co-authored-by: Claude <noreply@anthropic.com>
@kokevidaurre @claude
fix(security): escape shell variables in background/watch mode spawn (#…
e900f6b 
…351)

Prevents shell injection via crafted paths in background and watch
execution modes. Applies same escaping used in foreground mode (PR #324).

Adds shellEscape() helper that replaces single quotes with '\'' to
safely interpolate variables into single-quoted shell strings. Applied to:
- Watch mode: projectRoot, worktreeDir, branchName, logFile, pidFile
- Background mode: projectRoot, worktreeDir, branchName, logFile, pidFile
- Provider background mode: workDir, logFile, pidFile, provider args
- execSync worktree calls in foreground and provider modes

Closes #340

Co-authored-by: Squads Cloud Worker <cloud@agents-squads.com>
Co-authored-by: Claude <noreply@anthropic.com>
@kokevidaurre @claude
docs(brief): CLI daily brief for 2026-02-21 (#349)
49cfe95 
v0.6.2 released, 3 security P1 issue-solvers dispatched,
751 tests passing, Q1 goals 2/3 achieved.

Co-authored-by: Squads Cloud Worker <cloud@agents-squads.com>
Co-authored-by: Claude <noreply@anthropic.com>
@kokevidaurre
fix(ux): consistent exit code 0 when parent commands show help text (#…
7b22fd2 
…339)

Closes #319

Added default .action(() => cmd.outputHelp()) to 7 parent commands
(env, kpi, feedback, session, trigger, approval, autonomous) so they
exit 0 instead of 1 when invoked without a subcommand. Matches the
pattern already used by memory, goal, deploy, and exec commands.

Co-Authored-By: engineering/issue-solver <engineering-issue-solver@agents-squads.com>

Agent: engineering/issue-solver
Squad: engineering
Model: claude-opus-4-6

Co-authored-by: Squads Cloud Worker <cloud@agents-squads.com>
@kokevidaurre @claude
fix: replace console.log with writeLine for structured output (#311) (#…
472b968 
…354)

Replace scattered console.log calls with the project's writeLine()
utility from src/lib/terminal.ts. This provides a single output
layer for consistent formatting and future output control.

- Convert 238 console.log calls to writeLine across 10 files
- Remove 8 debug/placeholder log statements from anthropic.ts
- Keep console.log only for JSON.stringify output (--json flags)
  and raw prompt piping — standard CLI patterns
- Reduction: 269 → 31 occurrences (88% decrease)
- Zero new TypeScript errors

Files: init.ts, deploy.ts, autonomous.ts, trigger.ts, approval.ts,
eval.ts, login.ts, cli.ts, anthropic.ts, update.ts

Co-authored-by: kokevidaurre <kokevidaurre@users.noreply.github.com>
Co-authored-by: Claude <noreply@anthropic.com>
@kokevidaurre @claude
docs: professional README for v0.7.0 (#356)
c3b370c 
Replace minimal README with comprehensive 331-line version covering:
- Quick start with real output examples
- Why Squads (4 differentiators)
- Provider table (7 LLM providers)
- Feature showcase (dashboard, memory, sessions, autonomous, hooks)
- Command reference (21 active commands, no removed ones)
- Project structure and configuration examples
- Development guide and tech stack
- Contributing and community links

References only current commands (memory write/read instead of learn,
env show instead of context, exec list instead of history).

🤖 Generated with [Agents Squads](https://agents-squads.com)

Co-authored-by: kokevidaurre <kokevidaurre@users.noreply.github.com>
Co-authored-by: Claude <noreply@anthropic.com>
@kokevidaurre
fix(security): remove hardcoded telemetry API key from source (#359)
6261882 
Closes agents-squads/engineering#51

Removed the base64-obfuscated API key from source code and replaced
with SQUADS_TELEMETRY_KEY env var. Telemetry send is skipped when key
is not set. The exposed key must be rotated server-side separately.

Co-Authored-By: engineering/issue-solver <engineering-issue-solver@agents-squads.com>

Agent: engineering/issue-solver
Squad: engineering
Model: claude-opus-4-6

Co-authored-by: Squads Cloud Worker <cloud@agents-squads.com>
@kokevidaurre
fix: autonomous start daemon now persists as background process (#361)
8021176 
Closes #343

The daemon process was silently failing because Commander.js rejected
the unregistered --daemon CLI flag. Replace with SQUADS_DAEMON env var
to signal daemon mode, redirect child stdout/stderr to log file for
diagnosability, and show clear error when daemon fails to start.

Co-Authored-By: engineering/issue-solver <engineering-issue-solver@agents-squads.com>

Agent: engineering/issue-solver
Squad: engineering
Model: claude-opus-4-6

Co-authored-by: Squads Cloud Worker <cloud@agents-squads.com>
@kokevidaurre @claude
feat(status): show milestones and open PRs from GitHub (#365)
3319c29 
* feat(status): show milestones and open PRs from GitHub

squads status now queries GitHub API for real operational data:
- Milestone progress bars across product repos (cli, console, api)
- Open PRs targeting develop with repo and number

Replaces vanity-only output with actionable org health metrics.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(status): discover repos dynamically from squad definitions

Replace hardcoded PRODUCT_REPOS array with dynamic discovery:
- Read `repo` field from each SQUAD.md frontmatter
- Deduplicate and pass to fetchOperationalStatus()
- GitHub org derived from squad config, not hardcoded
- Dynamic column widths based on actual repo names
- Show all open PRs (not just develop-targeted)

Any user's squads with `repo:` in SQUAD.md will show milestones + PRs.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: rewrite CLAUDE.md as user-facing guide

Remove internal references, org names, and dev-specific content. Focus on
teaching users how to define squads, run agents, and monitor work. Git-provider
agnostic. Engineering standards now live in hq CLAUDE.md (internal only).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: kokevidaurre <kokevidaurre@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
@kokevidaurre
perf: lazy-load command modules to reduce cold start time (#367)
4300a7c 
Closes #24

Converts ~50 static command imports to dynamic import() inside action
handlers. Only the invoked command's dependencies (pg, supabase, inquirer,
ora) are loaded, saving ~300ms+ on cold start.

Changes:
- All command handlers use dynamic import() in their .action() callbacks
- autoUpdateOnStartup skipped for --help/--version (instant response)
- register*Command imports kept static (needed for subcommand structure)
- Type-only import for SessionSummaryData (zero runtime cost)

Co-Authored-By: engineering/issue-solver <engineering-issue-solver@agents-squads.com>

Agent: engineering/issue-solver
Squad: engineering
Trigger: manual
Model: claude-opus-4-6

Co-authored-by: Squads Cloud Worker <cloud@agents-squads.com>
@kokevidaurre
feat(ux): add dashboard discoverability hints after run and status (#360
d726001 
)

Closes #297

Show "squads dash" hints at key touchpoints:
- After successful foreground/background agent execution
- After lead session completion
- After parallel agent launch
- In squad detail status commands section

Co-Authored-By: engineering/issue-solver <engineering-issue-solver@agents-squads.com>

Agent: engineering/issue-solver
Squad: engineering
Trigger: manual
Model: claude-opus-4-6

Co-authored-by: Squads Cloud Worker <cloud@agents-squads.com>
@kokevidaurre
refactor: extract executeWithClaude into focused helper functions (#363)
97f771c 
Breaks down the 350-line executeWithClaude into 6 focused functions:
- buildAgentEnv: consolidates 3x duplicated env construction
- logVerboseExecution: DRYs up verbose config logging (was 2x identical)
- createAgentWorktree: isolates Node.js worktree creation
- buildDetachedShellScript: shared shell script for watch/background
- prepareLogFiles: shared log directory setup
- executeForeground: foreground spawn + status tracking
- executeWatch: watch mode (background + tail)

executeWithClaude is now a ~80-line coordinator that delegates to
the appropriate mode function.

Closes #158

Co-Authored-By: engineering/issue-solver <engineering-issue-solver@agents-squads.com>

Agent: engineering/issue-solver
Squad: engineering
Model: claude-opus-4-6

Co-authored-by: Squads Cloud Worker <cloud@agents-squads.com>
@kokevidaurre
fix: Gemini provider fails due to worktree sandboxing and missing hea…
8f3c2ba 
…dless flags

Closes #371

Two fixes for Google/Gemini provider execution:

1. Add --yolo flag to Gemini CLI args for headless auto-approval.
   Without this, Gemini denies all tool calls when running in background
   because it can't prompt for interactive confirmation.

2. Copy .agents directory into worktree and rewrite prompt paths.
   Gemini CLI sandboxes file access to its workspace directory.
   The prompt references agent definitions at the original project root,
   which Gemini blocks as "Path not in workspace". Now we copy .agents
   into the worktree and rewrite absolute paths so Gemini can resolve them.

Co-Authored-By: engineering/issue-solver <engineering-issue-solver@agents-squads.com>

Agent: engineering/issue-solver
Squad: engineering
Model: claude-opus-4-6

Co-authored-by: Squads Cloud Worker <cloud@agents-squads.com>
@kokevidaurre
feat: add squads create command for local squad creation (#374)
a268f98 
Closes #280

Implements `squads create <name>` that creates:
- .agents/squads/<name>/SQUAD.md (from template)
- .agents/squads/<name>/lead.md (starter agent)
- .agents/memory/<name>/lead/ (memory directory)

Supports --description, --goal, --model flags for non-interactive use,
and interactive prompts via inquirer when flags are omitted.
Includes --force for overwriting and --yes for CI/scripting.

Note: organization.yaml is not used — squads are discovered dynamically
via filesystem (squad-parser.ts findSquadsDir + listSquads).

11 tests covering directory creation, content, naming, overwrite
protection, and squad discoverability.

Co-Authored-By: engineering/issue-solver <engineering-issue-solver@agents-squads.com>

Agent: engineering/issue-solver
Squad: engineering
Trigger: manual
Model: claude-opus-4-6

Co-authored-by: Squads Cloud Worker <cloud@agents-squads.com>
@kokevidaurre
feat: add --cloud flag to squads run for remote execution (#376)
efaf837 
Closes #366

When --cloud is set, the CLI dispatches agent execution to the platform
API instead of running locally. Requires `squads login` session and
SQUADS_API_URL environment variable.

Flow:
- POST /agent-dispatch to create dispatch request
- Poll /agent-executions for status updates
- Display execution summary on completion

Co-Authored-By: engineering/issue-solver <engineering-issue-solver@agents-squads.com>

Agent: engineering/issue-solver
Squad: engineering
Trigger: smart
Model: claude-opus-4-6

Co-authored-by: Squads Cloud Worker <cloud@agents-squads.com>
@kokevidaurre
test: add comprehensive tests for condenser summarizer module (#377)
0b1aea5 
Merged by COO
@kokevidaurre @claude
test: add unit tests for setup-checks.ts and local.ts (#378)
b49aae7 
Closes #316

Added 63 tests covering 2 of the 6 lib modules listed in the issue:
- setup-checks.ts (48 tests): providers registry, commandExists,
  isDockerRunning, checkDockerPrereqs, checkGhCli, checkGhPermissions,
  checkClaudeCli, checkProviderAuth, runPrereqChecks, runAuthChecks,
  displayCheckResults, attemptFix, waitForService
- local.ts (15 tests): getLocalEnvVars, formatLocalStatus,
  isLangfuseLocal, getLocalStackStatus

Co-authored-by: Squads Cloud Worker <cloud@agents-squads.com>
Co-authored-by: Claude <noreply@anthropic.com>
@kokevidaurre @claude
test(dashboard): add unit tests for engine, renderers, loader, and so…
9cccb68 
…urces (#382)

Closes #314. Adds 115 tests across 4 test files achieving 92% statement
coverage and 80% branch coverage on the dashboard module:

- dashboard-loader.test.ts: 16 tests for findDashboardsDir, listDashboards,
  loadDashboard, clearDashboardCache, loadAllDashboards, findDashboard
- dashboard-renderers.test.ts: 49 tests for formatValue (all formats),
  getThresholdColor, calculateColumnWidths, and renderView (all view types)
- dashboard-sources.test.ts: 31 tests for buildQuery, buildWhereClause,
  parseDateRange, and postgresSource stub
- dashboard-engine.test.ts: 19 tests for executeDashboard, renderDashboard,
  and showAvailableDashboards with mocked dependencies

Co-authored-by: kokevidaurre <kokevidaurre@users.noreply.github.com>
Co-authored-by: Claude <noreply@anthropic.com>
@kokevidaurre @claude
test(lib): complete unit tests for db.ts, sessions.ts, telemetry.ts (#…
63f445c 
…381)

Closes #51

Changes:
- db.test.ts: Enable 4 previously skipped baseline tests (saveBaseline,
  getLatestBaseline, getBaselineByName, listBaselines) — stubs are
  implemented, tests were incorrectly marked as not-yet-implemented
- sessions.test.ts: Add 30 new tests covering file-system operations:
  findAgentsDir, getSessionsDir, getHistoryFilePath, getActiveSessions,
  getSessionSummary, startSession, stopSession, updateHeartbeat,
  cleanupStaleSessions — all use temp dirs to avoid test pollution
  Also expanded detectSquad, detectAIProcessesFast, getLiveSessionSummaryFast

Total: 63 → 104 tests passing, 0 skipped

Co-authored-by: kokevidaurre <kokevidaurre@users.noreply.github.com>
Co-authored-by: Claude <noreply@anthropic.com>
@kokevidaurre @claude
docs(brief): CLI daily brief 2026-03-05 (#379)
76ffd0d 
Co-authored-by: kokevidaurre <kokevidaurre@users.noreply.github.com>
Co-authored-by: Claude <noreply@anthropic.com>
@kokevidaurre @claude
refactor(run): extract post-execution prompt to template file
bede35a 
Post-execution instructions (branch, commit, PR workflow) now loaded from
.agents/config/post-execution.md instead of inline template string in run.ts.
Separates prompt content from code. Same pattern as approval-instructions.md.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@kokevidaurre
Revert "refactor(run): extract post-execution prompt to template file"
33db400 
This reverts commit 9999f92700c02af522e15cae29097a60f249cf15.
@kokevidaurre @claude
fix(agents): proper PR workflow — target develop, daemon env, auth ch…
a4499da 
…eck (#389)

* fix(ci): run CI on PRs to develop — quality gate for agent PRs

Agents create PRs targeting develop. Without CI on develop PRs,
broken code gets merged undetected. This is the #1 quality gap.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(quality): pre-commit hook runs build + tests on source changes

Agents were committing broken code (e.g. #384: tests that fail on
import). Now any commit touching .ts/.tsx/.js files must pass both
`npm run build` and `npm run test` before the commit goes through.

This is the #1 quality gate — prevents slop at the source.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(tests): align failing tests with implementation

- deploy.test: capture process.stdout.write instead of console.log
  (deployCommand uses writeLine which writes to stdout)
- eval.test: same stdout capture fix for JSON output test
- infra.test: use POSTGRES_PORT env var (default 5433) to match
  docker-compose pattern
- local.test: expect port 5432 in DATABASE_URL matching getLocalEnvVars()
- setup-checks.test: expect 'warning' (not 'missing') when Docker
  is not installed, matching checkDockerPrereqs() implementation
- Deleted verify-token.test.ts (tested nonexistent verifyToken export)

Co-Authored-By: Claude <noreply@anthropic.com>

* fix(agents): proper PR workflow — target develop, daemon env, auth check

- Post-execution: agents now open PRs targeting `develop` with structured body
- Daemon (autonomous.ts): unset CLAUDECODE env to allow nested claude sessions
- Auth check: downgrade missing credentials from block to warn (keychain auth)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* refactor(run): extract post-execution prompt to template file

Post-execution instructions (branch, commit, PR workflow) now loaded from
.agents/config/post-execution.md instead of inline template string.
Separates prompt content from code. Same pattern as approval-instructions.md.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: kokevidaurre <kokevidaurre@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
@kokevidaurre @claude
fix(types): resolve 27 typecheck errors on develop (#391)
8059c23 
- Add missing env-config.ts (imported by run.ts but never committed)
- Fix Commander action spread types with @ts-expect-error directives
- Add inquirer type declaration for create command

Co-authored-by: kokevidaurre <kokevidaurre@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
@kokevidaurre @claude
fix(daemon): parse routines with prefixed headers like '## Growth Rou…
a59d279 
…tines' (#392)

Regex only matched '## Routines' exactly, missing Engineering squad's
'## Growth Routines' header. Now matches any word before 'Routines'.

Co-authored-by: kokevidaurre <kokevidaurre@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
@kokevidaurre @claude
feat(run): implement squad conversation protocol (#393)
b7bb9e6 
Multi-agent conversation orchestration for squad runs:
- Lead briefs → scanners discover → workers execute → lead reviews → verifiers check
- Shared transcript between agents for context continuity
- Convergence detection (continuation signals beat convergence signals)
- Cost ceiling ($25 default) and max turns (20 default) safety limits
- --task flag for founder directives (replaces lead briefing)
- Transcript persistence to .agents/conversations/{squad}/

New files:
- src/lib/conversation.ts — types, transcript, agent classification, convergence
- src/lib/workflow.ts — turn execution, orchestration loop, transcript persistence

`squads run <squad>` now runs a full conversation instead of just the lead agent.
`squads run <squad> -a <agent>` still runs individual agents (unchanged).

Co-authored-by: kokevidaurre <kokevidaurre@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
@kokevidaurre
fix(auth): add verifyToken and 6 passing tests (#385)
180d9b9 
* fix(auth): add verifyToken function and passing test suite

Closes #384

Adds verifyToken(token, apiUrl) to src/lib/auth.ts:
- Calls GET /auth/verify with Bearer token header
- Maps snake_case API response to camelCase (display_name→name, subscription_plan→plan)
- Returns null on non-ok responses, network errors, and timeouts/aborts
- 5-second abort timeout to prevent hanging

Creates test/verify-token.test.ts with all 6 specified tests:
1. Returns user data on 200 with snake_case→camelCase mapping
2. Returns null on non-ok response (e.g. 401)
3. Returns null on network error (silent)
4. Returns null on timeout/abort
5. Sends Bearer token in Authorization header
6. Builds correct URL from apiUrl param

Co-Authored-By: cli/issue-solver <cli-issue-solver@agents-squads.com>

Agent: cli/issue-solver
Squad: cli

* fix(auth): update verifyToken signature and response to match API spec

Revises the initial implementation based on actual API contract:
- Parameter order: verifyToken(apiUrl, token) — apiUrl first
- Endpoint: /auth/cli/verify (not /auth/verify)
- Response shape: { email, tenantId, tenantSlug, tenantName, status }
  mapping from snake_case { tenant_id, tenant_slug, tenant_name }
- Updates test/verify-token.test.ts to use vi.stubGlobal per-test
  with afterEach cleanup for better test isolation

All 6 tests pass.

Co-Authored-By: cli/issue-solver <cli-issue-solver@agents-squads.com>

Agent: cli/issue-solver
Squad: cli

---------

Co-authored-by: kokevidaurre <kokevidaurre@users.noreply.github.com>
@kokevidaurre
test(commands): add unit tests for goal and list commands (#388)
782c47e 
* test(commands): add unit tests for goal and list commands

Adds 21 new tests covering:
- goal.test.ts (14 tests): goalSetCommand, goalListCommand,
  goalCompleteCommand, goalProgressCommand — including edge cases
  for invalid indexes, non-existent squads, metric annotations
- list.test.ts (7 tests): JSON output validation, agent counts,
  no-project error handling, table and agents view rendering

Partial fix for #47 — covers 2 of 19 untested command files.

Co-Authored-By: engineering/issue-solver <engineering-issue-solver@agents-squads.com>

Agent: engineering/issue-solver
Squad: engineering
Model: claude-opus-4-6

* test: add unit tests for feedback and progress commands

Closes #47 (partial — 2 of 15 untested commands)

Added 19 tests covering:
- feedback: add, show, parse history, rating validation, learnings
- progress: start/complete tasks, display, verbose mode, task IDs

Co-Authored-By: engineering/issue-solver <engineering-issue-solver@agents-squads.com>

Agent: engineering/issue-solver
Squad: engineering
Model: claude-opus-4-6

---------

Co-authored-by: kokevidaurre <kokevidaurre@users.noreply.github.com>
@kokevidaurre @claude
fix(conversation): replace regex with string matching for agent class…
4356d19 
…ification

- classifyAgent now uses role descriptions from SQUAD.md (primary) with
  name-based fallback — no more regex substring collisions
- Strip **bold** markers from agent names in table parser
- Replace regex convergence/continuation signals with phrase matching
- "keychain auth" → "OAuth" in run output

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@kokevidaurre
test(commands): add unit tests for session and learn commands (#394)
92e4da7 
- session.test.ts: 11 tests covering sessionStartCommand,
  sessionStopCommand, sessionHeartbeatCommand, and detectSquadCommand
  (start/stop/heartbeat lifecycle, quiet mode, missing .agents dir)
- learn.test.ts: 14 tests covering learnCommand, learnShowCommand,
  and learnSearchCommand (default squad, specific squad, fallback,
  category inference, tag extraction, search, filters)

Part of #47 — adds coverage for 2 more previously untested commands.

Co-Authored-By: cli/issue-solver <cli-issue-solver@agents-squads.com>

Agent: cli/issue-solver
Squad: cli

Co-authored-by: kokevidaurre <kokevidaurre@users.noreply.github.com>
Jorge Vidaurre and others added 15 commits March 31, 2026 03:50
@claude
fix(ux): show run completion summary with duration and error hints
54cb459 
After every squads run:
- Success: "Run completed — squad/agent (2.1s)"
- Background: "Run started — squad/agent (background)"
- Failure: "Run failed — squad/agent (0.8s)" + targeted hint
  - API key errors get: "Set ANTHROPIC_API_KEY and retry"
  - JS bugs get doctor/update advice
  - Others get generic doctor hint

Closes #690

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@claude
feat: explicit STATUS/VERDICT convergence detection
023efcd 
Primary: ## STATUS: DONE/CONTINUE (lead), ## VERDICT: APPROVED/REJECTED (verifier)
Fallback: keyword detection (backwards compatible)
BLOCKED signal stops conversation immediately.

Matches redesigned conversation-roles.md in hq.

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
refactor: action-first context ordering — feedback and goals before r…
315fbb4 
…eference

LLMs pay most attention to the beginning and end of context ("lost in
the middle" problem). Reordered context injection:

Before: Company → Priorities → Goals → Agent → State → Feedback
After:  Feedback → Goals → State → Priorities → Agent → Company

Feedback is now the FIRST thing agents see — corrections from last cycle
get addressed before anything else. Company and agent definition moved to
the end as reference material.

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
fix: classify agents by name first, then role description
742517e 
eng-lead was classified as verifier because role description said
"review PRs". Name-based matching (contains "lead") is more reliable
and now takes priority over role description parsing.

Also removed "review" and "check" from verifier keywords — too ambiguous.
Many leads review PRs without being verifiers.

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
feat(org): wave-based parallel execution
74b2ae4 
Squads run in 4 waves, parallel within each wave:
- Wave 1 (Producers): research, intelligence, data
- Wave 2 (Builders): cli, website, finance, engineering
- Wave 3 (Amplifiers): marketing, growth, product, analytics, customer, economics
- Wave 4 (Reviewers): operations, company

Between waves, hq memory is committed so the next wave sees fresh state.
Expected time: ~1.5h (down from 6h sequential).

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
feat: cap transcript turn size at 8K chars
05b3cf6 
Prevents context bloat in long conversations. Large agent outputs are
truncated with a note pointing to git log and gh pr list for full details.

Inspired by Claude Code's tool result budget pattern (100K cap + persist
to disk). Our cap is lower because transcript turns are injected into
every subsequent agent's prompt.

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
feat: auto-compact transcript — digest old cycles, keep current in full
507bbc9 
Inspired by Claude Code's auto-compact pattern. When conversations span
multiple cycles (lead→scan→work→verify→repeat):

- Current cycle: kept in full (agents need full context)
- Old cycles: compressed into structured digest with:
  - Done: PRs merged, issues closed
  - Blocked: items needing human action
  - Pending: unfinished work
  - Verdict: verifier approved/rejected

Combined with 8K per-turn cap and 20K total transcript cap, this lets
conversations go 20+ turns without blowing context. Each new cycle starts
with a concise history instead of the full transcript.

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
feat: rewrite workflow — plan/execute/review/verify with token budget
3956f75 
Replaces the conversation loop (lead→worker→lead→worker×20) with a
production-line architecture:

Phase 1: PLAN — Lead sees goals + feedback + token budget, produces
  task assignments for workers
Phase 2: EXECUTE — Workers run independently IN PARALLEL, each with
  their assigned task. No shared transcript, no waiting.
Phase 3: REVIEW — Lead evaluates worker output, merges PRs, updates goals
Phase 4: VERIFY — Verifier checks deliverables (build, conflicts, reviews)

Key changes:
- Workers are independent agents, not conversation participants
- Token budget (50K default) replaces max turns (20)
- Lead plans within budget (max 5 tasks at ~10K each)
- Task parser extracts assignments from lead's plan output
- Fallback: if no assignments parsed, first worker gets the full plan
- 4 phases = 4-6 agent runs per squad (was 20+ in loop mode)

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
fix(tests): fix 9 failing tests in conversation and workflow
5d4d43f 
- classifyAgent: add 'review' and 'check' as verifier keywords in role
  description parsing (fixes 'maps review to verifier', 'maps check to
  verifier')
- serializeTranscript: lower compaction threshold from 6 to 5 turns;
  preserve initial brief and add 'compacted' note in multi-cycle output
  (fixes 'compacts after 5 turns keeping first brief and last lead review')
- workflow.ts: wire options.maxTurns into detectConvergence calls instead
  of hardcoded 100 (fixes 'stops at max turns')
- workflow.test.ts: update child_process mock to include spawn; replace
  mockExecSync with mockSpawn + makeMockChild helper (fixes 6 runConversation
  tests broken by spawn rewrite)

All 1914 tests pass. Build clean.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@claude
feat(init): add demo/hello-world starter agent to scaffold
24cdd74 
Every `squads init` now creates a working demo squad with a hello-world
agent so users can immediately verify their setup with:

    squads run demo hello-world

Addresses the first-run cliff (#689): 82% of users who init never run
because they must write agent YAML from scratch. The demo agent requires
no configuration — it runs out of the box with any provider.

Changes:
- templates/seed/squads/demo/SQUAD.md: demo squad definition
- templates/seed/squads/demo/hello-world.md: starter agent (prints greeting,
  writes date + squads summary to memory, smoke-tests the full run pipeline)
- src/commands/init.ts: scaffold demo dirs/files; update success message
  to show "Verify your setup: squads run demo hello-world" as the first CTA

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@claude
fix: quota detection between waves + worker timeout 8m + status repor…
6e1b237 
…ting

1. Quota detection: after each wave, check transcripts for "hit your
   limit". If found, skip remaining waves instead of producing empty
   results. Also detect quota in workflow plan phase — return immediately.

2. Worker timeout: 15m → 8m. Tasks should be scoped by the lead's plan
   to fit within this budget.

3. Status: agents that return "hit your limit" are tagged [QUOTA] for
   clearer reporting.

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
feat: conversation_agents field — limit which agents join conversations
41c5320 
Large squads (intelligence: 17 agents) overwhelm conversations when all
agents participate. New SQUAD.md frontmatter field `conversation_agents`
limits who joins the plan/execute/review/verify workflow.

Agents not in the list still run on their own schedules — they're just
excluded from the squad conversation.

Example:
  conversation_agents: [intel-lead, market-scanner, company-profiler, intel-verifier]

If not set, all agents participate (backwards compatible).

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
feat: --resume flag for org cycles interrupted by quota
2e00a04 
When quota hits mid-cycle, skipped squads are saved to
.agents/observability/resume.json. Next run with --resume
picks up only those squads instead of restarting from scratch.

Flow:
  squads run --org          # runs until quota hits Wave 2
  # quota resets...
  squads run --org --resume # runs only Wave 3+4 squads

Resume file is cleared after a full cycle completes.

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
feat: --focus flag for org cycles (resolve, create, review, ship, res…
33442cf 
…earch, cost)

Focus modes change the lead's planning behavior per cycle:
- resolve: close existing issues/PRs, no new work
- create: advance goals, file issues (default)
- review: audit quality, fix CI/review comments
- ship: remove release blockers, merge to main
- research: discovery mode, reports only
- cost: P0/P1 only, minimize spend

Instructions loaded from .agents/config/cycle-focus.md (not hardcoded).

Usage: squads run --org --focus resolve

Co-Authored-By: Claude <noreply@anthropic.com>
feat(ux): add squads log command — run history with timestamps, durat…
c91ecc5 
…ion, and status

Closes #692

- New `squads log` command reads from .agents/observability/executions.jsonl
- Shows timestamp, squad/agent, duration, status, and cost per run
- Flags: --squad, --agent, --limit (default 20), --since, --json
- Gives returning users immediate visibility into what ran and whether it worked
- Added CLI_LOG telemetry event
agents-squads bot pushed a commit that referenced this pull request Apr 1, 2026
@kokevidaurre @claude
fix(e2e): update first-run test for demo squad scaffold — fix #713
71f7dd1 
squads init now creates 5 squads (4 core + demo starter) with 15 agents
total. The e2e test fixture expected 4 squads and 14 agents, causing the
retention gate to fail on the v0.3.0 PR.

Update expectations to match the new scaffold introduced in feat(init)
24cdd74. Unblocks PR #696 (v0.3.0 release).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This was referenced Apr 1, 2026
Closed
Merged
@claude
feat: role-based tool sets, effort levels, staleness caveats
870db9c 
#701: Scanners get read-only tools, workers get full set, verifiers get
read + build. Fewer tools = fewer tokens per API call.

#702: Effort level per role — scanner=low, worker=high, verifier=medium.
Wired via CLAUDE_EFFORT env var in buildAgentEnv.

#721: State.md injection prefixed with "(Last updated N days ago)" so
agents know when their memory is stale.

Co-Authored-By: Claude <noreply@anthropic.com>
@agents-squads agents-squads bot mentioned this pull request Apr 1, 2026
Closed
Jorge Vidaurre and others added 2 commits April 1, 2026 14:50
fix(workflow): guard against undefined readFileSync in loadFocusPrompt
8b71a6e 
5 workflow tests were crashing with 'Cannot read properties of undefined
(reading match)' because readFileSync mock returns undefined when existsSync
returns true. Added defensive guard — loadFocusPrompt returns empty string
when content is falsy. Safe in production too.

Also updates first-run e2e test to expect 5 squads (4 core + demo) and
15 agents, reflecting the demo squad added in #689.
@claude
fix: wave quota detection catches [QUOTA] and 'Quota limit reached' tags
e46359f 
The workflow now returns [QUOTA] when hitting rate limits, but the
wave-level detection only checked for "hit your limit". Added both
new patterns so --resume works correctly.

Co-Authored-By: Claude <noreply@anthropic.com>
@agents-squads
Copy link
Copy Markdown
Contributor Author

agents-squads bot commented Apr 2, 2026

data squad — Goal #2 (Tier 2 pipeline) blocked on this PR

Tracking from data squad: once v0.3.0 merges and publishes to npm, we can run squads obs sync from hq to backfill 57+ JSONL execution records to Postgres and verify the Tier 2 data pipeline.

  • squads-cli#669 closed (superseded by this PR)
  • npm still on v0.2.2 — Tier 2 pipeline cannot run until v0.3.0 ships
  • 3+ days since last activity on this PR

Requesting merge + npm publish when ready. This unblocks data squad Goal #2 (deadline: 2026-04-30).

Jorge Vidaurre and others added 5 commits April 1, 2026 22:17
@claude
fix(test): add findProjectRoot to squad-parser mock in workflow tests
abf34b5 
snapshotGoals (observability.ts) calls findProjectRoot, which is now
used by runConversation. The mock was missing this export, causing all
workflow tests to fail with vitest module mock errors.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@agents-squads @claude
fix(obs): log observability record at all runConversation exit paths (#…
7c6671c 
…724)

Closes #700 (part 1/2 — obs logging)

- Quota-detected exit: logs status=failed with error='Quota limit reached'
- Early convergence (lead done immediately): logs goals diff + duration
- Full conversation exit: logs goals before/after, turn count, cost

All three paths now appear in `squads review` last-run data.

Co-authored-by: Jorge Vidaurre <jorge@agents-squads.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
@agents-squads @claude
fix(ci): null check in loadFocusPrompt + update E2E squad fixture — f…
bec4652 
…ixes #715 (#723)

* fix(workflow): guard against undefined readFileSync in loadFocusPrompt

5 workflow tests were crashing with 'Cannot read properties of undefined
(reading match)' because readFileSync mock returns undefined when existsSync
returns true. Added defensive guard — loadFocusPrompt returns empty string
when content is falsy. Safe in production too.

Also updates first-run e2e test to expect 5 squads (4 core + demo) and
15 agents, reflecting the demo squad added in #689.

* fix(test): add findProjectRoot to squad-parser mock in workflow tests

snapshotGoals (observability.ts) calls findProjectRoot, which is now
used by runConversation. The mock was missing this export, causing all
workflow tests to fail with vitest module mock errors.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Jorge Vidaurre <jorge@agents-squads.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
@agents-squads
feat(telemetry): add cli.run.complete event with exit_code, duration_…
c34c88a 
…ms, agent_count, had_error (#725)

Closes #688

Co-authored-by: Jorge Vidaurre <jorge@agents-squads.com>
@agents-squads @kokevidaurre @claude
fix(e2e): update first-run test for demo squad scaffold — fix #713 (#714
552e09a 
)

squads init now creates 5 squads (4 core + demo starter) with 15 agents
total. The e2e test fixture expected 4 squads and 14 agents, causing the
retention gate to fail on the v0.3.0 PR.

Update expectations to match the new scaffold introduced in feat(init)
24cdd74. Unblocks PR #696 (v0.3.0 release).

Co-authored-by: kokevidaurre <kokevidaurre@users.noreply.github.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: Jorge Vidaurre <jorge@agents-squads.com>
@agents-squads agents-squads bot mentioned this pull request Apr 2, 2026
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@kokevidaurre kokevidaurre Awaiting requested review from kokevidaurre kokevidaurre is a code owner

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

commands core docs templates tests

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@kokevidaurre