From c5e45ebb5f6a45a182e36bedc43635599b6619cc Mon Sep 17 00:00:00 2001
From: Copilot <223556219+Copilot@users.noreply.github.com>
Date: Mon, 16 Mar 2026 10:38:14 -0700
Subject: [PATCH 1/6] chore(flight): update history with agent on-disk anatomy
 doc learning

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .squad/agents/flight/history.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/.squad/agents/flight/history.md b/.squad/agents/flight/history.md
index cd735f17a..439ac9325 100644
--- a/.squad/agents/flight/history.md
+++ b/.squad/agents/flight/history.md
@@ -25,3 +25,6 @@ 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/`.
+

From 0bf5806330d2f1cfc2b0ada8c491bb37ef2b6988 Mon Sep 17 00:00:00 2001
From: Copilot <223556219+Copilot@users.noreply.github.com>
Date: Mon, 16 Mar 2026 10:40:43 -0700
Subject: [PATCH 2/6] docs: Add extensibility guide for self-sorting change
 ideas

Adds comprehensive extensibility guide at docs/guide/extensibility.md to help Squad users determine WHERE their change idea belongs (Core, Extension, or Team Config).

Key sections:
- Three-layer extensibility model
- Decision tree flowchart (text-based)
- Examples for each layer
- The Claire test (RFC #328 as worked example)
- When to escalate to core
- How to build a plugin

Addresses common confusion about what belongs in Squad core vs plugins vs team configuration.

Updates test assertions in docs-build.test.ts for new guide page.

Related: #328

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .worktrees/323-clarify-copilot-requirement   |   1 +
 docs/src/content/docs/guide/extensibility.md | 559 +++++++++++++++++++
 test/docs-build.test.ts                      |   2 +-
 3 files changed, 561 insertions(+), 1 deletion(-)
 create mode 160000 .worktrees/323-clarify-copilot-requirement
 create mode 100644 docs/src/content/docs/guide/extensibility.md

diff --git a/.worktrees/323-clarify-copilot-requirement b/.worktrees/323-clarify-copilot-requirement
new file mode 160000
index 000000000..6e8a264d5
--- /dev/null
+++ b/.worktrees/323-clarify-copilot-requirement
@@ -0,0 +1 @@
+Subproject commit 6e8a264d51ac03dd3d6029159762c734bed020aa
diff --git a/docs/src/content/docs/guide/extensibility.md b/docs/src/content/docs/guide/extensibility.md
new file mode 100644
index 000000000..e830e0954
--- /dev/null
+++ b/docs/src/content/docs/guide/extensibility.md
@@ -0,0 +1,559 @@
+# Extensibility guide
+
+> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases.
+
+When you have an idea to improve Squad, where does it belong? Should it live in Squad core, become a marketplace plugin, or just be team configuration in your `.squad/` directory?
+
+This guide helps you self-sort. Most ideas don't need core changes — they can be expressed as **skills**, **ceremonies**, or **directives** in your team's configuration or shared as plugins for others to use.
+
+---
+
+## The three-layer extensibility model
+
+Squad is designed with a small core and large configuration surface. Here's how change ideas map to each layer:
+
+| Layer | What lives here | Who changes it | Distribution |
+|-------|----------------|----------------|--------------|
+| **Squad Core** | Coordinator behavior, routing logic, reviewer protocol, eager execution, core orchestration | Squad maintainers only | npm releases |
+| **Squad Extension** | Reusable patterns any team could adopt — skills, ceremonies, workflows | Plugin authors | Marketplace plugins |
+| **Team Configuration** | Decisions unique to THIS team's process | The team itself | Per-repo `.squad/` files |
+
+**Key principle:** Squad core stays small. Most ideas are skills, ceremonies, or directives.
+
+---
+
+## Decision tree: Where does your idea belong?
+
+Start here when you have a change idea:
+
+```
+┌─ Does your idea change HOW the coordinator routes work,
+│  spawns agents, or enforces core protocols?
+│
+├─ YES → Likely Squad Core
+│  └─ Examples:
+│     • New coordinator modes (triage, assign, execute)
+│     • Changes to reviewer approval rules
+│     • New agent spawning strategies
+│     • Core orchestration protocol changes
+│     └─ Action: Open an RFC issue to discuss with maintainers
+│
+└─ NO → Continue...
+   │
+   ┌─ Could OTHER teams benefit from this pattern?
+   │
+   ├─ YES → Squad Extension (plugin)
+   │  └─ Examples:
+   │     • Reusable workflows (client-delivery, research sprints)
+   │     • Domain-specific skills (cloud platforms, testing strategies)
+   │     • Ceremony templates (design reviews, post-mortems)
+   │     └─ Action: Build a plugin, share in marketplace
+   │
+   └─ NO → Team Configuration
+      └─ Examples:
+         • YOUR team's git workflow
+         • YOUR team's approval rules
+         • YOUR project's build process
+         • Agent charters specific to YOUR domain
+         └─ Action: Update `.squad/` files in your repo
+```
+
+**Quick heuristic:** If your idea starts with "Squad should...", check if it's really "My team should..." or "Teams using pattern X should...". That distinction determines the layer.
+
+---
+
+## Layer 1: Squad Core
+
+**What lives here:**
+- Coordinator modes (`triage`, `assign`, `execute`)
+- Work routing logic (how issues are matched to agents)
+- Reviewer protocol (how approvals work, blocking conditions)
+- Eager execution behavior
+- Agent spawning and lifecycle management
+- Core orchestration protocol
+
+**Who changes it:**
+Squad maintainers only.
+
+**When to propose a core change:**
+- You need a NEW coordinator mode or routing strategy
+- You need to change HOW reviewers approve work
+- You need to add enforcement rules that all squads must follow
+- Your idea changes the fundamental orchestration model
+
+**Examples of core changes:**
+- ✅ Adding a `validate` coordinator mode that runs checks before `assign`
+- ✅ Changing reviewer protocol to support conditional approvals
+- ✅ Adding agent capability declarations to enable better routing
+- ❌ Adding a specific workflow for your team (this is Layer 3)
+- ❌ Creating a reusable research sprint pattern (this is Layer 2)
+
+**How to propose a core change:**
+1. Open an RFC issue in the Squad repository
+2. Explain the problem you're solving
+3. Show why it can't be expressed as a skill, ceremony, or directive
+4. Describe the proposed coordinator or protocol change
+5. Wait for maintainer feedback before implementing
+
+---
+
+## Layer 2: Squad Extensions (plugins)
+
+**What lives here:**
+- Reusable skills any team could adopt
+- Ceremony templates for common workflows
+- Workflow patterns (planning loops, review cycles, research sprints)
+- Domain-specific expertise (cloud platforms, testing, security)
+
+**Who creates them:**
+Plugin authors — anyone in the community.
+
+**How they're distributed:**
+Marketplace plugins via GitHub repositories (like `github/awesome-copilot`).
+
+**When to build a plugin:**
+- Your idea solves a problem MANY teams face
+- It's a pattern, not a one-off configuration
+- You want to share it with the community
+- It doesn't require coordinator changes
+
+**Examples of plugins:**
+- ✅ `client-delivery-workflow` — discovery interviews, research sprints, multi-round review
+- ✅ `azure-cloud-platform` — skills for Azure deployment, monitoring, cost optimization
+- ✅ `tdd-workflow` — ceremony templates for test-driven development cycles
+- ✅ `security-review-ceremony` — OWASP checklist, threat modeling, pen-test protocols
+- ❌ YOUR team's specific git branch naming rules (this is Layer 3)
+- ❌ Changes to how the coordinator spawns agents (this is Layer 1)
+
+**Plugin structure:**
+```
+your-plugin/
+├── README.md               # What it does, how to use it
+├── skills/
+│   ├── skill-name/
+│   │   └── SKILL.md        # Skill definition
+├── ceremonies/
+│   └── ceremony-name.md    # Ceremony template
+└── directives/
+    └── directive-name.md   # Team directive template
+```
+
+**How to build and share a plugin:**
+1. Create a GitHub repository for your plugin
+2. Structure it with skills, ceremonies, or directives
+3. Write clear documentation (what problem it solves, how to install, how to use)
+4. Submit to a marketplace (e.g., `github/awesome-copilot`)
+5. Teams install with: `squad plugin install {owner/repo/plugin-name}`
+
+**Installing a plugin:**
+```bash
+squad plugin marketplace add github/awesome-copilot
+squad plugin install github/awesome-copilot/client-delivery-workflow
+```
+
+---
+
+## Layer 3: Team Configuration
+
+**What lives here:**
+- Skills specific to YOUR project
+- Ceremonies unique to YOUR team's process
+- Directives expressing YOUR team's decisions
+- Agent charters for YOUR domain
+- Routing rules for YOUR issue labels
+
+**Who changes it:**
+The team itself — these are per-repo configuration files.
+
+**When to use team configuration:**
+- This decision is unique to YOUR team
+- Other teams wouldn't benefit from this pattern
+- You're configuring existing Squad primitives, not adding new ones
+- You're expressing team process, not changing core behavior
+
+**Examples of team configuration:**
+- ✅ A skill for YOUR project's build system (`SKILL.md` in `.squad/skills/our-build-process/`)
+- ✅ A ceremony for YOUR team's weekly planning meeting (`.squad/ceremonies.md`)
+- ✅ Routing rules for YOUR issue labels (`.squad/routing.md`)
+- ✅ Agent charters for YOUR domain experts (`.squad/agents/{name}/charter.md`)
+- ❌ A reusable workflow pattern (this is Layer 2)
+- ❌ Changes to coordinator routing logic (this is Layer 1)
+
+**How to add team configuration:**
+
+**Add a skill:**
+```bash
+mkdir -p .squad/skills/my-skill
+cat > .squad/skills/my-skill/SKILL.md << 'EOF'
+---
+name: "my-skill"
+description: "What this skill does"
+domain: "category"
+confidence: "high"
+source: "team-decision"
+---
+
+## Context
+[Explain when to use this skill]
+
+## Steps
+1. Do this
+2. Then this
+3. Finally this
+EOF
+```
+
+**Add a ceremony:**
+Edit `.squad/ceremonies.md` to add a new ceremony block:
+```markdown
+## My Team Meeting
+
+| Field | Value |
+|-------|-------|
+| **Trigger** | manual |
+| **When** | before |
+| **Condition** | weekly sprint planning |
+| **Facilitator** | lead |
+| **Participants** | all |
+| **Time budget** | focused |
+| **Enabled** | ✅ yes |
+
+**Agenda:**
+1. Review last week's work
+2. Assign this week's issues
+3. Identify blockers
+```
+
+**Add a directive:**
+Write to `.squad/decisions/inbox/{agent}-{slug}.md`:
+```markdown
+# Decision: Always use TypeScript strict mode
+
+**Context:** We've had runtime type errors slip through.
+
+**Decision:** All new code must use `"strict": true` in tsconfig.json.
+
+**Rationale:** Catches type errors at compile time, reduces production bugs.
+
+**Applies to:** All agents writing TypeScript.
+```
+
+The Scribe will merge it into `.squad/decisions.md`.
+
+---
+
+## The Claire test: A worked example
+
+[Claire Novotny's RFC #328](https://github.com/bradygaster/squad/issues/328) proposed a sophisticated client-delivery workflow with discovery interviews, research sprints, multi-round review, and evidence-backed implementation gates. It felt like a big feature request.
+
+**The realization:** It maps ENTIRELY to existing Squad primitives. No core changes needed.
+
+### What Claire wanted
+
+- Discovery interviews before implementation
+- Research sprints when the direction is unclear
+- Multi-round plan review with `SHIP`/`NEEDS_WORK`/`BLOCKED` verdicts
+- Evidence bundles proving implementation quality
+- Local workflow artifacts (research briefs, scoring matrices, task graphs)
+
+### Where it actually belongs
+
+**Layer 2: Squad Extension (plugin)**
+
+Claire's workflow is a REUSABLE PATTERN any team could adopt. It's perfect as a marketplace plugin.
+
+**Plugin structure:**
+```
+client-delivery-workflow/
+├── README.md
+├── skills/
+│   ├── discovery-interview/SKILL.md
+│   ├── research-sprint/SKILL.md
+│   └── evidence-bundler/SKILL.md
+├── ceremonies/
+│   ├── plan-review.md
+│   └── implementation-review.md
+└── directives/
+    └── multi-round-review-policy.md
+```
+
+**Skills define the work:**
+- `discovery-interview` — Clarify rough requests, extract requirements, produce a context pack
+- `research-sprint` — Propose multiple directions, score them, recommend the best option
+- `evidence-bundler` — Collect test results, logs, screenshots proving implementation quality
+
+**Ceremonies define the gates:**
+- `plan-review` — Before implementation starts, reviewers approve or request changes
+- `implementation-review` — After implementation, reviewers verify evidence and approve
+
+**Directives define the rules:**
+- Multi-round review policy: up to 2 `NEEDS_WORK` rounds with the same author, forced reassignment on the 3rd rejection
+
+**How teams use it:**
+```bash
+# Install the plugin
+squad plugin install github/awesome-copilot/client-delivery-workflow
+
+# The plugin adds skills, ceremonies, and directives to your team
+# Agents automatically use them when appropriate
+```
+
+**What DOESN'T need core changes:**
+- ❌ New coordinator modes (existing `assign` and `execute` modes work fine)
+- ❌ New orchestration protocols (skills and ceremonies handle the workflow)
+- ❌ Changes to reviewer approval rules (directives express the policy)
+
+**Lesson learned:** Most sophisticated workflows are COMPOSITIONS of primitives, not core features.
+
+---
+
+## When to escalate to core
+
+Sometimes a change idea DOES need core work. Here are the signals:
+
+### You likely need a core change if:
+
+**1. You need a new coordinator mode**
+- Example: A `validate` mode that runs checks before `assign`
+- Why core: Coordinator modes are part of Squad's orchestration protocol
+
+**2. You need to change routing logic**
+- Example: Route based on agent workload, not just labels
+- Why core: Routing is a coordinator responsibility
+
+**3. You need to change reviewer protocol**
+- Example: Support conditional approvals ("approved if tests pass")
+- Why core: Reviewer approval is a core enforcement mechanism
+
+**4. You need to add global enforcement rules**
+- Example: Block merges if required evidence is missing
+- Why core: Enforcement rules are part of the orchestration protocol
+
+**5. Your skill needs data the coordinator doesn't expose**
+- Example: Access to agent spawn history or routing decisions
+- Why core: Skills run in agent context; they can't see coordinator state
+
+### You DON'T need a core change if:
+
+**1. You're defining a workflow pattern**
+- ❌ Not core: "Discovery interview → research sprint → plan review → implementation"
+- ✅ Solution: Express as a plugin with skills and ceremonies
+
+**2. You're adding domain expertise**
+- ❌ Not core: "Azure deployment best practices"
+- ✅ Solution: Write a skill or share a plugin
+
+**3. You're expressing team process**
+- ❌ Not core: "Our team requires design reviews before multi-agent tasks"
+- ✅ Solution: Add a ceremony to `.squad/ceremonies.md`
+
+**4. You're creating reusable templates**
+- ❌ Not core: "A ceremony template for security reviews"
+- ✅ Solution: Build a plugin with ceremony templates
+
+**5. You're configuring existing behavior**
+- ❌ Not core: "Route issues labeled `bug` to our QA agent"
+- ✅ Solution: Update `.squad/routing.md`
+
+---
+
+## How to build a plugin
+
+Building a Squad plugin is straightforward. Plugins are just collections of skills, ceremonies, and directives packaged for reuse.
+
+### 1. Create a GitHub repository
+
+```bash
+mkdir squad-plugin-my-workflow
+cd squad-plugin-my-workflow
+git init
+```
+
+### 2. Add a README
+
+Explain what problem your plugin solves, how to install it, and how to use it.
+
+```markdown
+# My Workflow Plugin
+
+Adds discovery interviews, research sprints, and multi-round review to Squad teams.
+
+## Installation
+
+squad plugin marketplace add github/awesome-copilot
+squad plugin install github/awesome-copilot/my-workflow
+
+## Usage
+
+When you assign work to your squad, agents will automatically:
+1. Conduct discovery interviews to clarify requirements
+2. Run research sprints when the direction is unclear
+3. Gate implementation on plan approval
+4. Collect evidence bundles proving quality
+```
+
+### 3. Add skills
+
+Create a `skills/` directory with one subdirectory per skill:
+
+```
+skills/
+├── discovery-interview/
+│   └── SKILL.md
+├── research-sprint/
+│   └── SKILL.md
+└── evidence-bundler/
+    └── SKILL.md
+```
+
+Each `SKILL.md` follows the Squad skill format:
+```markdown
+---
+name: "discovery-interview"
+description: "Clarify rough requests before implementation"
+domain: "planning"
+confidence: "high"
+source: "plugin"
+---
+
+## Context
+When a user's request is vague or incomplete, run a discovery interview.
+
+## Steps
+1. Ask clarifying questions
+2. Extract requirements
+3. Produce a context pack
+```
+
+### 4. Add ceremonies
+
+Create a `ceremonies/` directory with one file per ceremony:
+
+```
+ceremonies/
+├── plan-review.md
+└── implementation-review.md
+```
+
+Each ceremony follows the Squad ceremony format:
+```markdown
+## Plan Review
+
+| Field | Value |
+|-------|-------|
+| **Trigger** | auto |
+| **When** | before |
+| **Condition** | implementation starts |
+| **Facilitator** | lead |
+| **Participants** | all-relevant |
+| **Time budget** | focused |
+| **Enabled** | ✅ yes |
+
+**Agenda:**
+1. Review solution plan
+2. Review work plan
+3. Approve or request changes
+4. Verdict: SHIP, NEEDS_WORK, or BLOCKED
+```
+
+### 5. Add directives (optional)
+
+If your plugin includes team policy recommendations, add them to `directives/`:
+
+```
+directives/
+└── multi-round-review-policy.md
+```
+
+### 6. Share in a marketplace
+
+Submit your plugin to a marketplace repository (like `github/awesome-copilot`) via pull request. Maintainers will review and merge.
+
+**For detailed plugin authoring guidance, see the [Plugin Marketplace documentation](./../concepts/plugin-marketplace.md).**
+
+---
+
+## Examples for each layer
+
+### Layer 1: Squad Core
+
+**Example 1: Add a `validate` coordinator mode**
+- **Problem:** Before assigning work, teams want to run automated checks (lint, build, tests)
+- **Why core:** This adds a new coordinator mode that runs BEFORE `assign`
+- **Solution:** Core change required — new mode in coordinator
+
+**Example 2: Support conditional reviewer approvals**
+- **Problem:** Reviewers want to say "approved IF tests pass"
+- **Why core:** This changes the reviewer approval protocol
+- **Solution:** Core change required — extend reviewer logic
+
+**Example 3: Route based on agent workload**
+- **Problem:** Avoid overloading one agent by routing to the least-busy agent
+- **Why core:** This changes routing logic in the coordinator
+- **Solution:** Core change required — update routing algorithm
+
+### Layer 2: Squad Extensions (plugins)
+
+**Example 1: `client-delivery-workflow` plugin**
+- **Problem:** Teams want discovery interviews, research sprints, multi-round review
+- **Why plugin:** This is a reusable workflow pattern any team could adopt
+- **Contents:** Skills (discovery, research, evidence), ceremonies (plan review, implementation review), directives (review policy)
+
+**Example 2: `azure-platform` plugin**
+- **Problem:** Teams deploying to Azure need skills for infrastructure, monitoring, cost optimization
+- **Why plugin:** This is domain-specific expertise many teams need
+- **Contents:** Skills (deploy to AKS, set up Application Insights, optimize costs)
+
+**Example 3: `tdd-workflow` plugin**
+- **Problem:** Teams practicing TDD want structured red-green-refactor cycles
+- **Why plugin:** This is a reusable testing workflow
+- **Contents:** Ceremony templates (test review, refactor review), skills (generate failing tests, refactor safely)
+
+### Layer 3: Team Configuration
+
+**Example 1: Add a skill for YOUR build system**
+- **Problem:** Your project uses a custom build pipeline
+- **Why team config:** This is specific to YOUR project, not reusable
+- **Location:** `.squad/skills/our-build-process/SKILL.md`
+
+**Example 2: Add a ceremony for YOUR weekly planning**
+- **Problem:** Your team has a weekly sprint planning meeting
+- **Why team config:** This is YOUR team's process, not a generic pattern
+- **Location:** `.squad/ceremonies.md` (add a new ceremony block)
+
+**Example 3: Route issues to YOUR QA agent**
+- **Problem:** Issues labeled `bug` should go to your QA specialist
+- **Why team config:** This is YOUR team's routing rule
+- **Location:** `.squad/routing.md` (add a routing rule)
+
+**Example 4: Agent charter for YOUR domain**
+- **Problem:** You have a domain expert (e.g., database specialist)
+- **Why team config:** This charter is specific to YOUR project
+- **Location:** `.squad/agents/{name}/charter.md`
+
+---
+
+## Summary: Self-sorting your change idea
+
+1. **Start with the decision tree** — Most ideas are Layer 2 or Layer 3.
+2. **Default to team configuration** — If it's unique to your team, put it in `.squad/`.
+3. **Build a plugin if it's reusable** — If other teams would benefit, package it and share it.
+4. **Escalate to core only when primitives aren't enough** — If you need new coordinator modes, routing logic, or enforcement rules, open an RFC.
+
+**Key insight:** Squad core is intentionally small. The power is in composition — skills, ceremonies, and directives can express sophisticated workflows without core changes.
+
+**When in doubt:** Start with team configuration. If you find yourself copy-pasting it to other teams, promote it to a plugin. If you find plugins repeatedly hitting the same limitation, that's a signal for a 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.
diff --git a/test/docs-build.test.ts b/test/docs-build.test.ts
index 5d9adcee8..174ea3c44 100644
--- a/test/docs-build.test.ts
+++ b/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'];
 
 const EXPECTED_REFERENCE = ['cli', 'sdk', 'config', 'api-reference', 'integration', 'tools-and-hooks'];
 

From de8d657af76d99102b3e82133b1694fe9da81368 Mon Sep 17 00:00:00 2001
From: Copilot <223556219+Copilot@users.noreply.github.com>
Date: Mon, 16 Mar 2026 10:43:03 -0700
Subject: [PATCH 3/6] chore(pao): Update history with extensibility guide
 learning

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .squad/agents/pao/history.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/.squad/agents/pao/history.md b/.squad/agents/pao/history.md
index 71cdfefe3..b95a8ea94 100644
--- a/.squad/agents/pao/history.md
+++ b/.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.
+

From 9fe0ff62cb23b3b8075bf9e9f16b3aeeb01df2b7 Mon Sep 17 00:00:00 2001
From: Copilot <223556219+Copilot@users.noreply.github.com>
Date: Mon, 16 Mar 2026 10:43:42 -0700
Subject: [PATCH 4/6] decision(pao): Document three-layer extensibility model

Captures the architectural decision behind the extensibility guide: Squad core stays small, most ideas are composition (skills/ceremonies/directives).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .../inbox/pao-extensibility-guide.md          | 60 +++++++++++++++++++
 1 file changed, 60 insertions(+)
 create mode 100644 .squad/decisions/inbox/pao-extensibility-guide.md

diff --git a/.squad/decisions/inbox/pao-extensibility-guide.md b/.squad/decisions/inbox/pao-extensibility-guide.md
new file mode 100644
index 000000000..4bb073351
--- /dev/null
+++ b/.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.

From 1a254c5ff57823c754ec36e1ea605baec4d4614e Mon Sep 17 00:00:00 2001
From: Copilot <223556219+Copilot@users.noreply.github.com>
Date: Mon, 16 Mar 2026 11:04:23 -0700
Subject: [PATCH 5/6] docs: Compress extensibility guide to 100 lines

Flight's review flagged 559 lines as too verbose. Compressed to 100 lines:
- Kept: three-layer decision tree, Claire's RFC example, escalation signals
- Cut: verbose explanations, extended examples, repetitive how-to sections

Target Brady's preference: small, strategic docs.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .copilot/mcp-config.json                     |  17 +-
 .squad/agents/eecom/history.md               |   8 +
 .squad/agents/flight/history.md              |   3 +
 docs/src/content/docs/guide/extensibility.md | 532 ++-----------------
 4 files changed, 77 insertions(+), 483 deletions(-)

diff --git a/.copilot/mcp-config.json b/.copilot/mcp-config.json
index ff2159ec1..50e82ac41 100644
--- a/.copilot/mcp-config.json
+++ b/.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"
     }
   }
-}
+}
diff --git a/.squad/agents/eecom/history.md b/.squad/agents/eecom/history.md
index 51f9021d5..46fb7dbf0 100644
--- a/.squad/agents/eecom/history.md
+++ b/.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.
+
diff --git a/.squad/agents/flight/history.md b/.squad/agents/flight/history.md
index 439ac9325..7232a31a8 100644
--- a/.squad/agents/flight/history.md
+++ b/.squad/agents/flight/history.md
@@ -28,3 +28,6 @@ Rank by: (1) bugs with active user impact, (2) quality/test gaps blocking GA, (3
 ### 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.
+
diff --git a/docs/src/content/docs/guide/extensibility.md b/docs/src/content/docs/guide/extensibility.md
index e830e0954..28bd0b0e2 100644
--- a/docs/src/content/docs/guide/extensibility.md
+++ b/docs/src/content/docs/guide/extensibility.md
@@ -2,547 +2,129 @@
 
 > ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases.
 
-When you have an idea to improve Squad, where does it belong? Should it live in Squad core, become a marketplace plugin, or just be team configuration in your `.squad/` directory?
+Where does your change idea belong? Squad core, marketplace plugin, or team config?
 
-This guide helps you self-sort. Most ideas don't need core changes — they can be expressed as **skills**, **ceremonies**, or **directives** in your team's configuration or shared as plugins for others to use.
+**Key principle:** Squad core stays small. Most ideas are skills, ceremonies, or directives.
 
 ---
 
-## The three-layer extensibility model
-
-Squad is designed with a small core and large configuration surface. Here's how change ideas map to each layer:
+## The three layers
 
 | Layer | What lives here | Who changes it | Distribution |
 |-------|----------------|----------------|--------------|
-| **Squad Core** | Coordinator behavior, routing logic, reviewer protocol, eager execution, core orchestration | Squad maintainers only | npm releases |
-| **Squad Extension** | Reusable patterns any team could adopt — skills, ceremonies, workflows | Plugin authors | Marketplace plugins |
-| **Team Configuration** | Decisions unique to THIS team's process | The team itself | Per-repo `.squad/` files |
-
-**Key principle:** Squad core stays small. Most ideas are skills, ceremonies, or directives.
+| **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: Where does your idea belong?
-
-Start here when you have a change idea:
+## Decision tree
 
 ```
