From 9b248644bde5be70071c5fa2adfc21d72d262f0b Mon Sep 17 00:00:00 2001
From: Copilot <223556219+Copilot@users.noreply.github.com>
Date: Mon, 16 Mar 2026 10:35:59 -0700
Subject: [PATCH 1/5] docs: add agent on-disk anatomy concept doc

Developer-oriented guide explaining:
- Directory structure (.squad/agents/{name}/)
- charter.md format and parsing
- history.md append-only learnings
- Casting system (registry, policy, history)
- Relationship between .squad/ runtime and SDK source
- How an agent 'exists' (charter + roster + routing)
- Alumni pattern for retired agents
- Cross-agent context propagation

Requested by Brady via Dina. Addresses the question: 'What does it mean
on disk to be a Squad agent?'

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .../content/docs/concepts/agent-on-disk.md    | 394 ++++++++++++++++++
 1 file changed, 394 insertions(+)
 create mode 100644 docs/src/content/docs/concepts/agent-on-disk.md

diff --git a/docs/src/content/docs/concepts/agent-on-disk.md b/docs/src/content/docs/concepts/agent-on-disk.md
new file mode 100644
index 000000000..e3a425c71
--- /dev/null
+++ b/docs/src/content/docs/concepts/agent-on-disk.md
@@ -0,0 +1,394 @@
+# What It Means on Disk to Be a Squad Agent
+
+> Developer-oriented concept doc: the on-disk anatomy of a Squad agent
+
+## Overview
+
+A Squad agent is not a single file or code module. It's a **distributed identity** spanning three layers:
+
+1. **Runtime state** — `.squad/` directory (team-specific, git-committed)
+2. **SDK infrastructure** — `packages/squad-sdk/src/agents/` (compiled code)
+3. **Configuration** — `squad.config.ts` or `squad.config.json` (optional overrides)
+
+This doc explains how these layers work together to create an agent that can be spawned, collaborate, and accumulate knowledge over time.
+
+## Directory Structure
+
+Each agent exists in `.squad/agents/{name}/`:
+
+```
+.squad/
+└── agents/
+    ├── flight/
+    │   ├── charter.md       # Agent's identity, boundaries, voice
+    │   └── history.md       # Append-only learnings (optional)
+    ├── capcom/
+    │   └── charter.md
+    ├── scribe/
+    │   └── charter.md
+    └── _alumni/
+        └── verbal/          # Retired agents live here
+            └── charter.md
+```
+
+### Key Files
+
+#### `charter.md` — The Agent's DNA
+
+**Who writes it:** The team (usually via a specialist like Procedures, or manually by the team owner).
+
+**Who reads it:** The SDK's charter compiler (`charter-compiler.ts`) at agent spawn time.
+
+**What it contains:**
+
+```markdown
+# {Name} — {Role}
+
+> {One-line personality statement}
+
+## Identity
+- **Name:** Flight
+- **Role:** Lead
+- **Expertise:** Product vision, architecture, code review
+- **Style:** Decisive. Opinionated when it matters.
+
+## What I Own
+- Product direction and architectural decisions
+- Code review and quality gates
+
+## How I Work
+- Architecture decisions compound
+- Proposal-first: meaningful changes need docs/proposals/ before code
+
+## Boundaries
+**I handle:** Architecture, product direction, code review, scope.
+**I don't handle:** Implementation details, test writing, docs, distribution.
+
+## Model
+Preferred: auto
+```
+
+**Parsed sections:**
+- **Identity** → `name`, `role`, `expertise`, `style`
+- **What I Own** → `ownership` (plain text)
+- **Boundaries** → `boundaries` (plain text)
+- **Model** → `modelPreference`, `modelRationale`, `modelFallback`
+
+The charter is compiled into a `SquadCustomAgentConfig` object that includes:
+- The full charter content as the agent's system prompt
+- Parsed metadata (name, role, model preference)
+- Team context (from `team.md`, `routing.md`, `decisions.md`)
+
+**Format expectations:**
+- Markdown headings (`## `) structure the charter
+- The SDK parses specific sections by heading name
+- Freeform content is preserved and passed to the LLM
+- Personality and voice matter — agents have opinions
+
+#### `history.md` — Append-Only Learnings
+
+**Who writes it:** The agent itself, after completing work.
+
+**Who reads it:** The agent, before starting new work (via the charter compiler's history shadow feature).
+
+**What it contains:**
+
+```markdown
+# Flight — Project History
+
+> Knowledge accumulated through leading Squad development.
+
+## Core Context
+
+Three-branch model (main/dev/insiders). Apollo 13 team, 3931 tests. 
+Boundary review heuristic: "Squad Ships It" — if Squad doesn't ship 
+the code, it's IRL content.
+
+## Learnings
+
+### Adoption Tracking Architecture
+Three-tier opt-in system: Tier 1 (aggregate-only, `.github/adoption/`) 
+ships first; Tier 2 (opt-in registry) designed next; Tier 3 (public 
+showcase) launches when ≥5 projects opt in.
+
+### Remote Squad Access
+Three-phase rollout: Phase 1 — GitHub Discussions bot with `/squad` 
+command (1 day, zero hosting). Phase 2 — GitHub Copilot Extension via 
+Contents API (1 week). Phase 3 — Slack/Teams bot (2 weeks).
+```
+
+**What goes in:**
+- Context that persists across sessions (project patterns, established decisions)
+- Learnings that inform future work (what worked, what didn't)
+- Domain-specific knowledge accumulated over time
+
+**What doesn't go in:**
+- Transient task state (use the session-scoped SQL database for that)
+- Raw command output or logs (use `.squad/log/` for session logs)
+- Decisions that affect other agents (those go in `.squad/decisions.md`)
+
+**Format:**
+- Top-level `## Core Context` — stable facts
+- Top-level `## Learnings` — append new `### ` blocks here
+- No deletion — history is append-only
+
+### Alumni — The Retirement Pattern
+
+When an agent is no longer needed, it's moved to `.squad/agents/_alumni/{name}/`:
+
+```
+.squad/agents/_alumni/
+├── verbal/
+│   └── charter.md
+├── kobayashi/
+│   └── charter.md
+└── mcmanus/
+    └── charter.md
+```
+
+**What happens on retirement:**
+1. Agent directory moved from `.squad/agents/{name}/` to `.squad/agents/_alumni/{name}/`
+2. Agent removed from `team.md` roster
+3. Routing rules updated to remove agent from work assignments
+4. Charter preserved for historical reference
+5. Casting name returned to the pool (if using the casting system)
+
+Alumni agents cannot be spawned. Their charters are read-only archives.
+
+## The Casting System
+
+Squad uses a **thematic casting model** to assign memorable names from fictional universes.
+
+### Files
+
+#### `casting-registry.json` — Name Allocation
+
+```json
+{
+  "agents": {
+    "flight": {
+      "universe": "Apollo 13",
+      "character": "Flight Director",
+      "assigned": "2026-02-21T10:00:00Z"
+    }
+  }
+}
+```
+
+**Purpose:** Tracks which names are in use, which universe they're from, and when they were assigned.
+
+**Who manages it:** The casting module (`packages/squad-sdk/src/casting/`).
+
+**Lifecycle:**
+- Name allocated when agent created → entry added
+- Agent retired → entry remains (name not reused within same universe)
+- Universe exhausted → new universe added to `casting-policy.json`
+
+#### `casting-policy.json` — Universe Rules
+
+```json
+{
+  "casting_policy_version": "1.1",
+  "allowlist_universes": [
+    "The Usual Suspects",
+    "Reservoir Dogs",
+    "Alien",
+    "Ocean's Eleven"
+  ],
+  "universe_capacity": {
+    "The Usual Suspects": 6,
+    "Reservoir Dogs": 8,
+    "Alien": 8,
+    "Ocean's Eleven": 14
+  }
+}
+```
+
+**Purpose:** Defines which fictional universes are available and how many names each can provide.
+
+**Who manages it:** The team owner (manually edited when adding new universes).
+
+**Rules:**
+- Each universe has a capacity limit (prevents name dilution)
+- Names must be recognizable characters from that universe
+- No universe mixing on the same team (maintains thematic coherence)
+
+#### `casting-history.json` — Audit Log
+
+```json
+{
+  "universe_usage_history": [
+    {
+      "timestamp": "2026-02-21T10:00:00Z",
+      "universe": "Apollo 13",
+      "agent": "flight",
+      "character": "Flight Director",
+      "action": "assigned"
+    }
+  ],
+  "assignment_cast_snapshots": {}
+}
+```
+
+**Purpose:** Immutable audit trail of all casting decisions.
+
+**Who writes it:** The casting module (append-only).
+
+**Why it matters:** Enables rollback, debugging, and understanding team evolution over time.
+
+## How an Agent "Exists"
+
+An agent is **active** when all three conditions are met:
+
+1. **Charter exists** — `.squad/agents/{name}/charter.md` is present
+2. **Roster entry** — Agent listed in `team.md` with status `✅ Active` or `📋 Silent`
+3. **Routing rules** — Agent appears in `routing.md` work assignments
+
+Without all three, the agent cannot be spawned.
+
+**Spawn flow:**
+
+```
+User request
+    ↓
+Coordinator reads routing.md
+    ↓
+Identifies agent to spawn (e.g., "flight")
+    ↓
+SDK reads .squad/agents/flight/charter.md
+    ↓
+SDK reads .squad/agents/flight/history.md (if exists)
+    ↓
+SDK reads .squad/team.md, routing.md, decisions.md
+    ↓
+Charter compiler builds SquadCustomAgentConfig
+    ↓
+SDK spawns agent with compiled prompt
+    ↓
+Agent runs, writes to history.md after work
+```
+
+## Relationship to SDK Source Files
+
+The `.squad/` directory is **runtime state**, not code. The SDK provides the **infrastructure** to load, parse, and execute agents:
+
+| SDK Module | Purpose |
+|------------|---------|
+| `packages/squad-sdk/src/agents/charter-compiler.ts` | Parses `charter.md` into `SquadCustomAgentConfig` |
+| `packages/squad-sdk/src/agents/history-shadow.ts` | Loads `history.md` and injects into agent context |
+| `packages/squad-sdk/src/agents/lifecycle.ts` | Agent spawn, session management, termination |
+| `packages/squad-sdk/src/agents/model-selector.ts` | Resolves `## Model` preference to actual model |
+| `packages/squad-sdk/src/casting/` | Name allocation, registry management |
+
+**Key insight:** The SDK never hardcodes agent names or roles. It's a generic **agent runtime**. All specificity lives in `.squad/`.
+
+This means:
+- You can add new agents without changing SDK code
+- Multiple projects using the same SDK have different teams
+- Agents can be dynamically added, retired, or renamed
+
+## What About `squad.config.ts`?
+
+The optional `squad.config.ts` file provides **overrides** for charter-based agents:
+
+```typescript
+export default {
+  agents: {
+    flight: {
+      model: 'gpt-4.1', // Override charter's "Preferred: auto"
+      tools: ['read', 'write'], // Restrict tool access
+      extraPrompt: 'Focus on performance trade-offs.' // Append to charter
+    }
+  }
+}
+```
+
+**Merge order (config wins on conflict):**
+1. Charter parsed → base `SquadCustomAgentConfig`
+2. Config overrides applied → merged `SquadCustomAgentConfig`
+3. Team context injected → final prompt sent to LLM
+
+This allows:
+- Per-environment tuning (staging vs production)
+- Temporary restrictions (disable tools during testing)
+- A/B testing different prompts without editing charters
+
+## Cross-Agent Context Propagation
+
+Agents don't share memory. Context flows via **explicit artifacts**:
+
+### `team.md` — Shared Roster
+All agents read this to know who else exists and what they do.
+
+### `routing.md` — Work Assignment Rules
+Defines which agent handles which type of work. Coordinator uses this to route requests.
+
+### `decisions.md` — Canonical Decisions Log
+All agents read this before starting work. It's the shared memory.
+
+### `.squad/decisions/inbox/` — Decision Drop-Box
+Agents write decisions here. Scribe merges them into `decisions.md`.
+
+**Flow:**
+
+```
+Flight makes a decision
+    ↓
+Flight writes .squad/decisions/inbox/flight-api-versioning.md
+    ↓
+Scribe (background agent) runs
+    ↓
+Scribe reads inbox, appends to decisions.md, deletes inbox file
+    ↓
+CAPCOM starts work, reads decisions.md
+    ↓
+CAPCOM sees Flight's decision, respects it
+```
+
+### `.squad/log/` — Session Logs
+Scribe writes session summaries here. Useful for auditing and debugging.
+
+**Example log file:**
+
+```
+.squad/log/2026-03-16T10-00-00-feature-adoption-tracking.md
+```
+
+Contains:
+- Who worked
+- What was done
+- Decisions made
+- Key outcomes
+
+## Key Takeaways
+
+1. **An agent is a directory** — `.squad/agents/{name}/` with at least `charter.md`.
+2. **Charter is the source of truth** — defines identity, boundaries, voice.
+3. **History is optional** — but recommended for agents doing repeated work.
+4. **Casting adds personality** — thematic names make agents memorable.
+5. **SDK is generic infrastructure** — no agent-specific code in the runtime.
+6. **Context flows via files** — `team.md`, `routing.md`, `decisions.md`, `.squad/log/`.
+7. **Retirement is move + remove** — alumni live in `_alumni/`, can't be spawned.
+
+## Developer Checklist: Creating a New Agent
+
+- [ ] Create `.squad/agents/{name}/` directory
+- [ ] Write `charter.md` using `.squad/templates/charter.md` as reference
+- [ ] Add agent to `team.md` roster with status `✅ Active`
+- [ ] Add agent to `routing.md` with work type assignments
+- [ ] (Optional) Allocate name via casting system
+- [ ] (Optional) Create `history.md` if agent needs persistent memory
+- [ ] Test spawn: `squad spawn {name} "Hello, world"`
+
+## Further Reading
+
+- **Charter format reference:** `.squad/templates/charter.md`
+- **Roster format reference:** `.squad/templates/roster.md`
+- **SDK agent infrastructure:** `packages/squad-sdk/src/agents/`
+- **Casting system design:** `packages/squad-sdk/src/casting/`
+
+---
+
+**Author:** Flight  
+**Requested by:** Dina (via Brady)  
+**Date:** 2026-03-16

From cdc6cb26a5d4be2402a91148a48f8df2bdb6e472 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 2/5] 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 d3b7c38f6e909498f1101f50181ab8c59d9a6cbb 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 3/5] 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 38fd744adb456e4dd85a7106978a1d86ab8fae1f Mon Sep 17 00:00:00 2001
From: Copilot <223556219+Copilot@users.noreply.github.com>
Date: Mon, 16 Mar 2026 11:16:42 -0700
Subject: [PATCH 4/5] =?UTF-8?q?docs:=20Compress=20agent-on-disk=20concept?=
 =?UTF-8?q?=20doc=20(298=E2=86=92152=20lines)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Trim verbose explanations, redundant examples, over-explained sections
