bradygaster · tamirdresher · Jun 14, 2026 · Jun 11, 2026
@@ -0,0 +1,237 @@
+---
+title: Coordinator-as-Agent Export
+description: Compile your squad's coordinator into a repo-native Copilot custom agent file with squad export agent.
+---
+
+# Coordinator-as-Agent Export
+
+> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases.
+
+**Try this to generate a coordinator agent:**
+```bash
+squad export agent
+```
+
+**Try this for CI drift detection:**
+```bash
+squad export agent --check
+```
+
+**Try this for live development:**
+```bash
+squad export agent --watch
+```
+
+`squad export agent` compiles your `.squad/` state — team roster, routing rules, ceremony triggers, agent charters — into a single repository-native Copilot custom agent at `.github/agents/squad.md`. The generated file works across **every** Copilot surface (CLI, VS Code, GitHub Desktop, github.com) without requiring the Squad runtime installed.
+
+This is the "ship Squad as a portable agent" path. Use it when you want collaborators or downstream repos to get the benefit of your squad's setup with **zero install** — they just check out the repo and the agent is available.
+
+---
+
+## When to use it
+
+| Scenario | Use `squad export agent`? |
+|----------|-----------------------|
+| You want collaborators to use your team's coordinator without installing the CLI | ✅ Yes |
+| You want a portable, version-controlled snapshot of your coordinator behavior | ✅ Yes |
+| You want CI to enforce that `.github/agents/squad.md` stays in sync with `.squad/` | ✅ Yes — use `--check` |
+| You need full Squad runtime features (Scribe, Ralph, MCP state tools, ceremonies) | ❌ No — install the CLI |
+| You want to share state (decisions, history) not just coordinator behavior | ❌ No — use [`squad export`](/squad/docs/features/export-import/) (snapshot mode) |
+
+The exported coordinator agent has access to the team's roster and routing logic but does NOT include the live Squad runtime. Sub-agents in the exported coordinator will be dispatched via Copilot's native `task` tool, not via Squad's full spawn machinery.
+
+---
+
+## Commands
+
+### `squad export agent`
+
+Generate or update `.github/agents/squad.md` from your current `.squad/` state:
+
+```bash
+$ squad export agent
+
+🔧 Compiling coordinator agent...
+   - Read team.md (8 members)
+   - Read routing.md (24 work-type entries)
+   - Read ceremonies.md (3 ceremonies)
+   - Loaded 8 agent charters
+   - Compiled prompt: 12,847 tokens (under 14k soft budget — full mode)
+   - Wrote .github/agents/squad.md (38,294 bytes)
+
+✓ Coordinator exported to .github/agents/squad.md
+```
+
+The output is a self-contained Copilot custom-agent file with proper YAML frontmatter and a compiled coordinator prompt. Anyone in the repo can now run `copilot --agent squad` and get the coordinator's behavior.
+
+### `squad export agent --watch`
+
+Re-export on every change to `.squad/`. Useful during active team development when you want the exported agent file to track your edits:
+
+```bash
+$ squad export agent --watch
+👀 Watching .squad/ for changes...
+✓ .github/agents/squad.md up to date
+
+[edit .squad/routing.md]
+🔄 .squad/routing.md changed — re-exporting...
+✓ .github/agents/squad.md updated (38,401 bytes)
+```
+
+Press `Ctrl+C` to stop.
+
+### `squad export agent --check`
+
+Verify that `.github/agents/squad.md` is in sync with the current `.squad/` state. Exits with non-zero if drift is detected. Use this in CI to enforce "if you change `.squad/`, you must re-run `squad export agent`":
+
+```bash
+$ squad export agent --check
+
+✓ .github/agents/squad.md is up to date
+
+# Or, on drift:
+
+✗ Drift detected:
+   .squad/routing.md changed but .github/agents/squad.md not regenerated.
+   Run 'squad export agent' to update.
+exit 1
+```
+
+### `squad export agent --dry-run`
+
+Preview what would be written without actually writing the file:
+
+```bash
+$ squad export agent --dry-run
+
+🔍 DRY RUN — would write to .github/agents/squad.md:
+   Size: 38,294 bytes
+   Prompt tokens: ~12,847
+   Mode: full
+   Frontmatter:
+     name: squad
+     description: ...
+   No changes made.
+```
+
+### `squad export agent --compact`
+
+Force compact mode even if the prompt fits within the soft budget. Useful for keeping the generated file lean intentionally:
+
+```bash
+squad export agent --compact
+```
+
+Compact mode omits some optional sections (extended examples, on-demand reference pointers) and is the default when the prompt would otherwise exceed the soft token budget.
+
+---
+
+## Token budget modes
+
+The exporter adapts automatically to your team size:
+
+| Mode | Trigger | What's in the prompt |
+|------|---------|---------------------|
+| **Full** | ≤8 members AND prompt < 14k tokens | Full charters inlined, all routing tables, complete ceremony definitions |
+| **Compact** | Prompt 14k–20k tokens OR `--compact` flag | Condensed charters, abbreviated examples, on-demand references |
+| **Lazy-load** | >8 members OR roster > 3k tokens | Coordinator instructed to load charters on demand at dispatch time |
+| **(fails)** | Prompt > 20k hard budget | Fails with diagnostics — suggests removing rarely-used members or splitting the squad |
+
+These thresholds protect against generating a coordinator file that's too large for the LLM's context budget. If you hit the hard limit, the exporter prints actionable diagnostics:
+
+```
+✗ Coordinator prompt exceeds hard budget (22,841 / 20,000 tokens).
+  Top contributors:
+    - 8 large agent charters (avg 1,800 tokens each)
+    - Routing table: 24 entries
+
+  Suggestions:
+    - Remove rarely-spawned members from .squad/team.md
+    - Trim agent charter narrative sections (target: 1,500 tokens/charter)
+    - Split into multiple squads (see Multiple Squads docs)
+    - Use --compact to drop ~2k tokens
+```
+
+---
+
+## Safety guarantees
+
+The exporter is conservative about what it writes:
+
+- **Won't overwrite user-owned agent files.** If `.github/agents/squad.md` exists and lacks the generated-file marker comment header, the export fails unless you pass `--force`.
+- **Detects legacy `squad.agent.md` collisions.** The classic Squad CLI installation puts the coordinator at `.github/agents/squad.agent.md`. The export warns if both files would exist, and `squad init`/`squad upgrade` skip writing `squad.agent.md` when an exported `squad.md` is present.
+- **Generated files are marked.** The output starts with `<!-- generated by squad export agent — do not edit -->` so the file is unambiguous.
+- **`--check` mode never mutates.** Safe to run on every CI build.
+
+---
+
+## CI integration
+
+The pattern most teams use:
+
+```yaml
+# .github/workflows/squad-drift-check.yml
+name: Squad drift check
+on:
+  pull_request:
+    paths: ['.squad/**', '.github/agents/squad.md']
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: '22' }
+      - run: npm install -g @bradygaster/squad-cli
+      - run: squad export agent --check
+```
+
+If anyone changes `.squad/` without re-exporting, the PR fails CI with a clear message.
+
+---
+
+## What gets compiled into the exported agent
+
+The exporter loads these sources from your `.squad/`:
+
+| File | Used for |
+|------|----------|
+| `.squad/team.md` | Roster — agent names, roles, charter paths |
+| `.squad/routing.md` | Work-type → agent and module-ownership mappings |
+| `.squad/ceremonies.md` | Auto-trigger definitions for design review, retro, etc. |
+| `.squad/config.json` | State backend selection, model preferences |
+| `.squad/agents/{name}/charter.md` | Per-agent role definitions (inlined or referenced based on budget mode) |
+
+These get rendered into the output as:
+
+- **YAML frontmatter** — `name`, `description`, `model`, `tools` declarations
+- **Coordinator prompt body** — dispatch rules, routing table, ceremony triggers, agent identities, response mode selection
+- **On-demand reference markers** — pointers to charters in lazy-load mode
+
+What's NOT compiled in:
+- Decisions ledger (use snapshot export to share state)
+- Agent histories (personal learnings, owner-only)
+- Skills (live as separate files in `.copilot/skills/`)
+- Casting state (registry, history)
+
+---
+
+## Architecture (for the curious)
+
+The export pipeline lives at `packages/squad-sdk/src/repo-native/`:
+
+1. **Context loader** — parses `.squad/` files into a typed IR
+2. **Prompt compiler** — renders the coordinator prompt with budget enforcement
+3. **Frontmatter renderer** — emits valid custom-agent YAML
+4. **File writer** — handles safety checks and atomic write
+
+You can use the SDK module directly if you want to embed coordinator export into your own tooling — see `@bradygaster/squad-sdk/repo-native`.
+
+---
+
+## See also
+
+- [Export & Import](/squad/docs/features/export-import/) — full state snapshots (different from this)
+- [Self Upgrade](/squad/docs/features/self-upgrade/) — keeping the CLI itself updated
+- [Multiple Squads](/squad/docs/scenarios/multiple-squads/) — when one team gets too large
+- [Team Setup](/squad/docs/features/team-setup/) — composing the team that gets exported
@@ -0,0 +1,158 @@
+---
+title: Cross-Squad Discover & Delegate
+description: Discover other squads across repository boundaries and delegate work to them via squad discover and squad delegate.
+---
+
+# Cross-Squad Discover & Delegate
+
+> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases.
+
+**Try this to see what squads you can reach:**
+```bash
+squad discover
+```
+
+**Try this to send work to another squad:**
+```bash
+squad delegate platform-squad "Add monitoring dashboard for the auth service"
+```
+
+When you have multiple Squad-enabled repositories — a platform squad, a frontend squad, a data squad — you often need to ask the other squad to do something for you. Cross-squad orchestration lets a squad **discover** other squads and **delegate** issues to them, with proper labels and contact info, so the right team picks it up automatically.
+
+Both commands work via GitHub issues — no shared infrastructure required. Each squad's manifest declares what it accepts and how to reach it.
+
+---
+
+## How it works
+
+Each squad publishes a `.squad/manifest.json` file declaring:
+- Its name and capabilities (e.g., `kubernetes`, `helm`, `monitoring`)
+- Its GitHub repo (the contact)
+- The labels to apply to cross-squad issues
+- What work types it accepts (`issues`, `prs`)
+- Named skills it offers
+
+When you run `squad discover`, Squad reads manifests from:
+- **Upstream** — repos declared in your `.squad/upstreams/`
+- **Registry** — any registry sources configured
+- **Local** — manifests inside the current repo
+
+When you run `squad delegate <squad> "<description>"`, Squad finds the target manifest, creates a properly-labeled GitHub issue in its repo, and includes structured cross-squad metadata so the other squad's coordinator picks it up correctly.
+
+---
+
+## Commands
+
+### `squad discover`
+
+List known squads and their capabilities:
+
+```bash
+$ squad discover
+
+Discovered Squads (3):
+
+  Name             Capabilities                Repo                    Accepts
+  ──────────────   ──────────────────────────  ──────────────────────  ────────
+  platform-squad   kubernetes, helm, infra     myorg/platform          issues
+  frontend-squad   react, design-system, ui    myorg/web-app           issues
+  data-squad       etl, dbt, pipelines, ml     myorg/data-platform     issues, prs
+```
+
+If no squads are discovered, the output reminds you to configure upstreams or check that other repos have published `manifest.json` files.
+
+### `squad delegate <squad-name> "<description>"`
+
+Create a cross-squad work request in another squad's repository:
+
+```bash
+squad delegate platform-squad "Add Grafana dashboards for the auth service's p95 latency"
+```
+
+This creates an issue in `myorg/platform` titled `[cross-squad] Add Grafana dashboards...` with:
+- Squad's discovered labels applied automatically
+- A structured body with the originating repo, target squad, description, and acceptance criteria
+- The created issue's URL printed to your terminal
+
+Required:
+- The target squad's manifest must include the work type — `accepts: ["issues"]` for the default delegation flow
+- GitHub CLI (`gh`) installed and authenticated with permission to create issues in the target repo
+
+---
+
+## Publishing a manifest for your own squad
+
+To make your squad discoverable by others, create `.squad/manifest.json`:
+
+```json
+{
+  "name": "platform-squad",
+  "version": "1.0.0",
+  "description": "Infrastructure, Kubernetes, and platform services",
+  "capabilities": ["kubernetes", "helm", "monitoring", "infra"],
+  "contact": {
+    "repo": "myorg/platform",
+    "labels": ["cross-squad", "needs-triage"]
+  },
+  "accepts": ["issues"],
+  "skills": ["k8s-deployment", "helm-chart-authoring", "prometheus-alerting"]
+}
+```
+
+| Field | Required | Notes |
+|-------|----------|-------|
+| `name` | ✅ | Human-readable name (e.g., `platform-squad`). Used in `squad delegate <name>`. |
+| `version` | optional | Schema version for forward compatibility |
+| `description` | optional | One-line summary shown in `discover` output |
+| `capabilities` | ✅ | Tags other squads use to find you (`squad discover` filters here in future versions) |
+| `contact.repo` | ✅ | GitHub repo in `owner/repo` format where issues get created |
+| `contact.labels` | optional | Labels applied to every cross-squad issue (so your triage automation can find them) |
+| `accepts` | ✅ | Work types: `["issues"]`, `["prs"]`, or both |
+| `skills` | optional | Named skills your squad offers — informational today, filterable in future |
+
+Commit `manifest.json` to your repo's `.squad/` directory and push. Other squads that have your repo in their upstream list will pick it up on next `squad discover`.
+
+---
+
+## What the delegated issue looks like
+
+When `squad delegate` creates an issue, it uses this structured body so the receiving squad's coordinator can recognize and route it correctly:
+
+```markdown
+## Cross-Squad Work Request
+
+**From:** this repository
+**To:** platform-squad (myorg/platform)
+
+### Description
+
+Add Grafana dashboards for the auth service's p95 latency
+
+### Acceptance Criteria
+
+- [ ] Work completed and verified
+- [ ] Originating squad notified of completion
+
+*Created by squad cross-squad orchestration*
+```
+
+The receiving squad sees an issue with their `cross-squad` (and any custom) labels, structured metadata in the body, and clear acceptance criteria.
+
+---
+
+## Limitations in v0.10
+
+- **No automatic completion notification.** When the receiving squad closes the issue, the originating squad doesn't get notified back automatically. Today you watch the issue manually or via standard GitHub notifications.
+- **Discovery is upstream-driven.** A squad has to know about another squad (via an upstream declaration) before `discover` can see it. There's no global registry.
+- **No capability filtering on delegate.** `squad delegate <name>` requires the exact squad name. You can't say "delegate this to any squad that has the `kubernetes` capability" — yet.
+- **PRs aren't supported in the default flow.** Even though manifests can declare `accepts: ["prs"]`, the v0.10 `delegate` command only creates issues.
+
+These are tracked for follow-up. For now, cross-squad orchestration is a useful but minimal MVP — it removes the "where do I file this?" friction and ensures the right team gets a properly-formatted request.
+
+---
+
+## See also
+
+- [Distributed Mesh](/squad/docs/features/distributed-mesh/) — the broader cross-repo coordination architecture
+- [Multiple Squads](/squad/docs/scenarios/multiple-squads/) — running several squads in one organization
+- [Upstream Inheritance](/squad/docs/features/upstream-inheritance/) — how upstreams get discovered