-┌─ Does your idea change HOW the coordinator routes work,
-│  spawns agents, or enforces core protocols?
+┌─ Does it change HOW the coordinator routes, spawns, or enforces?
 │
-├─ YES → Likely Squad Core
-│  └─ Examples:
-│     • New coordinator modes (triage, assign, execute)
-│     • Changes to reviewer approval rules
-│     • New agent spawning strategies
-│     • Core orchestration protocol changes
-│     └─ Action: Open an RFC issue to discuss with maintainers
+├─ YES → Squad Core
+│  └─ Examples: New coordinator modes, reviewer protocol changes
+│     Action: Open an RFC issue
 │
 └─ NO → Continue...
    │
-   ┌─ Could OTHER teams benefit from this pattern?
+   ┌─ Could OTHER teams benefit?
    │
    ├─ YES → Squad Extension (plugin)
-   │  └─ Examples:
-   │     • Reusable workflows (client-delivery, research sprints)
-   │     • Domain-specific skills (cloud platforms, testing strategies)
-   │     • Ceremony templates (design reviews, post-mortems)
-   │     └─ Action: Build a plugin, share in marketplace
+   │  └─ Examples: Client-delivery workflow, Azure skills, TDD ceremonies
+   │     Action: Build a plugin
    │
    └─ NO → Team Configuration
