|
| 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. |
0 commit comments