docs: agent anatomy and hiring checklist by diberry · Pull Request #439 · bradygaster/squad

diberry · 2026-03-16T22:08:29Z

Minimal enrichment of two existing concept pages:

concepts/your-team.md - three new sections:

Anatomy of an agent (AI vs human vs @copilot)
Cross-agent context propagation
Hiring an agent developer checklist

concepts/github-workflow.md - one new section:

Working with your team (human-AI SDLC collaboration)

Two files changed, no new pages, no test changes needed.

Source material adapted from closed proposals (PRs #434, #435).

Closes #328

- 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>

diberry · 2026-03-16T23:02:37Z

@bradygaster — this one's ready for your review. Two concept pages enriched with agent anatomy and human-AI SDLC content. 4 commits, 2 files, ~75 lines added. Team-reviewed and feedback addressed.

- 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>

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 bradygaster#301 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

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>

…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>

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.

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>

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>

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

… 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

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

… 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 bradygaster#328 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

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>

- 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>

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>

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

diberry · 2026-03-17T17:13:11Z

@bradygaster This PR is ready for your review.

…gaster#439) * 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> * Fix bradygaster#423/bradygaster#399: Remove welcome typewriter animation blocking Users can now type immediately when shell launches. Removed 500ms typewriter animation and 300ms fade-in from welcome banner — title and content appear instantly. Pattern: instant feedback beats cosmetic delay. Matches bradygaster#427 shell loading fix. Closes bradygaster#423 Closes bradygaster#399 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Update Cheritto history: bradygaster#423 welcome animation fix Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

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>

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>

diberry force-pushed the squad/agent-anatomy branch 2 times, most recently from 208b252 to 1acb09e Compare March 17, 2026 14:04

diberry and others added 19 commits March 17, 2026 07:07

docs: update PAO history with first-session guide structure

89e9e33

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

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

5b4b26e

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>

fix: vitest resolve alias for workspace package mocking

67c9cef

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.

fix(docs): replace ~/.squad/ with platform-specific path references

6dbf688

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

deleted images

9f01554

docs(kobayashi): v0.8.21 release gate merge & publish trigger

4731456

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

docs: reframe lifecycle table as example, not prescriptive

0af6741

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>

diberry force-pushed the squad/agent-anatomy branch from 1acb09e to 0af6741 Compare March 17, 2026 14:12

fix: remove duplicate EXPECTED_CONCEPTS declaration

5c548a0

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

bradygaster merged commit ee10f72 into bradygaster:dev Mar 18, 2026
2 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: agent anatomy and hiring checklist#439

docs: agent anatomy and hiring checklist#439
bradygaster merged 22 commits intobradygaster:devfrom
diberry:squad/agent-anatomy

diberry commented Mar 16, 2026 •

edited

Loading

Uh oh!

diberry commented Mar 16, 2026

Uh oh!

diberry commented Mar 17, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

diberry commented Mar 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

diberry commented Mar 16, 2026

Uh oh!

diberry commented Mar 17, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

diberry commented Mar 16, 2026 •

edited

Loading