- Add Human Team Members section (👤 badge, no charter, not spawnable)
- Add @copilot Coding Agent section (🤖 badge, capability profile, copilot-instructions.md)
- Keep essential anatomy: charter, history, casting, SDK relationship
- Target: strategic, small docs per Brady's preference

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .../content/docs/concepts/agent-on-disk.md    | 373 +++++-------------
 1 file changed, 95 insertions(+), 278 deletions(-)

diff --git a/docs/src/content/docs/concepts/agent-on-disk.md b/docs/src/content/docs/concepts/agent-on-disk.md
index e3a425c71..c17f4df8a 100644
--- a/docs/src/content/docs/concepts/agent-on-disk.md
+++ b/docs/src/content/docs/concepts/agent-on-disk.md
@@ -4,17 +4,17 @@
 
 ## Overview
 
-A Squad agent is not a single file or code module. It's a **distributed identity** spanning three layers:
+A Squad agent is a **distributed identity** spanning three layers:
 
 1. **Runtime state** — `.squad/` directory (team-specific, git-committed)
 2. **SDK infrastructure** — `packages/squad-sdk/src/agents/` (compiled code)
 3. **Configuration** — `squad.config.ts` or `squad.config.json` (optional overrides)
 
-This doc explains how these layers work together to create an agent that can be spawned, collaborate, and accumulate knowledge over time.
+This doc explains how these layers work together to create spawnables agents (AI specialists), and how non-spawnables members (humans, @copilot) appear in the team roster.
 
