Epic: Squad Plugin / Extensibility System (PRD + Design)

Summary

Squad today bundles agents, skills, routing, decisions, and (in some cases) governance/scripts directly into a project's .squad/ directory. There is no first-class way to:

• Package a coherent capability (e.g., a knowledge pack, a memory backend, a governance pack, a domain skill bundle) as a reusable artifact.
• Install that artifact into another Squad project deterministically.
• Switch between alternative implementations of the same role (e.g., two memory plugins) and observe a behavior change.
• Audit what was installed, by whom, with what permissions, and roll it back.

This epic proposes a plugin/extensibility system for Squad that is governed-by-default, reproducible, and explicitly avoids arbitrary code execution in the MVP.

Goals

1. Define an authoring-time plugin manifest that describes what a plugin is and what it ships, without embedding install-time or distribution concerns.
2. Define an install request (what the consumer wants) and a lock file (what was actually resolved and installed) as separate artifacts.
3. Provide a squad plugin CLI surface to validate, dry-run, install, enable/disable/switch, and uninstall plugins.
4. Pilot the system with a real capability (knowledge/memory plugin) and prove switching changes agent behavior in tests.
5. Map plugin components to native Copilot adapter targets (skill / hook / extension metadata) - metadata only in MVP, no execution.
6. Ship a tutorial, demo plugins, and a security gate forbidding arbitrary code execution.

Non-Goals (MVP)

• No remote registry, signing infrastructure, or marketplace.
• No sandboxed runtime / no executing plugin-supplied code.
• No automatic capability inference beyond what is statically declared.
• No backwards-compatibility shims for pre-plugin .squad/ layouts beyond a documented migration path.

Key Design Decisions

These reflect the latest design iteration and supersede earlier drafts:

• Three-document split. The author's plugin.manifest.json describes the artifact only. The consumer's install request describes source + ref + intent. The generated plugin.lock.json captures the resolved immutable ref, digest, file list, and effective permissions. Each document has a single owner and a single purpose.
• Manifest excludes operational fields. verificationStatus, featureStatus, distribution, and concrete MVP permission grants do not belong in the author manifest. They are properties of an install/registry/runtime context, not of the artifact.
• Install source/ref live in the install request, not the manifest. The same manifest can be installed from a path, a git ref, or (future) a registry without being rewritten.
• Resolved ref / digest / artifact list live in the lock file. The lock is the source of truth for reproducibility, audit, and rollback.
• SemVer prerelease handles alpha/beta channels. No separate featureStatus enum in the manifest; 1.2.0-alpha.1 is sufficient.
• Dry-run infers risk from declared components, not from speculative capability strings. Future capabilities may be added when there is a concrete need.
• No arbitrary execution in MVP. Plugins ship declarative content (agents, skills, knowledge packs, routing fragments, decision fragments, hook metadata). A security gate (see child issue) enforces this.
• Native adapter targets are metadata-only in MVP. A plugin may declare it provides a Copilot skill / hook / extension, but Squad MVP does not load or execute that target - it only records and surfaces it.

PRD (Concise)

Problem. Squad capabilities are not portable, not switchable, and not auditable. Sharing a capability today means copy-pasting files, with no way to update, rollback, or compare alternatives.

Users. Squad project owners, agent authors, capability authors (e.g., someone shipping a "memory backend" plugin), and reviewers/auditors.

User stories.

• As an author, I can package my capability with a manifest, version it via SemVer (including prereleases), and publish it as a path/git ref without leaking install-time concerns into my artifact.
• As a consumer, I can squad plugin install <source>, see a dry-run of every file/permission/component before anything is written, get a plugin.lock.json for reproducibility, and squad plugin uninstall to fully roll back.
• As an operator, I can enable/disable/switch active plugin profiles and prove via tests that agent behavior changes accordingly.
• As a reviewer, I can audit the lock file to know exactly what is installed, what permissions it has, and what its resolved digest is.

Success criteria.

• Manifest schema is published, validated, and stable enough to author against.
• A real plugin (knowledge/memory pilot) installs, switches, and produces an observable behavior change covered by tests.
• Security gate test suite proves no arbitrary code path exists in the install/enable/switch flow.
• A tutorial walks a new author end-to-end in under 30 minutes.

Design Summary

Artifacts

1. plugin.manifest.json (author-owned, in the plugin source tree)

   • Identity: name, version (SemVer, prereleases allowed), description, authors, license.
   • Components: declarative lists of agents, skills, knowledge, memory, routing, decisions, hooks (metadata), adapters (Copilot skill/hook/extension targets, metadata only).
   • Compatibility: squad engine range.
   • Excludes verificationStatus, featureStatus, distribution, permission grants, install source.

