From 4dc724865330023159409c6d4fd2715b6f6032e7 Mon Sep 17 00:00:00 2001 From: Copilot Date: Wed, 14 Oct 2026 16:53:21 +0300 Subject: [PATCH] chore(cli): deprecate sdk-first initialization - Emit deprecation warnings for squad init --sdk and squad migrate --to sdk while preserving runtime and squad build compatibility - Update CLI help output, homepage feature card, release notes, and documentation to frame markdown-first .squad/ as the recommended layout - Add CLI init, migrate, and command-help test coverage for deprecation messaging Closes #341 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 5cf0811c-a02a-41a7-ab00-904b6900db7b --- .changeset/deprecate-sdk-init.md | 5 ++ README.md | 21 +------ README.zh.md | 21 +------ docs/proposals/deprecate-sdk-init.md | 24 ++++++++ docs/src/content/blog/024-v0823-release.md | 26 ++++----- .../content/docs/concepts/what-is-squad.md | 4 +- .../content/docs/features/built-in-roles.md | 4 +- .../docs/features/enterprise-platforms.md | 6 +- .../content/docs/get-started/installation.md | 2 + docs/src/content/docs/guide.md | 55 ++++--------------- docs/src/content/docs/reference/config.md | 6 +- docs/src/content/docs/reference/sdk.md | 4 +- .../content/docs/reference/tools-and-hooks.md | 4 +- docs/src/content/docs/sdk-first-mode.md | 51 +++++------------ docs/src/content/docs/whatsnew.md | 6 +- docs/src/navigation.ts | 2 +- docs/src/pages/index.astro | 4 +- packages/squad-cli/src/cli-entry.ts | 5 +- .../squad-cli/src/cli/commands/migrate.ts | 7 ++- .../squad-cli/src/cli/core/command-help.ts | 7 ++- packages/squad-cli/src/cli/core/init.ts | 8 ++- test/cli/command-help.test.ts | 17 ++++++ test/cli/init.test.ts | 17 +++++- test/migrate.test.ts | 15 ++++- 24 files changed, 165 insertions(+), 156 deletions(-) create mode 100644 .changeset/deprecate-sdk-init.md create mode 100644 docs/proposals/deprecate-sdk-init.md diff --git a/.changeset/deprecate-sdk-init.md b/.changeset/deprecate-sdk-init.md new file mode 100644 index 000000000..148c4a5fc --- /dev/null +++ b/.changeset/deprecate-sdk-init.md @@ -0,0 +1,5 @@ +--- +"@bradygaster/squad-cli": patch +--- + +Deprecate `squad init --sdk` ahead of its removal in v2 while retaining compatibility for existing `squad.config.ts` projects. diff --git a/README.md b/README.md index 8f41f05f4..c09b1c17e 100644 --- a/README.md +++ b/README.md @@ -459,26 +459,11 @@ When agents finish, the coordinator records follow-up work and leaves a breadcru **Commit this folder.** Your team persists. Names persist. Anyone who clones gets the team — with the same cast. -### SDK-First Mode (New in Phase 1) +### SDK-First Mode (Deprecated) -> ⚠️ **Experimental.** SDK-first mode is under active development and has known bugs. Use markdown-first (the default) for production teams. +> ⚠️ **Deprecated.** `squad init --sdk` will be removed in v2. Use the default markdown-first `squad init` flow for new teams. -Prefer TypeScript? You can define your team in code instead of markdown. Create a `squad.config.ts` with builder functions, run `squad build`, and the `.squad/` files are generated automatically. - -```typescript -// squad.config.ts -import { defineSquad, defineTeam, defineAgent } from '@bradygaster/squad-sdk'; - -export default defineSquad({ - team: defineTeam({ name: 'Platform Squad', members: ['@edie', '@mcmanus'] }), - agents: [ - defineAgent({ name: 'edie', role: 'TypeScript Engineer', model: 'claude-sonnet-5' }), - defineAgent({ name: 'mcmanus', role: 'DevRel', model: 'claude-haiku-4.5' }), - ], -}); -``` - -Run `squad build` to generate all the markdown. See the [SDK-First Mode Guide](docs/src/content/docs/sdk-first-mode.md) for full documentation. +Existing projects with a `squad.config.ts` can continue running `squad build` during the transition. See the [legacy SDK-First Mode Guide](docs/src/content/docs/sdk-first-mode.md) for compatibility information. --- diff --git a/README.zh.md b/README.zh.md index 30e21df85..c9b782502 100644 --- a/README.zh.md +++ b/README.zh.md @@ -263,26 +263,11 @@ Squad 不按人类的时间表工作。当你分配任务时，协调员会同 **提交此文件夹。** 你的团队会持久化。名字会持久化。任何克隆的人都会获得团队 —— 使用相同的演员表。 -### SDK 优先模式（Phase 1 新功能） +### SDK 优先模式（已弃用） -> ⚠️ **实验性功能。** SDK 优先模式正在积极开发中，存在已知 bug。生产环境团队请使用 markdown 优先模式（默认）。 +> ⚠️ **已弃用。** `squad init --sdk` 将在 v2 中移除。新团队请使用默认的 markdown 优先 `squad init` 流程。 -更喜欢 TypeScript？你可以用代码而不是 markdown 定义团队。创建一个带有构建器函数的 `squad.config.ts`，运行 `squad build`，`.squad/` 文件就会自动生成。 - -```typescript -// squad.config.ts -import { defineSquad, defineTeam, defineAgent } from '@bradygaster/squad-sdk'; - -export default defineSquad({ - team: defineTeam({ name: 'Platform Squad', members: ['@edie', '@mcmanus'] }), - agents: [ - defineAgent({ name: 'edie', role: 'TypeScript Engineer', model: 'claude-sonnet-5' }), - defineAgent({ name: 'mcmanus', role: 'DevRel', model: 'claude-haiku-4.5' }), - ], -}); -``` - -运行 `squad build` 生成所有 markdown 文件。完整文档请参阅 [SDK 优先模式指南](docs/src/content/docs/sdk-first-mode.md)。 +现有的 `squad.config.ts` 项目可以在过渡期间继续运行 `squad build`。兼容性信息请参阅 [旧版 SDK 优先模式指南](docs/src/content/docs/sdk-first-mode.md)。 --- diff --git a/docs/proposals/deprecate-sdk-init.md b/docs/proposals/deprecate-sdk-init.md new file mode 100644 index 000000000..fe7603091 --- /dev/null +++ b/docs/proposals/deprecate-sdk-init.md @@ -0,0 +1,24 @@ +# Proposal: Deprecate SDK-First Initialization + +> **Authors:** Brady Gaster and Tamir Dresher +> **Date:** 2026-09-01 +> **Status:** Accepted +> **Goal:** Make markdown-first configuration the single recommended authoring model before v2. + +## Decision + +Deprecate `squad init --sdk` immediately and remove it in v2. Keep the flag functional during the transition, but print a warning and stop recommending it for new teams. + +Existing `squad.config.ts` projects retain `squad build` compatibility during the transition. +This decision deprecates the file-authoring mode, not the programmatic `@bradygaster/squad-sdk` APIs. + +## Rationale + +The SDK-first builder schema and `squad build` generator represent only a subset of current Squad behavior. Maintaining parity requires two competing configuration models and weakens Squad's portable, CLI-independent markdown model. + +## Compatibility + +- `squad init --sdk` continues to generate `squad.config.ts` until v2. +- Existing `squad.config.ts` projects can continue using `squad build`. +- Default `squad init` behavior is unchanged. +- User-facing help and documentation identify SDK-first initialization as deprecated. diff --git a/docs/src/content/blog/024-v0823-release.md b/docs/src/content/blog/024-v0823-release.md index e3e66ccc2..3f5dade5e 100644 --- a/docs/src/content/blog/024-v0823-release.md +++ b/docs/src/content/blog/024-v0823-release.md @@ -10,6 +10,8 @@ hero: "v0.8.23 fixes a critical crash when running `squad init` on Node.js 24+ a # v0.8.23 Release: Node 24+ Compatibility, Squad RC Docs, and Critical Fixes > _v0.8.23 is a critical hotfix addressing a crash when running `squad init` on Node.js 24+ and GitHub Codespaces. It ships comprehensive Squad RC documentation, introduces lazy module loading for faster CLI startup, and includes a postinstall patch for ESM import issues. 2 issues closed, 3 PRs merged, 3,811 tests passing._ +> ⚠️ **Historical release note.** SDK-first initialization was deprecated after this release and will be removed in v2. Use markdown-first `squad init` for new teams. + --- ## What Shipped ### 1. SDK-First Mode (Phase 1) — The Headline Feature @@ -408,12 +410,13 @@ If you've had issues with `npx @bradygaster/squad-cli` on fresh machines, v0.8.2 npx @bradygaster/squad-cli@latest doctor # Now works reliably without dependency resolution errors ``` -### To Migrate to SDK-First (Optional) +### Historical SDK-First Migration Steps (Legacy Compatibility Only) +Do not adopt SDK-First mode for a new team; use markdown-first `squad init` instead. The steps below are preserved for teams maintaining legacy SDK-first configurations and should be read only as release-era migration context. 1. Create `squad.config.ts` with builder functions 2. Run `squad build --dry-run` to preview generated files 3. Run `squad build` to generate `.squad/` markdown 4. Commit the config, version control the generated files, and sync your team -Alternatively, keep your markdown-first squad — both modes will coexist indefinitely. +At the time of this release, both modes were expected to coexist indefinitely. SDK-First mode is now deprecated and scheduled for removal in v2; keep markdown as the source of truth for new teams. --- ## Getting Started with v0.8.22 @@ -424,7 +427,8 @@ npm install -g @bradygaster/squad-cli@latest npx squad doctor npx squad start ``` -### Option 2: Try SDK-First Mode (New) +### Historical Option 2: SDK-First Mode (Now Deprecated) +The following commands are preserved as release-history context, not as current adoption guidance. Do not use SDK-First mode for new teams. ```bash npm install -g @bradygaster/squad-cli@latest mkdir my-sdk-squad && cd my-sdk-squad @@ -475,19 +479,13 @@ This release was shipped by the Squad core team with community contributions: Thanks to all early SDK-First adopters for feedback. --- -## Try It Now +## Start a New Team with Markdown-First Initialization +For current releases, create new teams with markdown as the source of truth: ```bash npm install -g @bradygaster/squad-cli@latest -mkdir my-sdk-squad && cd my-sdk-squad +mkdir my-squad && cd my-squad git init -# Create squad.config.ts with builders -# (see quick start above, or copy from samples/azure-function-squad/) -# Build your squad -npx squad build -# See the generated markdown -cat .squad/team.md -# Run agents (same CLI, same experience) -npx squad start +squad init ``` --- @@ -510,4 +508,4 @@ npx squad start - #231 — Migration command feedback --- -_This post was written by McManus, the DevRel on Squad's own team. Squad is an open source project by [@bradygaster](https://github.com/bradygaster). [Try SDK-First Mode →](../sdk-first-mode.md)_ +_This post was written by McManus, the DevRel on Squad's own team. Squad is an open source project by [@bradygaster](https://github.com/bradygaster). [Legacy SDK-First Mode compatibility guide →](../sdk-first-mode.md)_ diff --git a/docs/src/content/docs/concepts/what-is-squad.md b/docs/src/content/docs/concepts/what-is-squad.md index bd7b909de..9f15e9e62 100644 --- a/docs/src/content/docs/concepts/what-is-squad.md +++ b/docs/src/content/docs/concepts/what-is-squad.md @@ -33,9 +33,9 @@ Squad enforces explicit safeguards at the framework level: - **Reviewer lockout** blocks agents from self-approving work that requires human sign-off. - **Escalation points** surface unresolved decisions to the designated human owner before execution continues. -### SDK-first design +### Markdown-first design -Squad configuration is written in TypeScript (`squad.config.ts`). Configuration is typed, testable, and linted. Teams that already use TypeScript get full editor support, compile-time validation, and familiar tooling. +Squad configuration lives in portable markdown under `.squad/`, so a team works across supported Copilot surfaces without a build step. The legacy `squad.config.ts` authoring mode is deprecated and will be removed in v2. ### Extensible diff --git a/docs/src/content/docs/features/built-in-roles.md b/docs/src/content/docs/features/built-in-roles.md index 6723078af..d01ab764d 100644 --- a/docs/src/content/docs/features/built-in-roles.md +++ b/docs/src/content/docs/features/built-in-roles.md @@ -62,7 +62,9 @@ Suggested team: Look right? [Yes] [Add someone] [Change a role] [Browse all roles] ``` -### In squad.config.ts (SDK Mode) +### In an existing squad.config.ts (legacy SDK-first mode) + +> ⚠️ **Deprecated authoring mode.** Do not adopt `squad.config.ts` for a new team. This example remains for compatibility with existing projects. ```typescript import { useRole, defineSquad } from '@bradygaster/squad-sdk'; diff --git a/docs/src/content/docs/features/enterprise-platforms.md b/docs/src/content/docs/features/enterprise-platforms.md index 97e3598f7..fbe0d75e6 100644 --- a/docs/src/content/docs/features/enterprise-platforms.md +++ b/docs/src/content/docs/features/enterprise-platforms.md @@ -147,9 +147,11 @@ Squad supports a hybrid model where your **repository** lives in GitHub or Azure 2. **Graph API access** — `az account get-access-token --resource-type ms-graph` 3. **Plan ID** — Found in the Planner URL or via Graph API -### Configuration +### Configuration (legacy SDK-first projects) -In `squad.config.ts`, specify the hybrid model: +> ⚠️ **Legacy compatibility only.** The `squad.config.ts` authoring mode is deprecated and will be removed in v2. Use markdown-first `squad init` for new teams. The example below remains for existing projects. + +Existing SDK-first projects can specify the hybrid model in `squad.config.ts`: ```typescript const config: SquadConfig = { diff --git a/docs/src/content/docs/get-started/installation.md b/docs/src/content/docs/get-started/installation.md index ca23d55e5..b7526dca7 100644 --- a/docs/src/content/docs/get-started/installation.md +++ b/docs/src/content/docs/get-started/installation.md @@ -152,6 +152,8 @@ npm install @bradygaster/squad-sdk import { defineConfig, loadConfig, resolveSquad } from '@bradygaster/squad-sdk'; ``` +The SDK remains supported for programmatic integrations. The separate `squad.config.ts` file-authoring mode created by `squad init --sdk` is deprecated; use markdown-first `squad init` for new teams. + See the [SDK Reference](../reference/sdk.md) for the typed configuration, routing, and agent lifecycle APIs. diff --git a/docs/src/content/docs/guide.md b/docs/src/content/docs/guide.md index 980becd3b..9503655d3 100644 --- a/docs/src/content/docs/guide.md +++ b/docs/src/content/docs/guide.md @@ -44,7 +44,7 @@ Squad works across multiple interfaces — GitHub Copilot CLI, VS Code, Squad CL - **GitHub Copilot CLI** — Day-to-day conversational work with your squad (recommended) - **VS Code** — Same experience, editor-integrated - **Squad CLI** — Setup, diagnostics, monitoring (`squad init`, `squad doctor`, `squad watch`) -- **SDK** — Build tools on top of Squad with `squad.config.ts` +- **SDK** — Build programmatic integrations with `@bradygaster/squad-sdk` - **Copilot Coding Agent** — Autonomous issue processing via `@copilot` **Multi-platform support:** Squad also works with Azure DevOps (work items, PRs via `az boards`/`az repos`), GitLab Issues, and Microsoft Planner through pluggable platform adapters. See [Enterprise Platforms](features/enterprise-platforms.md) for details. @@ -218,46 +218,13 @@ Squad automatically picks the right response speed based on your request complex --- -## SDK-first mode +## SDK-first mode (deprecated) -Define your team in TypeScript instead of maintaining markdown files manually. Write a `squad.config.ts` with type-safe builder functions, and `squad build` generates the `.squad/` governance markdown. +`squad init --sdk` is deprecated and will be removed in v2 because its TypeScript configuration model does not represent the full Squad feature set. Use `squad init` and maintain the generated markdown directly for new teams. -```typescript -import { defineSquad, defineTeam, defineAgent, defineRouting } from '@bradygaster/squad-sdk'; - -export default defineSquad({ - team: defineTeam({ - name: 'Core Squad', - description: 'The main engineering team', - members: ['@edie', '@mcmanus'], - }), - agents: [ - defineAgent({ - name: 'edie', - role: 'TypeScript Engineer', - model: 'claude-sonnet-5', - capabilities: [{ name: 'type-system', level: 'expert' }], - }), - ], - routing: defineRouting({ - rules: [{ pattern: 'feature-*', agents: ['@edie'], tier: 'standard' }], - defaultAgent: '@coordinator', - }), -}); -``` - -**Get started:** - -```bash -squad init --sdk # New project with SDK config -squad migrate --to sdk # Convert existing .squad/ to TypeScript -squad build # Generate .squad/ from config -squad build --check # Validate in CI without writing -``` - -Builder functions: `defineTeam()`, `defineAgent()`, `defineRouting()`, `defineCeremony()`, `defineHooks()`, `defineCasting()`, `defineTelemetry()`, `defineSkill()`, `defineSquad()`. +Existing `squad.config.ts` projects can continue using `squad build` and `squad build --check` during the transition. -→ [Full guide: SDK-First Mode](sdk-first-mode.md) +→ [Legacy SDK-First Mode compatibility guide](sdk-first-mode.md) --- @@ -267,7 +234,7 @@ Squad names agents from fictional universes — Apollo 13 / NASA Mission Control Casting is **persistent** — once an agent receives a name, it keeps that name across sessions. The casting registry lives in `.squad/casting/registry.json`. You control which universes are available through a policy allowlist and can set per-universe capacity limits. -In SDK-first mode, configure casting with `defineCasting()`: +Existing SDK-first projects can configure casting with `defineCasting()`: ```typescript defineCasting({ @@ -287,7 +254,7 @@ Skills are reusable knowledge patterns that agents load on demand. They live in Skills have a confidence lifecycle: `low` → `medium` → `high`, and track their source: `manual` (you wrote it), `observed` (agent saw a pattern), `earned` (validated through use), or `extracted` (imported from another project). -In SDK-first mode, define skills with `defineSkill()`: +Existing SDK-first projects can define skills with `defineSkill()`: ```typescript defineSkill({ @@ -314,7 +281,7 @@ Skills accumulate as you work. After a few sessions, your team has a knowledge b Ceremonies are structured team meetings. Squad ships with two default ceremonies — Design Review (triggers before multi-agent work) and Retrospective (triggers after failures). You can trigger ceremonies manually, create custom ones, or disable them. Configuration lives in `.squad/ceremonies.md`. -In SDK-first mode, define ceremonies with `defineCeremony()`: +Existing SDK-first projects can define ceremonies with `defineCeremony()`: ```typescript defineCeremony({ @@ -539,7 +506,7 @@ Squad maintains a clear ownership model: |------|-------|--------------| | `.github/agents/squad.agent.md` | Squad (overwritten on upgrade) | No — your changes will be lost | | `.squad/` | You and your team | Yes — this is your team's state | -| `squad.config.ts` | You | Yes — your SDK-first config | +| `squad.config.ts` | You | Legacy SDK-first projects only | | Everything else | You | Yes | --- @@ -549,7 +516,7 @@ Squad maintains a clear ownership model: | Command | What it does | |---------|-------------| | `squad init` | Initialize Squad in the current repo | -| `squad init --sdk` | Initialize with SDK-first TypeScript config | +| `squad init --sdk` | Deprecated; compatibility only until v2 | | `squad init --global` | Initialize a personal squad (cross-project) | | `squad build` | Generate `.squad/` from `squad.config.ts` | | `squad build --check` | Validate generated files match disk (for CI) | @@ -563,7 +530,7 @@ Squad maintains a clear ownership model: | `squad import --force` | Import, archiving existing agents | | `squad plugin install ` | Install a plugin from the marketplace | | `squad plugin list` | List installed plugins | -| `squad migrate --to sdk` | Convert existing squad to SDK-first config | +| `squad migrate --to sdk` | Deprecated; do not start new SDK-first migrations | | `squad migrate --from ai-team` | Migrate from `.ai-team/` to `.squad/` | | `squad subsquads` | Manage SubSquads | | `squad status` | Show team status and global config | diff --git a/docs/src/content/docs/reference/config.md b/docs/src/content/docs/reference/config.md index 61edf51e9..37166f69a 100644 --- a/docs/src/content/docs/reference/config.md +++ b/docs/src/content/docs/reference/config.md @@ -10,7 +10,9 @@ That's it. Squad works out of the box. Everything below is optional. ## squad.config.ts -For type-safe SDK-First configuration, create this at your project root: +> ⚠️ **Deprecated authoring mode.** `squad init --sdk` will be removed in v2. The reference below remains for existing projects using `squad build`. + +Legacy SDK-first projects may define this file at the project root: ```typescript import { @@ -124,7 +126,7 @@ rm -rf .squad && squad init # Full reset (back up agents/decisions first ## Routing Rules -Control which agent gets which work. Edit `.squad/routing.md` or configure in `squad.config.ts`: +Control which agent gets which work in `.squad/routing.md`. Existing SDK-first projects may instead configure routing in `squad.config.ts`: ```markdown # Routing Rules diff --git a/docs/src/content/docs/reference/sdk.md b/docs/src/content/docs/reference/sdk.md index 1f72499f1..7a53b0153 100644 --- a/docs/src/content/docs/reference/sdk.md +++ b/docs/src/content/docs/reference/sdk.md @@ -88,6 +88,8 @@ Use `result.errors` and `result.warnings` when presenting validation results. Th ## SDK-First Builders +> ⚠️ **Deprecated authoring mode.** `squad init --sdk` will be removed in v2. These builders remain documented for existing `squad.config.ts` projects and programmatic SDK consumers during the transition. + Builders validate typed team definitions before they are written to `.squad/` by `squad build`. ```typescript @@ -359,4 +361,4 @@ Use the [generated API reference](./api/) for the complete list of current expor - [Generated API reference](./api/) - exhaustive TypeDoc output - [Configuration reference](./config.md) - file format and migration details - [Tools and hooks](./tools-and-hooks.md) - focused orchestration examples -- [SDK-First Mode](../sdk-first-mode.md) - builder workflow and `squad build` +- [Legacy SDK-First Mode](../sdk-first-mode.md) - compatibility for existing builder workflows diff --git a/docs/src/content/docs/reference/tools-and-hooks.md b/docs/src/content/docs/reference/tools-and-hooks.md index 3a53f6839..cca7c3365 100644 --- a/docs/src/content/docs/reference/tools-and-hooks.md +++ b/docs/src/content/docs/reference/tools-and-hooks.md @@ -91,7 +91,9 @@ Squad ships 5 policies configured via `PolicyConfig`: 4. **Rate limits** — Cap tool invocations per agent per interval 5. **PII filters** — Redact sensitive data before model calls -Configure policies in `squad.config.ts` under the `hooks` key: +> ⚠️ **Legacy compatibility only.** The `squad.config.ts` authoring mode is deprecated and will be removed in v2. Use markdown-first `squad init` for new teams. The example below remains for existing projects. + +Existing SDK-first projects can configure policies under the `hooks` key: ```typescript export default defineConfig({ diff --git a/docs/src/content/docs/sdk-first-mode.md b/docs/src/content/docs/sdk-first-mode.md index 15be49f1a..cf592a09a 100644 --- a/docs/src/content/docs/sdk-first-mode.md +++ b/docs/src/content/docs/sdk-first-mode.md @@ -1,8 +1,10 @@ -# SDK-First Squad Mode +# Legacy SDK-First Squad Mode + +> ⚠️ **Deprecated.** `squad init --sdk` will be removed in v2 because `squad.config.ts` does not represent the full Squad feature set. Use markdown-first `squad init` for new teams. Existing projects can continue using `squad build` during the transition. > **Phase 1** — Type-safe team configuration with builder functions. -Squad now supports **SDK-First Mode**: define your team in TypeScript with full type safety, runtime validation, and editor autocomplete. Instead of manually maintaining markdown files in `.squad/`, you write clean TypeScript, and `squad build` generates the governance markdown. +Legacy SDK-First Mode defines a team in TypeScript and uses `squad build` to generate governance markdown. This page remains available only for teams maintaining an existing `squad.config.ts`. --- @@ -35,19 +37,19 @@ In SDK-First Mode: This replaces manual `.squad/team.md`, `.squad/routing.md`, and agent charters with a single source of truth in code. -**When to use SDK mode:** For a comparison of SDK-first mode versus CLI mode, see the [Getting started guide](/guide#how-teams-form-init-mode). +The remaining sections document compatibility for teams that already use SDK-first mode. Do not adopt this mode for a new team. --- -## Quick Start +## Maintaining an existing SDK-first project -### 1. Install the SDK +### 1. Keep the SDK dependency installed ```bash npm install @bradygaster/squad-sdk ``` -### 2. Create `squad.config.ts` +### 2. Maintain the existing `squad.config.ts` ```typescript import { @@ -104,50 +106,25 @@ This generates: --- -## Start a new SDK-first project +## Legacy initialization ```bash squad init --sdk ``` -This generates `.squad/` markdown files and a `squad.config.ts` at your project root using the `defineSquad()` builder syntax. Your TypeScript config is the source of truth — edit it, then run `squad build` to regenerate `.squad/`. +This deprecated command remains available temporarily for compatibility testing. It generates `.squad/` markdown files and a `squad.config.ts` at your project root using the `defineSquad()` builder syntax. Do not use it for new production teams. For the full team initialization flow, see [How teams form (Init Mode)](/guide#how-teams-form-init-mode) in the getting started guide. --- -## Migrating an Existing Squad to SDK-First - -```bash -squad migrate --to sdk # generate squad.config.ts from existing .squad/ -squad migrate --to sdk --dry-run # preview without writing -``` - -The migrate command reads your existing `.squad/` files (team.md, routing.md, agent charters) and generates a `squad.config.ts` that reproduces your current configuration using typed builders. - -### What Gets Migrated - -| Source | Generated | -|--------|-----------| -| `.squad/team.md` roster | `defineTeam({ members: [...] })` | -| `.squad/agents/*/charter.md` | `defineAgent({ name, role, ... })` per agent | -| `.squad/routing.md` rules | `defineRouting({ rules: [...] })` | -| `.squad/ceremonies.md` | `defineCeremony()` entries | -| `.squad/casting/policy.json` | `defineCasting()` block | - -### What's Preserved (Not Migrated) - -- `decisions.md` — append-only ledger, stays as-is -- `agents/*/history.md` — personal knowledge, stays as-is -- `orchestration-log/`, `log/` — append-only archives - -### Reverting to Markdown +## Migrating away from SDK-first mode ```bash squad migrate --to markdown ``` -This runs `squad build` to ensure `.squad/` is current, then removes `squad.config.ts`. +This runs `squad build` to ensure `.squad/` is current, then removes `squad.config.ts`. Review the generated markdown before deleting the TypeScript configuration from version control. ### Legacy Migration @@ -484,7 +461,7 @@ defineAgent({ You manually maintain this file and agent charters. -### After (SDK-First) +### Existing SDK-first project ```typescript export default defineSquad({ @@ -519,7 +496,7 @@ Run `squad build` and the markdown is generated. Version control your TypeScript ## Examples -### Full SDK-First Config +### Full legacy SDK-first config ```typescript import { diff --git a/docs/src/content/docs/whatsnew.md b/docs/src/content/docs/whatsnew.md index 52234e34b..0800e1ec0 100644 --- a/docs/src/content/docs/whatsnew.md +++ b/docs/src/content/docs/whatsnew.md @@ -1,5 +1,9 @@ # What's New +> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. + +> ⚠️ **Current status.** SDK-first initialization is deprecated and will be removed in v2. Entries below retain the release history for existing users; use markdown-first `squad init` for new teams. + Full release history for Squad — from beta through the v1 TypeScript replatform. Jump to the version you're looking for, or read top-down to see how the project evolved. --- @@ -7,7 +11,7 @@ Full release history for Squad — from beta through the v1 TypeScript replatfor ## v0.9.1 — Current Release - **Shell agent name extraction** — Robust multi-pattern fallback for extracting agent names from shell transcripts (#577) -- **Init scaffolding** — `squad init --sdk` now scaffolds typed casting files; silences remote-lookup warnings (#579) +- **Init scaffolding (deprecated)** — `squad init --sdk` scaffolded typed casting files and silenced remote-lookup warnings; the flag is retained only for transition compatibility (#579) - **Personal squad global mode** — `squad personal init --global` auto-discovers `~/.config/squad/` (#576) - **Release hardening** — CI playbook rewrite, publish policy linting, docs consistency checks (#564, #557) - **Doctor improvements** — Actionable warnings and `squad.agent.md` existence checks (#565, #533) diff --git a/docs/src/navigation.ts b/docs/src/navigation.ts index bed1f45d4..16e1735d0 100644 --- a/docs/src/navigation.ts +++ b/docs/src/navigation.ts @@ -168,7 +168,7 @@ export const NAV_SECTIONS: NavSection[] = [ ]; export const STANDALONE_PAGES = [ { title: "What's New", slug: 'whatsnew' }, - { title: 'SDK-First Mode', slug: 'sdk-first-mode' }, + { title: 'Legacy SDK-First Mode', slug: 'sdk-first-mode' }, { title: 'Community', slug: 'community' }, { title: 'Insider Program', slug: 'insider-program' }, ]; diff --git a/docs/src/pages/index.astro b/docs/src/pages/index.astro index d7c9927b0..41704a040 100644 --- a/docs/src/pages/index.astro +++ b/docs/src/pages/index.astro @@ -224,8 +224,8 @@ const base = import.meta.env.BASE_URL;
⚡
-

