Repository navigation
docs: add agent-first Squad setup guide - #2529
bradygaster wants to merge 7 commits into
Conversation
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Ask the owner to choose newest (incl. prerelease) or stable, resolve the tag from GitHub Releases, install checksum-verified release assets, and use npm only as a version-pinned fallback. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
🟡 Changes recommended
The documentation still contains unresolved setup and release-flow defects, including unverified script execution, architecture mismatch, missing PowerShell tag initialization, unintended VS Code changes, and an incomplete PR-body command.
5 open issues
What changed in this PR
Adds an agent-first Squad setup guide for Claude and GitHub Copilot, covering release-based installation, repository-specific customization, validation, and pull-request creation, while clarifying the canonical repository and exposing the guide throughout the documentation.
Changes:
- Added the comprehensive agent-first setup workflow with stable and prerelease selection, platform installation, customization, validation, and PR instructions.
- Linked the guide from the README and installation documentation.
- Added the guide to documentation navigation and build expectations.
| File | Description |
|---|---|
| test/docs-build.test.ts | Updates documentation build expectations to include the new agent setup page. |
| README.md | Clarifies that github/squad is the canonical repository and links to the agent setup guide. |
| docs/src/navigation.ts | Adds the agent setup guide to the Get Started documentation navigation. |
| docs/src/content/docs/get-started/installation.md | Links the installation documentation to the agent setup guide. |
| docs/src/content/docs/get-started/agent-setup.md | Adds release-based installation, repository customization, validation, and pull-request workflow instructions for Claude and GitHub Copilot. |
Review effort: Lite (adaptive)
🛫 PR Readiness Check
PR Scope: 🔧 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 | No source files changed — changeset not required |
| ✅ | Scope clean | No .squad/ or docs/proposals/ files |
| ✅ | No merge conflicts | No merge conflicts |
| ✅ | Copilot threads resolved | 1 active Copilot thread(s) resolved (4 outdated skipped) |
| ✅ | CI passing | All checks passing |
Files Changed (5 files, +312 −2)
| File | +/− |
|---|---|
README.md |
+8 −1 |
docs/src/content/docs/get-started/agent-setup.md |
+299 −0 |
docs/src/content/docs/get-started/installation.md |
+3 −0 |
docs/src/navigation.ts |
+1 −0 |
test/docs-build.test.ts |
+1 −1 |
Total: +312 −2
This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.
🟡 Impact Analysis — PR #2529Risk tier: 🟡 MEDIUM 📊 Summary
🎯 Risk Factors
📦 Modules Affecteddocs (3 files)
root (1 file)
tests (1 file)
This report is generated automatically for every PR. See #733 for details. |
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>


What
Adds an agent-first setup guide for Claude and GitHub Copilot that installs a user-selected stable or newest/prerelease Squad build from
github/squadGitHub Releases, customizes the generated team for the target repository, validates it, and opens a pull request. It also clarifies in the README thatgithub/squadis the canonical repository while legacy-named package-manager identifiers remain distribution names.Why
Repository owners need a single prompt they can paste into an agent session to receive a safe, codebase-specific Squad configuration rather than a generic initialization. GitHub Releases provide an inspectable source for stable and preview artifacts without relying on npm dist-tags.
No linked issue.
How
The guide asks the owner to choose the newest release (including prereleases) or newest stable release, resolves the exact tag through GitHub Releases, installs checksum-verified platform assets, and uses a pinned npm version only as a fallback. It then walks the agent through repository analysis, Squad initialization, Claude/Copilot discovery files, customization, review, validation, and PR creation while preserving existing instructions and keeping CI opt-in.
npx changeset add/.changeset/*.md, directCHANGELOG.mdentry for maintainers, orskip-changeloglabel for no user-facing changes) — N/A, documentation onlyPR Readiness Checklist
Branch & Commit
dev(notmain)devBuild & Test
npm run buildpasses — not run for documentation-only changesnpm testpasses — targetednpx vitest run test/docs-build.test.tspassed (22/22)npm run lintpasses — not run for documentation-only changesnpm run lint:eslintpasses — not run for documentation-only changesChangeset
npx changeset add— N/A, no SDK/CLI source changesCHANGELOG.mdentry — N/Askip-changeloglabel applied — N/ADocs
Exports
Breaking Changes
None.
Waivers
None.