@bradygaster/squad-sdk 0.8.25 → 0.9.1

package/templates/mcp-config.md

@@ -1,98 +1,90 @@
-# MCP Integration — Configuration and Samples
-
-MCP (Model Context Protocol) servers extend Squad with tools for external services — Trello, Aspire dashboards, Azure, Notion, and more. The user configures MCP servers in their environment; Squad discovers and uses them.
-
-> **Full patterns:** Read `.squad/skills/mcp-tool-discovery/SKILL.md` for discovery patterns, domain-specific usage, and graceful degradation.
-
-## Security Considerations
-
-> ⚠️ **Important:** The sample configs below use `npx -y` to run MCP server packages without version pinning. For production use:
-> - **Pin versions:** Use `npx -y @trello/mcp-server@1.2.3` instead of bare package names
-> - **Audit packages:** Review MCP server source code before granting access to credentials
-> - **Use least-privilege tokens:** Create tokens with minimal required scopes
-> - **Consider local installs:** Install packages locally (`npm install`) rather than fetching on each run
-
-## Config File Locations
-
-Users configure MCP servers at these locations (checked in priority order):
-1. **Repository-level:** `.copilot/mcp-config.json` (team-shared, committed to repo)
-2. **Workspace-level:** `.vscode/mcp.json` (VS Code workspaces)
-3. **User-level:** `~/.copilot/mcp-config.json` (personal)
-4. **CLI override:** `--additional-mcp-config` flag (session-specific)
-
-## Sample Config — Trello
-
-```json
-{
-  "mcpServers": {
-    "trello": {
-      "command": "npx",
-      "args": ["-y", "@trello/mcp-server"],
-      "env": {
-        "TRELLO_API_KEY": "${TRELLO_API_KEY}",
-        "TRELLO_TOKEN": "${TRELLO_TOKEN}"
-      }
-    }
-  }
-}
-```
-
-## Sample Config — GitHub
-
-```json
-{
-  "mcpServers": {
-    "github": {
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-github"],
-      "env": {
-        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
-      }
-    }
-  }
-}
-```
-
-## Sample Config — Azure
-
-```json
-{
-  "mcpServers": {
-    "azure": {
-      "command": "npx",
-      "args": ["-y", "@azure/mcp-server"],
-      "env": {
-        "AZURE_SUBSCRIPTION_ID": "${AZURE_SUBSCRIPTION_ID}",
-        "AZURE_CLIENT_ID": "${AZURE_CLIENT_ID}",
-        "AZURE_CLIENT_SECRET": "${AZURE_CLIENT_SECRET}",
-        "AZURE_TENANT_ID": "${AZURE_TENANT_ID}"
-      }
-    }
-  }
-}
-```
-
-## Sample Config — Aspire
-
-```json
-{
-  "mcpServers": {
-    "aspire": {
-      "command": "npx",
-      "args": ["-y", "@aspire/mcp-server"],
-      "env": {
-        "ASPIRE_DASHBOARD_URL": "${ASPIRE_DASHBOARD_URL}"
-      }
-    }
-  }
-}
-```
-
-## Authentication Notes
-
-- **GitHub MCP requires a separate token** from the `gh` CLI auth. Generate at https://github.com/settings/tokens
-- **Trello requires API key + token** from https://trello.com/power-ups/admin
-- **Azure requires service principal credentials** — see Azure docs for setup
-- **Aspire uses the dashboard URL** — typically `http://localhost:18888` during local dev
-
-Auth is a real blocker for some MCP servers. Users need separate tokens for GitHub MCP, Azure MCP, Trello MCP, etc. This is a documentation problem, not a code problem.
+# MCP Integration — Configuration and Samples
+
+MCP (Model Context Protocol) servers extend Squad with tools for external services — Trello, Aspire dashboards, Azure, Notion, and more. The user configures MCP servers in their environment; Squad discovers and uses them.
+
+> **Full patterns:** Read `.squad/skills/mcp-tool-discovery/SKILL.md` for discovery patterns, domain-specific usage, and graceful degradation.
+
+## Config File Locations
+
+Users configure MCP servers at these locations (checked in priority order):
+1. **Repository-level:** `.copilot/mcp-config.json` (team-shared, committed to repo)
+2. **Workspace-level:** `.vscode/mcp.json` (VS Code workspaces)
+3. **User-level:** `~/.copilot/mcp-config.json` (personal)
+4. **CLI override:** `--additional-mcp-config` flag (session-specific)
+
+## Sample Config — Trello
+
+```json
+{
+  "mcpServers": {
+    "trello": {
+      "command": "npx",
+      "args": ["-y", "@trello/mcp-server"],
+      "env": {
+        "TRELLO_API_KEY": "${TRELLO_API_KEY}",
+        "TRELLO_TOKEN": "${TRELLO_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+## Sample Config — GitHub
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+## Sample Config — Azure
+
+```json
+{
+  "mcpServers": {
+    "azure": {
+      "command": "npx",
+      "args": ["-y", "@azure/mcp-server"],
+      "env": {
+        "AZURE_SUBSCRIPTION_ID": "${AZURE_SUBSCRIPTION_ID}",
+        "AZURE_CLIENT_ID": "${AZURE_CLIENT_ID}",
+        "AZURE_CLIENT_SECRET": "${AZURE_CLIENT_SECRET}",
+        "AZURE_TENANT_ID": "${AZURE_TENANT_ID}"
+      }
+    }
+  }
+}
+```
+
+## Sample Config — Aspire
+
+```json
+{
+  "mcpServers": {
+    "aspire": {
+      "command": "npx",
+      "args": ["-y", "@aspire/mcp-server"],
+      "env": {
+        "ASPIRE_DASHBOARD_URL": "${ASPIRE_DASHBOARD_URL}"
+      }
+    }
+  }
+}
+```
+
+## Authentication Notes
+
+- **GitHub MCP requires a separate token** from the `gh` CLI auth. Generate at https://github.com/settings/tokens
+- **Trello requires API key + token** from https://trello.com/power-ups/admin
+- **Azure requires service principal credentials** — see Azure docs for setup
+- **Aspire uses the dashboard URL** — typically `http://localhost:18888` during local dev
+
+Auth is a real blocker for some MCP servers. Users need separate tokens for GitHub MCP, Azure MCP, Trello MCP, etc. This is a documentation problem, not a code problem.

