diff --git a/.squad/agents/booster/history.md b/.squad/agents/booster/history.md index 9465240c..2451584c 100644 --- a/.squad/agents/booster/history.md +++ b/.squad/agents/booster/history.md @@ -84,6 +84,15 @@ Analyzed 20 CI runs from March 15. Identified 3 distinct failure categories: 4. Better failure grouping/attribution in CI UI (distinguish "new gate" vs "regression") 5. Spell check dictionary maintenance workflow (easier to add known-good usernames/terms) +### whatsnew.md Version Sync — March 22, 2026 +**What was built:** scripts/sync-whatsnew-version.mjs — strips -build.N suffix from package.json version, finds the ## v{X} — Current Release heading in docs/src/content/docs/whatsnew.md, and replaces it with the current clean semver. Idempotent; writes only when changed. + +**Test added:** est/whatsnew-version-sync.test.ts — Vitest test that asserts the Current Release heading in whatsnew.md matches the stripped package.json version. Fails CI when versions diverge. + +**Hook:** Appended +ode scripts/sync-whatsnew-version.mjs to the prebuild npm script (runs after bump-build.mjs, so it always sees the bumped version). Also set SKIP_BUILD_BUMP=1 guard pattern documented for CI validate runs. + +**Immediate fix:** Updated the stale ## v0.8.2 — Current Release heading to ## v0.8.25 — Current Release to match the actual package.json version at time of work. ### CI Workflow Audit — March 23, 2026 **Status:** Conducted full audit of 15 workflow files. Brady's perception ("complete nightmare, 12,000 workflows") is not accurate — the codebase is lean, well-organized, and 99% authored by Brady (bradygaster + Copilot). diff --git a/.squad/agents/pao/history.md b/.squad/agents/pao/history.md index abbb323e..c4e3d998 100644 --- a/.squad/agents/pao/history.md +++ b/.squad/agents/pao/history.md @@ -94,12 +94,34 @@ Evaluated four docs pages from PR #331 (Tamir's blog analysis) against Squad-spe ### Boundary Review Execution (v0.8.26) Executed boundary review findings from PR #331: (1) Deleted ralph-operations.md (infrastructure around Squad, not Squad itself — moved to IRL); (2) Deleted proactive-communication.md (external tools/webhooks — moved to IRL); (3) Reframed issue-templates.md intro to clarify "GitHub feature configured for Squad" not "Squad feature"; (4) Updated EXPECTED_SCENARIOS in docs-build.test.ts to match remaining files. Pattern reinforced: boundary review = remove external infrastructure docs, reframe platform integration docs to clarify whose feature it is, keep Squad behavior/config docs. Changes staged for commit. -### Cross-Org Authentication Docs (v0.8.26) +### Docs Catalog Audit (2026-03-22) +Full audit of the Astro docs site identified critical quality and navigation gaps. **Findings:** 0 dead nav links (healthy); 15 orphaned pages not discoverable via sidebar (FAQ, guides, reference pages, 6 legacy root files); 3 stale/broken pages using deprecated install syntax; 5 duplicate content conflicts. **Top 5 Actions:** (1) Add CI test to enforce nav coverage — catch orphaned pages automatically; (2) Delete 6 root-level legacy files (guide.md, sample-prompts.md, tips-and-tricks.md, tour-*.md) — deprecated syntax and not in nav; (3) Make whatsnew.md a release checklist artifact — current report (v0.8.2) vs actual (v0.8.26+) erodes trust; (4) Update insider-program.md to current install method — replace deprecated `npx github:` syntax; (5) Resolve choose-your-interface vs choosing-your-path duplication — one canonical page rule. **Skill Created:** docs-catalog-audit (low confidence; audit framework needs iteration). **Decision:** Merged into decisions.md for team adoption. + +### Docs Fire Fixes (post-audit, 2026-03-22) +Fixed four fires from the catalog audit: (1) Updated `insider-program.md` — replaced all deprecated `npx github:bradygaster/squad#insider` commands with `npm install -g @bradygaster/squad-cli@insider`, and all `.ai-team/` references with `.squad/`; (2) Added six orphaned pages to `navigation.ts` — `guide/faq`, `guide/build-autonomous-agent`, `features/built-in-roles`, `features/context-hygiene`, `features/issue-templates`, `reference/vscode-troubleshooting`; (3) Deleted five stale root-level files via `git rm` (`guide.md`, `sample-prompts.md`, `tips-and-tricks.md`, `tour-first-session.md`, `tour-github-issues.md`); (4) Added `vscode-troubleshooting` to EXPECTED_REFERENCE in docs-build.test.ts — all 23 tests pass. New nav entries use sentence-case and "and" over ampersands per team decision. Created docs/src/content/docs/scenarios/cross-org-auth.md covering GitHub personal + Enterprise Managed Users (EMU) multi-account auth. Three solutions documented: (1) gh auth switch for manual account toggling; (2) Copilot instructions (.github/copilot-instructions.md) for account mapping documentation; (3) Squad skill pattern for auth error detection and recovery. Covered git credential helpers (per-host and per-org), EMU hostname variations (github.com vs dedicated instances), and common error messages (HTTP 401, authentication required). Added cross-references in troubleshooting.md (new section), enterprise-platforms.md (authentication section), and navigation.ts. Updated test/docs-build.test.ts with 'cross-org-auth' in EXPECTED_SCENARIOS. Pattern: Microsoft Style Guide (sentence-case), "Try this" prompts at top, problem/solution structure, practical examples over abstractions, links to related pages at bottom. ### Scannability Framework (v0.8.25) Format selection is a scannability decision, not style preference. Paragraphs for narrative/concepts (3-4 sentences max). Bullets for scannable items (features, options, non-sequential steps). Tables for comparisons or structured reference data (config, API params). Quotes/indents for callouts/warnings. Decision test: if reader hunts for one item in a paragraph, convert to bullets/table. This framework is now a hard rule in charter under SCANNABILITY REVIEW. +### Docs Catalog Audit (2026) +Full audit of the Astro-based docs site. Key patterns and findings: + +**Orphaned pages (exist but not in navigation.ts):** 15 total — `get-started/choose-your-interface.md`, `guide/faq.md`, `guide/build-autonomous-agent.md`, `guide/github-auth-setup.md`, `features/built-in-roles.md`, `features/context-hygiene.md`, `features/cost-tracking.md`, `features/issue-templates.md`, `reference/vscode-troubleshooting.md`, and 6 root-level legacy files (`guide.md`, `sample-prompts.md`, `tips-and-tricks.md`, `tour-first-session.md`, `tour-github-issues.md`, `tour-gitlab-issues.md`). + +**Stale content:** `whatsnew.md` reports v0.8.2 as current; actual is v0.8.26+. `insider-program.md` uses deprecated `npx github:` install format and references old `.ai-team/` directory name throughout. + +**Duplicate/overlap pairs:** `choosing-your-path.md` (in nav) vs `choose-your-interface.md` (orphan, more complete); root-level `sample-prompts.md` vs `guide/sample-prompts.md`; root-level `tips-and-tricks.md` vs `guide/tips-and-tricks.md`; root-level `tour-first-session.md` vs `get-started/first-session.md`. + +**Content quality:** All actively-navved pages are well-written, follow Microsoft Style Guide, and use correct install commands. Format standards (H1, experimental callout, "Try this" block, HR, H2 sections) are inconsistently applied — some orphaned pages like `built-in-roles.md` and `cost-tracking.md` lack the standard header/callout pattern. + +**Structural issues:** `features/team-setup.md` has a duplicate `## How Init Works` heading (merge artifact). `features/streams.md` nav title is "Streams" but H1 is "Squad SubSquads" (mismatch). `guide/faq.md` is a high-value page completely invisible from the sidebar. `features/built-in-roles.md` is a comprehensive roles reference also invisible from nav. + +**Gap:** No dedicated FAQ entry point, no changelog page, cookbook section is thin (one page), no user-facing explanation of the NASA Mission Control naming scheme for agents. + +**Navigation:** Zero dead nav links (every nav slug has a matching file). All orphan pages are linked internally from other pages so they are reachable — but not browseable via sidebar. + +📌 **Team update (2026-03-22T12:46:00Z):** Booster implemented automated version sync for `whatsnew.md` (finding #1). Script reads `package.json` version, updates "Current Release" heading on every prebuild, with Vitest test gate. Heading now correct (v0.8.25+), will stay in sync automatically on all future builds. Finding #1 resolved. ### Issue Triage (2026-03-22T06:44:01Z) **Flight triaged 6 unlabeled issues and filed 1 new issue.** diff --git a/.squad/decisions.md b/.squad/decisions.md index ded85571..b5290822 100644 --- a/.squad/decisions.md +++ b/.squad/decisions.md @@ -6526,6 +6526,77 @@ ESM module resolution uses dual-layer postinstall strategy: --- +## Docs Catalog Audit Findings — PAO Decision + +**Author:** PAO (DevRel) +**Date:** 2026-03-22 + +Comprehensive audit of the Astro-based Squad docs site identified critical gaps in navigation coverage, stale content, and structural inconsistencies. + +### 1. Navigation gap is a CI failure condition + +Every content file under docs/src/content/docs/ that is not in +avigation.ts (or STANDALONE_PAGES) must be treated as a defect. Pattern of 15 orphaned pages (FAQ, built-in roles reference, context hygiene guide, VS Code troubleshooting, autonomous agent guide, GitHub auth setup) shows no automated check preventing nav gaps. + +**Action:** Add test assertion in est/docs-build.test.ts to verify every .md file in docs content tree appears in either NAV_SECTIONS or STANDALONE_PAGES. + +### 2. Root-level legacy files must be removed + +Six root-level files ( our-first-session.md, our-github-issues.md, our-gitlab-issues.md, guide.md, sample-prompts.md, ips-and-tricks.md) are stale legacy artifacts using deprecated install commands ( +px github:bradygaster/squad, .ai-team/), not in nav, creating confusion. Delete or archive — do not keep indefinitely. + +### 3. whatsnew.md must be updated on every release + +What's New page is the trust signal for active maintenance. Currently reports v0.8.2 when actual is v0.8.26+. This erodes user trust. **Update policy:** whatsnew.md is a required artifact in every release checklist. + +### 4. insider-program.md must use current distribution + +Insider Program page uses deprecated +px github:bradygaster/squad#insider syntax and references old .ai-team/ directory. Must be updated to use current npm insider channel or removed if insider program format changed. + +### 5. choose-your-interface.md supersedes choosing-your-path.md + +Orphaned get-started/choose-your-interface.md is significantly more complete than navved get-started/choosing-your-path.md. Options: (a) add choose-your-interface to nav and point from installation.md, or (b) merge into single canonical page. Do not keep both — enforce "one canonical page per concept" rule. + +### Observations (No Action Required) + +- **Zero dead nav links** — every nav reference has backing file (healthy signal) +- **All actively-navved pages** follow Microsoft Style Guide, use correct install commands +- **Blog section healthy** — 28 posts, consistent format +- **Concepts section clean** — well-structured + +--- + +## whatsnew.md "Current Release" Version Sync + +**By:** Booster (CI/CD Engineer) +**Status:** Implemented +**Date:** 2026-03-22 + +### Problem + +`docs/src/content/docs/whatsnew.md` contains a `## v{X} — Current Release` heading that drifts from `package.json` version during build cycles. Manually updating it during releases is error-prone and easy to skip, eroding team trust in release docs. + +### Decision + +Implement automated version sync via prebuild script: + +1. **scripts/sync-whatsnew-version.mjs** — Reads `package.json` version, strips pre-release suffixes (e.g., `-build.N`), finds `## v{X} — Current Release` heading in whatsnew.md, replaces it if needed (idempotent, no-ops if already correct). +2. **Prebuild hook** — Wire into `package.json` `"prebuild"` script to run after `bump-build.mjs`, so it always sees freshly bumped version. +3. **Test gate** — Add Vitest test (`test/whatsnew-version-sync.test.ts`) that fails CI if heading and `package.json` are out of sync. + +### Rationale + +- Root cause: No automated gate. Version bumps fire via `bump-build.mjs` but `whatsnew.md` update was manual and skipped. +- **Prebuild** (not build) ensures it runs on every local `npm run build` + CI, keeping the file always current. +- Idempotent design allows safe use with `SKIP_BUILD_BUMP=1` (validate-only builds still sync). +- Test is the safety net: even manual edits to wrong version are caught. + +### Alternatives Rejected + +- **Git hook (pre-commit):** Not portable across all contributors and Copilot agents. +- **Test-only, no script:** Would fail CI but give no remediation path. +- **Modify bump-build.mjs:** Out of scope per Booster charter (don't modify internal bump logic). # Economy Mode Design — #500 **Date:** 2026-03-20 diff --git a/docs/src/content/docs/concepts/architecture.md b/docs/src/content/docs/concepts/architecture.md index 991891e3..a25ffb72 100644 --- a/docs/src/content/docs/concepts/architecture.md +++ b/docs/src/content/docs/concepts/architecture.md @@ -1,70 +1,542 @@ -# Architecture - -> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. - -How Squad works — one page, no handwaving. - ---- - -## System diagram - -``` -User request - ↓ -Coordinator (routing engine) - ↓ -Spawns agents in parallel - ↓ -Agents read memory (.squad/) → work → write results - ↓ -Scribe merges decisions, Ralph tracks issues - ↓ -Results returned to user -``` - ---- - -## Components - -### Coordinator - -The coordinator is Squad's routing engine. It reads your request, checks routing rules in `.squad/routing.md`, and decides which agents to spawn. If you say "team," it decomposes the work and launches multiple agents in parallel. If you name an agent, it routes directly to them. - -### Agents - -Each agent is a specialist with a charter, role, and persistent memory. Agents are spawned as independent subprocesses with their own context windows and tools. They read `.squad/decisions.md` and their own history before working, then write results back. Agents never see each other's conversations — the coordinator orchestrates coordination. - -### Memory (.squad/) - -All team state lives in `.squad/`. This includes the roster (`team.md`), routing rules (`routing.md`), decisions (`decisions.md`), agent charters and histories (`agents/`), and ceremony schedules (`ceremonies.md`). Agents read this before every spawn. You own these files — edit them anytime. - -### Routing - -Routing rules in `.squad/routing.md` define which agent handles which work. The coordinator reads these rules before spawning. You can override routing by naming an agent directly in your request. - -### Scribe - -The Scribe is a silent agent that tracks decisions and logs sessions. Every team has a Scribe. You never talk to them directly — they work in the background, merging decisions from all agents into `.squad/decisions.md`. - -### Ralph - -Ralph is the work monitor. He watches your GitHub or GitLab issues, tracks work in progress, and alerts the team when something is ready. Every team has a Ralph. He's silent unless you ask him for status. - ---- - -## What happens when you say "Team, build X"? - -1. **Coordinator reads the request** and checks `.squad/routing.md` for decomposition rules. -2. **Coordinator spawns multiple agents in parallel** — one for frontend, one for backend, one for tests, etc. -3. **Each agent reads `.squad/decisions.md`** and their own history (`agents/{name}/history.md`), then works independently. -4. **Agents write results** to their history files and propose decisions. -5. **Scribe merges all decisions** into `.squad/decisions.md`. -6. **Coordinator returns labeled results** to you, tagged with each agent's name. - ---- - -## Learn more - -- [**Work routing**](../features/routing) — How the coordinator decides which agents to spawn -- [**Memory and knowledge**](memory-and-knowledge) — How decisions, skills, and history persist -- [**Parallel work**](parallel-work) — How agents work simultaneously without conflicts +--- +title: Architecture +description: How Squad works — from user message to agent execution +--- + +# How Squad Works + +Squad is a programmable multi-agent orchestration runtime for GitHub Copilot that transforms how you build software. When you send a message to Squad, a coordinator reads your team's context and launches specialized agents in parallel — each working independently on focused tasks. Agents persist knowledge across sessions, communicate through a shared decision log (the .squad/ directory), and compound expertise with every job. + +The system is built on principles of isolation (agents don't block each other), persistence (all decisions commit to Git), and portability (teams export and import across repositories). Whether you're running three agents in parallel or managing complex dependencies between jobs, Squad handles scheduling, model selection, and knowledge synthesis automatically. + +This page explains the architecture layer by layer: how messages flow through the system, how state stays consistent during parallel work, and how knowledge compounds over time. + +--- + +## User Interaction Flow + +When you send a message to Squad, the coordinator reads your team's context and launches agents in parallel. Here's the journey: + +![User Interaction Flow](./images/architecture-user-flow.png) + +**What happens at each step:** +1. **User sends message** — via Copilot Chat or CLI (\copilot --agent squad\ or \squad\ shell) +2. **Coordinator resolves team** — reads \.squad/team.md\ to find agents, routes work based on \ outing.md\ +3. **Agents spawn** — each agent loads its charter, history, and shared decisions +4. **Parallel execution** — agents work independently; those with dependencies wait for upstream results +5. **Decisions captured** — agents write decisions to drop-box (\decisions/inbox/\) for deduplication +6. **Scribe merges** — \decisions.md\ updates automatically; session logged to \.squad/log/\ +7. **Git persists** — all changes committed so knowledge compounds across sessions + +
+View Mermaid source + +\\\mermaid +sequenceDiagram + participant User + participant CLI/IDE as Copilot CLI/
VS Code + participant Coordinator + participant Agents + participant State as .squad/ Files + participant Git + + User->>CLI/IDE: Message (Copilot Chat) + CLI/IDE->>Coordinator: Parse input, resolve team + Coordinator->>State: Load team.md, routing.md, decisions.md + Coordinator->>Agents: Spawn agents (parallel fan-out) + + par Parallel Work + Agents->>Agents: Read charter, history, decisions + Agents->>Agents: Perform work (code, docs, tests) + Agents->>State: Write to decisions/inbox/{name}-*.md + end + + State->>State: Scribe merges inbox → decisions.md + State->>Git: Commit changes (.squad/ + artifacts) + Agents->>CLI/IDE: Return results + CLI/IDE->>User: Display output & progress +\\\ + +
+ +--- + +## Component Architecture + +Squad layers multiple abstraction boundaries so each component has a single responsibility: + +![Component Architecture](./images/architecture-components.png) + +**Layer breakdown:** + +- **UI Layer** — Entry points (Copilot CLI, VS Code, shell). All feed into the Coordinator. +- **Orchestration** — Coordinator reads routing rules, analyzes dependencies, selects models, schedules work. +- **Execution** — Agents spawn (via \ ask\ tool) in parallel or sequential mode depending on dependencies. +- **State** — \.squad/\ is the source of truth. Team roster, decisions, and personal memory live here. +- **Persistence** — StorageProvider abstracts file I/O; Git is the transport (all \.squad/\ changes committed). +- **Artifacts** — Code, docs, tests, configs produced by agents. Usually committed alongside \.squad/\ updates. + +
+View Mermaid source + +\\\mermaid +graph TB + subgraph UI[\"\🖥️ User Interfaces\\"] + COPILOT[\"\Copilot CLI
copilot --agent squad\\"] + VSCODE[\"\VS Code Copilot Chat
Select Squad agent\\"] + SHELL[\"\Interactive Shell
squad\\"] + end + + subgraph ORK[\"\🗂️ Orchestration\\"] + COORD[\"\Coordinator
Routes, launches, schedules\\"] + ROUTE[\"\Routing Logic
team.md + routing.md\\"] + MODEL[\"\Model Selection
Task → right tier\\"] + end + + subgraph RUN[\"\⚡ Execution\\"] + SPAWN[\"\Agent Spawning
task tool (background/sync)\\"] + AGENTS[\"\Agents (Parallel)
Read charter + history\\"] + GATE[\"\Review Gates
Lead approval when needed\\"] + end + + subgraph STATE[\"\.squad/ State Files\\"] + TEAM[\"\ eam.md
Roster + roles\\"] + DECISIONS[\"\decisions.md
Shared rules\\"] + HISTORY[\"\gents/{name}/history.md
Personal memory\\"] + SKILLS[\"\skills/{name}/SKILL.md
Reusable patterns\\"] + CASTING[\"\casting/
Persistent names\\"] + INBOX[\"\decisions/inbox/\\"] + end + + subgraph PERSIST[\"\💾 Persistence\\"] + STORAGE[\"\StorageProvider
Abstract file I/O\\"] + GIT[\"\Git Repository
Append-only logs\\"] + end + + subgraph ART[\"\📄 Artifacts\\"] + CODE[\"\Code\\"] + DOCS[\"\Docs\\"] + TESTS[\"\Tests\\"] + CONFIG[\"\Config\\"] + end + + UI -->|Message| COORD + COORD -->|Read context| ROUTE + ROUTE -->|Analyze task| MODEL + MODEL -->|Spawn agent| SPAWN + SPAWN -->|Run in parallel| AGENTS + AGENTS -->|Read knowledge| STATE + AGENTS -->|Write decisions| INBOX + INBOX -->|Merge| DECISIONS + AGENTS -->|Produce| ART + AGENTS -->|Learn| HISTORY + + STATE -->|Persist| STORAGE + STORAGE -->|Commit| GIT + GATE -.->|Reviewer checks| AGENTS + + style UI fill:#4A9EFF + style ORK fill:#2ecc71 + style RUN fill:#f39c12 + style STATE fill:#9b59b6 + style PERSIST fill:#34495e + style ART fill:#e74c3c +\\\ + +
+ +--- + +## State Management + +Squad uses a drop-box pattern to avoid write conflicts when multiple agents work in parallel. Each agent writes to its own file in \.squad/decisions/inbox/\. A Scribe agent periodically merges these into \.squad/decisions.md\, deduplicating and linking related decisions. When a new agent spawns, it loads the shared decisions, its own history, and reusable patterns before starting work. + +![State Management](./images/architecture-state-management.png) + +**How it works:** + +1. **Agents write in parallel** — each writes to its own file in \.squad/decisions/inbox/\ (no conflicts). +2. **Scribe merges** — periodically consolidates inbox files into \.squad/decisions.md\, deduplicating overlaps. +3. **Shared brain loads** — on every agent spawn, the Coordinator loads: + - \decisions.md\ (shared rules, all agents read) + - \gents/{name}/history.md\ (personal memory, only that agent reads) + - \skills/\ (reusable patterns, all agents read) +4. **Personal history grows** — after each session, agents append what they learned to their \history.md\. +5. **Git persists** — everything in \.squad/\ is append-only and committed, so knowledge compounds. + +
+View Mermaid source + +\\\mermaid +graph TB + subgraph AGENTS[\"\👤 Agents Working in Parallel\\"] + A1[\"\Agent 1
Learns pattern\\"] + A2[\"\Agent 2
Discovers convention\\"] + A3[\"\Agent 3
Updates config\\"] + end + + subgraph DROPBOX[\"\.squad/decisions/inbox/
Drop-box (conflict-free writes)\\"] + D1[\"\gent1-pattern.md\\"] + D2[\"\gent2-convention.md\\"] + D3[\"\gent3-config.md\\"] + end + + subgraph SCRIBE[\"\🤖 Scribe Agent\\"] + MERGE[\"\Merge inbox
→ decisions.md
Deduplicate & link\\"] + end + + subgraph SHARED[\"\.squad/ Shared Brain\\"] + DECISIONS[\"\decisions.md
All agents read before working\\"] + HISTORY[\"\gents/{name}/history.md
Only {name} reads own\\"] + SKILLS[\"\skills/{name}/SKILL.md
All agents read\\"] + end + + subgraph LOG[\"\📋 Audit Trail\\"] + ORCHESTRATION[\"\.squad/orchestration-log/*.md
Who spawned, why, what happened\\"] + SESSION[\"\.squad/log/*.md
Full session transcript\\"] + end + + subgraph GIT[\"\🔗 Git (Persistence)\\"] + COMMIT[\"\Commit to main/dev
All changes versioned\\"] + end + + A1 -->|Write| D1 + A2 -->|Write| D2 + A3 -->|Write| D3 + + D1 & D2 & D3 -->|Batch merge| MERGE + MERGE -->|Consolidate| DECISIONS + + DECISIONS -->|Load before work| A1 & A2 & A3 + HISTORY -->|Personal context| A1 & A2 & A3 + SKILLS -->|Reusable patterns| A1 & A2 & A3 + + A1 & A2 & A3 -->|Session activity| ORCHESTRATION + MERGE -->|Session summary| SESSION + + DECISIONS & HISTORY & SKILLS & ORCHESTRATION & SESSION -->|All committed| GIT + + style AGENTS fill:#f39c12 + style DROPBOX fill:#e67e22 + style SCRIBE fill:#3498db + style SHARED fill:#9b59b6 + style LOG fill:#2c3e50 + style GIT fill:#27ae60 +\\\ + +
+ +--- + +## Parallel Execution Model + +Squad's default is **eager parallelism** — launch everything that can run immediately. The Coordinator analyzes task dependencies and chooses the execution mode: background (all independent agents run in parallel), sync (sequential when one agent depends on another's output), or review gates (reviewer approval before proceeding). + +![Parallel Execution Model](./images/architecture-parallel-execution.png) + +**Execution modes:** + +- **Background (fan-out)** — All independent agents run in parallel. Coordinator waits for all to finish, then collects results. +- **Sync (sequential)** — One agent waits for another's output. Used when there's a data dependency. +- **Review gates** — Lead agent reviews work before proceeding. Only approved work moves forward. +- **Concurrency limits** — Default is 5 agents in parallel; adjustable per session. + +
+View Mermaid source + +\\\mermaid +graph TB + subgraph PARALLEL[\"\Parallel Fan-Out (Background)\\"] + I1[\"\Independent Task 1\\"] + I2[\"\Independent Task 2\\"] + I3[\"\Independent Task 3\\"] + end + + subgraph WAIT[\"\Wait for Results\\"] + P1[\"\Agent 1 done\\"] + P2[\"\Agent 2 done\\"] + P3[\"\Agent 3 done\\"] + end + + subgraph SEQUENTIAL[\"\Sequential (Sync)\\"] + S1[\"\Agent 1
Produces output\\"] + S2[\"\Agent 2
Uses output\\"] + S3[\"\Agent 3
Refines\\"] + end + + subgraph GATE[\"\Review Gate\\"] + REVIEW[\"\Lead reviews
Agent 1's work\\"] + APPROVE[\"\Approved?\\"] + NEXT[\"\Agent 2 proceeds\\"] + end + + INPUT[\"\Coordinator
receives task\\"] -->|No dependencies| PARALLEL + INPUT -->|Has dependencies| SEQUENTIAL + INPUT -->|Reviewer gate| GATE + + PARALLEL --> I1 & I2 & I3 + I1 & I2 & I3 --> WAIT + WAIT -->|All done| COLLECT[\"\Collect &
synthesize\\"] + + SEQUENTIAL --> S1 + S1 --> S2 + S2 --> S3 + + GATE --> REVIEW + REVIEW --> APPROVE + APPROVE -->|Yes| NEXT + APPROVE -->|No| REJECT[\"\Request changes\\"] + + style PARALLEL fill:#2ecc71 + style SEQUENTIAL fill:#f39c12 + style GATE fill:#e74c3c + style COLLECT fill:#3498db + style APPROVE fill:#9b59b6 +\\\ + +
+ +--- + +## Casting & Persistent Naming + +Agents have permanent names from a thematic universe (for example, Apollo 13 mission control: Flight, Procedures, CAPCOM, EECOM). Names persist across sessions and repositories, allowing agents to accumulate knowledge and build expertise over time. Export a trained team and import it to a new project — the agents arrive with their full history intact. + +![Casting & Persistent Naming](./images/architecture-casting.png) + +**Why persistent names matter:** + +- **Identity** — Each agent (for example, "Flight", "Procedures") is known by one name forever. +- **Knowledge** — Flight builds up history in \.squad/agents/flight/history.md\ across sessions. +- **Portability** — Export a team, import it to a new repo, and Flight is there with all their knowledge. +- **Casting** — Names come from a thematic universe so your team feels cohesive (not random labels like "Agent1"). + +
+View Mermaid source + +\\\mermaid +graph TB + subgraph INIT[\"\Casting (Init Phase)\\"] + UNIVERSE[\"\Select universe
Apollo 13, Firefly, etc.\\"] + ASSIGN[\"\Allocate names
from universe\\"] + REGISTRY[\"\Create registry.json
Persistent name mapping\\"] + end + + subgraph MEMORY[\"\Persistent Identity\\"] + ROLE[\"\Agent name (e.g., Flight)
Same across repos\\"] + HISTORY_FILE[\"\.squad/agents/flight/history.md
Accumulates knowledge\\"] + CHARTER[\"\.squad/agents/flight/charter.md
Role, expertise, voice\\"] + end + + subgraph KNOWLEDGE[\"\Knowledge Compounds\\"] + SESSION1[\"\Session 1
Learns auth pattern\\"] + SESSION2[\"\Session 2
Refines pattern\\"] + SESSION3[\"\Session 3
Full expertise\\"] + end + + subgraph PORTABILITY[\"\Portability\\"] + EXPORT[\"\squad export
Snapshot team + knowledge\\"] + IMPORT[\"\squad import file.json
Same team, new repo\\"] + SHARED[\"\Shared cast guarantees
Same agent everywhere\\"] + end + + INIT --> REGISTRY + REGISTRY --> MEMORY + MEMORY -->|Load on spawn| SESSION1 + SESSION1 -->|Append learnings| SESSION2 + SESSION2 -->|Append learnings| SESSION3 + SESSION3 -->|Export with team| EXPORT + EXPORT -->|Import to new repo| IMPORT + IMPORT -->|Flight reappears
with full history| SHARED + + style INIT fill:#3498db + style MEMORY fill:#9b59b6 + style KNOWLEDGE fill:#f39c12 + style PORTABILITY fill:#2ecc71 +\\\ + +
+ +--- + +## Decision & Knowledge Flow + +Here's the complete loop of how decisions and knowledge move through the system. When you state a preference or directive ("Always use TypeScript strict mode"), the Coordinator writes it to the decision log. Agents read these decisions before working, and after each session, they append learnings to their personal history. The Scribe consolidates and commits everything, so the next session starts with richer context. + +![Decision & Knowledge Flow](./images/architecture-decisions.png) + +**Knowledge persistence:** + +1. **Directives captured** — When you say "always…" or "never…", the Coordinator writes to \decisions.md\. +2. **Decisions merged** — Scribe consolidates inbox files into shared \decisions.md\ automatically. +3. **Personal memory grows** — Agents append learnings to their \history.md\ after each session. +4. **Session logged** — Full orchestration and session logs written to \.squad/log/\ (append-only). +5. **Git commits all** — Every change persists to Git, so knowledge compounds and is never lost. + +
+View Mermaid source + +\\\mermaid +sequenceDiagram + participant You + participant Coordinator + participant Agents + participant Scribe + participant State as .squad/ Files + participant Git + + You->>Coordinator: "Always use TypeScript strict mode" + Coordinator->>Coordinator: Detect directive signal word + Coordinator->>State: Write decision to inbox/ + + You->>Coordinator: "Build the login page" + Coordinator->>Agents: Spawn Backend, Frontend, Tester + + par Agent Work + Agents->>State: Load decisions.md + own history.md + Agents->>Agents: Work independently + Agents->>State: Write to decisions/inbox/ + Agents->>State: Write to agents/{name}/history.md + end + + State->>Scribe: Inbox files ready to merge + Scribe->>State: Consolidate → decisions.md + Scribe->>State: Log session to log/*.md + + State->>Git: Commit (.squad/ + artifacts) + Git->>Git: All history preserved + + Note over You,Git: Next session... + You->>Coordinator: "Continue with payments" + Coordinator->>State: Load team.md, routing.md, decisions.md + Note over Coordinator: Agents read TypeScript directive automatically + Coordinator->>Agents: Spawn agents with updated context +\\\ + +
+ +--- + +## Git Worktree Lifecycle + +When worktree mode is enabled, Squad creates a dedicated git worktree for each issue. This isolates branch work, avoids disrupting the main checkout, and allows multiple agents to collaborate safely on the same issue. Each worktree gets its own \.squad/\ state directory. When the PR merges, the \merge=union\ driver combines decisions and histories from all branches automatically. + +![Git Worktree Lifecycle](./images/architecture-worktrees.png) + +**Worktree-local vs main-checkout strategy:** + +- **Worktree-local** (recommended) — Each worktree gets its own \.squad/\ branch-local state. When the PR merges, the \merge=union\ driver combines decisions and histories from all branches automatically. Safe for concurrent multi-agent sessions. +- **Main-checkout** — All worktrees share the main repo's \.squad/\ state on disk. Changes are immediately visible but not safe for concurrent work — use only with one active session at a time. + +**Key steps:** + +1. **Check worktree mode** — Look for \worktrees: true\ in config or \SQUAD_WORKTREES\ env var. +2. **Reuse if exists** — Before creating, run \git worktree list\ to check if worktree for this issue already exists. +3. **Create branch** — \git worktree add {path} -b squad/{issue}-{slug} {base_branch}\. +4. **Link dependencies** — Symlink \ +ode_modules\ from main repo to save build time. +5. **Multiple agents** — 2+ agents can safely work in the same worktree for the same issue. +6. **Merge state** — \.squad/\ files merge via \merge=union\ driver (append-only, no conflicts). +7. **Cleanup** — After PR merge, remove worktree and delete branch. + +
+View Mermaid source + +\\\mermaid +graph TB + subgraph TRIGGER[\"\🎯 Trigger\\"] + ISSUE[\"\Issue assigned
label: squad:agent
e.g., #42\\"] + end + + subgraph SETUP[\"\🏗️ Worktree Setup\\"] + CHECK[\"\Check worktree mode
squad.config.ts\\"] + LIST[\"\Check existing
git worktree list\\"] + EXISTS{\"\Worktree
exists?\\"} + CREATE[\"\Create worktree
git worktree add ../squad-42
-b squad/42-fix-login main\\"] + REUSE[\"\Reuse existing
worktree\\"] + LINK[\"\Link node_modules
ln -s ../squad/node_modules\\"] + end + + subgraph WORK[\"\🔧 Agent Work (Parallel)\\"] + AGENT1[\"\Agent 1
reads charter + history\\"] + AGENT2[\"\Agent 2
shares same worktree\\"] + SHARED[\"\.squad/ state
worktree-local
separate per branch\\"] + end + + subgraph COMMIT[\"\💬 Commit & Push\\"] + MODIFY[\"\Modify files
in worktree\\"] + COMMIT_MSG[\"\git commit
message with Co-authored trailer\\"] + PUSH[\"\git push origin squad/42-fix-login\\"] + end + + subgraph PR[\"\📤 PR Flow\\"] + CREATE_PR[\"\gh pr create
--base dev\\"] + REVIEW[\"\PR reviewed
agents + humans\\"] + MERGE[\"\Merge PR
to dev/main\\"] + end + + subgraph MERGE_STATE[\"\🔀 State Merge\\"] + MERGE_DECISION[\"\Merge .squad/ via
merge=union driver
(append-only)\\"] + DECISIONS_COMBINED[\"\decisions.md +
history.md combined\\"] + end + + subgraph CLEANUP[\"\🧹 Cleanup\\"] + REMOVE_WT[\"\git worktree remove
{worktree_path}\\"] + DELETE_BRANCH[\"\git branch -d
squad/42-fix-login\\"] + end + + subgraph STRATEGY[\"\Strategy Comparison\\"] + LOCAL[\"\worktree-local
(Recommended)
Each branch has own
.squad/ state
Merges via git\\"] + MAIN[\"\main-checkout
All worktrees share
main repo's .squad/
Simpler but
NOT concurrent-safe\\"] + end + + TRIGGER --> CHECK + CHECK --> LIST + LIST --> EXISTS + EXISTS -->|Yes| REUSE + EXISTS -->|No| CREATE + REUSE & CREATE --> LINK + LINK --> AGENT1 & AGENT2 + AGENT1 & AGENT2 --> SHARED + SHARED --> MODIFY + MODIFY --> COMMIT_MSG + COMMIT_MSG --> PUSH + PUSH --> CREATE_PR + CREATE_PR --> REVIEW + REVIEW --> MERGE + MERGE --> MERGE_DECISION + MERGE_DECISION --> DECISIONS_COMBINED + DECISIONS_COMBINED --> REMOVE_WT + REMOVE_WT --> DELETE_BRANCH + + DELETE_BRANCH -.-> STRATEGY + + style TRIGGER fill:#3498db + style SETUP fill:#2ecc71 + style WORK fill:#f39c12 + style COMMIT fill:#9b59b6 + style PR fill:#e74c3c + style MERGE_STATE fill:#1abc9c + style CLEANUP fill:#e67e22 + style STRATEGY fill:#34495e +\\\ + +
+ +--- + +## Tips + +- **Parallel by default** — Squad launches agents eagerly. Only switch to sequential if you have explicit dependencies or need to control costs. +- **Drop-box pattern** — Multiple agents can write decisions in parallel because each writes to a separate file in \decisions/inbox/\. +- **Memory compounds** — The more sessions you run, the smarter agents become. First session is always the least capable. +- **Commit \.squad/\** — Anyone who clones the repo gets the team with all their knowledge intact. +- **Portable teams** — Use \squad export\ and \squad import\ to move trained teams to new repositories. + +--- + +## Learn More + +- [Your Team](./your-team.md) — Understand roles, charter, and the reviewer protocol +- [Getting Started](../getting-started/first-session.md) — Run your first Squad session +- [Features](../features/) — Deep dive into Squad's capabilities diff --git a/docs/src/content/docs/concepts/images/architecture-casting.png b/docs/src/content/docs/concepts/images/architecture-casting.png new file mode 100644 index 00000000..22823c71 Binary files /dev/null and b/docs/src/content/docs/concepts/images/architecture-casting.png differ diff --git a/docs/src/content/docs/concepts/images/architecture-components.png b/docs/src/content/docs/concepts/images/architecture-components.png new file mode 100644 index 00000000..59169ac5 Binary files /dev/null and b/docs/src/content/docs/concepts/images/architecture-components.png differ diff --git a/docs/src/content/docs/concepts/images/architecture-decisions.png b/docs/src/content/docs/concepts/images/architecture-decisions.png new file mode 100644 index 00000000..0f69f8a3 Binary files /dev/null and b/docs/src/content/docs/concepts/images/architecture-decisions.png differ diff --git a/docs/src/content/docs/concepts/images/architecture-parallel-execution.png b/docs/src/content/docs/concepts/images/architecture-parallel-execution.png new file mode 100644 index 00000000..adcd5e7a Binary files /dev/null and b/docs/src/content/docs/concepts/images/architecture-parallel-execution.png differ diff --git a/docs/src/content/docs/concepts/images/architecture-state-management.png b/docs/src/content/docs/concepts/images/architecture-state-management.png new file mode 100644 index 00000000..6ae2fec5 Binary files /dev/null and b/docs/src/content/docs/concepts/images/architecture-state-management.png differ diff --git a/docs/src/content/docs/concepts/images/architecture-user-flow.png b/docs/src/content/docs/concepts/images/architecture-user-flow.png new file mode 100644 index 00000000..ce7d0909 Binary files /dev/null and b/docs/src/content/docs/concepts/images/architecture-user-flow.png differ diff --git a/docs/src/content/docs/concepts/images/architecture-worktrees.png b/docs/src/content/docs/concepts/images/architecture-worktrees.png new file mode 100644 index 00000000..7af8feda Binary files /dev/null and b/docs/src/content/docs/concepts/images/architecture-worktrees.png differ diff --git a/docs/src/content/docs/sample-prompts.md b/docs/src/content/docs/sample-prompts.md deleted file mode 100644 index b3a73fee..00000000 --- a/docs/src/content/docs/sample-prompts.md +++ /dev/null @@ -1,412 +0,0 @@ -# Sample Prompts - -Ready-to-use prompts for Squad. Copy any prompt, open Copilot, select **Squad**, and paste it in. - ---- - -## Quick Builds - -Small projects that ship in a single session. Good for parallel fan-out and fast iteration. - ---- - -### 1. CLI Pomodoro Timer - -``` -I'm building a cross-platform CLI pomodoro timer in Python: -- Configurable work/break intervals (25/5/15 defaults) -- Persistent stats tracker (local JSON) -- Desktop notifications (macOS, Windows, Linux) -- Focus mode: blocks domains via /etc/hosts (with undo) -- --report flag for weekly stats table - -Set up the team. I want this done fast — everyone works at once. -``` - -**What it demonstrates:** -- Parallel fan-out on a small, well-scoped project -- Backend handles timer logic while systems agent tackles cross-platform notifications -- Tester writes test cases from spec while implementation is in flight - ---- - -### 2. Markdown Static Site Generator - -``` -Zero-dependency static site generator in Node.js: markdown→HTML with built-in template, generates index page, outputs to dist/. Support front matter (title, date, tags), tag index pages, RSS feed. No frameworks — just fs, path, and a custom markdown parser. - -Set up the team and start building. -``` - -**What it demonstrates:** -- Agents own distinct pipeline components (parser, template engine, RSS, file I/O) -- Tester writes test cases from spec while others build in parallel -- Front matter format decisions propagate via decisions.md - ---- - -### 3. Retro Snake Game - -``` -Browser Snake game (vanilla HTML/CSS/JS, no frameworks): -- Canvas rendering at 60fps -- Arrow keys and WASD controls -- Score tracking with localStorage high scores -- Progressive speed increase every 5 points -- Retro CRT-style CSS filters -- Mobile: touch swipe controls -- Sound effects via Web Audio API - -Start building — I want to play in 20 minutes. -``` - -**What it demonstrates:** -- Frontend, audio, and input handling built in parallel -- Tester writes Playwright tests while game is under construction -- Fast iteration with visible progress across agents - ---- - -### 4. Turn-by-Turn Text Adventure Engine - -``` -Text-based adventure engine in TypeScript: -- Load worlds from JSON (rooms, items, NPCs, transitions) -- Command parser: go [dir], look, take [item], use [item] on [target], talk to [npc], inventory -- Sample adventure: 10 rooms, 5 items, 3 NPCs, 2 puzzles -- Save/load game state to JSON -- Terminal via Node.js with colored output (chalk) -- Narrator voice: descriptions vary by inventory/actions - -Build engine and sample adventure simultaneously. Content writer and engine builder work in parallel. -``` - -**What it demonstrates:** -- Natural split between engine logic and content creation -- Both streams run fully in parallel with shared data format decisions -- Tester writes test cases from spec before implementation completes - ---- - -### 5. Arcane Duel — A Card Battle Game - -``` -Strategic card duel game (browser, inspired by MTG): -- 30+ cards across 4 types: Attack, Defense, Spell, Trap (with mana cost, power, toughness, effects) -- Turn phases: Draw → Main → Combat → End -- Mana system: +1 per turn (max 10), some cards generate bonus mana -- Stack-based spell resolution -- HP: 20 each, win at 0 -- AI opponent with basic strategy -- HTML/CSS grid battlefield showing fields, hands, graveyards -- Card hover preview - -One agent designs cards/balance, another builds engine/rules, another builds UI, tester validates combat math. Go. -``` - -**What it demonstrates:** -- Deep parallelism requiring early data format alignment via decisions.md -- UI scaffolding proceeds while card design is underway -- Scribe's decision propagation becomes critical (mana curve affects engine and AI) - ---- - -### Squad Blog Engine (Meta Demo) - -``` -Static blog engine rendering markdown posts to HTML (no frameworks): - -Input: docs/blog/ markdown with YAML frontmatter (title, date, author, wave, tags, status, hero). - -Output: -- Index page: posts sorted by date, with title/hero/author/tags -- Post pages: clean typography, syntax-highlighted code, responsive tables -- Tag index grouping posts by tag -- Wave navigation: ← Previous | Next → links -- Dark mode toggle (CSS custom properties, localStorage) -- RSS feed (feed.xml) - -Design: Clean, modern, developer-focused. Monospace headings, proportional body. Dark code blocks with copy button. Mobile responsive. Fast — no JS for reading (JS only for dark mode and copy). - -Build parser, template engine, RSS generator, static output (dist/). Include `node build.js` script. Set up team and build in one session. -``` - -**What it demonstrates:** -- Meta-demo where Squad builds its own publishing tool -- All components (parser, templating, RSS, CSS) build in parallel -- Finished product is visual, functional, and self-documenting - ---- - -## Mid-Size Projects - -Real coordination needed. Agents make architectural decisions, share them, and build across multiple rounds. - ---- - -### 6. Cloud-Native E-Commerce Store - -``` -Build an event-driven e-commerce store: -- Product Catalog API (Node.js/Express, PostgreSQL) — CRUD + search -- Order Service (Node.js) — async processing via message queue, payment stubs, events -- Notification Service — listens for order events, emails confirmations -- API Gateway — auth (JWT), rate limiting -- RabbitMQ or in-memory stub for local dev -- React SPA: product grid, cart, checkout - -Each service with its own Dockerfile. Include docker-compose.yml. Orders return 202 Accepted, status polled/pushed via WebSocket. - -Set up a team. One agent per service. Coordinate on API contracts and event schemas early, then build in parallel. -``` - -**What it demonstrates:** -- True microservice parallelism with contract-first coordination -- Event schema decisions must propagate early via Scribe -- API gateway scaffolds while downstream services build independently - ---- - -### 7. Playwright-Tested Dashboard App - -``` -Build a project management dashboard (React + TypeScript, Node.js/Express): -- Kanban board with drag-and-drop (Backlog, In Progress, Review, Done) -- Task creation: title, description, assignee, priority, due date -- Filtering by assignee, priority, status -- Real-time updates via WebSocket -- User auth: login/signup (JWT, bcrypt) -- SQLite + Drizzle ORM - -Full Playwright test suite covering login, CRUD, drag-and-drop, filtering, real-time sync (two browser contexts). Write Gherkin feature files FIRST, then implement Playwright step definitions. Runnable with `npx playwright test`. - -Set up the team. Write Gherkin specs and test skeletons before implementation starts, update as UI takes shape. -``` - -**What it demonstrates:** -- Test-first development with Gherkin specs written before implementation -- Frontend and backend build in parallel while tests scaffold -- Anticipatory work pattern: tests and implementation converge without blocking - ---- - -### 8. GitHub Copilot Extension - -``` -Build a GitHub Copilot Chat extension (Copilot Extensions SDK): -- Act as @code-reviewer agent -- Accept GitHub repo URL or PR number -- Fetch diff via GitHub API, analyze for security (SQL injection, XSS, secrets), performance (N+1 queries), style violations (configurable .code-reviewer.yml) -- Return structured feedback with file-level annotations -- Blackbeard-style SSE streaming response -- Deploy as Vercel serverless function -- Include GitHub App manifest - -Read SDK docs carefully. One agent owns SDK integration/streaming, another owns analysis engine, another owns GitHub API. Set up the team. -``` - -**What it demonstrates:** -- Agents read external SDK docs and build to prescribed patterns -- SDK integration and analysis engine work in parallel with shared interface contract -- Real-world API integration with deployment considerations - ---- - -### 9. .NET Aspire Cloud-Native App - -``` -Build a cloud-native app with .NET Aspire (read https://learn.microsoft.com/en-us/dotnet/aspire/): -- AppHost orchestrating all services -- Blazor Server dashboard: current conditions + 5-day forecast for saved cities -- Weather API service: wraps OpenWeatherMap with Redis caching -- User Preferences service: stores cities (PostgreSQL) -- Background Worker: refreshes cache every 15 minutes -- Service discovery via Aspire (no hardcoded URLs) -- Health checks and OpenTelemetry tracing - -Team organized by Aspire integration: AppHost/discovery, Redis caching, PostgreSQL, Blazor frontend, background worker. Tester validates service discovery and end-to-end data flow. Set up the team. -``` - -**What it demonstrates:** -- Agents specialized by infrastructure component rather than traditional roles -- AppHost coordinates wiring while service agents build independently -- Infrastructure decisions (service names, connection strings) propagate via decisions.md - ---- - -## Large Projects - -Complex coordination, memory, and team size. Multiple rounds, cross-cutting decisions, agents remember earlier work. - ---- - -### 10. Legacy .NET-to-Azure Migration - -``` -Migrate legacy .NET Framework to Azure. Clone: -1. https://github.com/bradygaster/ProductCatalogApp — ASP.NET MVC with WCF SOAP, in-memory repo, MSMQ orders -2. https://github.com/bradygaster/IncomingOrderProcessor — Windows Service monitoring MSMQ - -Target: -- ProductCatalogApp → ASP.NET Core/.NET 10 or Blazor on App Service. WCF→REST API, MSMQ→Service Bus -- IncomingOrderProcessor → Azure Functions with Service Bus trigger -- Shared models → .NET 10 class library -- Infrastructure: Bicep for App Service, Function App, Service Bus -- CI/CD: GitHub Actions -- Local dev: docker-compose or Aspire - -Preserve all business logic. SOAP→REST with same data structures, MSMQ→Service Bus compatible format. - -Team: web app migration, WCF-to-API, Windows Service-to-Functions, shared models, Azure infrastructure, CI/CD, tester. Start with migration plan. -``` - -**What it demonstrates:** -- Realistic enterprise migration from legacy .NET Framework to modern Azure -- Agents analyze unfamiliar code and translate to Azure-native patterns -- Business logic preservation while modernizing infrastructure (WCF→REST, MSMQ→Service Bus) - ---- - -### 11. Multiplayer Space Trading Game - -``` -Build multiplayer space trading game (browser-based): -- Galaxy: 50+ procedural star systems with stations, trade routes -- Economy: dynamic commodity prices (fuel, ore, food, tech, luxuries) driven by supply/demand -- Ships: 3 tiers with cargo capacity, fuel range, hull strength -- Trading: buy low, sell high. Prices shift with player activity and events -- Combat: turn-based encounters with pirates/players -- Multiplayer: WebSocket real-time. Players see each other, chat, PvP opt-in -- Persistence: PostgreSQL (credits, cargo, location, ship) -- Frontend: Canvas galaxy map, HTML/CSS panels for station/trading/inventory - -Tech: Node.js, PostgreSQL, WebSocket, vanilla HTML/CSS/Canvas. - -One agent per system: economy/trading, galaxy generator/map, combat, multiplayer/networking, frontend UI, tester. Economy and galaxy work simultaneously — agree on star system data format early. Go. -``` - -**What it demonstrates:** -- Complex game with 6+ agents owning distinct but interoperating systems -- Data format decisions shared early and respected across all agents -- Economy and galaxy agents work in parallel from turn 1 - ---- - -### 12. AI Recipe App with Image Recognition - -``` -Build recipe app with image recognition (React Native Expo, Python FastAPI, SQLite): -- Camera: photograph ingredients -- Image analysis: GPT-4 Vision to identify ingredients -- Recipe matching: match against database (50+ recipes) -- Recipe display: ingredients (have vs. need), instructions, time -- Favorites: save, rate, notes -- Shopping list: auto-generate missing ingredients -- Dietary filters: vegetarian, vegan, gluten-free, dairy-free - -One agent: React Native frontend. One: FastAPI backend + DB. One: vision/AI integration. One: recipe curation/seed data. Tester: API tests with mocked vision responses. Set up team. -``` - -**What it demonstrates:** -- Cross-platform mobile + backend + AI integration in one project -- Recipe curator and AI integration agent work simultaneously with shared taxonomy -- Tester mocks vision API responses for deterministic testing before real integration - ---- - -### 13. DevOps Pipeline Builder - -``` -Build self-service DevOps platform (React, Go, PostgreSQL, Docker): -- Pipeline designer: drag-and-drop UI composing stages (build, test, deploy, notify) -- Stage templates: npm build, Docker build, Helm deploy, Slack notify -- Pipeline execution: stages run as Docker containers (Go orchestration) -- Live logs: stream to browser via SSE -- Pipeline-as-code: export/import YAML (GitHub Actions compatible) -- Secrets management: encrypted storage -- Execution history: searchable logs with status, duration, artifacts - -Team: frontend (drag-and-drop), backend (execution engine), Docker/infrastructure, security (secrets), tester. Set up team. -``` - -**What it demonstrates:** -- Agents with diverse expertise (UI, containers, cryptography) on one product -- Execution engine and pipeline designer build in parallel with shared data model -- Security agent works independently on secrets encryption - ---- - -### 14. Roguelike Dungeon Crawler - -``` -Build browser-based roguelike dungeon crawler: -- Dungeons: procedural rooms/corridors (BSP or cellular automata), 10 floors, scaling difficulty -- Character: warrior/mage/rogue with unique abilities (3 each), health/mana/stamina -- Combat: turn-based, grid-positioned. Enemy AI flanks, retreats at low HP -- Items: weapons, armor, potions, scrolls. Random loot tables. Unidentified items until used -- Fog of war: tile-based visibility with raycasting -- Rendering: Canvas with tilemap (16x16 or 32x32 colored squares) -- Permadeath: high score table with name, class, floor, cause of death -- Save: save-on-exit only (LocalStorage) - -One agent per: dungeon gen, combat + AI, items + loot, rendering + fog of war, tester. All build simultaneously with shared tile/entity data model. Start building. -``` - -**What it demonstrates:** -- Four independently buildable systems converging on shared data model -- Early data model decision via decisions.md enables full parallelism -- Tester validates game math from specs while systems are under construction - ---- - -### 15. Real-Time Collaborative Whiteboard - -``` -Build real-time collaborative whiteboard using React Flow (React + TypeScript, Node.js, WebSocket): -- Built on React Flow (https://reactflow.dev/) -- Shapes: rectangles, circles, text, sticky notes, arrows/edges -- Drag-and-drop from palette, reposition, resize (handles) -- Color picker, stroke width, fill/background per shape -- Multi-select (bounding box), group operations -- Real-time sync: cursor + edits via WebSocket -- Rooms: shareable URL -- Undo/redo per user -- Export: PNG and SVG -- Persistence: PostgreSQL (nodes, edges, viewport), auto-save every 30s - -Frontend agent: React Flow + drag-and-drop. Networking: WebSocket sync + conflict resolution. Backend: rooms + persistence. Tester: Playwright multi-user drag-and-drop tests. Set up team. -``` - -**What it demonstrates:** -- Networking and frontend agents coordinate closely on React Flow data model -- Frontend leverages React Flow's built-in features while networking syncs across users -- Tester writes multi-context Playwright tests for real-time sync validation - ---- - -### 16. Multiplayer Dice Roller — Bar Games PWA - -``` -Build mobile-first PWA dice roller (React + TypeScript, Three.js/React Three Fiber, Node.js + WebSocket, PostgreSQL): -- Mobile-first responsive, PWA installable, works offline -- Double-tap to roll: realistic 3D dice with physics (Three.js) -- Customizable: 1-10 dice, die types (d6, d10, d12, d20), colors -- Multiplayer: rooms with 6-digit code or QR, real-time roll sync, chat -- Game modes: Freeroll, Yahtzee (auto-scoring), Liar's Dice, custom rules -- Score history: roll log, replay animations, export JSON -- Sound effects, haptic feedback, night mode - -One agent: 3D dice/physics. One: PWA/gesture handling. One: multiplayer backend (rooms, WebSocket, scores). One: game logic. Tester: mobile Playwright for touch + multiplayer. Set up team. -``` - -**What it demonstrates:** -- Mobile-first project with agents specialized by concern (3D, touch, networking, logic) -- 3D and gesture agents coordinate on tap-to-roll triggers and animation states -- PWA requirements and mobile testing showcase production mobile app concerns - ---- - -## Advanced Features - -For detailed guidance on advanced features like export/import, GitHub Issues integration, ceremonies, PRD mode, human team members, and skills, see [Tips and Tricks](tips-and-tricks.md). - diff --git a/docs/src/content/docs/tour-github-issues.md b/docs/src/content/docs/tour-github-issues.md deleted file mode 100644 index aff55a70..00000000 --- a/docs/src/content/docs/tour-github-issues.md +++ /dev/null @@ -1,199 +0,0 @@ -# GitHub Issues Walkthrough - -A step-by-step tour of Squad's GitHub Issues workflow. This connects your team to a real repository's issue tracker so agents can pick up issues, create branches, open PRs, and handle review feedback. - -**Prerequisite:** The `gh` CLI must be installed and authenticated (`gh auth login`). - ---- - -## 1. Connect to a Repository - -Tell Squad which repo to track: - -``` -> Connect to myorg/recipe-app -``` - -Squad stores the issue source in team state: - -``` -✅ Issue source stored: myorg/recipe-app - Using gh CLI for issue tracking. -``` - -From now on, Squad can read issues from that repo and create branches and PRs against it. - ---- - -## 2. View the Backlog - -Ask to see open issues: - -``` -> Show the backlog -``` - -Squad pulls open issues via `gh` and displays them: - -``` -┌─────┬──────────────────────────────────────────┬───────────┬────────────┐ -│ # │ Title │ Labels │ Assignee │ -├─────┼──────────────────────────────────────────┼───────────┼────────────┤ -│ 12 │ Add ingredient search │ feature │ — │ -│ 15 │ Fix pagination on recipe list │ bug │ — │ -│ 18 │ Add user profile page │ feature │ — │ -│ 21 │ Rate limiting on API endpoints │ security │ — │ -│ 23 │ Mobile responsive layout │ ui │ — │ -└─────┴──────────────────────────────────────────┴───────────┴────────────┘ -5 open issues -``` - ---- - -## 3. Work on an Issue - -Pick an issue for an agent to work on: - -``` -> Work on #12 -``` - -Squad reads the issue details, routes it to the right agent, and kicks off the workflow: - -``` -🔧 Dallas — picking up #12 (Add ingredient search) - -Dallas is reading the issue and starting work. -``` - -Behind the scenes, the agent: - -1. **Creates a branch** — named descriptively based on the issue (e.g., `12-add-ingredient-search`) -2. **Does the implementation work** — writes code, tests, whatever the issue requires -3. **Opens a PR** — linked back to issue #12, with a description of what was done - -When the agent finishes: - -``` -🔧 Dallas — Completed #12 (Add ingredient search) - Branch: 12-add-ingredient-search - PR: #24 opened — "Add ingredient search (#12)" - Files changed: - - src/routes/recipes.ts (added search endpoint) - - src/models/recipe.ts (added text index) - - test/search.test.ts (6 test cases) -``` - ---- - -## 4. Multiple Issues in Parallel - -You can assign multiple issues at once: - -``` -> Work on #15 and #23 -``` - -``` -🔧 Dallas — picking up #15 (Fix pagination on recipe list) -⚛️ Ripley — picking up #23 (Mobile responsive layout) -📋 Scribe — logging session -``` - -Each agent creates its own branch and works independently. If your repo supports worktrees, Squad can work on multiple branches simultaneously. - ---- - -## 5. Handle Review Feedback - -After a PR is open, reviewers may leave comments. When you see feedback: - -``` -> There's review feedback on PR #24 -``` - -Squad routes the review to the agent who opened the PR: - -``` -🔧 Dallas — reading review comments on PR #24 - -Dallas is addressing the feedback now. -``` - -The agent reads the review comments, makes the requested changes, and pushes new commits to the same branch: - -``` -🔧 Dallas — Addressed review feedback on PR #24 - - Added input sanitization for search query (reviewer concern) - - Added test case for SQL injection attempt - - Pushed 2 new commits to 12-add-ingredient-search -``` - ---- - -## 6. Merge Completed Work - -When the PR is approved and ready: - -``` -> Merge PR #24 -``` - -``` -✅ PR #24 merged — "Add ingredient search (#12)" - Issue #12 closed. - Branch 12-add-ingredient-search deleted. -``` - -The issue is closed automatically when the PR merges (if the PR body includes `Closes #12`). - ---- - -## 7. Check Remaining Work - -After merging, see what's left: - -``` -> What's left? -``` - -Squad refreshes the backlog: - -``` -┌─────┬──────────────────────────────────────────┬───────────┬────────────┐ -│ # │ Title │ Labels │ Assignee │ -├─────┼──────────────────────────────────────────┼───────────┼────────────┤ -│ 15 │ Fix pagination on recipe list │ bug │ Dallas │ -│ 18 │ Add user profile page │ feature │ — │ -│ 21 │ Rate limiting on API endpoints │ security │ — │ -│ 23 │ Mobile responsive layout │ ui │ Ripley │ -└─────┴──────────────────────────────────────────┴───────────┴────────────┘ -4 open issues (2 in progress) -``` - ---- - -## Full Workflow at a Glance - -``` -Connect → "connect to myorg/recipe-app" -Browse → "show the backlog" -Assign → "work on #12" - └─ Agent creates branch, implements, opens PR -Review → "there's review feedback on PR #24" - └─ Agent reads comments, pushes fixes -Merge → "merge PR #24" - └─ PR merged, issue closed -Status → "what's left?" - └─ Updated backlog -``` - ---- - -## Tips - -- **You don't pick the agent.** Squad routes the issue to the agent whose expertise matches the issue's domain. A bug in the API goes to the backend agent. A UI issue goes to the frontend agent. -- **Agents name branches sensibly.** Branch names include the issue number and a slugified title, so they're easy to find in `git branch`. -- **PRs link to issues.** The PR description includes a `Closes #N` reference so merging automatically closes the issue. -- **Review feedback is incremental.** When you tell Squad about review feedback, the agent pushes new commits to the existing branch — no force-pushes, no new PRs. -- **Check `decisions.md` after issue work.** Agents often record decisions while working on issues (e.g., "chose cursor pagination" or "added text index for search"). These decisions carry forward to future issues.