docs: scenario and feature guides from blog analysis by diberry · Pull Request #331 · bradygaster/squad

diberry · 2026-03-10T17:52:37Z

New documentation pages

Derived from analysis of Tamir Dresher's public blog post Organized by AI. Content categorized into universal Squad patterns (this PR) vs community-specific patterns (separate Squad IRL PR).

New pages

Page	Category	Content
\scenarios/ralph-operations.md\	Scenario	Outer loop deployment, mutex patterns, logging, alerting, heartbeat
\scenarios/proactive-communication.md\	Scenario	Two-way Teams webhooks and email/Teams scanning
\eatures/issue-templates.md\	Feature	Squad-aware GitHub Issue templates, routing labels, mobile workflow
\eatures/reviewer-protocol.md\	Feature	Trust levels section added (full review / selective / self-managing)

Compliance

Microsoft Style Guide (sentence-case, active voice, no ampersands)
DOCS-TEST SYNC (\ est/docs-build.test.ts\ updated)
Privacy directive: aggregate references only, no individual repo names
PAO reviewed all pages before PR

Notes

All content describes how Squad features work + best practices — not one person's specific setup
Blog post is public — referenced directly with URL
Trust levels section extends existing reviewer-protocol.md (non-breaking addition)

Fixed test assertion arrays to match actual files on disk: - EXPECTED_SCENARIOS: expanded from 7 to 25 entries - EXPECTED_FEATURES: added new array with 32 entries This resolves the sync issue identified in PR bradygaster#331 review where test assertions were out of sync with docs/src/content/docs/ structure. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

diberry · 2026-03-10T23:09:07Z

Squad Review — PR #331

🏗️ Flight (Lead) — ✅ APPROVE

Scope is tight, boundary review correct
Deleted files (ralph-operations.md, proactive-communication.md) properly removed — infrastructure/IRL content, not Squad features
Trust Levels addition is architecturally sound — documents user choice within existing review system
Merge artifact cleanup (duplicate "How It Works" heading) confirmed safe
issue-templates.md reframe is correct distinction between platform features and Squad features

🧪 FIDO (Quality Owner) — ✅ APPROVE (after fix)

Initially blocked: test assertions were stale (EXPECTED_SCENARIOS had 7 entries, 25 files on disk; EXPECTED_FEATURES missing, 32 files on disk)
Fixed in commit d1bde8a: synced both arrays with disk state, all tests passing (6/6 structure validations)
Markdown structure, style compliance, links, and CI all verified

📝 PAO (DevRel) — bonus commit