package/templates/multi-agent-format.md

@@ -1,28 +1,28 @@
-# Multi-Agent Artifact Format
-
-When multiple agents contribute to a final artifact (document, analysis, design), use this format. The assembled result must include:
-
-- Termination condition
-- Constraint budgets (if active)
-- Reviewer verdicts (if any)
-- Raw agent outputs appendix
-
-## Assembly Structure
-
-The assembled result goes at the top. Below it, include:
-
-```
-## APPENDIX: RAW AGENT OUTPUTS
-
-### {Name} ({Role}) — Raw Output
-{Paste agent's verbatim response here, unedited}
-
-### {Name} ({Role}) — Raw Output
-{Paste agent's verbatim response here, unedited}
-```
-
-## Appendix Rules
-
-This appendix is for diagnostic integrity. Do not edit, summarize, or polish the raw outputs. The Coordinator may not rewrite raw agent outputs; it may only paste them verbatim and assemble the final artifact above.
-
-See `.squad/templates/run-output.md` for the complete output format template.
+# Multi-Agent Artifact Format
+
+When multiple agents contribute to a final artifact (document, analysis, design), use this format. The assembled result must include:
+
+- Termination condition
+- Constraint budgets (if active)
+- Reviewer verdicts (if any)
+- Raw agent outputs appendix
+
+## Assembly Structure
+
+The assembled result goes at the top. Below it, include:
+
+```
+## APPENDIX: RAW AGENT OUTPUTS
+
+### {Name} ({Role}) — Raw Output
+{Paste agent's verbatim response here, unedited}
+
+### {Name} ({Role}) — Raw Output
+{Paste agent's verbatim response here, unedited}
+```
+
+## Appendix Rules
+
+This appendix is for diagnostic integrity. Do not edit, summarize, or polish the raw outputs. The Coordinator may not rewrite raw agent outputs; it may only paste them verbatim and assemble the final artifact above.
+
+See `.squad/templates/run-output.md` for the complete output format template.

