docs(slides): Advanced Squad Patterns 0.10 deck — 65 slides, self-contained Build-500 talk - #1233
Closed
tamirdresher wants to merge 2 commits into
Closed
docs(slides): Advanced Squad Patterns 0.10 deck — 65 slides, self-contained Build-500 talk#1233tamirdresher wants to merge 2 commits into
tamirdresher wants to merge 2 commits into
Conversation
Self-contained Build-500-level deck for the Advanced Squad Patterns session, plus the python-pptx source builder and the captured two-layer walkthrough that grounds the deck in real session evidence. Slide arc (5 patterns + synthesis): - Pattern 1 (Memory) — three-layer model, governed classes, full write architecture (Agent → MCP → LocalMemoryStore → Provider → backend), memory providers, tools catalog, classify spotlight, retrieval, anti-patterns - Pattern 2 (State) — code-vs-state framing, backends compare, two-layer as three storages (analogy: book / journal / sticky notes), live upgrade demo, session evidence, branch topology + timeline + landings walkthrough, 6 git hooks with rationale, pre-commit fires + recovery flow, external state with motivation - Pattern 3 (Spawning) — fan-out, worktrees, SubSquads, HQ pattern, mission brief template (2-col layout), guardrails - Pattern 4 (Cross-squad) — manifest, discover/delegate, pattern compare, mesh - Pattern 5 (Monorepo) — agentFileRoot vs teamRoot, subfolder mode - Bonus — per-agent model selection cascade + throttling recipe - Synthesis — 8-slide end-to-end workflow (prompt → coordinator → classify → write → verify), progressive reveal Aspire-style Source citations grounded to actual code paths in bradygaster/squad. Reviewed by a 4-agent squad (architect, dev, presenter, devil's advocate). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Five fixes applied based on the tamresearch1 squad's content review (Picard, Q, Crusher, Troi, Guinan, Geordi, Paris, Neelix): 1. Slide 13 (classify spotlight) — corrected the classifier truth. The (CI|PR|build) regex sits in BOTH FORBIDDEN_PATTERNS AND the TRANSIENT heuristic; FORBIDDEN scan wins, so TRANSIENT branch is unreachable for those inputs (only fires via explicit --class). Removed incorrect "CI build always passes → TRANSIENT" example. Verified live against LocalMemoryStore.classify() on 2026-06-09. (Q's #1 ❌ FAIL finding.) 2. Slide 1 — changed "Co-creator of Squad" to "Contributor & maintainer" to avoid attribution risk noted by Q and Crusher (upstream creator is Brady Gaster per the tamresearch1 decisions.md). 3. Slide 16 — "ADC Squad runner demo" generalized to "External Squad-using project demo" (Crusher: unexplained acronym could read as internal codename in public talk). 4. Slide 4 — "dozens of changesets" expanded to "97 changesets across CLI and SDK (50 SDK + 71 CLI, deduplicated)" per CHANGELOG.md line 9 (Q: underquoting invites skepticism). 5. NEW slide 62 (page 61) — "The three questions, answered in human terms" closing synthesis that answers slide 02's opening questions in plain language. Bottom line: "your team doesn't lose context to keep the repo clean — it gets both." Addresses Troi/Guinan/Picard's structural feedback: the deck showed the mechanism honestly but was missing the relief. Plus: workflow stage 4 slide updated to note the FORBIDDEN/TRANSIENT regex overlap explicitly in the code comment block. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
🏗️ Architectural Review
Automated architectural review — informational only. |
Contributor
🛫 PR Readiness Check
PR Scope: 🔧 Infrastructure
|
| Status | Check | Details |
|---|---|---|
| ❌ | Single commit | 2 commits — consider squashing before review |
| ✅ | Not in draft | Ready for review |
| ❌ | Branch up to date | dev is 4 commit(s) ahead — rebase recommended |
| ❌ | 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 | 1 check(s) failing: Security Review — Permissions & Secrets |
Files Changed (50 files, +5828 −0)
| File | +/− |
|---|---|
docs/advanced-squad-session/README.md |
+92 −0 |
docs/advanced-squad-session/advanced-squad-session.pptx |
+0 −0 |
docs/advanced-squad-session/build_advanced_squad_native_pptx.py |
+3126 −0 |
docs/advanced-squad-session/deck.html |
+162 −0 |
docs/advanced-squad-session/memory-tools-guide.md |
+160 −0 |
docs/advanced-squad-session/outputs/01-memory-provider-status.txt |
+17 −0 |
docs/advanced-squad-session/outputs/02-memory-classify.txt |
+9 −0 |
docs/advanced-squad-session/outputs/03-memory-write.txt |
+14 −0 |
docs/advanced-squad-session/outputs/04-memory-search.txt |
+13 −0 |
docs/advanced-squad-session/outputs/05-memory-audit.txt |
+20 −0 |
docs/advanced-squad-session/outputs/06-delegate-presets-evidence.txt |
+69 −0 |
docs/advanced-squad-session/outputs/07-spawn-and-mesh-evidence.txt |
+78 −0 |
docs/advanced-squad-session/outputs/08-state-backends-evidence.txt |
+63 −0 |
docs/advanced-squad-session/outputs/09-engineering-source-map.txt |
+98 −0 |
docs/advanced-squad-session/outputs/10-demo-runbook.txt |
+124 −0 |
docs/advanced-squad-session/outputs/11-architecture-evidence-map.txt |
+99 −0 |
docs/advanced-squad-session/outputs/12-two-layer-real-demo-transcript.txt |
+151 −0 |
docs/advanced-squad-session/outputs/13-two-layer-real-demo-branch-proof.txt |
+20 −0 |
docs/advanced-squad-session/outputs/14-two-layer-real-demo-commands.md |
+31 −0 |
docs/advanced-squad-session/outputs/15-context-budget-issue-1037.md |
+188 −0 |
docs/advanced-squad-session/outputs/16-split-agent-issue-1036.md |
+69 −0 |
docs/advanced-squad-session/outputs/17-state-backend-pr-1004.md |
+81 −0 |
docs/advanced-squad-session/outputs/18-governed-memory-pr-1145.md |
+174 −0 |
docs/advanced-squad-session/outputs/19-context-slimming-pr-1035.md |
+66 −0 |
docs/advanced-squad-session/outputs/20-fanout-squads-pr-1022.md |
+37 −0 |
docs/advanced-squad-session/outputs/21-real-memory-session-extract.md |
+37 −0 |
docs/advanced-squad-session/outputs/22-two-layer-live-state.txt |
+81 −0 |
docs/advanced-squad-session/outputs/before-after-memory.md |
+55 −0 |
docs/advanced-squad-session/outputs/effects/decision-inbox-entry.md |
+12 −0 |
docs/advanced-squad-session/outputs/effects/memory-audit.jsonl |
+3 −0 |
docs/advanced-squad-session/outputs/effects/memory-index.json |
+13 −0 |
docs/advanced-squad-session/outputs/git-worktree-list.txt |
+2 −0 |
docs/advanced-squad-session/outputs/orchestration-transcript.txt |
+17 −0 |
docs/advanced-squad-session/outputs/worktree-status.txt |
+2 −0 |
docs/advanced-squad-session/prompts/01-team-orchestration.md |
+31 −0 |
docs/advanced-squad-session/prompts/02-worktree-isolation.md |
+26 −0 |
docs/advanced-squad-session/prompts/03-skill-guided-review.md |
+23 −0 |
docs/advanced-squad-session/prompts/04-memory-cli-proof.md |
+34 −0 |
docs/advanced-squad-session/prompts/05-copilot-memory-tool.md |
+30 −0 |
docs/advanced-squad-session/prompts/06-delegate-presets.md |
+27 −0 |
docs/advanced-squad-session/prompts/07-spawn-more-squads.md |
+27 −0 |
docs/advanced-squad-session/prompts/08-cross-squad-communication.md |
+27 −0 |
docs/advanced-squad-session/prompts/09-state-backends-memory.md |
+26 −0 |
docs/advanced-squad-session/prompts/10-500-level-runbook.md |
+27 −0 |
docs/advanced-squad-session/screenshots/memory-effect.svg |
+33 −0 |
docs/advanced-squad-session/screenshots/memory-write.svg |
+22 −0 |
docs/advanced-squad-session/screenshots/orchestration.svg |
+35 −0 |
docs/advanced-squad-session/screenshots/worktree-output.svg |
+17 −0 |
docs/advanced-squad-session/speaker-notes.md |
+71 −0 |
docs/advanced-squad-session/two-layer-walkthrough.md |
+189 −0 |
Total: +5828 −0
This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.
Contributor
🟠 Impact Analysis — PR #1233Risk tier: 🟠 HIGH 📊 Summary
🎯 Risk Factors
📦 Modules Affecteddocs (50 files)
This report is generated automatically for every PR. See #733 for details. |
Contributor
There was a problem hiding this comment.
Pull request overview
This PR adds a self-contained “Advanced Squad Patterns 0.10” technical talk deck under docs/advanced-squad-session/, including a reproducible PowerPoint builder (python-pptx), a browser-viewable deck (deck.html), presenter notes, demo prompts, and captured evidence artifacts used to ground claims in real repo sources/output.
Changes:
- Added a
python-pptxgenerator (build_advanced_squad_native_pptx.py) and a checked-in.pptxdeck artifact. - Added presenter aids (speaker notes, walkthrough) and “demo prompt” scripts with expected tool calls / fallbacks.
- Added a large set of captured evidence files (
outputs/,outputs/effects/) and SVG screenshots used by the deck.
Reviewed changes
Copilot reviewed 44 out of 50 changed files in this pull request and generated 9 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/advanced-squad-session/advanced-squad-session.pptx | Generated PowerPoint deck artifact committed for distribution. |
| docs/advanced-squad-session/build_advanced_squad_native_pptx.py | Python python-pptx source builder intended to reproduce the .pptx. |
| docs/advanced-squad-session/deck.html | Browser companion deck for presenting/printing outside PowerPoint. |
| docs/advanced-squad-session/README.md | Entry-point documentation for presenting and regenerating deck artifacts. |
| docs/advanced-squad-session/two-layer-walkthrough.md | Captured two-layer walkthrough used to ground the “state” section. |
| docs/advanced-squad-session/speaker-notes.md | Slide-by-slide presenter notes and live-proof command checklist. |
| docs/advanced-squad-session/memory-tools-guide.md | Presenter guide for demonstrating memory tool calls and deterministic CLI proof. |
| docs/advanced-squad-session/prompts/01-team-orchestration.md | Demo prompt: multi-agent release-readiness fan-out. |
| docs/advanced-squad-session/prompts/02-worktree-isolation.md | Demo prompt: worktree isolation workflow + fallback. |
| docs/advanced-squad-session/prompts/03-skill-guided-review.md | Demo prompt: skill-guided PR review behavior. |
| docs/advanced-squad-session/prompts/04-memory-cli-proof.md | Demo prompt: deterministic governed-memory CLI proof commands. |
| docs/advanced-squad-session/prompts/05-copilot-memory-tool.md | Demo prompt: memory tool call expectations + fallback. |
| docs/advanced-squad-session/prompts/06-delegate-presets.md | Demo prompt: delegate + presets commands grounded in repo. |
| docs/advanced-squad-session/prompts/07-spawn-more-squads.md | Demo prompt: bounded fan-out / iterative retrieval ladder. |
| docs/advanced-squad-session/prompts/08-cross-squad-communication.md | Demo prompt: cross-squad communication boundaries. |
| docs/advanced-squad-session/prompts/09-state-backends-memory.md | Demo prompt: state backend comparison + proof points. |
| docs/advanced-squad-session/prompts/10-500-level-runbook.md | Demo prompt: deep technical runbook prompt for rehearsal. |
| docs/advanced-squad-session/screenshots/worktree-output.svg | SVG screenshot: worktree list proof (accessible title/desc included). |
| docs/advanced-squad-session/screenshots/orchestration.svg | SVG screenshot: orchestration fan-out diagram (accessible title/desc included). |
| docs/advanced-squad-session/screenshots/memory-write.svg | SVG screenshot: governed memory write output proof. |
| docs/advanced-squad-session/screenshots/memory-effect.svg | SVG screenshot: “memory proof chain” diagram. |
| docs/advanced-squad-session/outputs/worktree-status.txt | Captured output: worktree status evidence. |
| docs/advanced-squad-session/outputs/orchestration-transcript.txt | Captured output: orchestration transcript used as fallback. |
| docs/advanced-squad-session/outputs/git-worktree-list.txt | Captured output: git worktree list evidence. |
| docs/advanced-squad-session/outputs/effects/memory-index.json | Captured effect: governed memory index snapshot. |
| docs/advanced-squad-session/outputs/effects/memory-audit.jsonl | Captured effect: governed memory audit log snapshot. |
| docs/advanced-squad-session/outputs/effects/decision-inbox-entry.md | Captured effect: decision inbox entry snapshot. |
| docs/advanced-squad-session/outputs/before-after-memory.md | Before/after narrative showing expected memory directive effect. |
| docs/advanced-squad-session/outputs/22-two-layer-live-state.txt | Captured output: live two-layer state inspection snapshot. |
| docs/advanced-squad-session/outputs/21-real-memory-session-extract.md | Captured extract: real memory/session evidence guidance. |
| docs/advanced-squad-session/outputs/20-fanout-squads-pr-1022.md | Captured PR summary evidence for fan-out / e2e testing skill. |
| docs/advanced-squad-session/outputs/19-context-slimming-pr-1035.md | Captured PR summary evidence for coordinator slimming work. |
| docs/advanced-squad-session/outputs/18-governed-memory-pr-1145.md | Captured PR summary evidence for governed memory model. |
| docs/advanced-squad-session/outputs/17-state-backend-pr-1004.md | Captured PR summary evidence for state backend wiring. |
| docs/advanced-squad-session/outputs/16-split-agent-issue-1036.md | Captured issue snapshot evidence for splitting coordinator prompt. |
| docs/advanced-squad-session/outputs/15-context-budget-issue-1037.md | Captured issue snapshot evidence for context budget pressure. |
| docs/advanced-squad-session/outputs/14-two-layer-real-demo-commands.md | Captured commands: two-layer demo command list. |
| docs/advanced-squad-session/outputs/13-two-layer-real-demo-branch-proof.txt | Captured output: two-layer demo refs/branches proof. |
| docs/advanced-squad-session/outputs/12-two-layer-real-demo-transcript.txt | Captured output: full two-layer demo transcript. |
| docs/advanced-squad-session/outputs/11-architecture-evidence-map.txt | Evidence map tying deck claims to repo sources. |
| docs/advanced-squad-session/outputs/10-demo-runbook.txt | Fallback runbook for demo execution and failure modes. |
| docs/advanced-squad-session/outputs/09-engineering-source-map.txt | Source map linking slides/topics to code paths and evidence. |
| docs/advanced-squad-session/outputs/08-state-backends-evidence.txt | Captured evidence: state backend comparison and caveats. |
| docs/advanced-squad-session/outputs/07-spawn-and-mesh-evidence.txt | Captured evidence: spawning/mesh protocols and constraints. |
| docs/advanced-squad-session/outputs/06-delegate-presets-evidence.txt | Captured evidence: delegate/preset grounding and failure modes. |
| docs/advanced-squad-session/outputs/05-memory-audit.txt | Captured output: memory audit command result. |
| docs/advanced-squad-session/outputs/04-memory-search.txt | Captured output: memory search command result. |
| docs/advanced-squad-session/outputs/03-memory-write.txt | Captured output: memory write command result. |
| docs/advanced-squad-session/outputs/02-memory-classify.txt | Captured output: memory classify command result. |
| docs/advanced-squad-session/outputs/01-memory-provider-status.txt | Captured output: provider status command result. |
Comment on lines
+3122
to
+3126
| out = Path(r"C:\Users\tamirdresher\source\repos\squad-advanced-squad-session-slides\docs\advanced-squad-session\advanced-squad-session.pptx") | ||
| out.parent.mkdir(parents=True, exist_ok=True) | ||
| prs.save(out) | ||
| print(f"slides={len(prs.slides)}") | ||
| print(out) |
Comment on lines
+22
to
+26
| | `advanced-squad-session.pptx` | PowerPoint version generated as full-slide images from `deck.html`. | | ||
| | `build_advanced_squad_native_pptx.py` | **Source of truth for the .pptx.** Builds the 64-slide deck via `python-pptx`. Run `python build_advanced_squad_native_pptx.py` to regenerate. | | ||
| | `two-layer-walkthrough.md` | Reference walkthrough used by slides 26-28 — a real captured trace showing branch topology, timeline, and what landed where for one task. | | ||
| | `deck.html` | Browser-based source deck. Edit this first. | | ||
| | `speaker-notes.md` | Technical presenter script, slide-by-slide notes, demo cues, caveats. | |
Comment on lines
+86
to
+92
| `advanced-squad-session.pptx` is regenerated by rendering each slide in `deck.html` at 1280x720 with Playwright and inserting the images into PowerPoint with `python-pptx`. Run generation from this worktree so `node_modules` and workspace paths resolve. | ||
|
|
||
| Validation target: | ||
|
|
||
| - `deck.html` script parses. | ||
| - Browser DOM reports the expected `.slide` count (`23` for this deck). | ||
| - PPTX opens as a valid zip package and contains the same number of slides as `deck.html`. |
| Use the real demo repo generated under the session workspace if it is still present: | ||
|
|
||
| ```powershell | ||
| cd C:\Users\tamirdresher\.copilot\session-state\854abecd-cee7-42f6-972a-e5f6abbaf32d\files\two-layer-demo-repo |
| ## Exact commands | ||
|
|
||
| ```powershell | ||
| cd C:\Users\tamirdresher\source\repos\squad-advanced-squad-session-slides |
|
|
||
| ### Problem | ||
|
|
||
| Changes to coordinator and agent templates (\.squad-templates/squad.agent.md\, \scribe-charter.md\, etc.) can't be validated by unit tests — they're prompts interpreted by an LLM at runtime. We discovered this gap during state-backend development (PR #1004), where we ran 12 manual E2E tests to validate template changes. |
Comment on lines
+22
to
+26
| - \.squad-templates/skills/e2e-template-testing/SKILL.md\ — new skill (canonical) | ||
| - \ emplates/skills/e2e-template-testing/SKILL.md\ — synced copy | ||
| - \packages/squad-cli/templates/skills/e2e-template-testing/SKILL.md\ — synced copy | ||
| - \packages/squad-sdk/templates/skills/e2e-template-testing/SKILL.md\ — synced copy | ||
| - \CONTRIBUTING.md\ — new section: Testing Template Changes (End-to-End) |
Comment on lines
+30
to
+37
| - \ | ||
| pm run build\ ✅ | ||
| - \ | ||
| px vitest run test/builtin-skills.test.ts\ — 5/5 passed ✅ | ||
| - \ | ||
| px vitest run test/template-sync.test.ts\ — 149/149 passed ✅ | ||
| - Template sync verified via \ | ||
| ode scripts/sync-templates.mjs\ ✅ |
| ### Commands | ||
|
|
||
| ```powershell | ||
| cd C:\Users\tamirdresher\source\repos\squad-advanced-squad-session-slides |
Collaborator
Author
|
Closing — wrong destination. This is personal talk-prep material that should live in a private repo, not on the public Squad framework. Moving it accordingly. |
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.
Ships a self-contained 65-slide Build-500-level technical session deck — Advanced Squad Patterns 0.10 — under
docs/advanced-squad-session/, plus the python-pptx source builder so the deck is reproducible from code, plus a captured real-session walkthrough that grounds the deck in actual git artifacts.The audience: ~150-300 architects/developers at a 45-min conference slot. They've already done
squad init— this deck is about what comes after.What this ships
Deck (65 slides, 5-pattern arc + synthesis)
LocalMemoryStore→ Provider → backend), memory providers, tools catalog, classify spotlight, retrieval, anti-patternsagentFileRootvsteamRoot, subfolder mode (PR squad init: Squad init should not run git init in a sub-folder of a repository (or ever) #939)Source-of-truth + reproducibility
build_advanced_squad_native_pptx.py— full python-pptx builder, 65 slides, ~2700 lines. Runpython build_advanced_squad_native_pptx.pyto regenerate the .pptxtwo-layer-walkthrough.md— captured trace from a real session (1 README change → 1 feature-branch commit + 7squad-statecommits + 7refs/notes/squadrefreshes). Source material for slides 27-29outputs/— 22 captured CLI evidence files used as grounding for slide claimsprompts/— 10 live-demo prompts including the 500-level runbookscreenshots/— 4 SVG visualsspeaker-notes.md+memory-tools-guide.md— presenter aidsSource citations grounded in code
Every architectural claim cites a real path in this repo. Examples:
packages/squad-sdk/src/memory/index.ts:134-143—MemoryProviderinterfacepackages/squad-sdk/src/memory/index.ts:360-372—FORBIDDEN_PATTERNSpackages/squad-sdk/src/memory/index.ts:594-621—classify()heuristicspackages/squad-sdk/src/state-backend.ts:791-840—StateBackendStorageAdapterpackages/squad-cli/src/cli/commands/install-hooks.ts:110-142— pre-commit + post-commit hookspackages/squad-sdk/src/config/init.ts:144-148, 1262, 1298-1305— monorepo subfolder support (PR squad init: Squad init should not run git init in a sub-folder of a repository (or ever) #939)CHANGELOG.md:7-66— 0.10.0 release scopeReview process — two passes, eight agents
Before this PR the deck went through two independent multi-agent reviews:
Pass 1 — engineering review (4 parallel agents on Sonnet 4.6):
Pass 2 — tamresearch1 content squad review (8 Star Trek Voyager cast voices):
Concrete fixes landed from both reviews (selected):
memory/index.ts:610-619(TRANSIENT first in the heuristic block)outputs/*.txt"verbatim" cites don't exist in the deck repoCI build always passes → TRANSIENTclaim is wrong (returns LOCAL)LocalMemoryStore.classify()and discovered the deeper finding: same(CI|PR|build)regex sits in BOTHFORBIDDEN_PATTERNSand the TRANSIENT heuristic. FORBIDDEN wins → TRANSIENT heuristic is unreachable for those inputs. Slide rewritten to surface this honestly.Follow-up items for the broader repo (not in this PR):
squad upgrade --state-backend two-layerpost-upgrade flow → filed as docs: state-backends upgrade flow misses pre-commit hook, file reappearance, and recovery #1226 + PR docs(state-backends): document pre-commit hook, post-upgrade flow, and recovery #1227 (docs only).gitignorefor two-layer/orphan state files → filed as feat: conditional .gitignore for two-layer/orphan state files (defense-in-depth) #1228 + PR fix(state-backend): conditional .gitignore for two-layer/orphan state files #1229 (code change)Scope
docs/advanced-squad-session/. Nopackages/source touched. No changeset required.Test plan
python build_advanced_squad_native_pptx.pyregenerates the .pptx successfully (65 slides)How to view
`powershell
PowerPoint
Start-Process .\docs\advanced-squad-session\advanced-squad-session.pptx
or browser-based source
Start-Process .\docs\advanced-squad-session\deck.html
`
Closes nothing directly — this is a new deck artifact, not tied to an open issue.