-      └─ Examples:
-         • YOUR team's git workflow
-         • YOUR team's approval rules
-         • YOUR project's build process
-         • Agent charters specific to YOUR domain
-         └─ Action: Update `.squad/` files in your repo
-```
-
-**Quick heuristic:** If your idea starts with "Squad should...", check if it's really "My team should..." or "Teams using pattern X should...". That distinction determines the layer.
-
----
-
-## Layer 1: Squad Core
-
-**What lives here:**
-- Coordinator modes (`triage`, `assign`, `execute`)
-- Work routing logic (how issues are matched to agents)
-- Reviewer protocol (how approvals work, blocking conditions)
-- Eager execution behavior
-- Agent spawning and lifecycle management
-- Core orchestration protocol
-
-**Who changes it:**
-Squad maintainers only.
-
-**When to propose a core change:**
-- You need a NEW coordinator mode or routing strategy
-- You need to change HOW reviewers approve work
-- You need to add enforcement rules that all squads must follow
-- Your idea changes the fundamental orchestration model
-
-**Examples of core changes:**
-- ✅ Adding a `validate` coordinator mode that runs checks before `assign`
-- ✅ Changing reviewer protocol to support conditional approvals
-- ✅ Adding agent capability declarations to enable better routing
-- ❌ Adding a specific workflow for your team (this is Layer 3)
-- ❌ Creating a reusable research sprint pattern (this is Layer 2)
-
-**How to propose a core change:**
-1. Open an RFC issue in the Squad repository
-2. Explain the problem you're solving
-3. Show why it can't be expressed as a skill, ceremony, or directive
-4. Describe the proposed coordinator or protocol change
-5. Wait for maintainer feedback before implementing
-
----
-
-## Layer 2: Squad Extensions (plugins)
-
-**What lives here:**
-- Reusable skills any team could adopt
-- Ceremony templates for common workflows
-- Workflow patterns (planning loops, review cycles, research sprints)
-- Domain-specific expertise (cloud platforms, testing, security)
-
-**Who creates them:**
-Plugin authors — anyone in the community.
-
-**How they're distributed:**
-Marketplace plugins via GitHub repositories (like `github/awesome-copilot`).
-
-**When to build a plugin:**
-- Your idea solves a problem MANY teams face
-- It's a pattern, not a one-off configuration
-- You want to share it with the community
-- It doesn't require coordinator changes
-
-**Examples of plugins:**
-- ✅ `client-delivery-workflow` — discovery interviews, research sprints, multi-round review
-- ✅ `azure-cloud-platform` — skills for Azure deployment, monitoring, cost optimization
-- ✅ `tdd-workflow` — ceremony templates for test-driven development cycles
-- ✅ `security-review-ceremony` — OWASP checklist, threat modeling, pen-test protocols
-- ❌ YOUR team's specific git branch naming rules (this is Layer 3)
-- ❌ Changes to how the coordinator spawns agents (this is Layer 1)
-
-**Plugin structure:**
-```
-your-plugin/
-├── README.md               # What it does, how to use it
-├── skills/
-│   ├── skill-name/
-│   │   └── SKILL.md        # Skill definition
-├── ceremonies/
-│   └── ceremony-name.md    # Ceremony template
-└── directives/
-    └── directive-name.md   # Team directive template
-```
-
-**How to build and share a plugin:**
-1. Create a GitHub repository for your plugin
-2. Structure it with skills, ceremonies, or directives
-3. Write clear documentation (what problem it solves, how to install, how to use)
-4. Submit to a marketplace (e.g., `github/awesome-copilot`)
-5. Teams install with: `squad plugin install {owner/repo/plugin-name}`
-
-**Installing a plugin:**
-```bash
-squad plugin marketplace add github/awesome-copilot
-squad plugin install github/awesome-copilot/client-delivery-workflow
+      └─ Examples: YOUR git workflow, YOUR build process, YOUR routing rules
+         Action: Update `.squad/` files
 ```
 
----
-
-## Layer 3: Team Configuration
-
-**What lives here:**
-- Skills specific to YOUR project
-- Ceremonies unique to YOUR team's process
-- Directives expressing YOUR team's decisions
-- Agent charters for YOUR domain
-- Routing rules for YOUR issue labels
-
-**Who changes it:**
-The team itself — these are per-repo configuration files.
-
-**When to use team configuration:**
-- This decision is unique to YOUR team
-- Other teams wouldn't benefit from this pattern
-- You're configuring existing Squad primitives, not adding new ones
-- You're expressing team process, not changing core behavior
-
-**Examples of team configuration:**
-- ✅ A skill for YOUR project's build system (`SKILL.md` in `.squad/skills/our-build-process/`)
-- ✅ A ceremony for YOUR team's weekly planning meeting (`.squad/ceremonies.md`)
-- ✅ Routing rules for YOUR issue labels (`.squad/routing.md`)
-- ✅ Agent charters for YOUR domain experts (`.squad/agents/{name}/charter.md`)
-- ❌ A reusable workflow pattern (this is Layer 2)
-- ❌ Changes to coordinator routing logic (this is Layer 1)
-
-**How to add team configuration:**
-
-**Add a skill:**
-```bash
-mkdir -p .squad/skills/my-skill
-cat > .squad/skills/my-skill/SKILL.md << 'EOF'
----
-name: "my-skill"
-description: "What this skill does"
-domain: "category"
-confidence: "high"
-source: "team-decision"
----
-
-## Context
-[Explain when to use this skill]
-
-## Steps
-1. Do this
-2. Then this
-3. Finally this
-EOF
-```
-
-**Add a ceremony:**
-Edit `.squad/ceremonies.md` to add a new ceremony block:
-```markdown
-## My Team Meeting
-
-| Field | Value |
-|-------|-------|
-| **Trigger** | manual |
-| **When** | before |
-| **Condition** | weekly sprint planning |
-| **Facilitator** | lead |
-| **Participants** | all |
-| **Time budget** | focused |
-| **Enabled** | ✅ yes |
-
-**Agenda:**
-1. Review last week's work
-2. Assign this week's issues
-3. Identify blockers
-```
-
-**Add a directive:**
-Write to `.squad/decisions/inbox/{agent}-{slug}.md`:
-```markdown
-# Decision: Always use TypeScript strict mode
-
-**Context:** We've had runtime type errors slip through.
-
-**Decision:** All new code must use `"strict": true` in tsconfig.json.
+**Heuristic:** "Squad should..." → check if it's really "My team should..." or "Teams using X should...".
 
