chore(cli): deprecate SDK-first initialization

.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.

README.md

@@ -460,26 +460,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.
 
 ---
 

README.zh.md

@@ -262,26 +262,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)。
 
 ---
 

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.

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

docs/src/content/docs/concepts/what-is-squad.md

@@ -35,9 +35,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
 
@@ -126,4 +126,3 @@ Squad is built on the principle that agentic systems must remain under human con
 
 Agents in Squad propose, draft, and record. Humans review, approve, and are accountable for final output. The governance features built into Squad, including reviewer lockout, escalation points, and auditable decision logs, are not optional settings. They are part of the framework's design contract. Squad extends human teams at scale; it doesn't remove the human from the loop.
 
-

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';

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.
 

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 <file> --force` | Import, archiving existing agents |
 | `squad plugin install <name>` | 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 |

docs/src/content/docs/reference/config.md

@@ -13,7 +13,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 {
@@ -127,7 +129,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

docs/src/content/docs/reference/sdk.md

@@ -90,6 +90,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
@@ -340,4 +342,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

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 {