SDK-First Design

-

Define your team in TypeScript with squad.config.ts. Typed, testable, version-controlled.

+

Markdown-First Design

+

Define your team in portable markdown under .squad/. Inspectable, version-controlled, and independent of the CLI.

diff --git a/packages/squad-cli/src/cli-entry.ts b/packages/squad-cli/src/cli-entry.ts index 1a4b160d8..d92f27399 100644 --- a/packages/squad-cli/src/cli-entry.ts +++ b/packages/squad-cli/src/cli-entry.ts @@ -154,7 +154,7 @@ async function main(): Promise { console.log(` ${BOLD}(default)${RESET} Launch interactive shell (no args)`); console.log(` Flags: --global (init in personal squad directory)`); console.log(` ${BOLD}init${RESET} Initialize Squad (markdown-only, default)`); - console.log(` Flags: --sdk (SDK builder syntax)`); + console.log(` Flags: --sdk (deprecated; removed in v2)`); console.log(` --roles (use base roles)`); console.log(` --global (personal squad dir)`); console.log(` --no-workflows (skip CI setup)`); @@ -171,7 +171,7 @@ async function main(): Promise { console.log(` --state-backend (migrate to orphan|two-layer)`); console.log(` ${BOLD}update-check${RESET} Report cached CLI update status (for tooling/CI)`); console.log(` Flags: --json (structured output), --refresh (bypass cache)`); - console.log(` ${BOLD}migrate${RESET} Convert between markdown and SDK-First squad formats`); + console.log(` ${BOLD}migrate${RESET} Convert between markdown and legacy SDK-First squad formats`); console.log(` Flags: --to sdk|markdown, --from ai-team, --dry-run`); console.log(` ${BOLD}sync${RESET} Sync squad-state branch(es) with remote (push/pull/both)`); console.log(` Flags: --push, --pull, --remote , --quiet`); @@ -1172,4 +1172,3 @@ main().catch(err => { } process.exit(1); }); - diff --git a/packages/squad-cli/src/cli/commands/migrate.ts b/packages/squad-cli/src/cli/commands/migrate.ts index 8375e1f30..5ce0d9a53 100644 --- a/packages/squad-cli/src/cli/commands/migrate.ts +++ b/packages/squad-cli/src/cli/commands/migrate.ts @@ -394,7 +394,7 @@ export async function runMigrate(cwd: string, options: MigrateOptions): Promise< console.log(`\n${BOLD}Squad Migrate${RESET} — .ai-team/ → .squad/\n`); await migrateDirectory(cwd); - console.log(`\n${dim('Next:')} Run ${BOLD}squad migrate --to sdk${RESET} to convert to SDK-First mode.`); + console.log(`\n${dim('Next:')} Review the migrated markdown under ${BOLD}.squad/${RESET}.`); return; } @@ -439,6 +439,8 @@ export async function runMigrate(cwd: string, options: MigrateOptions): Promise< // Handle --to sdk (markdown → SDK-First) if (options.to === 'sdk') { + warn('`squad migrate --to sdk` is deprecated and will be removed in v2 (do not start new SDK-first migrations). Keep markdown as the source of truth for new teams.'); + if (mode === 'none') { fatal('No squad found. Run `squad init` first.'); } @@ -510,8 +512,7 @@ export async function runMigrate(cwd: string, options: MigrateOptions): Promise< console.log(); console.log('Your .squad/ directory is the source of truth.'); console.log(); - console.log('To convert to SDK-First mode, run:'); - console.log(` ${BOLD}squad migrate --to sdk${RESET}`); + console.log(`${DIM}SDK-First migration is deprecated; keep markdown as the source of truth for new teams.${RESET}`); } else if (mode === 'sdk') { console.log(`Current mode: ${BOLD}SDK-First${RESET}`); console.log(); diff --git a/packages/squad-cli/src/cli/core/command-help.ts b/packages/squad-cli/src/cli/core/command-help.ts index 90ff42619..9d02f9c41 100644 --- a/packages/squad-cli/src/cli/core/command-help.ts +++ b/packages/squad-cli/src/cli/core/command-help.ts @@ -37,7 +37,7 @@ const COMMAND_HELP: Record = { console.log(`Creates a markdown-based squad layout under .squad/ plus default agent`); console.log(`workflows under .github/. Safe to re-run — existing files are preserved.\n`); console.log(`Options:`); - console.log(` ${BOLD}--sdk${RESET} Use SDK builder syntax (squad.config.ts)`); + console.log(` ${BOLD}--sdk${RESET} Generate squad.config.ts (deprecated; removed in v2)`); console.log(` ${BOLD}--roles${RESET} Seed the team with built-in base roles`); console.log(` ${BOLD}--global${RESET} Initialize in the personal (global) squad directory`); console.log(` ${BOLD}--no-workflows${RESET} Skip writing GitHub Actions workflows`); @@ -76,10 +76,11 @@ const COMMAND_HELP: Record = { }, migrate: (version) => { - header('migrate', version, 'Convert between markdown and SDK-First squad formats'); + header('migrate', version, 'Convert between markdown and legacy SDK-First squad formats'); console.log(`Usage: squad migrate --to sdk|markdown [options]\n`); console.log(`Options:`); - console.log(` ${BOLD}--to sdk|markdown${RESET} Target format`); + console.log(` ${BOLD}--to sdk${RESET} Generate squad.config.ts (deprecated; removed in v2 — do not start new SDK-first migrations)`); + console.log(` ${BOLD}--to markdown${RESET} Convert an existing SDK-First squad to markdown`); console.log(` ${BOLD}--from ai-team${RESET} Source format (defaults to current)`); console.log(` ${BOLD}--dry-run${RESET} Show planned changes without writing\n`); }, diff --git a/packages/squad-cli/src/cli/core/init.ts b/packages/squad-cli/src/cli/core/init.ts index d73ca9039..a2042b60f 100644 --- a/packages/squad-cli/src/cli/core/init.ts +++ b/packages/squad-cli/src/cli/core/init.ts @@ -7,7 +7,7 @@ import path from 'node:path'; import { execFileSync } from 'node:child_process'; import { FSStorageProvider } from '@bradygaster/squad-sdk'; import { detectSquadDir, resolveWorktreeMainCheckout } from './detect-squad-dir.js'; -import { success, BOLD, RESET, YELLOW, GREEN, DIM } from './output.js'; +import { success, warn, BOLD, RESET, YELLOW, GREEN, DIM } from './output.js'; import { fatal } from './errors.js'; import { detectProjectType } from './project-type.js'; import { getPackageVersion, stampVersion } from './version.js'; @@ -174,6 +174,12 @@ export interface RunInitOptions { export async function runInit(dest: string, options: RunInitOptions = {}): Promise { const version = getPackageVersion(); + if (options.sdk) { + warn('`squad init --sdk` is deprecated and will be removed in v2. Use `squad init` for new teams.'); + console.log(`${DIM}Existing squad.config.ts users can continue using ${BOLD}squad build${RESET}${DIM} during the transition.${RESET}`); + console.log(); + } + console.log(); await typewrite(`${DIM}Let's build your team.${RESET}`, 8); console.log(); diff --git a/test/cli/command-help.test.ts b/test/cli/command-help.test.ts index 417643f7c..db540e344 100644 --- a/test/cli/command-help.test.ts +++ b/test/cli/command-help.test.ts @@ -57,6 +57,8 @@ describe('printCommandHelp', () => { const blob = logs.join('\n'); expect(blob).toContain('squad init'); expect(blob).toContain('9.9.9-test'); + expect(blob).toContain('--sdk'); + expect(blob).toContain('deprecated; removed in v2'); expect(blob).toContain('Usage:'); }); @@ -66,6 +68,15 @@ describe('printCommandHelp', () => { expect(logs).toEqual([]); }); + it('marks SDK migration as deprecated', () => { + expect(printCommandHelp('migrate', '9.9.9-test')).toBe(true); + const blob = logs.join('\n'); + expect(blob).toContain('--to sdk'); + expect(blob).toContain('deprecated; removed in v2'); + expect(blob).toContain('do not start new SDK-first migrations'); + expect(blob).toContain('--to markdown'); + }); + it('normalizes subsquads aliases ("streams", "workstreams") to the canonical help block', () => { // Regression guard for PR #1202 review nit: cli-entry.ts routes // `squad streams` and `squad workstreams` to the subsquads command, @@ -197,6 +208,12 @@ describe.skipIf(!cliBuilt)('squad --help end-to-end', () => { rmSync(tempDir, { recursive: true, force: true }); }); + it('top-level help marks --sdk as deprecated', async () => { + const { stdout, stderr } = await runSquad(['--help'], tempDir); + const out = stdout + stderr; + expect(out).toContain('--sdk (deprecated; removed in v2)'); + }); + it('init --help prints help and does NOT scaffold files', async () => { const { stdout, stderr } = await runSquad(['init', '--help'], tempDir); const out = stdout + stderr; diff --git a/test/cli/init.test.ts b/test/cli/init.test.ts index cdd98425e..1ddf7fd7c 100644 --- a/test/cli/init.test.ts +++ b/test/cli/init.test.ts @@ -3,7 +3,7 @@ * Tests that the init command creates expected files in a temp directory */ -import { describe, it, expect, beforeEach, afterEach } from 'vitest'; +import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'; import { mkdir, rm, readdir, readFile, writeFile } from 'fs/promises'; import { join } from 'path'; import { existsSync } from 'fs'; @@ -51,6 +51,21 @@ describe('CLI: init command', () => { expect(content).toContain('version:'); }); + it('warns that --sdk is deprecated while preserving compatibility', async () => { + const log = vi.spyOn(console, 'log').mockImplementation(() => {}); + try { + await runInit(TEST_ROOT, { sdk: true }); + + const output = log.mock.calls.flat().join('\n'); + expect(output).toContain('squad init --sdk'); + expect(output).toContain('deprecated'); + expect(output).toContain('removed in v2'); + expect(existsSync(join(TEST_ROOT, 'squad.config.ts'))).toBe(true); + } finally { + log.mockRestore(); + } + }); + it('should stamp CLI version in squad.agent.md during init (#321)', async () => { await runInit(TEST_ROOT); diff --git a/test/migrate.test.ts b/test/migrate.test.ts index 6ce425dc4..9a67c5e1b 100644 --- a/test/migrate.test.ts +++ b/test/migrate.test.ts @@ -9,11 +9,12 @@ * @module test/migrate */ -import { describe, it, expect, beforeEach, afterEach } from 'vitest'; +import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'; import { mkdtemp, rm, readFile, writeFile, mkdir } from 'fs/promises'; import { join } from 'path'; import { tmpdir } from 'os'; import { existsSync } from 'fs'; +import { runMigrate } from '../packages/squad-cli/src/cli/commands/migrate.js'; // Note: migrate function location TBD - adjust import when implementation lands // Expected at packages/squad-sdk/src/config/migration.ts or cli command @@ -126,6 +127,18 @@ export default defineSquad({ */ }); + it('--to sdk warns that SDK-first migration is deprecated', async () => { + const log = vi.spyOn(console, 'log').mockImplementation(() => {}); + try { + await expect(runMigrate(tempDir, { to: 'sdk' })).rejects.toThrow('No squad found'); + const out = log.mock.calls.flat().join('\n'); + expect(out).toContain('`squad migrate --to sdk` is deprecated and will be removed in v2'); + expect(out).toContain('do not start new SDK-first migrations'); + } finally { + log.mockRestore(); + } + }); + it('--to sdk --dry-run prints preview without writing', async () => { await createMarkdownSquad(tempDir);