-**Rationale:** Catches type errors at compile time, reduces production bugs.
 
-**Applies to:** All agents writing TypeScript.
-```
-
-The Scribe will merge it into `.squad/decisions.md`.
 
 ---
 
-## The Claire test: A worked example
-
-[Claire Novotny's RFC #328](https://github.com/bradygaster/squad/issues/328) proposed a sophisticated client-delivery workflow with discovery interviews, research sprints, multi-round review, and evidence-backed implementation gates. It felt like a big feature request.
-
-**The realization:** It maps ENTIRELY to existing Squad primitives. No core changes needed.
+## Worked example: Claire's RFC
 
-### What Claire wanted
+[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.
 
-- Discovery interviews before implementation
-- Research sprints when the direction is unclear
-- Multi-round plan review with `SHIP`/`NEEDS_WORK`/`BLOCKED` verdicts
-- Evidence bundles proving implementation quality
-- Local workflow artifacts (research briefs, scoring matrices, task graphs)
+**The realization:** It maps entirely to existing Squad primitives. No core changes needed.
 
-### Where it actually belongs
+**Where it belongs:** Layer 2 (Squad Extension)
 
-**Layer 2: Squad Extension (plugin)**
-
-Claire's workflow is a REUSABLE PATTERN any team could adopt. It's perfect as a marketplace plugin.
+Claire's workflow is a reusable pattern any team could adopt — perfect as a marketplace plugin.
 
 **Plugin structure:**
 ```
 client-delivery-workflow/
