diff --git a/docs/src/content/docs/guide/building-extensions.md b/docs/src/content/docs/guide/building-extensions.md new file mode 100644 index 000000000..89db805c1 --- /dev/null +++ b/docs/src/content/docs/guide/building-extensions.md @@ -0,0 +1,126 @@ +# Building extensions + +> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. + +You've decided your idea is a Squad Extension (Layer 2). Now build one in five minutes. + +--- + +## What is an extension? + +An extension is a reusable collection of skills, ceremonies, and directives that any team can install. It lives outside Squad core, packaged as a GitHub repository or marketplace plugin. Extensions let you codify workflows (the client-delivery pattern), domain expertise (Azure deployment strategies), or testing ceremonies that other teams benefit from. + +--- + +## Extension structure + +``` +my-extension/ +├── skills/ +│ ├── SKILL1.md +│ └── SKILL2.md +├── ceremonies/ +│ └── CEREMONY.md +├── directives/ +│ └── DIRECTIVE.md +└── README.md +``` + +--- + +## Build one + +**Step 1: Create a repo** + +```bash +mkdir my-extension +cd my-extension +git init +``` + +**Step 2: Add a skill** + +Create `skills/example-skill.md`: + +```markdown +# Example Skill + +**When to use:** You need to do X. + +## Context + +Brief problem statement. + +## Steps + +1. Do the first thing +2. Do the second thing +3. Done +``` + +**Step 3 (optional): Add a ceremony** + +Create `ceremonies/code-review.md` following Squad ceremony format (decision gate, verdicts, escalation). + +**Step 4: Write the README** + +Explain the problem, installation, and usage: + +```markdown +# My Extension + +Codifies client-delivery workflows for consulting teams. + +## Install + +squad plugin install github/my-org/my-extension + +## What's Inside + +- **discovery-interview** skill — clarify requirements +- **evidence-bundler** skill — collect test results +- **plan-review** ceremony — gate for approval +``` + +**Step 5: Test locally** + +Copy your extension directory into `.squad/skills/`, `.squad/ceremonies/`, and `.squad/directives/`. Load your Squad session and verify the skills appear and work as expected. + +--- + +## Share it + +Push to GitHub: + +```bash +git add . +git commit -m "Initial extension: my-extension" +git push +``` + +Register with a marketplace or pin directly by repository URL: + +``` +squad plugin install github/my-org/my-extension +``` + +--- + +## Real examples + +- **Client-delivery workflow** ([RFC #328](https://github.com/bradygaster/squad/issues/328)) — discovery, research, multi-round review with evidence gates +- **Azure infrastructure patterns** — VM provisioning, Cosmos DB design, monitoring rules +- **Knowledge library skills** — document structured analysis, reference synthesis + +--- + +## Related docs + +- [Extensibility guide](./extensibility.md#decision-tree) — Where does your idea belong? (decision tree) +- [Plugin Marketplace](../features/plugins.md) — How teams discover and install your extension +- [Skills](../features/skills.md) — How to author reusable skills +- [Ceremonies](../features/ceremonies.md) — How to define decision gates and review rituals + +--- + +**Ready to share?** [Open a discussion](https://github.com/bradygaster/squad/discussions) in the Squad community. diff --git a/docs/src/content/docs/guide/extensibility.md b/docs/src/content/docs/guide/extensibility.md new file mode 100644 index 000000000..a9a70b304 --- /dev/null +++ b/docs/src/content/docs/guide/extensibility.md @@ -0,0 +1,130 @@ +# Extensibility guide + +> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. + +Where does your change idea belong? Squad core, marketplace plugin, or team config? + +**Key principle:** Squad core stays small. Most ideas are skills, ceremonies, or directives. + +--- + +## The three layers + +| Layer | What lives here | Who changes it | Distribution | +|-------|----------------|----------------|--------------| +| **Squad Core** | Coordinator behavior, routing logic, reviewer protocol | Squad maintainers only | npm releases | +| **Squad Extension** | Reusable patterns (skills, ceremonies, workflows) | Plugin authors | Marketplace plugins | +| **Team Configuration** | Decisions unique to THIS team | The team itself | `.squad/` files | + +--- + +## Decision tree + +``` +┌─ Does it change HOW the coordinator routes, spawns, or enforces? +│ +├─ YES → Squad Core +│ └─ Examples: New coordinator modes, reviewer protocol changes +│ Action: Open an RFC issue +│ +└─ NO → Continue... + │ + ┌─ Could OTHER teams benefit? + │ + ├─ YES → Squad Extension (plugin) + │ └─ Examples: Client-delivery workflow, Azure skills, TDD ceremonies + │ Action: Build a plugin + │ + └─ NO → Team Configuration + └─ Examples: YOUR git workflow, YOUR build process, YOUR routing rules + Action: Update `.squad/` files +``` + +**Heuristic:** "Squad should..." → check if it's really "My team should..." or "Teams using X should...". + + + +--- + +## Worked example: Client-delivery RFC + +[RFC #328](https://github.com/bradygaster/squad/issues/328) proposed a sophisticated client-delivery workflow: discovery interviews, research sprints, multi-round review with `SHIP`/`NEEDS_WORK`/`BLOCKED` verdicts, evidence bundles. + +**The realization:** It maps entirely to existing Squad primitives. No core changes needed. + +**Where it belongs:** Layer 2 (Squad Extension) + +This workflow is a reusable pattern any team could adopt — perfect as a marketplace plugin. + +**Plugin structure:** +``` +client-delivery-workflow/ +├── skills/ +│ ├── discovery-interview/ # Clarify requests, extract requirements +│ ├── research-sprint/ # Propose directions, score options +│ └── evidence-bundler/ # Collect test results, logs, screenshots +├── ceremonies/ +│ ├── plan-review.md # Gate: approve before implementation +│ └── implementation-review.md # Gate: verify evidence +└── directives/ + └── multi-round-review.md # Policy: 2 NEEDS_WORK rounds max +``` + +**Usage:** +```bash +squad plugin install github/awesome-copilot/client-delivery-workflow +``` + +**Lesson:** Most sophisticated workflows are compositions of primitives, not core features. + +--- + +## When to escalate to core + +You likely need a core change if: + +- **New coordinator mode** — Example: `validate` mode that runs checks before `assign` +- **Routing logic change** — Example: Route based on agent workload, not labels +- **Reviewer protocol change** — Example: Conditional approvals ("approved if tests pass") +- **Global enforcement rule** — Example: Block merges if evidence missing +- **Skill needs coordinator data** — Example: Access to agent spawn history + +You DON'T need core if: + +- **Workflow pattern** → Build a plugin (skills + ceremonies) +- **Domain expertise** → Write a skill +- **Team process** → Add a ceremony to `.squad/ceremonies.md` +- **Reusable templates** → Build a plugin +- **Configuring existing behavior** → Update `.squad/routing.md` + +--- + +## Build an extension + +Ready to build? See [Building extensions](./building-extensions.md) for a five-minute walkthrough. + +--- + +## Summary + +1. **Start with the decision tree** — Most ideas are Layer 2 or 3 +2. **Default to team config** — Unique to your team? → `.squad/` +3. **Build a plugin if reusable** — Other teams benefit? → Package and share +4. **Escalate to core rarely** — Need coordinator/routing changes? → Open an RFC + +**When in doubt:** Start with team config. Copy-pasting to other teams? Promote to plugin. Plugins repeatedly hitting limits? Signal for core change. + +--- + +## Related documentation + +- [Plugin Marketplace](../features/plugins.md) — How to browse, install, and share plugins +- [Skills](../features/skills.md) — How to write skills for your team or plugins +- [Ceremonies](../features/ceremonies.md) — How to define team meetings and gates +- [Routing](../features/routing.md) — How to configure work assignment rules +- [Building extensions](./building-extensions.md) — Step-by-step guide to building and sharing extensions +- [Contributing](https://github.com/bradygaster/squad/blob/main/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..c43b1e40c 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', 'building-extensions']; const EXPECTED_REFERENCE = ['cli', 'sdk', 'config', 'api-reference', 'integration', 'tools-and-hooks'];