diff --git a/docs/src/content/docs/features/coordinator-as-agent-export.md b/docs/src/content/docs/features/coordinator-as-agent-export.md new file mode 100644 index 000000000..8ad8179c5 --- /dev/null +++ b/docs/src/content/docs/features/coordinator-as-agent-export.md @@ -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 `` 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 diff --git a/docs/src/content/docs/features/cross-squad-discover.md b/docs/src/content/docs/features/cross-squad-discover.md new file mode 100644 index 000000000..6912a14e0 --- /dev/null +++ b/docs/src/content/docs/features/cross-squad-discover.md @@ -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 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 ""` + +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 `. | +| `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 ` 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 diff --git a/docs/src/content/docs/features/preset.md b/docs/src/content/docs/features/preset.md new file mode 100644 index 000000000..e39d7d3c8 --- /dev/null +++ b/docs/src/content/docs/features/preset.md @@ -0,0 +1,205 @@ +--- +title: Presets — Curated Agent Collections +description: Save, share, and apply pre-configured agent rosters across projects with squad preset commands. +--- + +# Presets — Curated Agent Collections + +> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. + +**Try this to see available presets:** +```bash +squad preset list +``` + +**Try this to apply a preset to a new project:** +```bash +squad init --preset backend-team +``` + +Presets are reusable, named bundles of agent charters you can apply to any squad. Built-in presets ship with Squad; you can save your own from any project's current agents and (optionally) sync them across machines via a private GitHub repo. + +Each preset is a directory at `~/.squad/presets//` containing a `preset.json` manifest and `agents/` charter files. The preset name is the directory name. + +--- + +## What presets capture + +Presets capture **agents only** (charters). For full squad snapshots including casting state, skills, routing rules, and decisions — for example to share a configured squad or publish to an agent toolbox — use [`squad export`](/squad/docs/features/export-import/) instead. + +| Captured by preset | NOT captured by preset | +|---|---| +| Agent charters (role, expertise, prompt style) | Casting state (registry, history) | +| Agent count + composition | `routing.md` rules | +| Built-in agent names + descriptions | `decisions.md` ledger | +| | Skills (`.copilot/skills/`) | +| | Ceremonies | +| | Memory (`.squad/memory/`) | + +This split is intentional. Presets are about the **shape** of a team. Skills, decisions, and history are about the **work** that team did. + +--- + +## Commands + +### `squad preset list` + +Show every preset available in your squad home (`~/.squad/presets/`): + +```bash +$ squad preset list + +Available Presets (3): + + Name Agents Description + ─────────────── ────── ──────────────────────────────────────── + backend-team 4 Backend-focused squad: lead, API, DB, QA + full-stack 6 Full-stack web app: lead, FE, BE, design, QA, devops + data-engineering 4 Data pipeline squad: lead, ETL, ML, QA +``` + +If no presets directory exists yet, you'll be prompted to run `squad preset init`. + +### `squad preset show ` + +Inspect a preset's manifest and agents before applying: + +```bash +$ squad preset show backend-team + +backend-team v1.0.0 + Backend-focused squad: lead, API, DB, QA + Author: bradygaster + Tags: backend, api + + Agents (4): + • lead (Lead) — owns architecture, scope, and code review + • api (Backend Dev) — REST endpoints, validation, error handling + • db (Database Engineer) — schema, migrations, query optimization + • qa (Tester) — test coverage, edge cases, CI/CD +``` + +### `squad preset apply [--force]` + +Install the preset's agents into the current squad. The current directory must be a Squad project (have a `.squad/` directory). + +```bash +squad preset apply backend-team +``` + +This copies the preset's `agents/` directory into your project's `.squad/agents/`. Existing agents with the same names are **NOT** overwritten unless you pass `--force`. + +### `squad preset save [--force] [--description "..."]` + +Save your current project's agents as a new preset: + +```bash +squad preset save my-team --description "My favorite roster for greenfield projects" +``` + +This snapshots the agents from the current squad's `.squad/agents/` directory into `~/.squad/presets/my-team/` along with a `preset.json` manifest. Pass `--force` to overwrite an existing preset of the same name. + +### `squad preset init [--remote]` + +Initialize the presets directory in your squad home (`~/.squad/presets/`). + +- **Local-only** (`squad preset init`) — creates the directory and seeds the built-in presets +- **Remote-synced** (`squad preset init --remote`) — creates the directory, seeds built-ins, AND creates a private GitHub repo (`{your-gh-user}/squad-home`) backing the directory so presets sync across machines + +Requirements for `--remote`: +- GitHub CLI (`gh`) installed and authenticated (`gh auth login`) +- Permission to create private repos + +On a second machine, run `squad preset init --remote` again and it will detect and clone your existing `squad-home` repo automatically. + +--- + +## Applying a preset at init time + +The most common usage — bootstrap a new project with a preset team: + +```bash +mkdir my-new-project +cd my-new-project +git init +squad init --preset backend-team +``` + +This creates the standard `.squad/` scaffold AND applies the preset's agents. If `~/.squad/presets/` doesn't exist yet, `squad init` auto-runs `squad preset init` first to seed the built-in presets. + +--- + +## Cross-machine workflow + +Use the remote-backed setup if you want presets to follow you to new machines or shared dev environments: + +```bash +# Machine A — initial setup +squad preset init --remote +squad preset save my-team --description "My standard team" + +# Machine B — same user, same GitHub account +squad preset init --remote # detects existing squad-home repo, clones it +squad preset list # my-team is already here +``` + +The remote repo lives at `https://github.com//squad-home` (private by default). + +--- + +## Sharing presets between users + +Today, the simplest path to share a preset with someone else is: + +1. They run `squad preset init --remote` to set up their own squad home +2. You manually copy the preset directory across (or clone yours, copy the directory in, push) + +A formal "publish/install from another user's repo" flow is on the roadmap but not in v0.10. + +For collaborative team rosters that go beyond just agents (skills, decisions, routing), use [`squad export`](/squad/docs/features/export-import/) instead. + +--- + +## What's in a preset directory + +``` +~/.squad/presets/backend-team/ +├── preset.json # manifest (name, version, description, tags, agents list) +└── agents/ + ├── lead/ + │ └── charter.md + ├── api/ + │ └── charter.md + ├── db/ + │ └── charter.md + └── qa/ + └── charter.md +``` + +The `preset.json` manifest format: + +```json +{ + "name": "backend-team", + "version": "1.0.0", + "description": "Backend-focused squad: lead, API, DB, QA", + "author": "bradygaster", + "tags": ["backend", "api"], + "agents": [ + { "name": "lead", "role": "Lead", "description": "owns architecture, scope, and code review" }, + { "name": "api", "role": "Backend Dev", "description": "REST endpoints, validation, error handling" }, + { "name": "db", "role": "Database Engineer", "description": "schema, migrations, query optimization" }, + { "name": "qa", "role": "Tester", "description": "test coverage, edge cases, CI/CD" } + ] +} +``` + +You can hand-edit this file to refine descriptions or add/remove agents — but the corresponding `agents//charter.md` files must match. + +--- + +## See also + +- [Export & Import](/squad/docs/features/export-import/) — full squad snapshots including state +- [Skills](/squad/docs/features/skills/) — earned knowledge (separate from presets) +- [Plugin Marketplace](/squad/docs/features/plugins/) — community-curated bundles