-├── README.md
 ├── skills/
-│   ├── discovery-interview/SKILL.md
-│   ├── research-sprint/SKILL.md
-│   └── evidence-bundler/SKILL.md
+│   ├── discovery-interview/      # Clarify requests, extract requirements
+│   ├── research-sprint/           # Propose directions, score options
+│   └── evidence-bundler/          # Collect test results, logs, screenshots
 ├── ceremonies/
-│   ├── plan-review.md
-│   └── implementation-review.md
+│   ├── plan-review.md             # Gate: approve before implementation
+│   └── implementation-review.md   # Gate: verify evidence
 └── directives/
-    └── multi-round-review-policy.md
+    └── multi-round-review.md      # Policy: 2 NEEDS_WORK rounds max
 ```
 
-**Skills define the work:**
-- `discovery-interview` — Clarify rough requests, extract requirements, produce a context pack
-- `research-sprint` — Propose multiple directions, score them, recommend the best option
-- `evidence-bundler` — Collect test results, logs, screenshots proving implementation quality
-
-**Ceremonies define the gates:**
-- `plan-review` — Before implementation starts, reviewers approve or request changes
-- `implementation-review` — After implementation, reviewers verify evidence and approve
-
-**Directives define the rules:**
-- Multi-round review policy: up to 2 `NEEDS_WORK` rounds with the same author, forced reassignment on the 3rd rejection
-
-**How teams use it:**
+**Usage:**
 ```bash
-# Install the plugin
 squad plugin install github/awesome-copilot/client-delivery-workflow
-
-# The plugin adds skills, ceremonies, and directives to your team
-# Agents automatically use them when appropriate
 ```
 
-**What DOESN'T need core changes:**
-- ❌ New coordinator modes (existing `assign` and `execute` modes work fine)
-- ❌ New orchestration protocols (skills and ceremonies handle the workflow)
-- ❌ Changes to reviewer approval rules (directives express the policy)
-
-**Lesson learned:** Most sophisticated workflows are COMPOSITIONS of primitives, not core features.
+**Lesson:** Most sophisticated workflows are compositions of primitives, not core features.
 
 ---
 
 ## When to escalate to core
 
-Sometimes a change idea DOES need core work. Here are the signals:
-
-### You likely need a core change if:
+You likely need a core change if:
 
-**1. You need a new coordinator mode**
-- Example: A `validate` mode that runs checks before `assign`
-- Why core: Coordinator modes are part of Squad's orchestration protocol
+- **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
 
-**2. You need to change routing logic**
-- Example: Route based on agent workload, not just labels
-- Why core: Routing is a coordinator responsibility
+You DON'T need core if:
 
-**3. You need to change reviewer protocol**
-- Example: Support conditional approvals ("approved if tests pass")
-- Why core: Reviewer approval is a core enforcement mechanism
-
-**4. You need to add global enforcement rules**
-- Example: Block merges if required evidence is missing
-- Why core: Enforcement rules are part of the orchestration protocol
-
-**5. Your skill needs data the coordinator doesn't expose**
-- Example: Access to agent spawn history or routing decisions
-- Why core: Skills run in agent context; they can't see coordinator state
-
-### You DON'T need a core change if:
-
-**1. You're defining a workflow pattern**
-- ❌ Not core: "Discovery interview → research sprint → plan review → implementation"
-- ✅ Solution: Express as a plugin with skills and ceremonies
-
-**2. You're adding domain expertise**
-- ❌ Not core: "Azure deployment best practices"
-- ✅ Solution: Write a skill or share a plugin
-
-**3. You're expressing team process**
-- ❌ Not core: "Our team requires design reviews before multi-agent tasks"
-- ✅ Solution: Add a ceremony to `.squad/ceremonies.md`
-
-**4. You're creating reusable templates**
-- ❌ Not core: "A ceremony template for security reviews"
-- ✅ Solution: Build a plugin with ceremony templates
-
-**5. You're configuring existing behavior**
-- ❌ Not core: "Route issues labeled `bug` to our QA agent"
-- ✅ Solution: Update `.squad/routing.md`
+- **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`
 
 ---
 
