From 4ccb71007c386903d1f73e1be0df0a03713a27d7 Mon Sep 17 00:00:00 2001 From: bradygaster Date: Thu, 19 Feb 2026 20:17:57 -0800 Subject: [PATCH 1/2] fix: clarify /agent vs /agents for CLI and VS Code (#93) The Copilot CLI uses /agent (singular) while VS Code uses /agents (plural). Updated documentation to show both commands so users on either platform find the right command without confusion. Changes: - README.md: Already had correct dual-platform instructions - index.js: Already had correct dual-platform instructions - docs/tour-first-session.md: Updated to show /agent (CLI) or /agents (VS Code) - docs/scenarios/existing-repo.md: Updated in 2 places for dual platforms - docs/scenarios/mid-project.md: Updated to show /agent (CLI) or /agents (VS Code) - docs/scenarios/new-project.md: Updated in 2 places for dual platforms - docs/scenarios/private-repos.md: Updated to show /agent (CLI) or /agents (VS Code) - docs/scenarios/troubleshooting.md: Updated problem statement Fixes #93 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../skills/squadified-repo-discovery/SKILL.md | 158 +++++++++++ .../skills/squadified-repo-report/SKILL.md | 246 ++++++++++++++++++ docs/scenarios/existing-repo.md | 4 +- docs/scenarios/mid-project.md | 2 +- docs/scenarios/new-project.md | 4 +- docs/scenarios/private-repos.md | 2 +- docs/scenarios/troubleshooting.md | 2 +- docs/tour-first-session.md | 2 +- templates/workflows/squad-main-guard.yml | 62 ++++- 9 files changed, 460 insertions(+), 22 deletions(-) create mode 100644 .ai-team/skills/squadified-repo-discovery/SKILL.md create mode 100644 .ai-team/skills/squadified-repo-report/SKILL.md diff --git a/.ai-team/skills/squadified-repo-discovery/SKILL.md b/.ai-team/skills/squadified-repo-discovery/SKILL.md new file mode 100644 index 000000000..e965f0df1 --- /dev/null +++ b/.ai-team/skills/squadified-repo-discovery/SKILL.md @@ -0,0 +1,158 @@ +--- +name: "squadified-repo-discovery" +description: "Find all repositories using Squad (bradygaster/squad) across GitHub — public and private" +domain: "community-analysis" +confidence: "medium" +source: "earned" +tools: + - name: "github-mcp-server-search_code" + description: "GitHub code search API — searches file contents across repos" + when: "Primary discovery method for public repos" + - name: "gh search code" + description: "GitHub CLI code search — includes private repos the user has access to" + when: "Discovers private repos not visible to API search" + - name: "gh api" + description: "Direct GitHub API calls to check specific repos" + when: "Verify individual repos, check non-default branches" +--- + +## Context + +Squad leaves a reliable fingerprint in every repo it's installed in: `.github/agents/squad.agent.md`. This file is committed to the repo (unlike `.ai-team/` which is often gitignored or blocked from main by the guard workflow). Searching for this file is the most reliable way to find squadified repositories. + +This skill is used to produce a comprehensive list of all squadified repos for impact reporting, community tracking, and adoption metrics. Run it periodically ("on a reggie") to track growth. + +## Patterns + +### Primary Search: squad.agent.md (highest signal) + +The most reliable fingerprint. Every squadified repo has this file. + +**Via GitHub MCP (public repos only):** +``` +github-mcp-server-search_code: + query: 'path:.github/agents "squad.agent.md"' + perPage: 100 +``` + +**Via gh CLI (public + private repos the authenticated user can access):** +```bash +gh search code "squad.agent.md" --filename squad.agent.md --json repository --limit 100 +``` + +The gh CLI search is critical — it surfaces private repos that the MCP search cannot see. Always run both. + +### Secondary Searches: Additional Fingerprints + +These catch repos where `squad.agent.md` might be on a non-default branch: + +``` +# .ai-team/ directory committed to a visible branch +github-mcp-server-search_code: + query: 'path:.ai-team/team.md "## Members"' + +# Casting registry (confirms full Squad setup, not just agent file) +github-mcp-server-search_code: + query: 'path:.ai-team/casting/registry.json "persistent_name"' + +# Squad workflows +github-mcp-server-search_code: + query: 'path:.github/workflows/squad-main-guard.yml' + +# .gitattributes merge driver (Squad-specific pattern) +github-mcp-server-search_code: + query: 'path:.gitattributes ".ai-team/decisions.md merge=union"' +``` + +### Private Repo Deep Scan + +For known owners/orgs, enumerate their repos and check individually: + +```bash +# List all private repos for an owner +gh repo list {owner} --json name,isPrivate --limit 100 --jq '.[] | select(.isPrivate==true) | .name' + +# Check each for squad.agent.md +gh api repos/{owner}/{repo}/contents/.github/agents/squad.agent.md --jq '.name' 2>&1 +``` + +This is necessary because: +- Private repos may not appear in code search results +- Some repos have `.ai-team/` gitignored but still have the agent file +- The guard workflow blocks `.ai-team/` from main/preview, but `.github/agents/` is always committed + +### Known Owner List + +Maintain and grow this list. These are confirmed Squad adopters to deep-scan: + +``` +bradygaster, csharpfritz, FritzAndFriends, spboyer, elbruno, +mpaulosky, fboucher, quartznet, carlfranklin, lucabol, +Ansteorra, londospark, lewing, shelwig, danielscholl-osdu, mlinnen +``` + +### Result Deduplication + +Both search methods may return duplicates. Deduplicate by `owner/repo` (case-insensitive). Track: +- `owner/repo` +- `isPrivate` (boolean) +- `isFork` (boolean — exclude forks from primary counts) +- Discovery method (MCP search, gh CLI search, deep scan) + +### Verification Step + +For repos found only via secondary searches (not `squad.agent.md`), verify with a direct API check: + +```bash +gh api repos/{owner}/{repo}/contents/.github/agents/squad.agent.md --jq '.name' +``` + +If this returns 404, the repo may have Squad on a non-default branch only. Note this in the results. + +### Rate Limit Management + +GitHub code search has aggressive rate limits (~10 requests/minute for authenticated users). Strategy: +1. Run the primary `squad.agent.md` search first (highest value) +2. Run secondary searches only if primary returns < expected results +3. Space searches 40+ seconds apart if rate-limited +4. Use `gh` CLI as fallback — different rate limit pool than MCP + +## Examples + +### Full Discovery Run + +``` +1. MCP search: path:.github/agents "squad.agent.md" → 24 public repos +2. gh CLI search: squad.agent.md --filename → 32 repos (public + private) +3. Deep scan known owners' private repos → 2 additional private repos +4. Deduplicate → 33 unique repos +5. Verify stragglers → 31 confirmed squadified +6. Compile final list with owner, visibility, fork status +``` + +### Output Format + +Present results as a table grouped by owner: + +``` +| Owner | Repo | Visibility | Notes | +|-------|------|------------|-------| +| bradygaster | squad | Public | Source repo | +| bradygaster | AspireSquad | Public | .NET Aspire | +| bradygaster | Influence | Private | — | +| ... | ... | ... | ... | +``` + +Include summary counts: +- Total repos +- Public vs. private +- Unique owners/orgs +- New since last scan (if prior scan data exists) + +## Anti-Patterns + +- **Don't search only for `.ai-team/` files.** The guard workflow blocks these from main. You'll miss most repos. +- **Don't skip the gh CLI search.** MCP search only sees public repos. Private repos are invisible without it. +- **Don't search by repo description.** Many projects use "squad" in their name/description but aren't using bradygaster/squad. The agent file is the only reliable fingerprint. +- **Don't assume one search catches everything.** GitHub code search indexes branches inconsistently. Run multiple queries and deduplicate. +- **Don't forget rate limits.** Space searches apart. The 403 error is silent — you'll get empty results, not an error, if you're rate-limited on MCP. diff --git a/.ai-team/skills/squadified-repo-report/SKILL.md b/.ai-team/skills/squadified-repo-report/SKILL.md new file mode 100644 index 000000000..0861559c8 --- /dev/null +++ b/.ai-team/skills/squadified-repo-report/SKILL.md @@ -0,0 +1,246 @@ +--- +name: "squadified-repo-report" +description: "Build an impact report from discovered squadified repositories — adoption metrics, activity signals, and community insights" +domain: "community-analysis" +confidence: "medium" +source: "earned" +tools: + - name: "github-mcp-server-search_code" + description: "Search for Squad-specific files within repos" + when: "Checking for .ai-team/ files, casting registry, decisions" + - name: "github-mcp-server-get_file_contents" + description: "Read files from remote repos" + when: "Reading team.md, registry.json, decisions.md from each repo" + - name: "github-mcp-server-list_issues" + description: "List issues in a repo" + when: "Counting issues for activity metrics" + - name: "github-mcp-server-list_pull_requests" + description: "List PRs in a repo" + when: "Counting PRs for activity metrics" + - name: "github-mcp-server-list_commits" + description: "List commits in a repo" + when: "Counting commits and checking activity recency" + - name: "gh api" + description: "Direct GitHub API for metrics not available via MCP" + when: "Getting contributor counts, repo metadata, branch info" +--- + +## Context + +After discovering squadified repos (see `squadified-repo-discovery` skill), this skill produces a comprehensive impact report. The report quantifies Squad's real-world adoption and the value it's delivering across the community. + +This report is used for: +- Tracking adoption growth over time +- Demonstrating Squad's impact to stakeholders +- Identifying patterns in how teams use Squad +- Celebrating community achievements + +## Patterns + +### Data Collection Per Repo + +For each discovered repo, gather these data points: + +#### Core Metrics (from GitHub API) + +```bash +# Issues (total, open, closed) +gh issue list --repo {owner/repo} --state all --json number --limit 1000 | jq length +gh issue list --repo {owner/repo} --state open --json number --limit 1000 | jq length +gh issue list --repo {owner/repo} --state closed --json number --limit 1000 | jq length + +# Pull Requests (total, open, closed/merged) +gh pr list --repo {owner/repo} --state all --json number --limit 1000 | jq length +gh pr list --repo {owner/repo} --state open --json number --limit 1000 | jq length +gh pr list --repo {owner/repo} --state closed --json number --limit 1000 | jq length + +# Commits (recent activity) +gh api repos/{owner/repo}/commits --jq length +# Or: github-mcp-server-list_commits for paginated access + +# Stars, forks, watchers +gh api repos/{owner/repo} --jq '{stars: .stargazers_count, forks: .forks_count, watchers: .watchers_count}' + +# Contributors +gh api repos/{owner/repo}/contributors --jq length + +# Languages +gh api repos/{owner/repo}/languages +``` + +#### Squad-Specific Metrics (from file contents) + +Read these files when accessible (may be blocked by guard workflow on main): + +``` +# Team composition +.ai-team/team.md → roster size, member roles, universe used +.ai-team/casting/registry.json → universe name, agent count, casting dates + +# Decision density +.ai-team/decisions.md → count decision blocks (### headings) + +# Session activity +.ai-team/log/ → count session log files + +# Skills earned +.ai-team/skills/ → count SKILL.md files +``` + +For repos where `.ai-team/` is blocked from the default branch, try: +1. Check the `dev` branch: `gh api repos/{owner/repo}/contents/.ai-team/team.md?ref=dev` +2. Check `squad/*` branches for activity signals +3. Fall back to proxy signals: commit messages with `docs(ai-team):` prefix, branch names starting with `squad/` + +#### Proxy Signals (when .ai-team/ is not visible) + +```bash +# Squad-related commits (Scribe commit pattern) +gh api "repos/{owner/repo}/commits?per_page=100" --jq '[.[] | select(.commit.message | startswith("docs(ai-team)"))] | length' + +# Squad branches (active issue work) +gh api repos/{owner/repo}/branches --jq '[.[] | select(.name | startswith("squad/"))] | length' + +# Squad labels +gh label list --repo {owner/repo} --json name --jq '[.[] | select(.name | startswith("squad"))] | length' +``` + +### Activity Classification + +Classify each repo into tiers based on observable signals: + +| Tier | Signal | Description | +|------|--------|-------------| +| **🟢 Fully Squadified** | team.md + decisions + active commits + issues/PRs | Active daily use with full Squad lifecycle | +| **🟡 Squadified** | team.md + some decisions or sessions | Squad installed and used, moderate activity | +| **🟠 Minimal** | squad.agent.md exists, little other activity | Installed but lightly used or just getting started | +| **🔴 Inactive** | squad.agent.md exists, no recent commits | Installed but dormant | + +### Token & Request Estimation + +Estimate Copilot premium request usage based on observable signals: + +``` +Per session estimate: +- Coordinator overhead: ~2-4K tokens per message +- Single agent spawn: ~15-20K tokens (prompt + response) +- Multi-agent fan-out (3-4 agents): ~50-80K tokens +- Full ceremony: ~80-120K tokens +- Typical session: 2-5 agent spawns + +Per premium request: +- Each `task` tool call = 1 premium request +- Scribe fires on nearly every session = 1 additional request +- Typical session: 3-6 premium requests + +Estimation from proxy signals: +- Each Scribe commit ≈ 1 session ≈ 3-6 premium requests +- Each decision block ≈ 1 agent spawn ≈ 1 premium request +- Each squad/ branch ≈ 1 issue lifecycle ≈ 5-10 premium requests +``` + +### Human Hours Saved Estimation + +Conservative model based on task type: + +| Task Type | Signal | Hours Saved per Instance | +|-----------|--------|--------------------------| +| Issue triage + routing | squad labels | 0.25 - 0.5 hrs | +| Implementation (PR created) | merged PRs | 2 - 8 hrs | +| Code review | review comments on PRs | 0.5 - 1 hr | +| Decision documentation | decision blocks | 0.25 - 0.5 hrs | +| Architecture planning | ceremony logs | 1 - 3 hrs | +| Test creation | test files in PRs | 1 - 3 hrs | + +### Report Structure + +Output the report as a markdown file with this structure: + +```markdown +# Squadified Repos Report — {date} + +## Executive Summary +{2-3 sentences: total repos, owners, growth since last scan} + +## By the Numbers +| Metric | Value | +|--------|-------| +| Total repos | {N} | +| Unique owners | {N} | +| Public / Private | {N} / {N} | +| Total issues | {N} | +| Total PRs | {N} | +| Total commits | {N} | +| Estimated human hours saved | {N} | + +## Adoption Overview +{Table: owner, repo, visibility, tier, issues, PRs, commits, stars} + +## Activity by Owner +{Grouped summary per owner} + +## What Squad Built +{Generalized problem categories, not per-repo descriptions} +{Group repos by domain: distributed systems, developer tooling, creative projects, etc.} + +## Casting Universes +{Table of universes used across all repos} + +## Estimated Token & Request Usage +{Per-repo and aggregate estimates} + +## Growth Since Last Scan +{Comparison to prior scan if available} + +## Methodology +{How data was collected, caveats, limitations} +``` + +### Tone Guidelines + +- Professional but warm — celebrating what the community built +- Not a sales pitch, not dry +- Transparent about estimation uncertainty (use ranges, not point estimates) +- Self-contained: someone unfamiliar with Squad can understand the report +- Reframe specific repos into generalized use cases (don't position demo apps as production evidence) + +### Storing Scan Results + +After each scan, store the repo list and key metrics for comparison: + +``` +.ai-team/skills/squadified-repo-discovery/last-scan.json: +{ + "scan_date": "ISO-8601", + "total_repos": N, + "repos": [ + { "owner": "...", "repo": "...", "visibility": "public|private", "tier": "..." } + ] +} +``` + +This enables growth-over-time tracking in future scans. + +## Examples + +### Quick Scan (list only) + +Use the discovery skill to find repos, then present a simple table: +``` +| # | Owner/Repo | Visibility | Tier | +|---|------------|------------|------| +| 1 | quartznet/quartznet | Public | 🟢 Fully Squadified | +``` + +### Full Report + +Run discovery → collect metrics per repo → classify tiers → estimate tokens → compile report markdown. + +## Anti-Patterns + +- **Don't run all API calls in parallel.** Rate limits will kill you. Batch by owner, space requests. +- **Don't treat `.ai-team/` absence as "not squadified."** Guard workflow blocks it from main. Check the agent file first. +- **Don't position demo/sample repos as production evidence.** Call out their actual use case (e.g., demo script → sample app generation). +- **Don't present point estimates for tokens/hours.** Always use ranges — these are speculations, not measurements. +- **Don't inflate numbers.** If a repo has squad.agent.md but no other activity, classify it honestly as Minimal or Inactive. +- **Don't forget private repos.** They're often the most interesting (production use, not just experiments). diff --git a/docs/scenarios/existing-repo.md b/docs/scenarios/existing-repo.md index 61af7c557..8498361a1 100644 --- a/docs/scenarios/existing-repo.md +++ b/docs/scenarios/existing-repo.md @@ -42,7 +42,7 @@ Squad is ready. Next steps: 1. Open Copilot: copilot - 2. Select Squad from the /agents list + 2. Select Squad from the /agent list (CLI) or /agents (VS Code) 3. Tell it what you're building ``` @@ -56,7 +56,7 @@ If you already have a `.gitattributes` file, Squad appends `merge=union` rules f copilot ``` -Select **Squad** from the `/agents` list. When Squad asks what you're building, describe the project as it exists today: +Select **Squad** from the `/agent` list (CLI) or `/agents` (VS Code). When Squad asks what you're building, describe the project as it exists today: ``` > This is a SaaS invoicing app. React frontend, Node.js/Express API, diff --git a/docs/scenarios/mid-project.md b/docs/scenarios/mid-project.md index 42b647360..436e3bbaa 100644 --- a/docs/scenarios/mid-project.md +++ b/docs/scenarios/mid-project.md @@ -49,7 +49,7 @@ Squad is ready. copilot ``` -Select **Squad** from `/agents`. Describe the project **as it is today**, not as you originally planned it: +Select **Squad** from `/agent` (CLI) or `/agents` (VS Code). Describe the project **as it is today**, not as you originally planned it: ``` > This is an e-commerce platform. We're 4 months into development. diff --git a/docs/scenarios/new-project.md b/docs/scenarios/new-project.md index 4c7a8b048..34405bf52 100644 --- a/docs/scenarios/new-project.md +++ b/docs/scenarios/new-project.md @@ -41,7 +41,7 @@ Squad is ready. Next steps: 1. Open Copilot: copilot - 2. Select Squad from the /agents list + 2. Select Squad from the /agent list (CLI) or /agents (VS Code) 3. Tell it what you're building ``` @@ -53,7 +53,7 @@ Next steps: copilot ``` -Select **Squad** from the `/agents` list. Squad greets you: +Select **Squad** from the `/agent` list (CLI) or `/agents` (VS Code). Squad greets you: ``` Hey Jordan, what are you building? diff --git a/docs/scenarios/private-repos.md b/docs/scenarios/private-repos.md index 5817a4f1f..243560631 100644 --- a/docs/scenarios/private-repos.md +++ b/docs/scenarios/private-repos.md @@ -30,7 +30,7 @@ When you run: copilot ``` -And select **Squad** from the `/agents` list, Squad runs **on your machine** using Copilot's infrastructure. +And select **Squad** from the `/agent` list (CLI) or `/agents` (VS Code), Squad runs **on your machine** using Copilot's infrastructure. **What this means:** - Your code stays local diff --git a/docs/scenarios/troubleshooting.md b/docs/scenarios/troubleshooting.md index 906fc4f98..89763683f 100644 --- a/docs/scenarios/troubleshooting.md +++ b/docs/scenarios/troubleshooting.md @@ -79,7 +79,7 @@ If below v22, upgrade Node.js: ## Squad agent not appearing in Copilot -**Problem:** After install, `squad` doesn't show up in the `/agents` list in GitHub Copilot. +**Problem:** After install, `squad` doesn't show up in the `/agent` (CLI) or `/agents` (VS Code) list in GitHub Copilot. **Cause:** The `.github/agents/squad.agent.md` file may not have been created, or Copilot hasn't refreshed its agent list. diff --git a/docs/tour-first-session.md b/docs/tour-first-session.md index 26e5e7374..d8d9f76f2 100644 --- a/docs/tour-first-session.md +++ b/docs/tour-first-session.md @@ -34,7 +34,7 @@ Start the Copilot CLI: copilot ``` -Select **Squad** from the `/agents` list. Squad greets you by name (pulled from `git config user.name`): +Select **Squad** from the `/agent` list (CLI) or `/agents` (VS Code). Squad greets you by name (pulled from `git config user.name`): ``` Hey Brady, what are you building? diff --git a/templates/workflows/squad-main-guard.yml b/templates/workflows/squad-main-guard.yml index cc927f78a..ef3d4b840 100644 --- a/templates/workflows/squad-main-guard.yml +++ b/templates/workflows/squad-main-guard.yml @@ -19,20 +19,51 @@ jobs: uses: actions/github-script@v7 with: script: | - // Fetch all files changed in this PR (paginated) - const files = []; - let page = 1; - while (true) { - const resp = await github.rest.pulls.listFiles({ - owner: context.repo.owner, - repo: context.repo.repo, - pull_number: context.payload.pull_request.number, - per_page: 100, - page - }); - files.push(...resp.data); - if (resp.data.length < 100) break; - page++; + // Fetch all files changed - handles both PR and push events + let files = []; + + if (context.eventName === 'pull_request') { + // PR event: use pulls.listFiles API + let page = 1; + while (true) { + const resp = await github.rest.pulls.listFiles({ + owner: context.repo.owner, + repo: context.repo.repo, + pull_number: context.payload.pull_request.number, + per_page: 100, + page + }); + files.push(...resp.data); + if (resp.data.length < 100) break; + page++; + } + } else if (context.eventName === 'push') { + // Push event: compare against base branch + const base = context.payload.before; + const head = context.payload.after; + + // If this is not a force push and base exists, compare commits + if (base && base !== '0000000000000000000000000000000000000000') { + const comparison = await github.rest.repos.compareCommits({ + owner: context.repo.owner, + repo: context.repo.repo, + base, + head + }); + files = comparison.data.files || []; + } else { + // Force push or initial commit: list all files in the current tree + core.info('Force push detected or initial commit, checking tree state'); + const { data: tree } = await github.rest.git.getTree({ + owner: context.repo.owner, + repo: context.repo.repo, + tree_sha: head, + recursive: 'true' + }); + files = tree.tree + .filter(item => item.type === 'blob') + .map(item => ({ filename: item.path, status: 'added' })); + } } // Check each file against forbidden path rules @@ -43,6 +74,8 @@ jobs: .filter(f => { // .ai-team/** — ALL team state files, zero exceptions if (f === '.ai-team' || f.startsWith('.ai-team/')) return true; + // .ai-team-templates/** — Squad's own templates, stay on dev + if (f === '.ai-team-templates' || f.startsWith('.ai-team-templates/')) return true; // team-docs/** — ALL internal team docs, zero exceptions if (f.startsWith('team-docs/')) return true; return false; @@ -59,6 +92,7 @@ jobs: '', 'The following files must NOT be merged into `main`.', '`.ai-team/` is runtime team state — it belongs on dev branches only.', + '`.ai-team-templates/` is Squad\'s internal planning — it belongs on dev branches only.', '`team-docs/` is internal team content — it belongs on dev branches only.', '', '### Forbidden files found:', From afccde847308cd87c1421bfbdafabdbb0dbe14e8 Mon Sep 17 00:00:00 2001 From: bradygaster Date: Thu, 19 Feb 2026 20:19:02 -0800 Subject: [PATCH 2/2] docs(mcmanus): record CLI vs VS Code command parity fix in history and decisions --- .ai-team/agents/mcmanus/history.md | 2 ++ .../mcmanus-cli-vs-vscode-command-parity.md | 19 +++++++++++++++++++ 2 files changed, 21 insertions(+) create mode 100644 .ai-team/decisions/inbox/mcmanus-cli-vs-vscode-command-parity.md diff --git a/.ai-team/agents/mcmanus/history.md b/.ai-team/agents/mcmanus/history.md index 837dfbe57..44fca520e 100644 --- a/.ai-team/agents/mcmanus/history.md +++ b/.ai-team/agents/mcmanus/history.md @@ -16,6 +16,7 @@ _Summarized from initial assessment, messaging overhaul, demo script, and README - **Casting is a competitive moat** — thematic persistent names make agents memorable and referenceable, unlike generic labels. Elevated from Easter egg to headline feature. - **Demo script uses beat format** (ON SCREEN / VOICEOVER / WHAT TO DO) — README order is non-negotiable for demos. Payoff at end, not beginning. - **README rewrite (Proposal 006)**: Hero → Quick Start → Why Squad? → Parallel Work → How It Works → Cast System → What Gets Created → Growing the Team → Reviewer Protocol → Install → Troubleshooting → Status. +- **CLI vs VS Code command parity (2026-02-19)** — Copilot CLI uses `/agent` (singular), VS Code uses `/agents` (plural). Documentation must reference both forms explicitly, not assume one platform. (#93) ### Session Summaries @@ -38,6 +39,7 @@ _Summarized from initial assessment, messaging overhaul, demo script, and README - **Super Bowl Weekend post — edit pass and honest assessment (2026-02-09)** - **v0.2.0 release blog post (2026-02-09)** - **Executive summary research section (2026-02-14)** — Added "Research Opportunities" section to `docs/squad-executive-summary.md` before Caveats. Four hypotheses (H1–H4) addressing: task completion speed, accessibility, retention via lock-in, complexity scaling + ROI threshold. Synthesized from Keaton's research framework. +- **CLI vs VS Code command documentation fix (2026-02-19)** — Fixed #93: Updated 6 doc files to reference both `/agent` (CLI) and `/agents` (VS Code). Users on either platform now get the correct command without confusion. PR #100. ## Learnings diff --git a/.ai-team/decisions/inbox/mcmanus-cli-vs-vscode-command-parity.md b/.ai-team/decisions/inbox/mcmanus-cli-vs-vscode-command-parity.md new file mode 100644 index 000000000..8043be96c --- /dev/null +++ b/.ai-team/decisions/inbox/mcmanus-cli-vs-vscode-command-parity.md @@ -0,0 +1,19 @@ +### 2026-02-19: CLI vs VS Code Command Parity + +**By:** McManus + +**What:** Documentation now explicitly mentions both `/agent` (Copilot CLI, singular) and `/agents` (VS Code, plural) wherever users are directed to launch Squad. Updated 6 documentation files across scenarios and guides. + +**Why:** Issue #93 reported confusion — users on the CLI see `/agent` but all docs say `/agents`. This creates friction at the critical first moment ("I can't find the command"). The fix is simple: be platform-aware. When instructing users to launch Squad, say "Type `/agent` (CLI) or `/agents` (VS Code)." This removes ambiguity and respects the fact that we ship on two platforms with different affordances. + +**Files changed:** +- `docs/tour-first-session.md` — first-session walkthrough (critical UX) +- `docs/scenarios/existing-repo.md` — adding Squad mid-project +- `docs/scenarios/mid-project.md` — onboarding late-stage projects +- `docs/scenarios/new-project.md` — new project setup (also critical) +- `docs/scenarios/private-repos.md` — private repo guidance +- `docs/scenarios/troubleshooting.md` — problem statement for agent discovery + +**Platform context:** README.md and index.js already had correct dual-platform language (looks like this was partially addressed in HEAD). The fix ensures consistency across all scenarios and guides. + +**Decision:** Explicit platform notation is clearer than implicit. We say "CLI" and "VS Code" in parentheses to make it unmissable. No need for fancy UI—just honest writing.