chore(cli): deprecate SDK-first initialization - #1968
Open
tamirdresher wants to merge 7 commits into
Open
Conversation
## Summary - Warn when users invoke squad init --sdk and announce removal in v2 - Keep squad build compatibility for existing squad.config.ts projects - Update English and Chinese guidance to recommend markdown-first initialization - Document the accepted deprecation decision and add a CLI changeset Closes bradygaster#341 Closes bradygaster#347 ## Test Plan - npm run build - npm exec vitest run test/cli/init.test.ts test/cli/command-help.test.ts - npm exec markdownlint-cli2 on updated documentation Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Contributor
🏗️ Architectural Review
Automated architectural review — informational only. |
Contributor
🟡 Impact Analysis — PR #1968Risk tier: 🟡 MEDIUM 📊 Summary
🎯 Risk Factors
📦 Modules Affecteddocs (11 files)
root (3 files)
squad-cli (3 files)
tests (2 files)
This report is generated automatically for every PR. See #733 for details. |
Contributor
🛫 PR Readiness Check
PR Scope: 📦🔧 Mixed (product + infrastructure)
|
| Status | Check | Details |
|---|---|---|
| ❌ | Single commit | 7 commits — consider squashing before review |
| ✅ | Not in draft | Ready for review |
| ✅ | Branch up to date | Up to date with dev |
| ❌ | Copilot review | No Copilot review yet — it may still be processing |
| ✅ | Changeset present | Changeset file found |
| ✅ | Scope clean | |
| ✅ | No merge conflicts | No merge conflicts |
| ❌ | Copilot threads resolved | 1 unresolved Copilot thread(s) — fix and resolve before merging |
| ❌ | CI passing | 6 check(s) still running |
Files Changed (19 files, +112 −130)
| File | +/− |
|---|---|
.changeset/deprecate-sdk-init.md |
+5 −0 |
README.md |
+3 −18 |
README.zh.md |
+3 −18 |
docs/proposals/deprecate-sdk-init.md |
+24 −0 |
docs/src/content/blog/024-v0823-release.md |
+2 −0 |
docs/src/content/docs/concepts/what-is-squad.md |
+2 −3 |
docs/src/content/docs/features/built-in-roles.md |
+3 −1 |
docs/src/content/docs/get-started/installation.md |
+2 −0 |
docs/src/content/docs/guide.md |
+11 −44 |
docs/src/content/docs/reference/config.md |
+4 −2 |
docs/src/content/docs/reference/sdk.md |
+3 −1 |
docs/src/content/docs/sdk-first-mode.md |
+14 −37 |
docs/src/content/docs/whatsnew.md |
+2 −0 |
docs/src/navigation.ts |
+1 −1 |
packages/squad-cli/src/cli-entry.ts |
+1 −2 |
packages/squad-cli/src/cli/core/command-help.ts |
+1 −1 |
packages/squad-cli/src/cli/core/init.ts |
+7 −1 |
test/cli/command-help.test.ts |
+8 −0 |
test/cli/init.test.ts |
+16 −1 |
Total: +112 −130
This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.
Contributor
There was a problem hiding this comment.
Copilot review overview
🟡 Changes recommended
The docs introduce a new [!CAUTION] admonition syntax and the init test mixes package vs source import paths, both of which reduce consistency and confidence in rendered output and test representativeness.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Review tier: Lite
Findings: 1
New issues introduced by this change (4)
| Severity | Finding |
|---|---|
 |
test/cli/init.test.ts — This test file imports runInit from the published entrypoint and also imports the same module via a… |
 |
