Skip to content

Commit 38be241

Browse files
diberryCopilot
andauthored
docs: Add extensibility and building extensions guides (#436)
- Extensibility guide: decision tree for where ideas belong (Squad Core vs Extension vs Team Config) - Building extensions guide: 5-step practical tutorial - Updated test assertions for both new guide pages Closes #328 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent f87a7a5 commit 38be241

3 files changed

Lines changed: 257 additions & 1 deletion

File tree

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
# Building extensions
2+
3+
> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases.
4+
5+
You've decided your idea is a Squad Extension (Layer 2). Now build one in five minutes.
6+
7+
---
8+
9+
## What is an extension?
10+
11+
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.
12+
13+
---
14+
15+
## Extension structure
16+
17+
```
18+
my-extension/
19+
├── skills/
20+
│ ├── SKILL1.md
21+
│ └── SKILL2.md
22+
├── ceremonies/
23+
│ └── CEREMONY.md
24+
├── directives/
25+
│ └── DIRECTIVE.md
26+
└── README.md
27+
```
28+
29+
---
30+
31+
## Build one
32+
33+
**Step 1: Create a repo**
34+
35+
```bash
36+
mkdir my-extension
37+
cd my-extension
38+
git init
39+
```
40+
41+
**Step 2: Add a skill**
42+
43+
Create `skills/example-skill.md`:
44+
45+
```markdown
46+
# Example Skill
47+
48+
**When to use:** You need to do X.
49+
50+
## Context
51+
52+
Brief problem statement.
53+
54+
## Steps
55+
56+
1. Do the first thing
57+
2. Do the second thing
58+
3. Done
59+
```
60+
61+
**Step 3 (optional): Add a ceremony**
62+
63+
Create `ceremonies/code-review.md` following Squad ceremony format (decision gate, verdicts, escalation).
64+
65+
**Step 4: Write the README**
66+
67+
Explain the problem, installation, and usage:
68+
69+
```markdown
70+
# My Extension
71+
72+
Codifies client-delivery workflows for consulting teams.
73+
74+
## Install
75+
76+
squad plugin install github/my-org/my-extension
77+
78+
## What's Inside
79+
80+
- **discovery-interview** skill — clarify requirements
81+
- **evidence-bundler** skill — collect test results
82+
- **plan-review** ceremony — gate for approval
83+
```
84+
85+
**Step 5: Test locally**
86+
87+
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.
88+
89+
---
90+
91+
## Share it
92+
93+
Push to GitHub:
94+
95+
```bash
96+
git add .
97+
git commit -m "Initial extension: my-extension"
98+
git push
99+
```
100+
101+
Register with a marketplace or pin directly by repository URL:
102+
103+
```
104+
squad plugin install github/my-org/my-extension
105+
```
106+
107+
---
108+
109+
## Real examples
110+
111+
- **Client-delivery workflow** ([RFC #328](https://github.com/bradygaster/squad/issues/328)) — discovery, research, multi-round review with evidence gates
112+
- **Azure infrastructure patterns** — VM provisioning, Cosmos DB design, monitoring rules
113+
- **Knowledge library skills** — document structured analysis, reference synthesis
114+
115+
---
116+
117+
## Related docs
118+
119+
- [Extensibility guide](./extensibility.md#decision-tree) — Where does your idea belong? (decision tree)
120+
- [Plugin Marketplace](../features/plugins.md) — How teams discover and install your extension
121+
- [Skills](../features/skills.md) — How to author reusable skills
122+
- [Ceremonies](../features/ceremonies.md) — How to define decision gates and review rituals
123+
124+
---
125+
126+
**Ready to share?** [Open a discussion](https://github.com/bradygaster/squad/discussions) in the Squad community.
Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
# Extensibility guide
2+
3+
> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases.
4+
5+
Where does your change idea belong? Squad core, marketplace plugin, or team config?
6+
7+
**Key principle:** Squad core stays small. Most ideas are skills, ceremonies, or directives.
8+
9+
---
10+
11+
## The three layers
12+
13+
| Layer | What lives here | Who changes it | Distribution |
14+
|-------|----------------|----------------|--------------|
15+
| **Squad Core** | Coordinator behavior, routing logic, reviewer protocol | Squad maintainers only | npm releases |
16+
| **Squad Extension** | Reusable patterns (skills, ceremonies, workflows) | Plugin authors | Marketplace plugins |
17+
| **Team Configuration** | Decisions unique to THIS team | The team itself | `.squad/` files |
18+
19+
---
20+
21+
## Decision tree
22+
23+
```
24+
┌─ Does it change HOW the coordinator routes, spawns, or enforces?
25+
│
26+
├─ YES → Squad Core
27+
│ └─ Examples: New coordinator modes, reviewer protocol changes
28+
│ Action: Open an RFC issue
29+
│
30+
└─ NO → Continue...
31+
│
32+
┌─ Could OTHER teams benefit?
33+
│
34+
├─ YES → Squad Extension (plugin)
35+
│ └─ Examples: Client-delivery workflow, Azure skills, TDD ceremonies
36+
│ Action: Build a plugin
37+
│
38+
└─ NO → Team Configuration
39+
└─ Examples: YOUR git workflow, YOUR build process, YOUR routing rules
40+
Action: Update `.squad/` files
41+
```
42+
43+
**Heuristic:** "Squad should..." → check if it's really "My team should..." or "Teams using X should...".
44+
45+
46+
47+
---
48+
49+
## Worked example: Client-delivery RFC
50+
51+
[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.
52+
53+
**The realization:** It maps entirely to existing Squad primitives. No core changes needed.
54+
55+
**Where it belongs:** Layer 2 (Squad Extension)
56+
57+
This workflow is a reusable pattern any team could adopt — perfect as a marketplace plugin.
58+
59+
**Plugin structure:**
60+
```
61+
client-delivery-workflow/
62+
├── skills/
63+
│ ├── discovery-interview/ # Clarify requests, extract requirements
64+
│ ├── research-sprint/ # Propose directions, score options
65+
│ └── evidence-bundler/ # Collect test results, logs, screenshots
66+
├── ceremonies/
67+
│ ├── plan-review.md # Gate: approve before implementation
68+
│ └── implementation-review.md # Gate: verify evidence
69+
└── directives/
70+
└── multi-round-review.md # Policy: 2 NEEDS_WORK rounds max
71+
```
72+
73+
**Usage:**
74+
```bash
75+
squad plugin install github/awesome-copilot/client-delivery-workflow
76+
```
77+
78+
**Lesson:** Most sophisticated workflows are compositions of primitives, not core features.
79+
80+
---
81+
82+
## When to escalate to core
83+
84+
You likely need a core change if:
85+
86+
- **New coordinator mode** — Example: `validate` mode that runs checks before `assign`
87+
- **Routing logic change** — Example: Route based on agent workload, not labels
88+
- **Reviewer protocol change** — Example: Conditional approvals ("approved if tests pass")
89+
- **Global enforcement rule** — Example: Block merges if evidence missing
90+
- **Skill needs coordinator data** — Example: Access to agent spawn history
91+
92+
You DON'T need core if:
93+
94+
- **Workflow pattern** → Build a plugin (skills + ceremonies)
95+
- **Domain expertise** → Write a skill
96+
- **Team process** → Add a ceremony to `.squad/ceremonies.md`
97+
- **Reusable templates** → Build a plugin
98+
- **Configuring existing behavior** → Update `.squad/routing.md`
99+
100+
---
101+
102+
## Build an extension
103+
104+
Ready to build? See [Building extensions](./building-extensions.md) for a five-minute walkthrough.
105+
106+
---
107+
108+
## Summary
109+
110+
1. **Start with the decision tree** — Most ideas are Layer 2 or 3
111+
2. **Default to team config** — Unique to your team? → `.squad/`
112+
3. **Build a plugin if reusable** — Other teams benefit? → Package and share
113+
4. **Escalate to core rarely** — Need coordinator/routing changes? → Open an RFC
114+
115+
**When in doubt:** Start with team config. Copy-pasting to other teams? Promote to plugin. Plugins repeatedly hitting limits? Signal for core change.
116+
117+
---
118+
119+
## Related documentation
120+
121+
- [Plugin Marketplace](../features/plugins.md) — How to browse, install, and share plugins
122+
- [Skills](../features/skills.md) — How to write skills for your team or plugins
123+
- [Ceremonies](../features/ceremonies.md) — How to define team meetings and gates
124+
- [Routing](../features/routing.md) — How to configure work assignment rules
125+
- [Building extensions](./building-extensions.md) — Step-by-step guide to building and sharing extensions
126+
- [Contributing](https://github.com/bradygaster/squad/blob/main/CONTRIBUTING.md) — How to propose changes to Squad core
127+
128+
---
129+
130+
**Questions?** [Open an issue](https://github.com/bradygaster/squad/issues/new) or join the discussion in the Squad community.

‎test/docs-build.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ const DIST_DIR = join(DOCS_DIR, 'dist');
1717
// Expected content directories in src/content/docs/
1818
const EXPECTED_GET_STARTED = ['choose-your-interface', 'first-session', 'installation', 'migration'];
1919

20-
const EXPECTED_GUIDES = ['tips-and-tricks', 'sample-prompts', 'personal-squad', 'contributing', 'contributors', 'shell', 'faq'];
20+
const EXPECTED_GUIDES = ['tips-and-tricks', 'sample-prompts', 'personal-squad', 'contributing', 'contributors', 'shell', 'faq', 'extensibility', 'building-extensions'];
2121

2222
const EXPECTED_REFERENCE = ['cli', 'sdk', 'config', 'api-reference', 'integration', 'tools-and-hooks'];
2323

0 commit comments

Comments
 (0)