package/templates/orchestration-log.md

@@ -1,27 +1,27 @@
-# Orchestration Log Entry
-
-> One file per agent spawn. Saved to `.squad/orchestration-log/{timestamp}-{agent-name}.md`
-
----
-
-### {timestamp} — {task summary}
-
-| Field | Value |
-|-------|-------|
-| **Agent routed** | {Name} ({Role}) |
-| **Why chosen** | {Routing rationale — what in the request matched this agent} |
-| **Mode** | {`background` / `sync`} |
-| **Why this mode** | {Brief reason — e.g., "No hard data dependencies" or "User needs to approve architecture"} |
-| **Files authorized to read** | {Exact file paths the agent was told to read} |
-| **File(s) agent must produce** | {Exact file paths the agent is expected to create or modify} |
-| **Outcome** | {Completed / Rejected by {Reviewer} / Escalated} |
-
----
-
-## Rules
-
-1. **One file per agent spawn.** Named `{timestamp}-{agent-name}.md`.
-2. **Log BEFORE spawning.** The entry must exist before the agent runs.
-3. **Update outcome AFTER the agent completes.** Fill in the Outcome field.
-4. **Never delete or edit past entries.** Append-only.
-5. **If a reviewer rejects work,** log the rejection as a new entry with the revision agent.
+# Orchestration Log Entry
+
+> One file per agent spawn. Saved to `.squad/orchestration-log/{timestamp}-{agent-name}.md`
+
+---
+
+### {timestamp} — {task summary}
+
+| Field | Value |
+|-------|-------|
+| **Agent routed** | {Name} ({Role}) |
+| **Why chosen** | {Routing rationale — what in the request matched this agent} |
+| **Mode** | {`background` / `sync`} |
+| **Why this mode** | {Brief reason — e.g., "No hard data dependencies" or "User needs to approve architecture"} |
+| **Files authorized to read** | {Exact file paths the agent was told to read} |
+| **File(s) agent must produce** | {Exact file paths the agent is expected to create or modify} |
+| **Outcome** | {Completed / Rejected by {Reviewer} / Escalated} |
+
+---
+
+## Rules
+
+1. **One file per agent spawn.** Named `{timestamp}-{agent-name}.md`.
+2. **Log BEFORE spawning.** The entry must exist before the agent runs.
+3. **Update outcome AFTER the agent completes.** Fill in the Outcome field.
+4. **Never delete or edit past entries.** Append-only.
+5. **If a reviewer rejects work,** log the rejection as a new entry with the revision agent.

package/templates/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/templates/plugin-marketplace.md