-## Directory Structure
+## AI Agent Directory Structure
 
-Each agent exists in `.squad/agents/{name}/`:
+Each spawnable AI agent exists in `.squad/agents/{name}/`:
 
 ```
 .squad/
@@ -24,10 +24,8 @@ Each agent exists in `.squad/agents/{name}/`:
     │   └── history.md       # Append-only learnings (optional)
     ├── capcom/
     │   └── charter.md
-    ├── scribe/
-    │   └── charter.md
     └── _alumni/
-        └── verbal/          # Retired agents live here
+        └── verbal/          # Retired agents
             └── charter.md
 ```
 
@@ -35,237 +33,68 @@ Each agent exists in `.squad/agents/{name}/`:
 
 #### `charter.md` — The Agent's DNA
 
-**Who writes it:** The team (usually via a specialist like Procedures, or manually by the team owner).
-
-**Who reads it:** The SDK's charter compiler (`charter-compiler.ts`) at agent spawn time.
-
-**What it contains:**
-
-```markdown
-# {Name} — {Role}
-
-> {One-line personality statement}
-
-## Identity
-- **Name:** Flight
-- **Role:** Lead
-- **Expertise:** Product vision, architecture, code review
-- **Style:** Decisive. Opinionated when it matters.
-
-## What I Own
-- Product direction and architectural decisions
-- Code review and quality gates
+Compiled by the SDK at spawn time into the agent's system prompt.
 
-## How I Work
-- Architecture decisions compound
-- Proposal-first: meaningful changes need docs/proposals/ before code
+**Core sections:**
+- **Identity** → name, role, expertise, style
+- **What I Own** → responsibilities (plain text)
+- **How I Work** → patterns, preferences, workflows
+- **Boundaries** → what the agent handles vs. delegates
+- **Model** → preferred model (e.g., `auto`, `gpt-4.1`, `claude-sonnet-4.6`)
 
-## Boundaries
-**I handle:** Architecture, product direction, code review, scope.
-**I don't handle:** Implementation details, test writing, docs, distribution.
-
-## Model
-Preferred: auto
-```
-
-**Parsed sections:**
-- **Identity** → `name`, `role`, `expertise`, `style`
-- **What I Own** → `ownership` (plain text)
-- **Boundaries** → `boundaries` (plain text)
-- **Model** → `modelPreference`, `modelRationale`, `modelFallback`
-
-The charter is compiled into a `SquadCustomAgentConfig` object that includes:
-- The full charter content as the agent's system prompt
-- Parsed metadata (name, role, model preference)
+The charter is parsed into a `SquadCustomAgentConfig` object with:
+- Full charter as system prompt
+- Metadata (name, role, model preference)
 - Team context (from `team.md`, `routing.md`, `decisions.md`)
 
