Skip to content

docs: session model, known limitations, repo anatomy, and FAQ#384

Closed
diberry wants to merge 20 commits intobradygaster:mainfrom
diberry:squad/doc-intelligence-signals
Closed

docs: session model, known limitations, repo anatomy, and FAQ#384
diberry wants to merge 20 commits intobradygaster:mainfrom
diberry:squad/doc-intelligence-signals

Conversation

@diberry
Copy link
Copy Markdown
Collaborator

@diberry diberry commented Mar 14, 2026

Summary

Four new documentation pages sourced from doc-intelligence signals (2026-03-13 Teams and GitHub scan). These address the highest-confidence documentation gaps identified across community signals.

New Pages

Page Section Signal
Session Model Concepts Teams users confused about session continuity and tool switching
Known Limitations Get Started Crashes-are-normal during preview needs explicit docs
Repo Anatomy Concepts .squad/\ directory structure is tribal knowledge
FAQ Guide 6+ repeated questions from Teams welcome channel

Navigation

All 4 pages added to
avigation.ts\ in their respective sections.

Also Created

Docs Build

\
✅ 132 pages built successfully
✅ 129 pages indexed (7,256 words)
\\

Generated by Squad doc-intelligence skill → activity-aggregator workflow

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

@craigb
Copy link
Copy Markdown

craigb commented Mar 14, 2026

🔴 CI Failure — Build Error

The test job failed with TypeScript compilation errors in squad-cli:

src/cli/commands/roles.ts(1,10): error TS2305: Module '"@bradygaster/squad-sdk"' has no exported member 'listRoles'.
src/cli/commands/roles.ts(1,21): error TS2305: Module '"@bradygaster/squad-sdk"' has no exported member 'searchRoles'.
src/cli/commands/roles.ts(1,34): error TS2305: Module '"@bradygaster/squad-sdk"' has no exported member 'getCategories'.
src/cli/core/cast.ts(9,10): error TS2305: Module '"@bradygaster/squad-sdk"' has no exported member 'getRoleById'.
src/cli/core/cast.ts(9,23): error TS2305: Module '"@bradygaster/squad-sdk"' has no exported member 'generateCharterFromRole'.
src/cli/shell/coordinator.ts(3,10): error TS2305: Module '"@bradygaster/squad-sdk"' has no exported member 'listRoles'.
src/cli/shell/coordinator.ts(3,21): error TS2305: Module '"@bradygaster/squad-sdk"' has no exported member 'searchRoles'.

Root cause: This branch is based on an older main that doesn't include the recently-added role API exports (listRoles, searchRoles, getCategories, getRoleById, generateCharterFromRole).

Fix: Rebase or merge latest main into this branch to pick up the SDK changes.

🤖 Flagged by Ralph (Work Monitor)

jongio and others added 20 commits March 14, 2026 08:25
@jongio
fix(cli): eliminate terminal scroll flicker and rerender storm
e971831 
Root cause: four independent issues combined into a scroll storm:
1. Ink fullscreen clearTerminal path firing every render cycle
2. ~16 unsynchronized animation re-renders/sec from 3 timers
3. Unstable Static component keys causing Ink remounts
4. Layout shift from height toggling between processing states

Changes:
- Patch Ink fullscreen path (disable clearTerminal, incrementalRendering, trailing newline)
- Widen spinner/animation intervals (80->150ms spinner, 500->800ms pulse)
- Share terminal dimension hook with 150ms debounce
- Pin root height to prevent logUpdate cursor drift
- Keep conversation in live viewport (not Static scrollback)
- Stable UUID-based Static keys, responsive maxVisible
- Fix bump-build.mjs to produce valid semver prerelease format
- Fix marketplace test for Windows path compat

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@diberry
docs: update PAO history with first-session guide structure
3b27bee 
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
chore: remove pao/history.md session artifact from PR diff
bf385b5 
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
83cf34a 
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
docs: add scenario and feature guides from Tamir blog analysis
d3f8fee 
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
cce2551 
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
a6ed97f 
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>
test: sync EXPECTED_SCENARIOS and EXPECTED_FEATURES with disk
ef14aea 
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>
docs(ai-team): Merge post-work orchestration — boundary heuristic, co…
8df4e5b 
…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>
@diberry
feat: add task context classification to coordinator acknowledgment
75c25c3 
The coordinator's Acknowledge Immediately section now requires a task
context signal (Continuing/New task/Related pivot) before naming agents.
This helps users understand whether the system recognizes their message
as part of ongoing work or a fresh request.