Added cross-org authentication scenario docs (separate from Docs: Add 'What's in .squad/?' explainer to first-session.md #289 scope, but on same branch per owner request)

Verdict: Ready for merge. @bradygaster — the squad reviewed this and it's good to go. FIDO's test sync fix is included in the latest push.

…#353) Closes bradygaster#331 ThinkingIndicator component: rotating phrases, elapsed time, activity hints, color cycling. 16 new tests. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

bradygaster · 2026-03-12T03:59:06Z

@diberry - few conflicts popped up in this one. love the content - could you resolve these? then i'll merge, thanks!

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Reverts .squad/agents/pao/history.md to upstream/main so it no longer appears in the PR diff. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Session: 2026-03-10-adoption-tracking Requested by: Scribe Changes: - Merged 4 decisions from inbox to decisions.md: adoption tracking 3-tier architecture, implementation, append-only governance, ampersand style guide - Updated Flight and EECOM history.md with team cross-agent updates - Created orchestration logs for PAO (PR bradygaster#303 rebase), Flight (adoption proposal), EECOM (Tier 1 implementation) - Created session log documenting adoption tracking architecture finalization - Deleted decision inbox files after merge

New docs pages derived from public blog post analysis: - scenarios/ralph-operations.md: outer loop deployment, mutex, logging, alerting - scenarios/proactive-communication.md: two-way Teams webhooks and scanning - features/issue-templates.md: squad-aware issue templates, routing labels - features/reviewer-protocol.md: trust levels section (full/selective/self-managing) - test/docs-build.test.ts: assertions updated for new pages All content follows Microsoft Style Guide. No individual repo names — aggregate references only per owner privacy directive. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Remove ralph-operations.md and proactive-communication.md — both document infrastructure around Squad (webhooks, WorkIQ, deployment patterns) rather than Squad itself. Content moves to Squad IRL repo. Reframe issue-templates.md to clarify GitHub Issue Templates are a platform feature configured for Squad routing, not a Squad feature. Litmus test applied: if Squad doesn't ship the code/config, it belongs in IRL. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Created comprehensive documentation for working across GitHub personal accounts and GitHub Enterprise Managed Users (EMU): - New scenario page: scenarios/cross-org-auth.md - Three solution approaches: gh auth switch, Copilot instructions, Squad skill pattern - Git credential helper configuration - Common error messages and verification steps - Updated troubleshooting.md with cross-org auth section - Updated enterprise-platforms.md authentication section with cross-ref - Added navigation entry for Cross-Org Auth scenario - Updated test assertions in docs-build.test.ts Follows Microsoft Style Guide (sentence-case headings, active voice). Includes practical examples and cross-references to related pages. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Fixed test assertion arrays to match actual files on disk: - EXPECTED_SCENARIOS: expanded from 7 to 25 entries - EXPECTED_FEATURES: added new array with 32 entries This resolves the sync issue identified in PR bradygaster#331 review where test assertions were out of sync with docs/src/content/docs/ structure. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…ntent triage, remote access proposal Session: 2026-03-11T01-27-57-post-work-orchestration Agents: FIDO (Quality Owner), Flight (Lead) Changes: - Orchestration logs for FIDO (test assertion sync fix, commit 6599db6) and Flight (content triage skill) - Merged 6 decisions from inbox to decisions.md - Consolidated boundary heuristic: "Squad Ships It" (docs vs IRL) across content-triage skill and PR bradygaster#331 review - Added content-triage workflow for external content integration - Added phased rollout proposal for remote Squad access (Discussions → Copilot → Chat) - Added PR trust levels spectrum (full/selective/self-managing) - Cross-agent updates: FIDO, Flight, PAO history.md sync; boundary heuristic shared Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Fixed test assertion arrays to match actual files on disk: - EXPECTED_SCENARIOS: expanded from 7 to 25 entries - EXPECTED_FEATURES: added new array with 32 entries This resolves the sync issue identified in PR #331 review where test assertions were out of sync with docs/src/content/docs/ structure. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…ntent triage, remote access proposal Session: 2026-03-11T01-27-57-post-work-orchestration Agents: FIDO (Quality Owner), Flight (Lead) Changes: - Orchestration logs for FIDO (test assertion sync fix, commit 6599db6) and Flight (content triage skill) - Merged 6 decisions from inbox to decisions.md - Consolidated boundary heuristic: "Squad Ships It" (docs vs IRL) across content-triage skill and PR #331 review - Added content-triage workflow for external content integration - Added phased rollout proposal for remote Squad access (Discussions → Copilot → Chat) - Added PR trust levels spectrum (full/selective/self-managing) - Cross-agent updates: FIDO, Flight, PAO history.md sync; boundary heuristic shared Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…xplainer

Fixed test assertion arrays to match actual files on disk: - EXPECTED_SCENARIOS: expanded from 7 to 25 entries - EXPECTED_FEATURES: added new array with 32 entries This resolves the sync issue identified in PR bradygaster#331 review where test assertions were out of sync with docs/src/content/docs/ structure. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…ntent triage, remote access proposal Session: 2026-03-11T01-27-57-post-work-orchestration Agents: FIDO (Quality Owner), Flight (Lead) Changes: - Orchestration logs for FIDO (test assertion sync fix, commit 6599db6) and Flight (content triage skill) - Merged 6 decisions from inbox to decisions.md - Consolidated boundary heuristic: "Squad Ships It" (docs vs IRL) across content-triage skill and PR bradygaster#331 review - Added content-triage workflow for external content integration - Added phased rollout proposal for remote Squad access (Discussions → Copilot → Chat) - Added PR trust levels spectrum (full/selective/self-managing) - Cross-agent updates: FIDO, Flight, PAO history.md sync; boundary heuristic shared Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Fixed test assertion arrays to match actual files on disk: - EXPECTED_SCENARIOS: expanded from 7 to 25 entries - EXPECTED_FEATURES: added new array with 32 entries This resolves the sync issue identified in PR bradygaster#331 review where test assertions were out of sync with docs/src/content/docs/ structure. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…ntent triage, remote access proposal Session: 2026-03-11T01-27-57-post-work-orchestration Agents: FIDO (Quality Owner), Flight (Lead) Changes: - Orchestration logs for FIDO (test assertion sync fix, commit 6599db6) and Flight (content triage skill) - Merged 6 decisions from inbox to decisions.md - Consolidated boundary heuristic: "Squad Ships It" (docs vs IRL) across content-triage skill and PR bradygaster#331 review - Added content-triage workflow for external content integration - Added phased rollout proposal for remote Squad access (Discussions → Copilot → Chat) - Added PR trust levels spectrum (full/selective/self-managing) - Cross-agent updates: FIDO, Flight, PAO history.md sync; boundary heuristic shared Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* docs: comprehensive new-user experience improvements Add 4 new docs pages and update 3 existing: - New: five-minute-start.md (5-minute quickstart) - New: architecture.md (how Squad works) - New: choosing-your-path.md (CLI vs SDK vs Copilot) - New: glossary.md (key terms reference) - Update: troubleshooting.md (common errors table) - Update: first-session.md (jargon definitions) - Update: navigation.ts (sidebar entries) Closes #301 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs: update PAO history with first-session guide structure Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * chore: remove pao/history.md session artifact from PR diff Reverts .squad/agents/pao/history.md to upstream/main so it no longer appears in the PR diff. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs(ai-team): Merge adoption tracking decisions and governance rules Session: 2026-03-10-adoption-tracking Requested by: Scribe Changes: - Merged 4 decisions from inbox to decisions.md: adoption tracking 3-tier architecture, implementation, append-only governance, ampersand style guide - Updated Flight and EECOM history.md with team cross-agent updates - Created orchestration logs for PAO (PR #303 rebase), Flight (adoption proposal), EECOM (Tier 1 implementation) - Created session log documenting adoption tracking architecture finalization - Deleted decision inbox files after merge * docs: add scenario and feature guides from Tamir blog analysis New docs pages derived from public blog post analysis: - scenarios/ralph-operations.md: outer loop deployment, mutex, logging, alerting - scenarios/proactive-communication.md: two-way Teams webhooks and scanning - features/issue-templates.md: squad-aware issue templates, routing labels - features/reviewer-protocol.md: trust levels section (full/selective/self-managing) - test/docs-build.test.ts: assertions updated for new pages All content follows Microsoft Style Guide. No individual repo names — aggregate references only per owner privacy directive. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs: scope Squad docs to framework-only content Remove ralph-operations.md and proactive-communication.md — both document infrastructure around Squad (webhooks, WorkIQ, deployment patterns) rather than Squad itself. Content moves to Squad IRL repo. Reframe issue-templates.md to clarify GitHub Issue Templates are a platform feature configured for Squad routing, not a Squad feature. Litmus test applied: if Squad doesn't ship the code/config, it belongs in IRL. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs: add cross-org authentication scenario Created comprehensive documentation for working across GitHub personal accounts and GitHub Enterprise Managed Users (EMU): - New scenario page: scenarios/cross-org-auth.md - Three solution approaches: gh auth switch, Copilot instructions, Squad skill pattern - Git credential helper configuration - Common error messages and verification steps - Updated troubleshooting.md with cross-org auth section - Updated enterprise-platforms.md authentication section with cross-ref - Added navigation entry for Cross-Org Auth scenario - Updated test assertions in docs-build.test.ts Follows Microsoft Style Guide (sentence-case headings, active voice). Includes practical examples and cross-references to related pages. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs(ai-team): Merge post-work orchestration — boundary heuristic, content triage, remote access proposal Session: 2026-03-11T01-27-57-post-work-orchestration Agents: FIDO (Quality Owner), Flight (Lead) Changes: - Orchestration logs for FIDO (test assertion sync fix, commit 6599db6) and Flight (content triage skill) - Merged 6 decisions from inbox to decisions.md - Consolidated boundary heuristic: "Squad Ships It" (docs vs IRL) across content-triage skill and PR #331 review - Added content-triage workflow for external content integration - Added phased rollout proposal for remote Squad access (Discussions → Copilot → Chat) - Added PR trust levels spectrum (full/selective/self-managing) - Cross-agent updates: FIDO, Flight, PAO history.md sync; boundary heuristic shared Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix: vitest resolve alias for workspace package mocking Resolve workspace packages to source in vitest so vi.mock intercepts correctly. Without this, npm ci installs a duplicate squad-sdk under squad-cli/node_modules which bypasses the mock. * feat: add non-blocking version check on CLI startup (Phase 1) Adds a background update check that runs when the interactive shell starts. On startup, Squad checks the npm registry for a newer version and displays a passive notification banner if one is available. Key design decisions: - Fire-and-forget: never blocks or delays shell startup - 24-hour cache: avoids repeated network calls - 3-second fetch timeout via AbortController - Opt-out via SQUAD_NO_UPDATE_CHECK=1 env var - Triple-wrapped error handling: silent on any failure New file: packages/squad-cli/src/cli/self-update.ts Modified: packages/squad-cli/src/cli-entry.ts (wired into no-args shell path) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs(pao): add SCANNABILITY REVIEW hard rule to PAO charter Adds a mandatory scannability framework for all content reviews: - Paragraphs: narrative flow, conceptual explanations (3-4 sentences max) - Bullet lists: features, options, scannable items (parallel structure) - Tables: comparisons, structured reference data, attribute grids - Quotes/indents: warnings, callouts, cited material - Decision test: hunt-for-one-item = convert to bullets/table PAO applies this on every PR with documentation impact. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(docs): replace ~/.squad/ with platform-specific path references Closes #343 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * deleted images * docs(ai-team): v0.8.21 release session logged; npm publish automation merged Session: 2026-03-07T20-03-20Z-v0821-release Requested by: Spawn manifest (release coordination) Changes: - Logged orchestration outputs for Kobayashi, Hockney, McManus, Rabin - Logged session summary: v0.8.21 release complete (3,768 tests passing, docs deployed) - Merged decisions from inbox: npm publish CI directive + Kobayashi's GitHub Actions automation - Propagated cross-agent updates to affected agents' history.md (Kobayashi, Hockney, McManus, Rabin) Directives: - GitHub Actions (publish.yml) is now authoritative for npm publishing; local npm publish deprecated - Brady must add NPM_TOKEN secret to GitHub repo settings to enable CI-based publishing * docs(kobayashi): v0.8.21 release gate merge & publish trigger Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs: add agent anatomy, cross-agent context, and hiring checklist to your-team concept page Enriches the existing your-team.md with: - Anatomy of an agent (AI vs human vs @copilot) - Cross-agent context propagation - Hiring an agent developer checklist Closes #328 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs: add human-AI collaboration section to github-workflow concept page Adds a 'Working with your team' section explaining how humans and AI agents collaborate through the SDLC: triage, design review, implementation, PR review, and merge. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs: address team review feedback on PR #439 - Fix broken links to memory docs (memory-and-knowledge.md → ../features/memory.md) - Rename heading to 'Agent anatomy' (noun-first, sentence case) - De-duplicate Human/AI table — reference existing section, keep @copilot details - Tighten tone — flatten parenthetical asides - Trim 'Working with your team' — framework + links, not re-teaching Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs: reframe lifecycle table as example, not prescriptive Clarify that the human-AI lifecycle table is illustrative. Teams determine their own processes using ceremonies and directives. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix: remove duplicate EXPECTED_CONCEPTS declaration Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs: add 'Planning your team' checklist before agent anatomy Pre-init planning checklist with ~10 bullet points covering decisions new squad owners should make before running squad init. Cross-references existing sections rather than duplicating content. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs: replace personal/repo-level bullet with squad topology guidance Replace the 'Personal or repo-level squad?' bullet in the Planning your team checklist with a new bullet about squad topology — how many squads and where they live relative to repos. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: James Sturtevant <jsturtevant@gmail.com> Co-authored-by: bradygaster <bradyg@microsoft.com>

diberry and others added 8 commits March 12, 2026 08:36

docs: update PAO history with first-session guide structure

4c4f06d

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

chore: remove pao/history.md session artifact from PR diff

8d0e1b3

Reverts .squad/agents/pao/history.md to upstream/main so it no longer appears in the PR diff. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

diberry force-pushed the squad/289-squad-dir-explainer branch from d1bde8a to 02fefa7 Compare March 12, 2026 21:12

Merge remote-tracking branch 'origin/main' into squad/289-squad-dir-e…

6d99e26

…xplainer

bradygaster merged commit d092ef0 into bradygaster:main Mar 13, 2026
1 check failed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: scenario and feature guides from blog analysis#331

docs: scenario and feature guides from blog analysis#331
bradygaster merged 9 commits intobradygaster:mainfrom
diberry:squad/289-squad-dir-explainer

diberry commented Mar 10, 2026

Uh oh!

diberry commented Mar 10, 2026

Uh oh!

bradygaster commented Mar 12, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

diberry commented Mar 10, 2026

New documentation pages

New pages

Compliance

Notes

Uh oh!

diberry commented Mar 10, 2026

Squad Review — PR #331

🏗️ Flight (Lead) — ✅ APPROVE

🧪 FIDO (Quality Owner) — ✅ APPROVE (after fix)

📝 PAO (DevRel) — bonus commit

Uh oh!

bradygaster commented Mar 12, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants