docs: Add extensibility and building extensions guides

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 (the 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
+
+- **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](../features/skills.md) — How to author reusable skills
+- [Ceremonies](../features/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,130 @@
+# 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: Client-delivery RFC
+
+[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)
+
+This 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`
+
+---
+
+## Build an extension
+
+Ready to build? See [Building extensions](./building-extensions.md) for a five-minute walkthrough.
+
+---
+
+## 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](../features/plugins.md) — How to browse, install, and share plugins
+- [Skills](../features/skills.md) — How to write skills for your team or plugins
+- [Ceremonies](../features/ceremonies.md) — How to define team meetings and gates
+- [Routing](../features/routing.md) — How to configure work assignment rules
+- [Building extensions](./building-extensions.md) — Step-by-step guide to building and sharing extensions
+- [Contributing](https://github.com/bradygaster/squad/blob/main/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'];