@@ -1,49 +1,49 @@
-# Plugin Marketplace
-
-Plugins are curated agent templates, skills, instructions, and prompts shared by the community via GitHub repositories (e.g., `github/awesome-copilot`, `anthropics/skills`). They provide ready-made expertise for common domains — cloud platforms, frameworks, testing strategies, etc.
-
-## Marketplace State
-
-Registered marketplace sources are stored in `.squad/plugins/marketplaces.json`:
-
-```json
-{
-  "marketplaces": [
-    {
-      "name": "awesome-copilot",
-      "source": "github/awesome-copilot",
-      "added_at": "2026-02-14T00:00:00Z"
-    }
-  ]
-}
-```
-
-## CLI Commands
-
-Users manage marketplaces via the CLI:
-- `squad plugin marketplace add {owner/repo}` — Register a GitHub repo as a marketplace source
-- `squad plugin marketplace remove {name}` — Remove a registered marketplace
-- `squad plugin marketplace list` — List registered marketplaces
-- `squad plugin marketplace browse {name}` — List available plugins in a marketplace
-
-## When to Browse
-
-During the **Adding Team Members** flow, AFTER allocating a name but BEFORE generating the charter:
-
-1. Read `.squad/plugins/marketplaces.json`. If the file doesn't exist or `marketplaces` is empty, skip silently.
-2. For each registered marketplace, search for plugins whose name or description matches the new member's role or domain keywords.
-3. Present matching plugins to the user: *"Found '{plugin-name}' in {marketplace} marketplace — want me to install it as a skill for {CastName}?"*
-4. If the user accepts, install the plugin (see below). If they decline or skip, proceed without it.
-
-## How to Install a Plugin
-
-1. Read the plugin content from the marketplace repository (the plugin's `SKILL.md` or equivalent).
-2. Copy it into the agent's skills directory: `.squad/skills/{plugin-name}/SKILL.md`
-3. If the plugin includes charter-level instructions (role boundaries, tool preferences), merge those into the agent's `charter.md`.
-4. Log the installation in the agent's `history.md`: *"📦 Plugin '{plugin-name}' installed from {marketplace}."*
-
-## Graceful Degradation
-
-- **No marketplaces configured:** Skip the marketplace check entirely. No warning, no prompt.
-- **Marketplace unreachable:** Warn the user (*"⚠ Couldn't reach {marketplace} — continuing without it"*) and proceed with team member creation normally.
-- **No matching plugins:** Inform the user (*"No matching plugins found in configured marketplaces"*) and proceed.
+# Plugin Marketplace
+
+Plugins are curated agent templates, skills, instructions, and prompts shared by the community via GitHub repositories (e.g., `github/awesome-copilot`, `anthropics/skills`). They provide ready-made expertise for common domains — cloud platforms, frameworks, testing strategies, etc.
+
+## Marketplace State
+
+Registered marketplace sources are stored in `.squad/plugins/marketplaces.json`:
+
+```json
+{
+  "marketplaces": [
+    {
+      "name": "awesome-copilot",
+      "source": "github/awesome-copilot",
+      "added_at": "2026-02-14T00:00:00Z"
+    }
+  ]
+}
+```
+
+## CLI Commands
+
+Users manage marketplaces via the CLI:
+- `squad plugin marketplace add {owner/repo}` — Register a GitHub repo as a marketplace source
+- `squad plugin marketplace remove {name}` — Remove a registered marketplace
+- `squad plugin marketplace list` — List registered marketplaces
+- `squad plugin marketplace browse {name}` — List available plugins in a marketplace
+
+## When to Browse
+
+During the **Adding Team Members** flow, AFTER allocating a name but BEFORE generating the charter:
+
+1. Read `.squad/plugins/marketplaces.json`. If the file doesn't exist or `marketplaces` is empty, skip silently.
+2. For each registered marketplace, search for plugins whose name or description matches the new member's role or domain keywords.
+3. Present matching plugins to the user: *"Found '{plugin-name}' in {marketplace} marketplace — want me to install it as a skill for {CastName}?"*
+4. If the user accepts, install the plugin (see below). If they decline or skip, proceed without it.
+
+## How to Install a Plugin
+
+1. Read the plugin content from the marketplace repository (the plugin's `SKILL.md` or equivalent).
+2. Copy it into the agent's skills directory: `.squad/skills/{plugin-name}/SKILL.md`
+3. If the plugin includes charter-level instructions (role boundaries, tool preferences), merge those into the agent's `charter.md`.
+4. Log the installation in the agent's `history.md`: *"📦 Plugin '{plugin-name}' installed from {marketplace}."*
+
+## Graceful Degradation
+
+- **No marketplaces configured:** Skip the marketplace check entirely. No warning, no prompt.
+- **Marketplace unreachable:** Warn the user (*"⚠ Couldn't reach {marketplace} — continuing without it"*) and proceed with team member creation normally.
+- **No matching plugins:** Inform the user (*"No matching plugins found in configured marketplaces"*) and proceed.