-**Format expectations:**
-- Markdown headings (`## `) structure the charter
-- The SDK parses specific sections by heading name
-- Freeform content is preserved and passed to the LLM
-- Personality and voice matter — agents have opinions
+Personality and voice matter — agents have opinions.
 
 #### `history.md` — Append-Only Learnings
 
-**Who writes it:** The agent itself, after completing work.
-
-**Who reads it:** The agent, before starting new work (via the charter compiler's history shadow feature).
-
-**What it contains:**
-
-```markdown
-# Flight — Project History
-
-> Knowledge accumulated through leading Squad development.
-
-## Core Context
-
-Three-branch model (main/dev/insiders). Apollo 13 team, 3931 tests. 
-Boundary review heuristic: "Squad Ships It" — if Squad doesn't ship 
-the code, it's IRL content.
-
-## Learnings
-
-### Adoption Tracking Architecture
-Three-tier opt-in system: Tier 1 (aggregate-only, `.github/adoption/`) 
-ships first; Tier 2 (opt-in registry) designed next; Tier 3 (public 
-showcase) launches when ≥5 projects opt in.
-
-### Remote Squad Access
-Three-phase rollout: Phase 1 — GitHub Discussions bot with `/squad` 
-command (1 day, zero hosting). Phase 2 — GitHub Copilot Extension via 
-Contents API (1 week). Phase 3 — Slack/Teams bot (2 weeks).
-```
-
-**What goes in:**
-- Context that persists across sessions (project patterns, established decisions)
-- Learnings that inform future work (what worked, what didn't)
-- Domain-specific knowledge accumulated over time
-
-**What doesn't go in:**
-- Transient task state (use the session-scoped SQL database for that)
-- Raw command output or logs (use `.squad/log/` for session logs)
-- Decisions that affect other agents (those go in `.squad/decisions.md`)
-
-**Format:**
-- Top-level `## Core Context` — stable facts
-- Top-level `## Learnings` — append new `### ` blocks here
-- No deletion — history is append-only
-
-### Alumni — The Retirement Pattern
-
-When an agent is no longer needed, it's moved to `.squad/agents/_alumni/{name}/`:
-
-```
-.squad/agents/_alumni/
-├── verbal/
-│   └── charter.md
-├── kobayashi/
-│   └── charter.md
-└── mcmanus/
-    └── charter.md
-```
+Written by the agent after work. Read at spawn time.
 
-**What happens on retirement:**
-1. Agent directory moved from `.squad/agents/{name}/` to `.squad/agents/_alumni/{name}/`
-2. Agent removed from `team.md` roster
-3. Routing rules updated to remove agent from work assignments
-4. Charter preserved for historical reference
-5. Casting name returned to the pool (if using the casting system)
+**Structure:**
+- `## Core Context` — stable project facts
+- `## Learnings` — accumulated patterns and decisions
 
-Alumni agents cannot be spawned. Their charters are read-only archives.
+**What belongs:**
+- Project patterns (e.g., "three-branch model")
+- Domain knowledge (e.g., "boundary review heuristic")
+- Cross-session learnings
 
-## The Casting System
+**What doesn't:**
+- Transient task state (use SQL)
+- Raw logs (use `.squad/log/`)
+- Multi-agent decisions (use `.squad/decisions.md`)
 
-Squad uses a **thematic casting model** to assign memorable names from fictional universes.
+### Alumni — Retirement
 
-### Files
+Retired agents move to `.squad/agents/_alumni/{name}/`. They cannot be spawned. Charters are preserved as read-only archives.
 
-#### `casting-registry.json` — Name Allocation
+## The Casting System (Optional)
 
-```json
-{
-  "agents": {
-    "flight": {
-      "universe": "Apollo 13",
-      "character": "Flight Director",
-      "assigned": "2026-02-21T10:00:00Z"
-    }
-  }
-}
-```
+Squad assigns memorable names from fictional universes:
 
-**Purpose:** Tracks which names are in use, which universe they're from, and when they were assigned.
-
-**Who manages it:** The casting module (`packages/squad-sdk/src/casting/`).
-
-**Lifecycle:**
-- Name allocated when agent created → entry added
-- Agent retired → entry remains (name not reused within same universe)
-- Universe exhausted → new universe added to `casting-policy.json`
-
-#### `casting-policy.json` — Universe Rules
-
-```json
-{
-  "casting_policy_version": "1.1",
-  "allowlist_universes": [
-    "The Usual Suspects",
-    "Reservoir Dogs",
-    "Alien",
-    "Ocean's Eleven"
-  ],
-  "universe_capacity": {
-    "The Usual Suspects": 6,
-    "Reservoir Dogs": 8,
-    "Alien": 8,
-    "Ocean's Eleven": 14
-  }
-}
-```
-
-**Purpose:** Defines which fictional universes are available and how many names each can provide.
-
-**Who manages it:** The team owner (manually edited when adding new universes).
-
-**Rules:**
-- Each universe has a capacity limit (prevents name dilution)
-- Names must be recognizable characters from that universe
-- No universe mixing on the same team (maintains thematic coherence)
+- **`casting-registry.json`** — tracks allocated names, universes, timestamps
+- **`casting-policy.json`** — defines available universes and capacity limits
+- **`casting-history.json`** — immutable audit trail
 
-#### `casting-history.json` — Audit Log
+Names are not reused within the same universe. When a universe is exhausted, a new one is added to the policy.
 
-```json
-{
-  "universe_usage_history": [
-    {
-      "timestamp": "2026-02-21T10:00:00Z",
-      "universe": "Apollo 13",
-      "agent": "flight",
-      "character": "Flight Director",
-      "action": "assigned"
-    }
-  ],
-  "assignment_cast_snapshots": {}
-}
-```
+## How an AI Agent "Exists"
 
-**Purpose:** Immutable audit trail of all casting decisions.
-
-**Who writes it:** The casting module (append-only).
-
-**Why it matters:** Enables rollback, debugging, and understanding team evolution over time.
-
-## How an Agent "Exists"
-
-An agent is **active** when all three conditions are met:
+An AI agent is **active** when:
 
 1. **Charter exists** — `.squad/agents/{name}/charter.md` is present
 2. **Roster entry** — Agent listed in `team.md` with status `✅ Active` or `📋 Silent`
 3. **Routing rules** — Agent appears in `routing.md` work assignments
 
-Without all three, the agent cannot be spawned.
-
 **Spawn flow:**
 
 ```
-User request
-    ↓
-Coordinator reads routing.md
-    ↓
-Identifies agent to spawn (e.g., "flight")
-    ↓
-SDK reads .squad/agents/flight/charter.md
-    ↓
-SDK reads .squad/agents/flight/history.md (if exists)
-    ↓
-SDK reads .squad/team.md, routing.md, decisions.md
-    ↓
-Charter compiler builds SquadCustomAgentConfig
-    ↓
-SDK spawns agent with compiled prompt
-    ↓
-Agent runs, writes to history.md after work
+User request → Coordinator reads routing.md → Identifies agent
+→ SDK reads charter.md, history.md → Compiles SquadCustomAgentConfig
+→ Spawns agent → Agent runs → Writes to history.md
 ```
 
 ## Relationship to SDK Source Files
@@ -287,7 +116,7 @@ This means:
 - Multiple projects using the same SDK have different teams
 - Agents can be dynamically added, retired, or renamed
 
-## What About `squad.config.ts`?
+## Config Overrides
 
 The optional `squad.config.ts` file provides **overrides** for charter-based agents:
 
@@ -295,100 +124,88 @@ The optional `squad.config.ts` file provides **overrides** for charter-based age
 export default {
   agents: {
     flight: {
-      model: 'gpt-4.1', // Override charter's "Preferred: auto"
-      tools: ['read', 'write'], // Restrict tool access
-      extraPrompt: 'Focus on performance trade-offs.' // Append to charter
+      model: 'gpt-4.1', // Override charter
+      tools: ['read', 'write'], // Restrict tools
+      extraPrompt: 'Focus on performance.' // Append to charter
     }
   }
 }
 ```
 
-**Merge order (config wins on conflict):**
-1. Charter parsed → base `SquadCustomAgentConfig`
-2. Config overrides applied → merged `SquadCustomAgentConfig`
-3. Team context injected → final prompt sent to LLM
+**Merge order:** Charter → Config → Team context → Final prompt
 
-This allows:
-- Per-environment tuning (staging vs production)
-- Temporary restrictions (disable tools during testing)
-- A/B testing different prompts without editing charters
+Use cases: per-environment tuning, temporary restrictions, A/B testing.
 
-## Cross-Agent Context Propagation
+## Cross-Agent Context
 
 Agents don't share memory. Context flows via **explicit artifacts**:
 
-### `team.md` — Shared Roster
-All agents read this to know who else exists and what they do.
+- **`team.md`** — Shared roster (who exists, what they do)
+- **`routing.md`** — Work assignment rules (coordinator uses this)
+- **`decisions.md`** — Canonical decisions log (shared memory)
+- **`.squad/decisions/inbox/`** — Decision drop-box (agents write, Scribe merges)
+- **`.squad/log/`** — Session summaries (auditing and debugging)
 
-### `routing.md` — Work Assignment Rules
-Defines which agent handles which type of work. Coordinator uses this to route requests.
+## Human Team Members (👤)
 
-### `decisions.md` — Canonical Decisions Log
-All agents read this before starting work. It's the shared memory.
+Squad supports **human members** in the roster:
 
-### `.squad/decisions/inbox/` — Decision Drop-Box
-Agents write decisions here. Scribe merges them into `decisions.md`.
+```markdown
+| Name | Role | Status | Badge |
+|------|------|--------|-------|
+| dina | Product Manager | ✅ Active | 👤 Human |
+```
 
-**Flow:**
+**Key differences from AI agents:**
+- **No charter** — Humans don't have `.squad/agents/{name}/charter.md`
+- **No history** — Humans don't accumulate `history.md`
+- **Not spawnable** — Coordinator presents work and waits for human input (asynchronous collaboration)
+- **Participate in routing** — Routing rules can assign work to humans (e.g., "UX design → dina")
+- **Code review** — Humans can be listed as required reviewers in routing
 
-```
-Flight makes a decision
-    ↓
-Flight writes .squad/decisions/inbox/flight-api-versioning.md
-    ↓
-Scribe (background agent) runs
-    ↓
-Scribe reads inbox, appends to decisions.md, deletes inbox file
-    ↓
-CAPCOM starts work, reads decisions.md
-    ↓
-CAPCOM sees Flight's decision, respects it
-```
+Humans are roster members but operate asynchronously. The coordinator surfaces work to them and waits.
 
-### `.squad/log/` — Session Logs
-Scribe writes session summaries here. Useful for auditing and debugging.
+## @copilot Coding Agent (🤖)
 
-**Example log file:**
+Squad supports **@copilot** as a roster member:
 
-```
-.squad/log/2026-03-16T10-00-00-feature-adoption-tracking.md
+```markdown
+| Name | Role | Status | Badge |
+|------|------|--------|-------|
+| @copilot | Coding Agent | ✅ Active | 🤖 Coding Agent |
 ```
 
-Contains:
-- Who worked
-- What was done
-- Decisions made
-- Key outcomes
+**Key differences from AI agents:**
+- **No charter** — @copilot uses `copilot-instructions.md` (injected via `.github/copilot-instructions.md`)
+- **Not spawnable** — Works via GitHub issue assignment (asynchronous)
+- **Creates `copilot/*` branches** — Opens draft PRs for review
+- **Capability profile** — Has a 🟢/🟡/🔴 profile in `team.md` (e.g., 🟢 TypeScript, 🟡 Architecture, 🔴 Security audits)
+- **Self-checks before starting** — Reads capability profile, only takes work it's suited for
+
+The coordinator routes work to @copilot by assigning issues. @copilot autonomously picks up work, performs capability checks, and opens PRs.
 
 ## Key Takeaways
 
-1. **An agent is a directory** — `.squad/agents/{name}/` with at least `charter.md`.
-2. **Charter is the source of truth** — defines identity, boundaries, voice.
-3. **History is optional** — but recommended for agents doing repeated work.
-4. **Casting adds personality** — thematic names make agents memorable.
-5. **SDK is generic infrastructure** — no agent-specific code in the runtime.
-6. **Context flows via files** — `team.md`, `routing.md`, `decisions.md`, `.squad/log/`.
-7. **Retirement is move + remove** — alumni live in `_alumni/`, can't be spawned.
+1. **AI agents are directories** — `.squad/agents/{name}/` with `charter.md`
+2. **Charter is source of truth** — identity, boundaries, voice
+3. **History is optional** — recommended for repeated work
+4. **Casting adds personality** — thematic names (Apollo 13, Ocean's Eleven)
+5. **SDK is generic** — no agent-specific code in the runtime
+6. **Context flows via files** — `team.md`, `routing.md`, `decisions.md`
+7. **Humans and @copilot are roster members** — but not spawnable
 
-## Developer Checklist: Creating a New Agent
+## Developer Checklist: Creating a New AI Agent
 
 - [ ] Create `.squad/agents/{name}/` directory
-- [ ] Write `charter.md` using `.squad/templates/charter.md` as reference
-- [ ] Add agent to `team.md` roster with status `✅ Active`
-- [ ] Add agent to `routing.md` with work type assignments
+- [ ] Write `charter.md` (use `.squad/templates/charter.md`)
+- [ ] Add to `team.md` roster with status `✅ Active`
+- [ ] Add to `routing.md` with work type assignments
 - [ ] (Optional) Allocate name via casting system
-- [ ] (Optional) Create `history.md` if agent needs persistent memory
+- [ ] (Optional) Create `history.md` for persistent memory
 - [ ] Test spawn: `squad spawn {name} "Hello, world"`
 
-## Further Reading
-
-- **Charter format reference:** `.squad/templates/charter.md`
-- **Roster format reference:** `.squad/templates/roster.md`
-- **SDK agent infrastructure:** `packages/squad-sdk/src/agents/`
-- **Casting system design:** `packages/squad-sdk/src/casting/`
-
 ---
 
-**Author:** Flight  
-**Requested by:** Dina (via Brady)  
+**Author:** Flight
+**Requested by:** Dina (via Brady)
 **Date:** 2026-03-16

From b66f08b4df7bb217446a623b5cd569119ab5949b Mon Sep 17 00:00:00 2001
From: Copilot <223556219+Copilot@users.noreply.github.com>
Date: Mon, 16 Mar 2026 11:18:08 -0700
Subject: [PATCH 5/5] chore(flight): add doc compression pattern to history

---
 .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 439ac9325..9f4bdae37 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/`.
 
+### Doc Compression Patterns (2026-03-16)
+**Surgical trimming:** When compressing verbose docs (298→152 lines, ~49%), cut who-writes-it/who-reads-it sections, redundant examples, over-explained flows. Keep essential anatomy and code structures. **Human and @copilot coverage:** Squad supports non-spawnable roster members: humans (👤 badge, no charter/history, coordinator waits for input) and @copilot (🤖 badge, uses copilot-instructions.md, capability profile, async via issue assignment). Both participate in routing and reviews. **Strategic docs:** Brady wants small, focused concept docs. Add new sections only when expanding coverage (human members, coding agents) — don't inflate with verbose explanations.
+