release: v0.2.1 — first-run experience reset

[kokevidaurre]

Summary

• Version 0.2.1: Complete first-run experience reset for new users
• squads init --yes works without gh CLI (warning, not error)
• Default business brief: "autonomous execution + track big AI players" — interesting first-run output
• Auto-commits scaffolding so agents can use git worktrees immediately
• 4 core squads (research, company, intelligence, product) for every user
• Getting Started shows squads run as autopilot entry point
• Phase-ordered execution, role-based context, infra cleanup
• 1732 tests passing, all CI checks green

Notable changes since v0.7.0

• First-run experience completely reworked (feat: reset first-run experience for v0.2.1 #600)
• Phase-ordered execution with depends_on (feat: phase-ordered execution, role-based context, infra cleanup #597)
• Role-based context injection for agents (feat(run): inject SYSTEM.md as immutable Layer 1 in agent prompt #590)
• Unified squads run entry point (replaces daemon)
• 200+ new tests added
• Security fixes (PII removal, hook cleanup)
• README rewrite

Test plan

• Docker first-run test passes (Ubuntu 24.04 + Node 22)
• 1732 unit tests passing
• E2E first-run journey test passing
• Smoke test passing
• npm install smoke test passing

🤖 Generated with Claude Code

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request delivers a foundational update to the squads-cli, primarily focusing on a significantly improved first-run experience and the introduction of a local-first cognition engine. It streamlines the core command-line interface, consolidates autonomous operation logic, and enhances how AI agents receive context and learn from their actions. The changes aim to make the system more intuitive for new users and more intelligent in its continuous operation.

Highlights

• First-Run Experience Overhaul: Completely reworked the initial user setup, including a new squads init flow that now auto-commits scaffolding and works gracefully without the gh CLI.
• Cognition Engine Integration: Introduced a local-first cognition engine (src/lib/cognition.ts) enabling agents to learn, synthesize signals, evaluate decisions, and reflect on outcomes.
• Autopilot Mode Enhancement: The squads run command now serves as the primary entry point for autopilot mode, supporting phase-ordered execution based on squad dependencies and role-based context injection.
• New AI Workforce Intelligence Command: Added a squads stats command to provide executive-level insights, scorecards, and ROI metrics for the AI workforce.
• Documentation and Template Refinement: Extensively updated README.md, AGENTS.md, and seed templates to improve clarity, agent guidance, and reflect the new architecture and first-run experience.
• Infrastructure and Command Streamlining: Removed several legacy commands (list, stack, cron, tonight, live, env list, env activate) and infrastructure-related files, simplifying the local setup and focusing on cloud-native integration.
• E2E Testing for User Journey: Implemented a new E2E smoke test (scripts/e2e-smoke.sh) to validate the complete first-run user journey in an isolated environment.

Changelog

• .changeset/config.json
  • Removed Changeset configuration file.
• .changeset/github-app-bot.md
  • Removed changelog entry for GitHub App bot identity.
• CHANGELOG.md
  • Removed the project's changelog file, indicating a shift in changelog management.
• scripts/release.sh
  • Removed the release automation script.
• scripts/update-docs-changelog.cjs
  • Removed the script for updating the documentation changelog.

Ignored Files

• Ignored by pattern: .github/workflows/** (1)
  • .github/workflows/ci.yml

Activity

• The first-run experience has been completely reset for new users.
• squads init --yes now functions without requiring the gh CLI, issuing a warning instead of an error.
• The default business brief is set to 'autonomous execution + track big AI players', designed to produce interesting initial output.
• Scaffolding is now auto-committed, allowing agents to immediately utilize git worktrees.
• Four core squads (research, company, intelligence, product) are now provided to every user by default.
• The 'Getting Started' guide highlights squads run as the autopilot entry point.
• Execution now features phase-ordered processing, role-based context injection, and general infrastructure cleanup.
• All 1732 existing unit tests are passing, and all CI checks are green.
• Over 200 new tests have been added to the codebase.
• Security enhancements include PII removal and hook cleanup.
• The README.md has been rewritten for improved clarity and comprehensiveness.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This is a massive and impressive pull request that fundamentally resets the project's first-run experience and internal architecture. The changes are centered around simplifying the user setup, providing a more guided initial experience with default squads, and introducing a sophisticated intelligence layer for autonomous operation and performance tracking.

Key improvements include:

• A unified squads run command that replaces the old daemon and serves as the single entry point for both manual and autonomous execution.
• A much richer scaffolding from squads init, providing four core squads out-of-the-box.
• A new role-based, layered context injection system (run-context.ts) that should significantly improve agent performance and relevance.
• The introduction of an intelligence layer with outcome tracking (outcomes.ts), cognition (cognition.ts), and insights (insights.ts), which is a major step towards a self-improving system.
• Significant refactoring that moves complex logic out of command files into dedicated library modules (squad-loop.ts, run-context.ts), improving maintainability.
• Removal of Docker as a hard dependency, making the tool more accessible.

The overall direction is very strong. My feedback is focused on a few areas of inconsistency and potential robustness improvements that came up during this large-scale refactoring.

I am having trouble creating individual review comments. Click here to see my feedback.

package-lock.json (3)

The version in package-lock.json (0.7.1) is inconsistent with the version in package.json (0.2.1). This can lead to dependency and publishing issues. Please run npm install again to regenerate the lockfile with the correct version.

src/commands/run.ts (1417-1612)

The main while (running) loop in runAutopilot lacks a top-level try...catch block. An unhandled exception in any of the awaited functions within the loop (e.g., scoreSquads, runCognitionCycle) could crash the entire autopilot process. For a long-running daemon, it would be more robust to wrap the loop's body in a try...catch to log the error and continue to the next cycle.

CLAUDE.md (81)

This document mentions that PRs should be made to the develop branch. However, other parts of the repository and historical context (like the previous release script) seem to point to a main-based workflow. It would be good to clarify the branching strategy and ensure it's consistent across all contribution guides to avoid confusion.

src/cli.ts (268-269)

For consistency and better maintainability, since the command has been renamed from create to add, it would be clearer to also rename the source file src/commands/create.js to src/commands/add.js and the function createCommand to addCommand.

src/commands/list.ts (68)

The suggested command squads run research/researcher refers to an agent that seems to have been removed in this PR. The new lead agent for the research squad appears to be lead. Please update the suggestion to squads run research/lead.

    writeLine(`  ${colors.dim}  squads run research/lead${RESET}`);

src/lib/anthropic.ts (202)

The implementation for deleteSkill appears to have been removed, leaving it as an empty function. If this is intentional, consider adding a // TODO comment explaining why it's stubbed out. If it's no longer used, it might be better to remove the function entirely to avoid confusion.

src/lib/anthropic.ts (217)

Similar to deleteSkill, the implementation for getSkill seems to be missing. It currently just returns null. If this is a placeholder for future implementation, a // TODO comment would be beneficial. Otherwise, if the function is obsolete, it should be removed.