docs: Add Squad overview and comprehensive installation guide#1453
Open
ElazarK wants to merge 1 commit into
Open
docs: Add Squad overview and comprehensive installation guide#1453ElazarK wants to merge 1 commit into
ElazarK wants to merge 1 commit into
Conversation
- Add what-is-squad.md in concepts/ with detailed feature overview, architecture, and workflow explanation - Add install-comprehensive.md in get-started/ with step-by-step CLI, VS Code, and SDK installation paths - Both articles include prerequisites, troubleshooting, and optional advanced setup sections - Format adapted for Astro docs structure Co-authored-by: Elazar Krieger <elkrieger@microsoft.com>
Contributor
🟢 Impact Analysis — PR #1453Risk tier: 🟢 LOW 📊 Summary
🎯 Risk Factors
📦 Modules Affecteddocs (2 files)
This report is generated automatically for every PR. See #733 for details. |
Contributor
🛫 PR Readiness Check
PR Scope: 🔧 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 | No source files changed — changeset not required |
| ✅ | Scope clean | No .squad/ or docs/proposals/ files |
| ✅ | No merge conflicts | No merge conflicts |
| ✅ | Copilot threads resolved | No Copilot review threads |
| ❌ | CI passing | 6 check(s) still running |
Files Changed (2 files, +336 −0)
| File | +/− |
|---|---|
docs/src/content/docs/concepts/what-is-squad.md |
+129 −0 |
docs/src/content/docs/get-started/install-comprehensive.md |
+207 −0 |
Total: +336 −0
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.
Pull request overview
This PR adds two new documentation pages to the Astro docs site: a conceptual overview of Squad (architecture/capabilities) and a comprehensive installation guide covering CLI/VS Code/SDK paths plus troubleshooting.
Changes:
- Add a new “What is Squad?” concepts article describing core components, workflow, and governance.
- Add a new “Installation (comprehensive)” get-started guide covering install/update/init/validation and optional personal squad + typed config.
- Include onboarding-friendly sections like troubleshooting and cross-project personal squad setup.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 6 comments.
| File | Description |
|---|---|
| docs/src/content/docs/get-started/install-comprehensive.md | New installation guide; currently contains several correctness issues (Node version requirement, npx usage, personal squad path, typed config example, stale expected output). |
| docs/src/content/docs/concepts/what-is-squad.md | New conceptual overview; one claim about memory persistence “across branches” is misleading given .squad/ is typically git-tracked and branch-specific. |
Comment on lines
+11
to
+13
| - **[Node.js 20 or later](https://nodejs.org/en/download)** — verify by running `node --version` | ||
| - **[A Git repository](https://git-scm.com/)** (new or existing) | ||
| - **[GitHub Copilot](https://github.com/features/copilot)** — required for the VS Code agent workflow |
| squad status | ||
| ``` | ||
|
|
||
| You can also use `npx squad status` if you skipped the global install. |
Comment on lines
+148
to
+154
| Squad writes the personal configuration to a platform-specific path: | ||
|
|
||
| | Platform | Path | | ||
| | --- | --- | | ||
| | Linux | `~/.config/squad/` | | ||
| | macOS | `~/Library/Application Support/squad/` | | ||
| | Windows | `%APPDATA%\squad\` | |
Comment on lines
+160
to
+170
| ```typescript | ||
| import { defineConfig } from '@bradygaster/squad-sdk'; | ||
|
|
||
| export default defineConfig({ | ||
| agents: { | ||
| dir: '.github/agents', | ||
| }, | ||
| squad: { | ||
| dir: '.squad', | ||
| }, | ||
| }); |
Comment on lines
+21
to
+24
| ### Persistent memory across sessions | ||
|
|
||
| Each agent writes its working state to `.squad/agents/`. Memory persists between VS Code sessions, across branches, and across team members. An agent that reviewed a pull request yesterday remembers the context when it picks up the follow-on task today. | ||
|
|
Comment on lines
+108
to
+116
| **Expected output:** | ||
|
|
||
| ``` | ||
| ✅ Squad installed. | ||
| .github/agents/squad.agent.md — coordinator agent | ||
| .squad/templates/ — 11 template files | ||
|
|
||
| Open GitHub Copilot and select Squad from the agent list. | ||
| ``` |
tamirdresher
reviewed
Jul 7, 2026
tamirdresher
left a comment
tamirdresher
left a comment
Collaborator
There was a problem hiding this comment.
Nice docs addition. A few things to fix before merge:
- Broken internal link in the overview page.
npm bin -gis deprecated in npm 9+ — recommend replacing with the current equivalent.- The governance section overstates enforcement guarantees relative to how Squad actually behaves; suggest softening the wording for public docs.
Collaborator
|
Thanks for putting this together, @ElazarK — the two new pages fill a real gap and read well. Consolidating my earlier review plus Copilot's inline notes into one ask so you have a single revision list. All items are confirmed against
Could you push one focused revision covering these items and I'll re-review right away? Really appreciate the contribution. |
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.
This PR adds two new documentation articles to the Squad docs:
What's included
Key features
Both articles provide thorough setup guidance for new Squad users.