Closes bradygaster#359

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@jsturtevant
fix: resolve npm audit vulnerabilities and Aspire Docker test cleanup
ca19301 
- Bump minimatch 9.0.6→9.0.9 (ReDoS: GHSA-7r86-cg39-jmmj, GHSA-23c5-xmqv-rm74)
- Bump rollup 4.58.0→4.59.0 (path traversal: GHSA-mw96-cpmx-2vgc)
- Add --name to squad aspire Docker command to prevent unnamed orphan containers
- Align test and CLI on shared container name (squad-aspire-dashboard)
- Add SIGINT/SIGTERM/exit handlers to aspire integration test for cleanup

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@jsturtevant
fix: vitest resolve alias for workspace package mocking
799170c 
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.
@diberry
docs: recommend --yolo in README Quick Start
6328bb9 
Add prominent recommendation to use copilot --yolo in step 4 of the
Quick Start guide. Squad sessions involve many tool calls, so --yolo
provides a smoother experience by skipping individual approval prompts.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@spboyer
feat: add 20 built-in base roles for faster team casting (bradygaster…
51898d0 
…#368)

Add a curated catalog of 20 base roles that serve as starting points
during team casting, replacing expensive LLM improvisation with
deterministic role selection + lightweight project refinement.

Software Development (12): lead, frontend, backend, fullstack, reviewer,
tester, devops, security, data, docs, ai, designer

Business & Operations (8): marketing-strategist, sales-strategist,
product-manager, project-manager, support-specialist, game-developer,
media-buyer, compliance-legal

New features:
- useRole() SDK builder for squad.config.ts
- squad roles CLI command (--category, --search)
- listRoles(), searchRoles(), getRoleById() API
- generateCharterFromRole() for cast.ts integration
- Updated cast.ts to use catalog before generic fallback
- 148 tests, documentation page

Role content adapted from agency-agents by AgentLand Contributors (MIT)
https://github.com/msitarzewski/agency-agents

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@spboyer
feat: integrate base role catalog into Init Mode (bradygaster#368)
eb2597a 
Update coordinator and Init Mode prompts to reference the 20 built-in
base roles during team casting. The LLM now prefers catalog roles
(which have deep charter content) over improvising custom roles.

- coordinator.ts: buildInitModePrompt() includes base role catalog
- squad.agent.md templates: Init Mode Phase 1 step 3 matches to catalog
- Both SDK and CLI template files updated in sync

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
feat: add non-blocking version check on CLI startup (Phase 1)
bae1204 
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>
@diberry
feat: conversation-aware thinking phrases in ThinkingIndicator
b54dcff 
When prior conversation history exists, the ThinkingIndicator cycles
through context-aware phrases (e.g. 'Reviewing conversation context',
'Connecting to previous work') instead of generic ones. This gives users
immediate feedback that the system recognizes ongoing conversation.

- Add CONVERSATION_PHRASES array to ThinkingIndicator
- Add hasConversation prop threaded through App -> MessageStream -> ThinkingIndicator
- Derive hasConversation from messages array in App.tsx (true when agent responses exist)

Closes bradygaster#360

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
docs(pao): add SCANNABILITY REVIEW hard rule to PAO charter
8a7e043 
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>
@jsturtevant
fix(docs): replace ~/.squad/ with platform-specific path references
94307e0 
Closes bradygaster#343

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
docs: add session model, known limitations, repo anatomy, and FAQ pages
02f3437 
New pages sourced from doc-intelligence signals (2026-03-13 scan):
- concepts/session-model: session boundaries, persistence, resuming work
- concepts/repo-anatomy: .squad/ directory structure and file roles
- get-started/known-limitations: stability, tool approval, platform notes
- guide/faq: community Q&A from Teams channel signals

Also creates GitHub issues for signals needing discussion:
- bradygaster#382: Why Squad value proposition page
- bradygaster#383: Onboarding UX consolidation

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@diberry diberry force-pushed the squad/doc-intelligence-signals branch from 2fe281a to 02f3437 Compare March 14, 2026 15:26
@diberry diberry mentioned this pull request Mar 14, 2026
Closed
@diberry
Copy link
Copy Markdown
Collaborator Author

diberry commented Mar 14, 2026

Superseded by #388 — clean PR with only the 5 docs files.

@diberry diberry closed this Mar 14, 2026
tamirdresher pushed a commit to tamirdresher/squad that referenced this pull request Mar 16, 2026
@bradygaster
test: human journey E2E tests - 7 real user scenarios, 39 assertions (b…
ae4a212 
…radygaster#408)

* chore(squad): Phase 2 launch — thinking feedback, P0 bugs, dual telemetry

Phase 1 complete: 5 issues closed (bradygaster#325, bradygaster#326, bradygaster#327, bradygaster#328, bradygaster#329), 5 PRs merged.
Phase 2 launched with Cheritto (thinking feedback), Hockney (P0 bugs), Saul (dual telemetry).
Decision inbox merged and archived.

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

* chore(squad): Phase 2 Wave 1 merged, Wave 2 launched

Session: 2026-02-23T2145-phase2-wave2
Phase 2 Wave 1 complete (PRs bradygaster#351, bradygaster#352, bradygaster#353 merged).
Wave 2 launched: Cheritto on ghost response detection (bradygaster#332), Hockney on error hardening (bradygaster#334).

Changes:
- Session log created: 2026-02-23T2145-phase2-wave2.md
- Merged 3 inbox decisions (Cheritto, Hockney, Saul)
- Deleted inbox files post-merge

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

* chore(squad): Epic bradygaster#323 complete — all phases shipped 🎉

All 3 phases delivered:
- Phase 1 (Testing Wave): 6 issues closed
- Phase 2 (Improvement): 6 issues closed
- Phase 3 (Breathtaking): 7 issues closed
- 17 PRs merged, 19 issues closed total

Session log: 2026-02-23T2320-epic-complete.md
Decisions merged from inbox: P2 UX Polish, first-run wow moment

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

* hostile QA: end-to-end quality assessment — 10 findings, 4 HIGH severity

Candid assessment requested by Brady. Traced every code path in cli-entry.ts,
shell/index.ts, shell/commands.ts, App.tsx, coordinator.ts, spawn.ts, and the
SDK adapter client.

Key findings:
- Dead sessions never evicted from agentSessions Map after connection drop
- No React ErrorBoundary — any render throw kills the shell
- Nasty-inputs corpus (95 strings) is never imported by any test
- No SIGTERM handler in interactive shell
- MemoryManager exported but never instantiated (dead code)
- Single streaming content slot clobbers multi-agent output
- User input silently dropped during processing (no type-ahead buffer)

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

* chore(squad): quality review findings — 7 issues filed

Quality audit complete: 5 agents assessed CLI across testing, coverage, stability, accessibility, UX.
Results: 4 P0 blockers (bradygaster#365–bradygaster#368), 3 P1 items (bradygaster#369–bradygaster#371).
Blocking: Waingro dead sessions, ErrorBoundary, dropped input; Marquez help text consistency.

Changes:
- Logged session summary to .squad/log/2026-02-24T0205-quality-review-complete.md
- Updated .squad/identity/now.md with quality review findings and new issue numbers

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

* chore(squad): merge decision — Marquez UX audit findings

Quality assessment merged from inbox (Grade B): 11 improvements (3 P0, 4 P1, 4 P2). help text, stub commands, vocabulary, separators, roster.

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

* chore(squad): test sprint launch

Session: 2026-02-24T0210-test-sprint
Changes:
- Logged test sprint: 5 agents, 7+ issues
- Branches: P0 fixes, stale tests, E2E, hostile/SDK, A11y

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

* test: add human journey E2E tests for 7 real user scenarios

Test the actual human experience, not internal modules. Each describe
block maps to a filed GitHub issue and simulates what a real person
does when they encounter Squad for the first time and beyond.

Journeys tested (39 assertions):
1. I just installed this — squad init creates .squad/, shows ceremony,
   gives clear next step, writes first-run marker, exits cleanly
2. My first conversation — welcome banner shows agent roster with
   names/roles/emojis, project description, focus area, first-run
   ceremony is one-time only
3. I'm waiting and getting anxious — ThinkingIndicator appears
   immediately, shows elapsed time, activity hints override default,
   NO_COLOR mode works
4. Something went wrong — friendly error messages with remediation
   tips, no stack traces leaked, whitespace input handled gracefully
5. I want to talk to a specific agent — @agent routing, case-
   insensitive matching, comma syntax, unknown names fall to
   coordinator
6. I'm a power user now — /help, /status, /agents, /history, /quit
   all return useful output, unknown commands guide to /help
7. I came back the next day — state persists, first-run consumed,
   team still loaded, focus area survives between sessions

Closes bradygaster#383, bradygaster#384, bradygaster#385, bradygaster#386, bradygaster#394, bradygaster#396, bradygaster#398

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

* Copy polish: warmer, human-centered messages across CLI

Every message now feels helpful, not corporate. Changes include:

- cli-entry.ts: 'Your AI team, always ready' instead of generic desc
- commands.ts: Status output changed from 'Root/Active now' to 'Home/Active'
- Help text: 'Check your team' instead of 'Show which squad'
- InputPrompt: 'Message or @agent' instead of corporate placeholder
- App.tsx: 'Your team is assembled. Let's try:' (warmer tone)
- init.ts: 'Your team is assembled' instead of 'ready'
- ThinkingIndicator: Dynamic thinking phrases (Processing, Working)
- All command help: Casual verbs (Who's here, Fresh screen, Leave)

Tests updated to match new output strings. All 125+ CLI tests pass.

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

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
tamirdresher pushed a commit to tamirdresher/squad that referenced this pull request Mar 16, 2026
@bradygaster
test: human journey — My first conversation (bradygaster#384) (bradyg…
1ccf737 
…aster#482)

* test: human journey — Power user (bradygaster#396)

Add E2E journey test covering advanced shell features:
- /help and /status slash commands
- Tab completion for /commands and @agent names
- Ctrl+C cancel during processing
- Double Ctrl+C exit
- Multiple slash commands in sequence
- @agent direct routing with complex messages

Closes bradygaster#396

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

* test: human journey — My first conversation (bradygaster#384)

Add E2E journey test covering a new user's first interaction with Squad:
- Welcome banner display (title, version, agents, help hint)
- First message submission and coordinator routing
- Thinking indicator during processing
- Receiving agent responses via ShellApi
- /help command exploration
- /status agent roster check
- @agent direct message routing
- Graceful exit (exit, quit, Ctrl+C)

28 tests across 8 journey steps using createShellHarness() pattern.

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

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
tamirdresher pushed a commit to tamirdresher/squad that referenced this pull request Mar 16, 2026
@bradygaster
test: human journey — Something went wrong (bradygaster#386) (bradyga…
051dfd2 
…ster#483)

* test: human journey — Power user (bradygaster#396)

Add E2E journey test covering advanced shell features:
- /help and /status slash commands
- Tab completion for /commands and @agent names
- Ctrl+C cancel during processing
- Double Ctrl+C exit
- Multiple slash commands in sequence
- @agent direct routing with complex messages

Closes bradygaster#396

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

* test: human journey — My first conversation (bradygaster#384)

Add E2E journey test covering a new user's first interaction with Squad:
- Welcome banner display (title, version, agents, help hint)
- First message submission and coordinator routing
- Thinking indicator during processing
- Receiving agent responses via ShellApi
- /help command exploration
- /status agent roster check
- @agent direct message routing
- Graceful exit (exit, quit, Ctrl+C)

28 tests across 8 journey steps using createShellHarness() pattern.

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

* test: human journey — Something went wrong (bradygaster#386)

Add E2E journey tests covering error scenarios users may encounter:

- SDK connection failure shows helpful error message
- Agent dispatch failure is caught and shown to user
- Invalid /command shows conversational hint with /help
- Network-like errors during streaming are handled gracefully
- ErrorBoundary catches React rendering errors
- Shell remains usable after errors (can submit new messages)
- Error messages are user-friendly, not raw stack traces

21 tests across 7 describe blocks verify the full error UX.

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

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

6 participants

@diberry @craigb @jongio @jsturtevant @spboyer