Repository navigation
chore(cli): deprecate SDK-first initialization - #1968
tamirdresher wants to merge 1 commit into
Conversation
🏗️ Architectural Review
Automated architectural review — informational only. |
🟠 Impact Analysis — PR #1968Risk tier: 🟠 HIGH 📊 Summary
🎯 Risk Factors
📦 Modules Affecteddocs (14 files)
root (3 files)
squad-cli (4 files)
tests (3 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 | 1 commit — clean history |
| ✅ | 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 active Copilot thread(s) resolved (6 outdated skipped) |
| ❌ | CI passing | 2 check(s) still running |
Files Changed (24 files, +165 −156)
| 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 |
+12 −14 |
docs/src/content/docs/concepts/what-is-squad.md |
+2 −2 |
docs/src/content/docs/features/built-in-roles.md |
+3 −1 |
docs/src/content/docs/features/enterprise-platforms.md |
+4 −2 |
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/reference/tools-and-hooks.md |
+3 −1 |
docs/src/content/docs/sdk-first-mode.md |
+14 −37 |
docs/src/content/docs/whatsnew.md |
+5 −1 |
docs/src/navigation.ts |
+1 −1 |
docs/src/pages/index.astro |
+2 −2 |
packages/squad-cli/src/cli-entry.ts |
+2 −3 |
packages/squad-cli/src/cli/commands/migrate.ts |
+4 −3 |
packages/squad-cli/src/cli/core/command-help.ts |
+4 −3 |
packages/squad-cli/src/cli/core/init.ts |
+7 −1 |
test/cli/command-help.test.ts |
+17 −0 |
test/cli/init.test.ts |
+16 −1 |
test/migrate.test.ts |
+14 −1 |
Total: +165 −156
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.
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… |
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
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. |
|
👋 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. |
|
👋 Friendly nudge — this PR has had no activity for 10 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. |
Preserve the SDK-init deprecation review fixes while resolving the dev merge conflicts in release notes and init coverage. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 56b93cdd-082a-48a9-a5b5-bde7429ad4ce
Bring the deprecation remediation branch current without rebasing or force-pushing. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 56b93cdd-082a-48a9-a5b5-bde7429ad4ce
Mark remaining squad.config.ts guidance as legacy compatibility and remove the SDK-first adoption CTA from the historical release post. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 56b93cdd-082a-48a9-a5b5-bde7429ad4ce
Clarify the historical SDK-First release guidance and align top-level migrate help with the legacy terminology. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 56b93cdd-082a-48a9-a5b5-bde7429ad4ce
Label legacy migration steps as historical compatibility context and direct new teams to markdown-first squad init. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 56b93cdd-082a-48a9-a5b5-bde7429ad4ce
97b7d18 to
9c89057
Compare
- 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 github#341 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 5cf0811c-a02a-41a7-ab00-904b6900db7b
9c89057 to
4dc7248
Compare
|
Rebased onto latest dev (5cd199c) as a single clean commit (4dc7248) and addressed all review items:
Ready for re-review @bradygaster. |
|
👋 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. |
|
👋 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. |
|
👋 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)