@mdsohail99/opencode-agent-teams 2.0.0 โ 2.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +64 -120
- package/CHANGELOG.md +170 -137
- package/README.md +179 -351
- package/agents/orchestrators/agent-teams.md +131 -183
- package/agents/orchestrators/ai-data.md +79 -91
- package/agents/orchestrators/backend.md +93 -109
- package/agents/orchestrators/devops.md +77 -89
- package/agents/orchestrators/frontend.md +96 -117
- package/agents/orchestrators/qa.md +77 -89
- package/agents/orchestrators/security.md +85 -98
- package/bin/cli.js +357 -351
- package/package.json +13 -8
- package/src/index.ts +133 -115
- package/src/state/tracker.ts +102 -102
- package/src/tools/broadcast.ts +58 -58
- package/src/tools/delegate.ts +181 -154
- package/src/tools/status.ts +25 -25
- package/src/tools/terminate.ts +70 -70
- package/src/tui.ts +9 -9
- package/src/worktree/manager.ts +142 -142
- package/agents/orchestrators-fork/orchestrator-agent-teams.md +0 -203
- package/bin/install.mjs +0 -418
- package/bin/lib/config-root.mjs +0 -51
- package/bin/lib/merge-commands.mjs +0 -138
- package/bin/lib/merge-env-flags.mjs +0 -92
- package/bin/lib/merge-schema.mjs +0 -77
- package/bin/lib/merge-subagent-depth.mjs +0 -133
- package/bin/lib/plugin-park.mjs +0 -48
- package/bin/lib/relay-process.mjs +0 -116
- package/bin/lib/runtime-state.mjs +0 -118
- package/bin/menu.mjs +0 -582
- package/bin/uninstall.mjs +0 -360
package/README.md
CHANGED
|
@@ -1,351 +1,179 @@
|
|
|
1
|
-
<div align="center">
|
|
2
|
-
<h1
|
|
3
|
-
<p><strong>
|
|
4
|
-
|
|
5
|
-
<p>
|
|
6
|
-
<img src="https://img.shields.io/npm/v/opencode-agent-teams
|
|
7
|
-
<img src="https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square" alt="License"/>
|
|
8
|
-
<img src="https://img.shields.io/
|
|
9
|
-
<img src="https://img.shields.io/badge/
|
|
10
|
-
<img src="https://img.shields.io/badge/
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
---
|
|
26
|
-
|
|
27
|
-
##
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
```
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
---
|
|
156
|
-
|
|
157
|
-
##
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
> 1. Install / Upgrade Agent-Teams
|
|
181
|
-
2. Revert to Backup
|
|
182
|
-
3. Check Status
|
|
183
|
-
4. Uninstall
|
|
184
|
-
5. Exit
|
|
185
|
-
```
|
|
186
|
-
|
|
187
|
-
---
|
|
188
|
-
|
|
189
|
-
## ๐ฎ Swarm Slash Command Palette
|
|
190
|
-
|
|
191
|
-
Agent-Teams registers 6 native slash commands directly into your OpenCode configuration (`opencode.json`), giving you real-time command-and-control over the swarm:
|
|
192
|
-
|
|
193
|
-
| Slash Command | Question It Answers | What It Does |
|
|
194
|
-
| :--- | :--- | :--- |
|
|
195
|
-
| **`/tree [filter]`** | *"Who is working right now?"* | Renders a live hierarchical ASCII parent-child tree showing running/completed agents, elapsed execution time, and `[stalled]` tags. |
|
|
196
|
-
| **`/report [filter]`** | *"What is the status of the work?"* | Harvests all completed deliverables, code changes, and active tasks across leads to synthesize an executive summary. |
|
|
197
|
-
| **`/ask <agent> <query>`** | *"Can I steer a worker mid-flight?"* | Sends an out-of-band side query directly to an active subagent without interrupting its execution or losing turn state. |
|
|
198
|
-
| **`/resume <agent> [notes]`**| *"How do I un-stick a paused task?"* | Resumes a stalled, paused, or failed worker, keeping its accumulated memory, tool context, and git worktree sandbox intact. |
|
|
199
|
-
| **`/stop [agent|all]`** | *"How do I halt runaway workers?"* | Surgically halts a specific worker or triggers an immediate full-swarm emergency stop. |
|
|
200
|
-
| **`/errors`** | *"Did anything break?"* | Scans the swarm for failed, errored, or stalled workers and outputs actionable diagnostic traces. |
|
|
201
|
-
|
|
202
|
-
---
|
|
203
|
-
|
|
204
|
-
## โ๏ธ Installation Modes
|
|
205
|
-
|
|
206
|
-
The package ships **two installation modes** to support both upstream stock OpenCode and custom native forks:
|
|
207
|
-
|
|
208
|
-
### 1. `full` โ Default (Stock OpenCode + Swarm Control Plane)
|
|
209
|
-
|
|
210
|
-
```powershell
|
|
211
|
-
npx opencode-agent-teams-relay-install
|
|
212
|
-
# or, from this repo:
|
|
213
|
-
.\install.ps1
|
|
214
|
-
```
|
|
215
|
-
|
|
216
|
-
Installs the complete orchestration suite:
|
|
217
|
-
1. **74 Curated Agents**: `agents/orchestrators/*.md` + `agents/specialists/*.md`.
|
|
218
|
-
2. **`AGENTS.md` Rules**: Injects Department Lead orchestration and hub-and-spoke rules (non-destructive marker-based merge).
|
|
219
|
-
3. **Native `subagent_depth = 2` & `max_concurrent_agents = 20`**: Configured directly in `opencode.json` for deep hierarchy support.
|
|
220
|
-
4. **Slash Commands**: Registers `/tree`, `/report`, `/ask`, `/resume`, `/stop`, and `/errors` in `opencode.json`.
|
|
221
|
-
5. **Agent-Teams Plugin**: `plugins/agent-teams.ts` providing fast-path capability probing and bridge tools.
|
|
222
|
-
6. **Background Relay Daemon**: `relay/agent-teams-relay.mjs` providing out-of-band monitoring, SQLite WAL state persistence, and native git worktree sandboxing.
|
|
223
|
-
7. **NPM Dependency**: Adds `@opencode-ai/plugin` to `~/.config/opencode/package.json`.
|
|
224
|
-
|
|
225
|
-
*Use this mode if you are running official stock OpenCode (`v1.18.34+`) from npm.*
|
|
226
|
-
|
|
227
|
-
### 2. `agents` โ Agents-Only (Native Fork / Ultra-Lean Mode)
|
|
228
|
-
|
|
229
|
-
```powershell
|
|
230
|
-
npx opencode-agent-teams-relay-install --agents-only
|
|
231
|
-
# or, from this repo:
|
|
232
|
-
.\install.ps1 -AgentsOnly
|
|
233
|
-
```
|
|
234
|
-
|
|
235
|
-
Installs **only**:
|
|
236
|
-
1. **74 Curated Agents**: Uses the fork-native orchestrator configured for in-engine `Task(background=true, daemon=true, worktree=true)`.
|
|
237
|
-
2. **`AGENTS.md` Rules**: Full department orchestration contracts.
|
|
238
|
-
3. **Native `subagent_depth = 2`**: Configured directly in `opencode.json`.
|
|
239
|
-
|
|
240
|
-
*Does **NOT** install the plugin, the relay daemon, or extra npm dependencies. Zero background processes, zero open ports, zero overhead. Ideal for native forks (e.g. `anomalyco/opencode`) where background primitives are compiled directly into the binary.*
|
|
241
|
-
|
|
242
|
-
### Mode Marker & Uninstall Discipline
|
|
243
|
-
|
|
244
|
-
Every installation writes `.installed-mode` (`"full"` or `"agents"`) into your OpenCode configuration directory. The uninstaller inspects this marker so it only removes what that specific mode manages:
|
|
245
|
-
- In `agents` mode, uninstalling never touches user plugins, `node_modules`, or `package.json`.
|
|
246
|
-
- In `full` mode, uninstaller cleans up the relay and parked plugins while preserving user settings.
|
|
247
|
-
- Re-running the installer seamlessly switches between modes (`full` โ `agents`).
|
|
248
|
-
- Check current status anytime with `npx opencode-agent-teams-relay-uninstall status`.
|
|
249
|
-
|
|
250
|
-
---
|
|
251
|
-
|
|
252
|
-
## ๐ ๏ธ Commands & Automation
|
|
253
|
-
|
|
254
|
-
For CI/CD scripts or automated deployment, use non-interactive binary commands:
|
|
255
|
-
|
|
256
|
-
| Command | Description |
|
|
257
|
-
|---|---|
|
|
258
|
-
| `npx opencode-agent-teams-relay` | Interactive TUI menu (install, upgrade, revert, status) |
|
|
259
|
-
| `npx opencode-agent-teams-relay-install` | Direct, non-interactive installation script (full mode) |
|
|
260
|
-
| `npx opencode-agent-teams-relay-install --agents-only` | Agents-only install (no plugin/relay/npm โ native fork) |
|
|
261
|
-
| `npx opencode-agent-teams-relay-uninstall` | Non-interactive uninstaller & revert utility |
|
|
262
|
-
|
|
263
|
-
### Non-Interactive Flag Examples
|
|
264
|
-
|
|
265
|
-
```powershell
|
|
266
|
-
# Direct silent installation (full mode)
|
|
267
|
-
npx opencode-agent-teams-relay-install
|
|
268
|
-
|
|
269
|
-
# Agents-only installation (native fork โ no plugin/relay/npm)
|
|
270
|
-
npx opencode-agent-teams-relay-install --agents-only
|
|
271
|
-
|
|
272
|
-
# Check current installation, installed mode & available backups
|
|
273
|
-
npx opencode-agent-teams-relay-uninstall status
|
|
274
|
-
|
|
275
|
-
# Revert to most recent automatic backup
|
|
276
|
-
npx opencode-agent-teams-relay-uninstall revert
|
|
277
|
-
|
|
278
|
-
# Revert to a specific backup version
|
|
279
|
-
npx opencode-agent-teams-relay-uninstall revert v0.1.0
|
|
280
|
-
|
|
281
|
-
# Complete clean uninstall (preserves custom AGENTS.md rules; agents-only mode
|
|
282
|
-
# also preserves any other user plugins)
|
|
283
|
-
npx opencode-agent-teams-relay-uninstall uninstall
|
|
284
|
-
```
|
|
285
|
-
|
|
286
|
-
### Local PowerShell Installation
|
|
287
|
-
|
|
288
|
-
```powershell
|
|
289
|
-
cd c:\Dev\opencode\orchestration
|
|
290
|
-
.\install.ps1 # full mode (default)
|
|
291
|
-
.\install.ps1 -AgentsOnly # agents-only mode (native fork)
|
|
292
|
-
```
|
|
293
|
-
|
|
294
|
-
---
|
|
295
|
-
|
|
296
|
-
## ๐ Department Leads & Agents
|
|
297
|
-
|
|
298
|
-
This package provisions **7 Orchestrators** and **67 Specialist Agents** into your `~/.config/opencode/agents/` directory:
|
|
299
|
-
|
|
300
|
-
| Department | Orchestrator Agent | Specialized Domain Agents |
|
|
301
|
-
|---|---|---|
|
|
302
|
-
| โก **Async Fan-Out** | **`Agent-Teams`** | Multi-agent parallel routing (`running_agents`, `next_agent`, `agents_status`) |
|
|
303
|
-
| ๐จ **Frontend** | `Frontend` | `Frontend Developer`, `UI Designer`, `UX Architect`, `Accessibility Auditor`, `USWDS Developer` |
|
|
304
|
-
| โ๏ธ **Backend** | `Backend` | `Backend Architect`, `Database Optimizer`, `API Platform Engineer`, `Payments Billing Engineer`, `Rust Refactoring Specialist` |
|
|
305
|
-
| ๐ก๏ธ **Security** | `Security` | `Security Architect`, `Penetration Tester`, `Cloud Security Architect`, `Secrets Credential Hygiene Engineer`, `Privacy Engineer` |
|
|
306
|
-
| ๐ **DevOps** | `DevOps` | `DevOps Automator`, `SRE (Site Reliability Engineer)`, `FinOps Engineer`, `IoT Fleet Engineer`, `Incident Response Commander` |
|
|
307
|
-
| ๐ง **AI & Data** | `AI & Data` | `AI Engineer`, `RAG Pipeline Engineer`, `Prompt Engineer`, `Data Engineer`, `Search Relevance Engineer` |
|
|
308
|
-
| ๐งช **QA** | `QA` | `Test Automation Engineer`, `API Tester`, `Performance Benchmarker`, `Reality Checker`, `Test Results Analyzer` |
|
|
309
|
-
|
|
310
|
-
---
|
|
311
|
-
|
|
312
|
-
## ๐ Upgrade & Automatic Backup System
|
|
313
|
-
|
|
314
|
-
Every installation automatically creates a full, timestamped backup before modifying your configuration:
|
|
315
|
-
|
|
316
|
-
1. **Detection:** Reads `.installed-version` in your OpenCode config folder.
|
|
317
|
-
2. **Full Backup:** Copies entire config state to `~/.config/opencode/.backups/<version>-<timestamp>/`.
|
|
318
|
-
3. **Smart Merge:** Injects or updates the `AGENTS.md` orchestration block using start/end markers (`<!-- agent-teams-orchestration:start -->`), **preserving all existing user rules**.
|
|
319
|
-
4. **Pruning:** Automatically keeps the last 5 backups and prunes older entries to conserve space.
|
|
320
|
-
|
|
321
|
-
### Backup Storage Directory
|
|
322
|
-
|
|
323
|
-
```text
|
|
324
|
-
~/.config/opencode/.backups/
|
|
325
|
-
โโโ v0.1.0-2026-08-05T20-45-00/
|
|
326
|
-
โ โโโ agents/
|
|
327
|
-
โ โโโ plugins/
|
|
328
|
-
โ โโโ relay/
|
|
329
|
-
โ โโโ .installed-version
|
|
330
|
-
โโโ .backup-version
|
|
331
|
-
```
|
|
332
|
-
|
|
333
|
-
---
|
|
334
|
-
|
|
335
|
-
## ๐ Security & Context Isolation
|
|
336
|
-
|
|
337
|
-
- **Token Protection:** The background relay generates a cryptographically secure 32-byte hex token on startup. All IPC requests require a matching `Authorization: Bearer <token>` header.
|
|
338
|
-
- **Port Isolation:** Every OpenCode server URL gets a unique, hash-derived relay port (20000โ50000). Multiple terminal windows and projects remain completely isolated.
|
|
339
|
-
- **Context Preservation:** Sub-agent completions return **only final assistant text summaries** to parent sessions, preventing transcript inflation.
|
|
340
|
-
|
|
341
|
-
---
|
|
342
|
-
|
|
343
|
-
## ๐ค Contributing
|
|
344
|
-
|
|
345
|
-
Contributions of new specialized agents, workflow patterns, and relay optimizations are welcome! Please feel free to open an issue or submit a pull request.
|
|
346
|
-
|
|
347
|
-
---
|
|
348
|
-
|
|
349
|
-
## ๐ License
|
|
350
|
-
|
|
351
|
-
Distributed under the **MIT License**. See [`LICENSE`](LICENSE) for details.
|
|
1
|
+
<div align="center">
|
|
2
|
+
<h1>โก OpenCode Agent-Teams v2</h1>
|
|
3
|
+
<p><strong>Native Hierarchical Multi-Agent Swarms & Automated Git Worktree Sandboxing for OpenCode v2</strong></p>
|
|
4
|
+
|
|
5
|
+
<p>
|
|
6
|
+
<a href="https://www.npmjs.com/package/@mdsohail99/opencode-agent-teams"><img src="https://img.shields.io/npm/v/@mdsohail99/opencode-agent-teams?style=flat-square&color=blue" alt="NPM Version"/></a>
|
|
7
|
+
<img src="https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square" alt="License"/>
|
|
8
|
+
<img src="https://img.shields.io/badge/OpenCode-v2.3.2-FF6B6B?style=flat-square&logo=opencode&logoColor=white" alt="OpenCode v2"/>
|
|
9
|
+
<img src="https://img.shields.io/badge/Node.js-%3E%3D20.19-339933?style=flat-square&logo=nodedotjs&logoColor=white" alt="Node.js"/>
|
|
10
|
+
<img src="https://img.shields.io/badge/TypeScript-5.0-3178C6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript"/>
|
|
11
|
+
</p>
|
|
12
|
+
</div>
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
## ๐ Overview
|
|
17
|
+
|
|
18
|
+
**`@mdsohail99/opencode-agent-teams`** is the official **native multi-agent orchestration plugin** for [OpenCode v2](https://github.com/sst/opencode) (`@opencode/cli@2.3.2`).
|
|
19
|
+
|
|
20
|
+
In v1, running multi-agent swarms required external Node.js relay daemons, port tokens, and background socket connections.
|
|
21
|
+
**In v2, the relay is completely eliminated.**
|
|
22
|
+
|
|
23
|
+
Agent-Teams v2 runs **100% in-process** using OpenCode's native `@opencode/plugin` and `@opencode/client` architecture. It enables high-performance **2-level hierarchical swarms** (`experimental.subagent_depth = 2`), **isolated Git worktree sandboxing**, and real-time swarm steering with **zero background processes, zero localhost ports, and zero configuration bloat**.
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
## ๐๏ธ v2 Swarm Architecture
|
|
28
|
+
|
|
29
|
+
<p align="center">
|
|
30
|
+
<img src="assets/agent_teams_v2_architecture.gif" alt="OpenCode Agent-Teams v2 Architecture" width="720"/>
|
|
31
|
+
</p>
|
|
32
|
+
|
|
33
|
+
<details>
|
|
34
|
+
<summary><b>View Raw Mermaid Architecture Flow</b></summary>
|
|
35
|
+
|
|
36
|
+
```mermaid
|
|
37
|
+
flowchart TD
|
|
38
|
+
User(["๐งโ๐ป Developer"]) -->|opencode| OC["OpenCode v2 Engine"]
|
|
39
|
+
|
|
40
|
+
subgraph Plugin["Agent-Teams v2 Plugin (In-Process)"]
|
|
41
|
+
OC --> Root["Depth 0: agent-teams (Root Orchestrator)"]
|
|
42
|
+
|
|
43
|
+
Root -->|Fan-Out / Escalate| Dept1["Depth 1: Backend Lead"]
|
|
44
|
+
Root -->|Fan-Out / Escalate| Dept2["Depth 1: Frontend Lead"]
|
|
45
|
+
Root -->|Fan-Out / Escalate| Dept3["Depth 1: Security Lead"]
|
|
46
|
+
Root -->|Fan-Out / Escalate| Dept4["Depth 1: QA Lead"]
|
|
47
|
+
|
|
48
|
+
Dept1 -->|team_delegate\nworktree: true| Spec1["Depth 2: Backend Architect\n(Git Worktree: swarm/backend-...)"]
|
|
49
|
+
Dept2 -->|team_delegate\nworktree: true| Spec2["Depth 2: Frontend Developer\n(Git Worktree: swarm/frontend-...)"]
|
|
50
|
+
Dept3 -->|team_delegate\nworktree: false| Spec3["Depth 2: AppSec Engineer\n(In-Place Read-Only Audit)"]
|
|
51
|
+
end
|
|
52
|
+
|
|
53
|
+
Spec1 -->|Verified & Tested| Merge1["Auto-Commit & Auto-Merge\ninto Active Branch"]
|
|
54
|
+
Spec2 -->|Verified & Tested| Merge2["Auto-Commit & Auto-Merge\ninto Active Branch"]
|
|
55
|
+
|
|
56
|
+
Merge1 --> Summary["Consolidated Executive Report\nto User"]
|
|
57
|
+
Merge2 --> Summary
|
|
58
|
+
Spec3 --> Summary
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
</details>
|
|
62
|
+
|
|
63
|
+
---
|
|
64
|
+
|
|
65
|
+
### ๐ Hub-and-Spoke: The Delegating Agent as Escalation Resolver
|
|
66
|
+
|
|
67
|
+
In multi-agent swarms, letting specialists or leads call arbitrary peer agents causes unbounded circular recursion and write collisions. Agent-Teams enforces a strict **Hub-and-Spoke Management by Exception** protocol:
|
|
68
|
+
|
|
69
|
+
1. **Strict Department Scoping:** Department Leads (`backend`, `frontend`, `qa`, etc.) can only dispatch their own subagent specialists. A lead *never* launches a peer department lead directly.
|
|
70
|
+
2. **Management by Exception (`ESCALATE`):** If a lead encounters a cross-cutting blocker (e.g., `qa` detects an unhandled backend endpoint, or `frontend` requires a new authentication schema), the lead immediately returns:
|
|
71
|
+
```text
|
|
72
|
+
ESCALATE: <dept> | WHAT: <need> | WHERE: <file/module> | CONTEXT: <work done + blocker details>
|
|
73
|
+
```
|
|
74
|
+
3. **The Delegating Agent Resolves:** The root orchestrator (`agent-teams`) acts as the central **Escalation Resolver**:
|
|
75
|
+
- It intercepts the escalation without terminating the caller.
|
|
76
|
+
- It checks whether the target department lead is already running (to reuse active session memory) or spawns it inside an isolated Git worktree (`swarm/...`).
|
|
77
|
+
- Once the fix is verified and merged, `agent-teams` hands the context back to the originating lead, allowing it to complete its remaining work seamlessly.
|
|
78
|
+
|
|
79
|
+
---
|
|
80
|
+
|
|
81
|
+
## โจ Key Features in v2
|
|
82
|
+
|
|
83
|
+
* **๐ 100% In-Process Native Plugin**: Built directly on `@opencode/plugin@2.3.2` and `@opencode/client@2.3.2`. No external relay daemons, no background servers, no socket tokens, and zero orphaned processes.
|
|
84
|
+
* **๐ณ 2-Level Hierarchical Swarms (`experimental.subagent_depth = 2`)**: Out-of-the-box support for nested multi-agent trees:
|
|
85
|
+
* **Depth 0**: Root Orchestrator (`agent-teams`)
|
|
86
|
+
* **Depth 1**: Department Leads (`backend`, `frontend`, `security`, `qa`, `devops`, `ai-data`)
|
|
87
|
+
* **Depth 2**: 68 Curated Domain Specialists (`backend-architect`, `api-tester`, `a11y-auditor`, `threat-detection-engineer`, etc.)
|
|
88
|
+
* **๐ก๏ธ Automated Git Worktree Sandboxing**: Never suffer from file collisions when parallel agents write code. `team_delegate(worktree: true)` creates dedicated branches (`swarm/...`), allows the agent to build and test in isolation, auto-commits verified changes, and merges back to your working branch cleanly.
|
|
89
|
+
* **๐ ๏ธ Swarm Control Tooling**:
|
|
90
|
+
* `team_delegate`: Dispatch tasks with optional Git worktree sandboxing.
|
|
91
|
+
* `team_status`: Inspect live progress, deliverables, and active Git worktrees.
|
|
92
|
+
* `team_broadcast`: Steer running teammates with instructions simultaneously.
|
|
93
|
+
* `team_terminate`: Gracefully halt workers and discard unneeded worktrees.
|
|
94
|
+
* **โจ๏ธ Dynamic In-Memory Slash Commands**: `/team`, `/team-status`, and `/team-stop` are injected dynamically at runtime via `ctx.command.transform()`. Zero hardcoded bloat in your `opencode.json`.
|
|
95
|
+
* **๐จ Clean Interactive TUI Installer**: Running the CLI with no arguments launches a full-featured terminal menu to inspect status, install globally, or cleanly uninstall.
|
|
96
|
+
* **๐งน Manifest-Tracked Clean Uninstall**: Installs a `.agent-teams-manifest.json` tracking all 75 curated agents. Running `uninstall` deletes strictly the plugin-owned files, preserving any custom agents you added.
|
|
97
|
+
|
|
98
|
+
---
|
|
99
|
+
|
|
100
|
+
## โก Quickstart & Installation
|
|
101
|
+
|
|
102
|
+
### Option 1: Automatic Installer (Global - Recommended)
|
|
103
|
+
|
|
104
|
+
Run the interactive setup tool:
|
|
105
|
+
|
|
106
|
+
```bash
|
|
107
|
+
npx @mdsohail99/opencode-agent-teams
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
This automatically:
|
|
111
|
+
1. Configures your global `~/.config/opencode/opencode.json` with `"experimental": { "subagent_depth": 2 }` and registers the plugin.
|
|
112
|
+
2. Copies the 75 curated Department Leads and Specialists into `~/.config/opencode/agents/`.
|
|
113
|
+
|
|
114
|
+
---
|
|
115
|
+
|
|
116
|
+
### Option 2: Declarative Config
|
|
117
|
+
|
|
118
|
+
Add the plugin to your global `~/.config/opencode/opencode.json` (or your project's `./opencode.json`):
|
|
119
|
+
|
|
120
|
+
```json
|
|
121
|
+
{
|
|
122
|
+
"$schema": "https://opencode.ai/config.json",
|
|
123
|
+
"experimental": {
|
|
124
|
+
"subagent_depth": 2
|
|
125
|
+
},
|
|
126
|
+
"plugins": [
|
|
127
|
+
"@mdsohail99/opencode-agent-teams"
|
|
128
|
+
]
|
|
129
|
+
}
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
---
|
|
133
|
+
|
|
134
|
+
## ๐ฎ How to Use in OpenCode
|
|
135
|
+
|
|
136
|
+
1. **Launch OpenCode**:
|
|
137
|
+
```bash
|
|
138
|
+
opencode
|
|
139
|
+
```
|
|
140
|
+
2. **Select Agent-Teams**:
|
|
141
|
+
* Press **`Ctrl + x`** followed by **`a`**, then select `agent-teams`.
|
|
142
|
+
* *Or* press **`Shift + Tab`** to cycle agents.
|
|
143
|
+
* *Or* mention `@agent-teams` directly in your prompt.
|
|
144
|
+
|
|
145
|
+
### Example Prompts:
|
|
146
|
+
|
|
147
|
+
#### 1. Full-Stack Parallel Feature Build (Isolated Worktrees)
|
|
148
|
+
> *"Build user authentication: have Backend implement the JWT endpoints in `src/routes/auth.js` while Frontend creates the login dialog in `src/components/LoginModal.tsx`."*
|
|
149
|
+
- **What happens:** Backend and Frontend each receive dedicated Git worktrees. Both code simultaneously. Changes are auto-tested and merged back into your active branch.
|
|
150
|
+
|
|
151
|
+
#### 2. Comprehensive Read-Only Architectural Audit
|
|
152
|
+
> *"Run an architectural audit across this repository. Strict read-only mode: inspect API routes, state management, and edge cases in parallel without creating files."*
|
|
153
|
+
- **What happens:** The Orchestrator dispatches `backend`, `frontend`, and `security` in-place, returning an integrated Executive Findings Report.
|
|
154
|
+
|
|
155
|
+
---
|
|
156
|
+
|
|
157
|
+
## ๐น๏ธ Swarm Slash Commands
|
|
158
|
+
|
|
159
|
+
| Command | Action |
|
|
160
|
+
| :--- | :--- |
|
|
161
|
+
| **`/team`** | Displays a live ASCII hierarchy tree showing which agents are running, active worktrees, and elapsed times. |
|
|
162
|
+
| **`/team-status`** | Synthesizes current progress and deliverables across all active departments. |
|
|
163
|
+
| **`/team-stop`** | Gracefully terminates active background workers and cleans up their worktrees. |
|
|
164
|
+
|
|
165
|
+
---
|
|
166
|
+
|
|
167
|
+
## ๐๏ธ Clean Uninstallation
|
|
168
|
+
|
|
169
|
+
To remove Agent-Teams globally without touching any custom user agents or personal config:
|
|
170
|
+
|
|
171
|
+
```bash
|
|
172
|
+
npx @mdsohail99/opencode-agent-teams uninstall
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
---
|
|
176
|
+
|
|
177
|
+
## ๐ License
|
|
178
|
+
|
|
179
|
+
MIT ยฉ [Sohail Mohammed](https://github.com/mdsohail99)
|