-## How to build a plugin
+## Quick start: Building a plugin
 
-Building a Squad plugin is straightforward. Plugins are just collections of skills, ceremonies, and directives packaged for reuse.
-
-### 1. Create a GitHub repository
+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
-mkdir squad-plugin-my-workflow
-cd squad-plugin-my-workflow
-git init
-```
-
-### 2. Add a README
-
-Explain what problem your plugin solves, how to install it, and how to use it.
-
-```markdown
-# My Workflow Plugin
-
-Adds discovery interviews, research sprints, and multi-round review to Squad teams.
-
-## Installation
-
 squad plugin marketplace add github/awesome-copilot
-squad plugin install github/awesome-copilot/my-workflow
-
-## Usage
-
-When you assign work to your squad, agents will automatically:
-1. Conduct discovery interviews to clarify requirements
-2. Run research sprints when the direction is unclear
-3. Gate implementation on plan approval
-4. Collect evidence bundles proving quality
-```
-
-### 3. Add skills
-
-Create a `skills/` directory with one subdirectory per skill:
-
-```
-skills/
-├── discovery-interview/
-│   └── SKILL.md
-├── research-sprint/
-│   └── SKILL.md
-└── evidence-bundler/
-    └── SKILL.md
-```
-
-Each `SKILL.md` follows the Squad skill format:
-```markdown
----
-name: "discovery-interview"
-description: "Clarify rough requests before implementation"
-domain: "planning"
-confidence: "high"
-source: "plugin"
----
-
-## Context
-When a user's request is vague or incomplete, run a discovery interview.
-
-## Steps
-1. Ask clarifying questions
-2. Extract requirements
-3. Produce a context pack
-```
-
-### 4. Add ceremonies
-
-Create a `ceremonies/` directory with one file per ceremony:
-
-```
-ceremonies/
-├── plan-review.md
-└── implementation-review.md
+squad plugin install github/awesome-copilot/your-plugin
 ```
 
-Each ceremony follows the Squad ceremony format:
-```markdown
-## Plan Review
-
-| Field | Value |
-|-------|-------|
-| **Trigger** | auto |
-| **When** | before |
-| **Condition** | implementation starts |
-| **Facilitator** | lead |
-| **Participants** | all-relevant |
-| **Time budget** | focused |
-| **Enabled** | ✅ yes |
-
-**Agenda:**
-1. Review solution plan
-2. Review work plan
-3. Approve or request changes
-4. Verdict: SHIP, NEEDS_WORK, or BLOCKED
-```
-
-### 5. Add directives (optional)
-
-If your plugin includes team policy recommendations, add them to `directives/`:
-
-```
-directives/
-└── multi-round-review-policy.md
-```
-
-### 6. Share in a marketplace
-
-Submit your plugin to a marketplace repository (like `github/awesome-copilot`) via pull request. Maintainers will review and merge.
-
-**For detailed plugin authoring guidance, see the [Plugin Marketplace documentation](./../concepts/plugin-marketplace.md).**
-
----
-
-## Examples for each layer
-
-### Layer 1: Squad Core
-
-**Example 1: Add a `validate` coordinator mode**
-- **Problem:** Before assigning work, teams want to run automated checks (lint, build, tests)
-- **Why core:** This adds a new coordinator mode that runs BEFORE `assign`
-- **Solution:** Core change required — new mode in coordinator
-
-**Example 2: Support conditional reviewer approvals**
-- **Problem:** Reviewers want to say "approved IF tests pass"
-- **Why core:** This changes the reviewer approval protocol
-- **Solution:** Core change required — extend reviewer logic
-
-**Example 3: Route based on agent workload**
-- **Problem:** Avoid overloading one agent by routing to the least-busy agent
-- **Why core:** This changes routing logic in the coordinator
-- **Solution:** Core change required — update routing algorithm
-
-### Layer 2: Squad Extensions (plugins)
-
-**Example 1: `client-delivery-workflow` plugin**
-- **Problem:** Teams want discovery interviews, research sprints, multi-round review
-- **Why plugin:** This is a reusable workflow pattern any team could adopt
-- **Contents:** Skills (discovery, research, evidence), ceremonies (plan review, implementation review), directives (review policy)
-
-**Example 2: `azure-platform` plugin**
-- **Problem:** Teams deploying to Azure need skills for infrastructure, monitoring, cost optimization
-- **Why plugin:** This is domain-specific expertise many teams need
-- **Contents:** Skills (deploy to AKS, set up Application Insights, optimize costs)
-
-**Example 3: `tdd-workflow` plugin**
-- **Problem:** Teams practicing TDD want structured red-green-refactor cycles
-- **Why plugin:** This is a reusable testing workflow
-- **Contents:** Ceremony templates (test review, refactor review), skills (generate failing tests, refactor safely)
-
-### Layer 3: Team Configuration
-
-**Example 1: Add a skill for YOUR build system**
-- **Problem:** Your project uses a custom build pipeline
-- **Why team config:** This is specific to YOUR project, not reusable
-- **Location:** `.squad/skills/our-build-process/SKILL.md`
-
-**Example 2: Add a ceremony for YOUR weekly planning**
-- **Problem:** Your team has a weekly sprint planning meeting
-- **Why team config:** This is YOUR team's process, not a generic pattern
-- **Location:** `.squad/ceremonies.md` (add a new ceremony block)
-
-**Example 3: Route issues to YOUR QA agent**
-- **Problem:** Issues labeled `bug` should go to your QA specialist
-- **Why team config:** This is YOUR team's routing rule
-- **Location:** `.squad/routing.md` (add a routing rule)
-
-**Example 4: Agent charter for YOUR domain**
-- **Problem:** You have a domain expert (e.g., database specialist)
-- **Why team config:** This charter is specific to YOUR project
-- **Location:** `.squad/agents/{name}/charter.md`
+**See [Plugin Marketplace docs](./../concepts/plugin-marketplace.md) for details.**
 
 ---
 
-## Summary: Self-sorting your change idea
-
-1. **Start with the decision tree** — Most ideas are Layer 2 or Layer 3.
-2. **Default to team configuration** — If it's unique to your team, put it in `.squad/`.
-3. **Build a plugin if it's reusable** — If other teams would benefit, package it and share it.
-4. **Escalate to core only when primitives aren't enough** — If you need new coordinator modes, routing logic, or enforcement rules, open an RFC.
+## Summary
 
-**Key insight:** Squad core is intentionally small. The power is in composition — skills, ceremonies, and directives can express sophisticated workflows without core changes.
+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 configuration. If you find yourself copy-pasting it to other teams, promote it to a plugin. If you find plugins repeatedly hitting the same limitation, that's a signal for a core change.
+**When in doubt:** Start with team config. Copy-pasting to other teams? Promote to plugin. Plugins repeatedly hitting limits? Signal for core change.
 
 ---
 

From c2a03779fab0578a9eeb7f6e815c68d03a274c2c Mon Sep 17 00:00:00 2001
From: Copilot <223556219+Copilot@users.noreply.github.com>
Date: Mon, 16 Mar 2026 13:13:10 -0700
Subject: [PATCH 6/6] docs: Add building extensions guide

Practical guide for authoring Squad extensions (skills, ceremonies, directives).
Fills the gap between the extensibility decision tree and plugin installation docs.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .../content/docs/guide/building-extensions.md | 126 ++++++++++++++++++
 test/docs-build.test.ts                       |   2 +-
 2 files changed, 127 insertions(+), 1 deletion(-)
 create mode 100644 docs/src/content/docs/guide/building-extensions.md

diff --git a/docs/src/content/docs/guide/building-extensions.md b/docs/src/content/docs/guide/building-extensions.md
new file mode 100644
index 000000000..15503f3c3
--- /dev/null
+++ b/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.
diff --git a/test/docs-build.test.ts b/test/docs-build.test.ts
index 174ea3c44..c43b1e40c 100644
--- a/test/docs-build.test.ts
+++ b/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', 'extensibility'];
+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'];