2. Install request (consumer-supplied, ephemeral or persisted in .squad/plugins/requested.json)

   • source (path | git), ref (branch/tag/commit), optional name pin, optional permission acknowledgements.

3. plugin.lock.json (generated, committed by consumer)

   • Resolved immutable ref + content digest, file inventory with hashes, effective permissions, install timestamp, installer version, source provenance.

CLI Surface

squad plugin validate <path>
squad plugin dry-run <source> [--ref <ref>]
squad plugin install <source> [--ref <ref>]
squad plugin enable <name>
squad plugin disable <name>
squad plugin switch <role> <name>
squad plugin uninstall <name>
squad plugin list

Risk Inference (MVP Dry-Run)

Risks are derived from declared components: writing under .squad/agents/, .squad/skills/, .squad/routing/, .squad/decisions/, declaring hook metadata, declaring adapter targets, etc. No speculative capability strings in MVP. Future capabilities may be added when concrete needs arise (e.g., network egress, filesystem write outside .squad/).

Security Posture

• Installer never executes plugin-supplied code.
• Hook metadata may be recorded, but hook execution is out of scope for MVP and gated by a follow-up RFC.
• Adapter targets (Copilot skill/hook/extension) are metadata-only in MVP.
• A dedicated security gate child issue defines the test suite that enforces this.

Roadmap / Child Issues

Implementation child issues will be created and linked back to this epic. The MVP set covers:

1. Manifest schema + validator + dry-run.
2. Installer + lock file + rollback (path/git sources).
3. Enable / disable / switch plugin profiles.
4. Knowledge / memory plugin pilot (proves a real capability works).
5. Native Copilot adapter target metadata (skill / hook / extension declarations only - no execution).
6. Demo plugins + tests proving switching changes behavior.
7. Tutorial and reference documentation.
8. Security gate: no arbitrary execution, no hidden capabilities.

Provenance and Related Work

Planning provenance (downstream planning repo)

The full PRD/design document lives in a planning worktree of tamirdresher_microsoft/tamresearch1 (not externally accessible from this repo). Local file path for reference: tamresearch1-plugin-prd/docs/squad-plugin-extension-prd-design.md.

Local planning issues that informed this epic:

• tamirdresher_microsoft/tamresearch1#2916 - Epic: governed plugin install, switching, and demo plugins
• tamirdresher_microsoft/tamresearch1#2917 - Manifest schema, validator, and dry-run CLI
• tamirdresher_microsoft/tamresearch1#2918 - Local/path plugin install with lock and audit files
• tamirdresher_microsoft/tamresearch1#2919 - Enable, disable, and switch active plugin profiles
• tamirdresher_microsoft/tamresearch1#2920 - Knowledge and memory plugin pilot
• tamirdresher_microsoft/tamresearch1#2921 - Docs/context-pack demo plugin
• tamirdresher_microsoft/tamresearch1#2922 - Governance-lite policy demo plugin
• tamirdresher_microsoft/tamresearch1#2923 - Tiny sample plugin to prove switching mechanics
• tamirdresher_microsoft/tamresearch1#2924 - Demo install flow for plugin created by another user
• tamirdresher_microsoft/tamresearch1#2925 - Tests and fixtures proving plugin switching changes behavior
• tamirdresher_microsoft/tamresearch1#2926 - Tutorial: create, share, install, switch, and uninstall a plugin
• tamirdresher_microsoft/tamresearch1#2927 - Security review gate: no arbitrary execution or hidden capabilities

Related upstream issues (verified)

• squad upgrade overwrites squad.agent.md — no mechanism to preserve local customizations #1052 - squad upgrade overwrites squad.agent.md - no mechanism to preserve local customizations. Directly relevant: a plugin/extension model must define how upgrades and user customizations coexist.
• Bug: "squad new agent" command is not updating "squad.config.ts" #1047 - squad new agent not updating squad.config.ts. Relevant to how plugin-installed agents must be discovered/registered consistently.
• Bug: "squad build" is not generating files to the "squad externalize" location #1048 - squad build not generating files to the squad externalize location. Relevant to externalization paths a plugin will need to target deterministically.
• fix: replace hardcoded Brady in template examples #1063 - replace hardcoded Brady in template examples (PR). Relevant to making templates plugin-friendly and parameterizable.

Open Questions

• Exact JSON schema field names and required/optional split for plugin.manifest.json v0.1.
• Profile model: a single active profile vs. per-role active plugin map.
• Lock file location and whether it is committed by default.
• Migration story for existing .squad/ content into a "core" or "in-tree" pseudo-plugin.

This epic is the upstream tracking issue for the plugin / extensibility design. Child implementation issues will be opened and cross-linked below.