docs: Add building extensions guide

.copilot/mcp-config.json

@@ -1,15 +1,16 @@
 {
   "mcpServers": {
-    "EXAMPLE-trello": {
+    "azure-devops": {
       "command": "npx",
       "args": [
         "-y",
-        "@trello/mcp-server"
-      ],
-      "env": {
-        "TRELLO_API_KEY": "${TRELLO_API_KEY}",
-        "TRELLO_TOKEN": "${TRELLO_TOKEN}"
-      }
+        "@azure-devops/mcp",
+        "msft-skilling"
+      ]
+    },
+    "powerbi-remote": {
+      "type": "http",
+      "url": "https://api.fabric.microsoft.com/v1/mcp/powerbi"
     }
   }
-}
+}

.squad/agents/eecom/history.md

@@ -80,3 +80,11 @@ CLI completeness audit (2026-03-08) confirmed: 26 primary commands routed in cli
 
 **PR:** #417 opened targeting dev.
 
+### PR Review Pattern — Description vs Diff Mismatch (2026-03-16)
+
+**Pattern:** Always verify PR body/title matches actual diff content before reviewing. Use `gh pr diff` + `gh api repos/{owner}/{repo}/pulls/{number}/files` to get file list, then cross-reference with PR description.
+
+**Learned from:** PR #434 review — body described "Agent-inclusive SDLC paper (~3,800 words)" but actual diff contained PAO external comms infrastructure (skills, templates, SQL schema). Branch name was `squad/agent-sdlc-paper` but no paper file in diff. Posted ⚠️ Needs Clarity review requesting alignment.
+
+**Review efficiency:** For docs PRs, check line count (`+394` lines) against "small, strategic" preference. PR #435 (agent on-disk anatomy) at 394 lines was borderline but justified for foundational concept doc. Flag verbosity concerns explicitly in review.
+

.squad/agents/flight/history.md

@@ -25,3 +25,9 @@ Zero code changes. Skill files in templates/skills/, scripts in scripts/mesh/, d
 ### Sprint Prioritization Pattern
 Rank by: (1) bugs with active user impact, (2) quality/test gaps blocking GA, (3) high-ROI features unblocking downstream work. Interleave stability (bugs/quality) with velocity (features) across sprint capacity.
 
+### Agent On-Disk Anatomy Documentation
+Developer concept doc clarifying the distributed identity model: runtime state (`.squad/agents/{name}/`), SDK infrastructure (`packages/squad-sdk/src/agents/`), and optional config overrides. Charter is DNA (parsed into agent prompt), history is append-only learnings, casting adds memorable names. Three conditions for active agent: charter.md exists, roster entry in team.md, routing rules. Alumni pattern preserves retired agents in `_alumni/`. Context flows via explicit artifacts (team.md, routing.md, decisions.md), not shared memory. SDK is generic runtime — all agent specificity lives in `.squad/`.
+
+### PR Review Patterns (2026-03-16)
+**Scope discipline:** Apply "Squad Ships It" test rigorously — reject PRs mixing runtime code with IRL content (knowledge library, book material). **Verbosity threshold for docs:** Brady prefers small, strategic changes. Flag docs PRs >400-500 lines as "too verbose" — compress examples, remove redundancy, target 50-60% reduction. **Cross-branch pollution:** Watch for history files with 900+ lines from unrelated branches (Fenster history in a PAO PR = rebase artifact). **Worktree artifacts:** `.worktrees/` submodule commits are pollution, not features — flag for removal. **Infrastructure vs features:** Large infra PRs (PAO comms with templates, tests, audit) are appropriate if they establish new capabilities with proper gates.
+

.squad/agents/pao/history.md

@@ -29,3 +29,6 @@ External tool integrations require explicit "where to get it" guidance. Placehol
 ### Cross-Org Authentication Docs
 Problem/solution structure for multi-account auth: gh auth switch, Copilot instructions, Squad skill pattern. Cover credential helpers, EMU variations, common error messages. Cross-reference in troubleshooting and enterprise-platforms pages.
 
