chore(cli): deprecate SDK-first initialization - #1968
tamirdresher wants to merge 7 commits into
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>
🏗️ Architectural Review
Automated architectural review — informational only. |
🟡 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. |
🛫 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.
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
left a comment
bradygaster
left a comment
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.
## 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
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.
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>
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>
bradygaster
left a comment
bradygaster
left a comment
There was a problem hiding this comment.
EECOM review — PR #1968
Verdict: Changes recommended (blocking messaging-consistency gaps; core runtime/build compatibility is otherwise sound).
What I verified as correct
runInit()only adds awarn()+ compatibility note whenoptions.sdkis set; the actualconfigFormat: options.sdk ? 'sdk' : 'markdown'branch and all downstream scaffolding are untouched —squad init --sdkstill works, non-interactively and without polluting any JSON/stdout parsing path (no--jsonmode oninit).squad build,squad build --check,squad migrate --to markdown, and all ofpackages/squad-sdkare untouched — programmatic SDK and existingsquad.config.tsbuild compatibility is fully preserved.- Rebuilt the branch (
npm run build) and rannpx vitest run test/cli/init.test.ts test/cli/command-help.test.ts— 32/32 pass, matching the PR description. - All 7 review threads from the Copilot review are resolved; all required checks are green (the readiness comment showing unresolved items is stale).
- Changeset is correctly scoped (
patchon@bradygaster/squad-clionly).
Blocking findings
-
[high] Homepage still markets SDK-first as a current headline feature —
docs/src/pages/index.astro(feature grid, "SDK-First Design" card, ~line 227) still reads: "Define your team in TypeScript withsquad.config.ts. Typed, testable, version-controlled." with no deprecation notice. This directly contradicts the new "Markdown-first design" framing this same PR adds todocs/src/content/docs/concepts/what-is-squad.md. The homepage is the most prominent "active reference" a new user sees, and it was not touched by this PR despite the summary's claim to update messaging "across CLI help, READMEs, onboarding, navigation, role guidance, and active references." Please either remove/relabel this card or add a deprecation note consistent with the rest of the PR. -
[medium]
squad migrate --to sdkCLI help/runtime doesn't match the new docs —docs/src/content/docs/guide.md's command table now sayssquad migrate --to sdkis "Deprecated; do not start new SDK-first migrations," butpackages/squad-cli/src/cli/core/command-help.ts(migratehelp) andpackages/squad-cli/src/cli/commands/migrate.ts(runtime) emit no deprecation warning at all. Verified directly:node dist/cli-entry.js migrate --helpstill prints "Convert between markdown and SDK-First squad formats" with zero deprecation indication. Since this PR's stated goal is CLI-help consistency and it already touchescommand-help.tsforinit, the same treatment should be applied tomigrate --to sdk(or the guide.md wording should be walked back to avoid overstating what the CLI actually communicates).
Non-blocking note
docs/src/content/docs/whatsnew.md's new "Current status" deprecation banner says deprecated SDK-first mode is "described in older entries below," but the very next bullet is under v0.9.1 — Current Release: "Init scaffolding —squad init --sdknow scaffolds typed casting files..." — worded as an active, still-improving feature. Consider a short deprecation aside on that specific bullet, or reword the banner so it doesn't imply the current-release entry is "older."
Blockers to merge
- Findings 1–2 above (messaging inconsistency on a primary user-facing surface + CLI help/runtime not matching docs it introduces).
- No code/build/test blockers — everything else in the diff is accurate and internally consistent.
bradygaster
left a comment
bradygaster
left a comment
There was a problem hiding this comment.
I reviewed the current diff and cannot approve this yet. Please update the homepage SDK-First Design content and add a deprecation note to the squad migrate --to sdk help text. The current branch leaves those user-facing surfaces inconsistent with the deprecation described elsewhere.
|
👋 Friendly nudge — this PR has had no activity for 7 days. What needs attention:
If this PR is abandoned, please close it. If it's blocked on something external, leave a comment so the team knows. |
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)