docs/src/content/docs/sdk-first-mode.md — The docs currently use blockquote callouts like > ⚠️ **Experimental** — .... The new `>… |
|
docs/src/content/docs/reference/sdk.md — This page introduces > [!CAUTION] for an admonition, but the surrounding docs typically use `> |
|
docs/src/content/docs/reference/config.md — [!CAUTION] isn’t used elsewhere in these docs; existing callouts use the `> |
What changed in this PR
This PR deprecates SDK-first initialization (squad init --sdk) across the CLI, help output, and documentation, while keeping squad build working for existing squad.config.ts projects during the transition to v2.
Changes:
- Add a deprecation warning path when
runInit(..., { sdk: true })is used, while keeping the flag functional. - Update CLI help text (top-level and
inithelp) and strengthen tests to assert deprecation messaging. - Update docs/READMEs to recommend markdown-first initialization and record the accepted decision + include a CLI changeset.
| File | Description |
|---|---|
packages/squad-cli/src/cli/core/init.ts |
Emits deprecation warning when --sdk is used while preserving compatibility. |
packages/squad-cli/src/cli/core/command-help.ts |
Marks init --sdk as deprecated in command help output. |
packages/squad-cli/src/cli-entry.ts |
Marks --sdk as deprecated in top-level CLI help text. |
test/cli/init.test.ts |
Adds coverage for the deprecation warning + compatibility behavior. |
test/cli/command-help.test.ts |
Asserts --sdk deprecation is reflected in help output. |
README.md |
Updates SDK-first section to “Deprecated” and points to legacy compatibility docs. |
README.zh.md |
Chinese README: same deprecation shift + legacy compatibility pointer. |
docs/src/content/docs/sdk-first-mode.md |
Reframes SDK-first docs as legacy/compatibility-focused and discourages new adoption. |
docs/src/content/docs/reference/sdk.md |
Adds deprecation notice for SDK-first builders. |
docs/src/content/docs/reference/config.md |
Adds deprecation notice for squad.config.ts reference. |
docs/src/content/docs/guide.md |
Updates guide to label SDK-first mode and related commands as deprecated/legacy. |
docs/src/content/docs/concepts/what-is-squad.md |
Reorients concept framing to markdown-first and notes legacy deprecation. |
docs/proposals/deprecate-sdk-init.md |
Records the accepted decision and rationale for deprecating --sdk init. |
.changeset/deprecate-sdk-init.md |
Patch changeset for @bradygaster/squad-cli documenting the deprecation. |
Suppressed comments (1)
test/cli/init.test.ts:59
- Use the same
runInitimport used by the rest of the file when exercising--sdkdeprecation behavior, so this test validates the public entrypoint rather than a second import path.
const log = vi.spyOn(console, 'log').mockImplementation(() => {});
try {
await runInitFromSource(TEST_ROOT, { sdk: true });
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
bradygaster
approved these changes
Sep 1, 2026
bradygaster
left a comment
bradygaster
left a comment
Owner
There was a problem hiding this comment.
kill it with fire and never allow me to make a bad decision like this without significant ridicule.
bradygaster
approved these changes
Sep 3, 2026
## Summary - Address Copilot review feedback by using the public init import and established warning callouts - Remove SDK-first recommendations from active onboarding and role documentation - Label the compatibility guide clearly in navigation and references ## Test Plan - npm run build - npm exec vitest run test/cli/init.test.ts test/cli/command-help.test.ts - npm run docs:build Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Restore the role guide's existing line endings while keeping the SDK-first deprecation notice. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…k-init # Conflicts: # docs/src/content/docs/get-started/install-comprehensive.md # docs/src/content/docs/get-started/installation.md
Contributor
There was a problem hiding this comment.
Copilot encountered an error: Your billing is not configured or you have Copilot licenses from multiple standalone organizations or enterprises. To use premium requests, select a billing entity via the GitHub site, under Settings > Copilot > Features.
Contributor
There was a problem hiding this comment.
Copilot review overview
🟢 Approval recommended
The functional behavior remains compatible, tests cover the deprecation messaging, and the remaining feedback is limited to small documentation/help-text consistency nits.
Review tier: Lite
Findings: 2
New issues introduced by this change (2)
| Severity | Finding |
|---|---|
|
docs/src/content/docs/sdk-first-mode.md — The page is now presented throughout the docs/nav as “Legacy SDK-First Mode”, but the H1 still… |
|
packages/squad-cli/src/cli/core/command-help.ts — The init subcommand help uses a different deprecation style/casing (“Deprecated: …”) than other… |
Clarify that the deprecation applies to squad.config.ts file authoring, not the supported programmatic SDK APIs. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Copilot review overview
🟡 Changes recommended
Prominent user-facing docs still describe SDK-first as current/recommended (e.g., “What’s New” current release notes), which conflicts with the PR’s stated goal of recommending markdown-first across active references.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Review tier: Lite
Findings: 3
New issues introduced by this change (1)
| Severity | Finding |
|---|---|
|
docs/src/content/docs/guide.md — This guide correctly marks squad init --sdk as deprecated, but there are still prominent docs… |
Pre-existing issues (2)
| Severity | Finding |
|---|---|
|
packages/squad-cli/src/cli/core/command-help.ts — The init subcommand help uses a different deprecation style/casing (“Deprecated: …”) than other… View comment |
|
docs/src/content/docs/sdk-first-mode.md — The page is now presented throughout the docs/nav as “Legacy SDK-First Mode”, but the H1 still… View comment |
Suppressed comments (1)
docs/src/content/docs/sdk-first-mode.md:1
- The page is now positioned as “legacy”, but the H1 still reads “SDK-First Squad Mode”. This makes the navigation/title inconsistent (e.g., sidebar says “Legacy SDK-First Mode”) and can confuse readers about what’s recommended.
# SDK-First Squad Mode
Align legacy guide and CLI help naming, and mark historical SDK-first release pages with the current deprecation status. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
squad init --sdkand announce its removal in v2squad buildcompatibility for existingsquad.config.tsprojectsCloses #341
Closes #347
Testing
npm run buildnpm exec vitest run test/cli/init.test.ts test/cli/command-help.test.ts(32 passed)