+### Extensibility Guide Three-Layer Model
+Created comprehensive extensibility guide showing users WHERE their change idea belongs. Three layers: Squad Core (coordinator/protocol), Squad Extension (marketplace plugins), Team Configuration (.squad/ files). Decision tree helps self-sorting. Used Claire's RFC #328 as worked example — sophisticated client-delivery workflow maps entirely to existing primitives (skills + ceremonies + directives) without core changes. Key principle: Squad core stays small. Most ideas are composition, not coordinator changes. Doc includes escalation signals, plugin build guide, concrete examples for each layer.
+

.squad/decisions/inbox/pao-extensibility-guide.md

@@ -0,0 +1,60 @@
+# Decision: Three-layer extensibility model
+
+**Date:** 2026-03-16  
+**Author:** PAO  
+**Context:** Claire's RFC #328 revealed users need guidance on WHERE their change ideas belong.
+
+## The model
+
+Squad uses a three-layer extensibility model:
+
+1. **Squad Core** — Coordinator behavior, routing, reviewer protocol, eager execution
+   - Changed by: Squad maintainers only
+   - Distributed via: npm releases
+
+2. **Squad Extension** — Reusable patterns (skills, ceremonies, workflows)
+   - Created by: Plugin authors
+   - Distributed via: Marketplace plugins
+
+3. **Team Configuration** — Decisions unique to THIS team
+   - Changed by: The team itself
+   - Lives in: `.squad/` files per-repo
+
+## Key principle
+
+**Squad core stays small. Most ideas are skills, ceremonies, or directives.**
+
+## Decision tree
+
+When someone has a change idea:
+- Does it change HOW the coordinator routes work, spawns agents, or enforces core protocols? → Layer 1 (Core)
+- Could OTHER teams benefit from this pattern? → Layer 2 (Extension/plugin)
+- Is this unique to THIS team's process? → Layer 3 (Team config)
+
+## The Claire test
+
+Claire's RFC #328 proposed a sophisticated client-delivery workflow with discovery interviews, research sprints, and multi-round review. It FELT like a core feature.
+
+**Realization:** It maps entirely to existing primitives:
+- Skills: `discovery-interview`, `research-sprint`, `evidence-bundler`
+- Ceremonies: `plan-review`, `implementation-review`
+- Directives: Multi-round review policy
+
+No core changes needed. It's a Layer 2 plugin.
+
+## Escalation signals
+
+You likely need a core change if:
+- You need a new coordinator mode
+- You need to change routing logic
+- You need to change reviewer protocol
+- You need global enforcement rules
+- Your skill needs coordinator state data
+
+## Documentation
+
+Comprehensive guide at `docs/guide/extensibility.md` with decision tree, examples, plugin build instructions.
+
+## Applies to
+
+All team members, contributors, and users proposing changes.

docs/src/content/docs/guide/building-extensions.md

@@ -0,0 +1,126 @@
+# Building extensions
+
+> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases.
+
+You've decided your idea is a Squad Extension (Layer 2). Now build one in five minutes.
+
+---
+
+## What is an extension?
+
+An extension is a reusable collection of skills, ceremonies, and directives that any team can install. It lives outside Squad core, packaged as a GitHub repository or marketplace plugin. Extensions let you codify workflows (Claire's client-delivery pattern), domain expertise (Azure deployment strategies), or testing ceremonies that other teams benefit from.
+
+---
+
+## Extension structure
+
+```
+my-extension/
+├── skills/
+│   ├── SKILL1.md
+│   └── SKILL2.md
+├── ceremonies/
+│   └── CEREMONY.md
+├── directives/
+│   └── DIRECTIVE.md
+└── README.md
+```
+
+---
+
+## Build one
+
+**Step 1: Create a repo**
+
+```bash
+mkdir my-extension
+cd my-extension
+git init
+```
+
+**Step 2: Add a skill**
+
+Create `skills/example-skill.md`:
+
+```markdown
+# Example Skill
+
+**When to use:** You need to do X.
+
+## Context
+
+Brief problem statement.
+
+## Steps
+
+1. Do the first thing
+2. Do the second thing
+3. Done
+```
+
+**Step 3 (optional): Add a ceremony**
+
+Create `ceremonies/code-review.md` following Squad ceremony format (decision gate, verdicts, escalation).
+
+**Step 4: Write the README**
+
+Explain the problem, installation, and usage:
+
+```markdown
+# My Extension
+
+Codifies client-delivery workflows for consulting teams.
+
+## Install
+
+squad plugin install github/my-org/my-extension
+
+## What's Inside
+
+- **discovery-interview** skill — clarify requirements
+- **evidence-bundler** skill — collect test results
+- **plan-review** ceremony — gate for approval
+```
+
+**Step 5: Test locally**
+
+Copy your extension directory into `.squad/skills/`, `.squad/ceremonies/`, and `.squad/directives/`. Load your Squad session and verify the skills appear and work as expected.
+
+---
+
+## Share it
+
+Push to GitHub:
+
+```bash
+git add .
+git commit -m "Initial extension: my-extension"
+git push
+```
+
+Register with a marketplace or pin directly by repository URL:
+
+```
+squad plugin install github/my-org/my-extension
+```
+
+---
+
+## Real examples
+
+- **Claire's client-delivery workflow** ([RFC #328](https://github.com/bradygaster/squad/issues/328)) — discovery, research, multi-round review with evidence gates
+- **Azure infrastructure patterns** — VM provisioning, Cosmos DB design, monitoring rules
+- **Knowledge library skills** — document structured analysis, reference synthesis
+
+---
+
+## Related docs
+
+- [Extensibility guide](./extensibility.md#decision-tree) — Where does your idea belong? (decision tree)
+- [Plugin Marketplace](../features/plugins.md) — How teams discover and install your extension
+- [Skills](../concepts/skills.md) — How to author reusable skills
+- [Ceremonies](../concepts/ceremonies.md) — How to define decision gates and review rituals
+
+---
+
+**Ready to share?** [Open a discussion](https://github.com/bradygaster/squad/discussions) in the Squad community.

docs/src/content/docs/guide/extensibility.md

@@ -0,0 +1,141 @@
+# Extensibility guide
+
+> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases.
+
+Where does your change idea belong? Squad core, marketplace plugin, or team config?
+
+**Key principle:** Squad core stays small. Most ideas are skills, ceremonies, or directives.
+
+---
+
+## The three layers
+
+| Layer | What lives here | Who changes it | Distribution |
+|-------|----------------|----------------|--------------|
+| **Squad Core** | Coordinator behavior, routing logic, reviewer protocol | Squad maintainers only | npm releases |
+| **Squad Extension** | Reusable patterns (skills, ceremonies, workflows) | Plugin authors | Marketplace plugins |
+| **Team Configuration** | Decisions unique to THIS team | The team itself | `.squad/` files |
+
+---
+
+## Decision tree
+
+```
+┌─ Does it change HOW the coordinator routes, spawns, or enforces?
+│
+├─ YES → Squad Core
+│  └─ Examples: New coordinator modes, reviewer protocol changes
+│     Action: Open an RFC issue
+│
+└─ NO → Continue...
+   │
+   ┌─ Could OTHER teams benefit?
+   │
+   ├─ YES → Squad Extension (plugin)
+   │  └─ Examples: Client-delivery workflow, Azure skills, TDD ceremonies
+   │     Action: Build a plugin
+   │
+   └─ NO → Team Configuration
+      └─ Examples: YOUR git workflow, YOUR build process, YOUR routing rules
+         Action: Update `.squad/` files
+```
+
+**Heuristic:** "Squad should..." → check if it's really "My team should..." or "Teams using X should...".
+
+
+
+---
+
+## Worked example: Claire's RFC
+
+[Claire's RFC #328](https://github.com/bradygaster/squad/issues/328) proposed a sophisticated client-delivery workflow: discovery interviews, research sprints, multi-round review with `SHIP`/`NEEDS_WORK`/`BLOCKED` verdicts, evidence bundles.
+
+**The realization:** It maps entirely to existing Squad primitives. No core changes needed.
+
+**Where it belongs:** Layer 2 (Squad Extension)
+
+Claire's workflow is a reusable pattern any team could adopt — perfect as a marketplace plugin.
+
+**Plugin structure:**
+```
+client-delivery-workflow/
+├── skills/
+│   ├── discovery-interview/      # Clarify requests, extract requirements
+│   ├── research-sprint/           # Propose directions, score options
+│   └── evidence-bundler/          # Collect test results, logs, screenshots
+├── ceremonies/
+│   ├── plan-review.md             # Gate: approve before implementation
+│   └── implementation-review.md   # Gate: verify evidence
+└── directives/
+    └── multi-round-review.md      # Policy: 2 NEEDS_WORK rounds max
+```
+
+**Usage:**
+```bash
+squad plugin install github/awesome-copilot/client-delivery-workflow
+```
+
+**Lesson:** Most sophisticated workflows are compositions of primitives, not core features.
+
+---
+
+## When to escalate to core
+
+You likely need a core change if:
+
+- **New coordinator mode** — Example: `validate` mode that runs checks before `assign`
+- **Routing logic change** — Example: Route based on agent workload, not labels
+- **Reviewer protocol change** — Example: Conditional approvals ("approved if tests pass")
+- **Global enforcement rule** — Example: Block merges if evidence missing
+- **Skill needs coordinator data** — Example: Access to agent spawn history
+
+You DON'T need core if:
+
+- **Workflow pattern** → Build a plugin (skills + ceremonies)
+- **Domain expertise** → Write a skill
+- **Team process** → Add a ceremony to `.squad/ceremonies.md`
+- **Reusable templates** → Build a plugin
+- **Configuring existing behavior** → Update `.squad/routing.md`
+
+---
+
+## Quick start: Building a plugin
+
+1. Create a GitHub repo with `skills/`, `ceremonies/`, `directives/` directories
+2. Add skills as `SKILL.md` files (frontmatter + context + steps)
+3. Add ceremonies following Squad ceremony format
+4. Write a README explaining problem/install/usage
+5. Submit to marketplace (e.g., `github/awesome-copilot`)
+
+**Installation:**
+```bash
+squad plugin marketplace add github/awesome-copilot
+squad plugin install github/awesome-copilot/your-plugin
+```
+
+**See [Plugin Marketplace docs](./../concepts/plugin-marketplace.md) for details.**
+
+---
+
+## Summary
+
+1. **Start with the decision tree** — Most ideas are Layer 2 or 3
+2. **Default to team config** — Unique to your team? → `.squad/`
+3. **Build a plugin if reusable** — Other teams benefit? → Package and share
+4. **Escalate to core rarely** — Need coordinator/routing changes? → Open an RFC
+
+**When in doubt:** Start with team config. Copy-pasting to other teams? Promote to plugin. Plugins repeatedly hitting limits? Signal for core change.
+
+---
+
+## Related documentation
+
+- [Plugin Marketplace](./../concepts/plugin-marketplace.md) — How to browse, install, and share plugins
+- [Skills](./../concepts/skills.md) — How to write skills for your team or plugins
+- [Ceremonies](./../concepts/ceremonies.md) — How to define team meetings and gates
+- [Routing](./../concepts/routing.md) — How to configure work assignment rules
+- [Contributing](./contributing.md) — How to propose changes to Squad core
+
+---
+
+**Questions?** [Open an issue](https://github.com/bradygaster/squad/issues/new) or join the discussion in the Squad community.

test/docs-build.test.ts

@@ -17,7 +17,7 @@ const DIST_DIR = join(DOCS_DIR, 'dist');
 // Expected content directories in src/content/docs/
 const EXPECTED_GET_STARTED = ['choose-your-interface', 'first-session', 'installation', 'migration'];
 
-const EXPECTED_GUIDES = ['tips-and-tricks', 'sample-prompts', 'personal-squad', 'contributing', 'contributors', 'shell', 'faq'];
+const EXPECTED_GUIDES = ['tips-and-tricks', 'sample-prompts', 'personal-squad', 'contributing', 'contributors', 'shell', 'faq', 'extensibility', 'building-extensions'];
 
 const EXPECTED_REFERENCE = ['cli', 'sdk', 'config', 'api-reference', 'integration', 'tools-and-hooks'];