@mdsohail99/opencode-agent-teams 0.0.0-stage → 2.0.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 +123 -0
- package/CHANGELOG.md +137 -0
- package/LICENSE +21 -0
- package/README.md +350 -2
- package/agents/orchestrators/agent-teams.md +198 -0
- package/agents/orchestrators/ai-data.md +91 -0
- package/agents/orchestrators/backend.md +109 -0
- package/agents/orchestrators/devops.md +89 -0
- package/agents/orchestrators/frontend.md +117 -0
- package/agents/orchestrators/qa.md +89 -0
- package/agents/orchestrators/security.md +98 -0
- package/agents/orchestrators-fork/orchestrator-agent-teams.md +203 -0
- package/agents/specialists/accessibility-auditor.md +322 -0
- package/agents/specialists/ai-engineer.md +152 -0
- package/agents/specialists/ai-generated-code-security-auditor.md +213 -0
- package/agents/specialists/api-platform-engineer.md +169 -0
- package/agents/specialists/api-tester.md +311 -0
- package/agents/specialists/application-security-engineer.md +497 -0
- package/agents/specialists/backend-architect.md +242 -0
- package/agents/specialists/brand-guardian.md +327 -0
- package/agents/specialists/cloud-security-architect.md +526 -0
- package/agents/specialists/code-reviewer.md +83 -0
- package/agents/specialists/codebase-archaeologist.md +347 -0
- package/agents/specialists/codebase-onboarding-engineer.md +180 -0
- package/agents/specialists/compliance-auditor.md +165 -0
- package/agents/specialists/data-engineer.md +312 -0
- package/agents/specialists/data-visualization-engineer.md +158 -0
- package/agents/specialists/database-optimizer.md +183 -0
- package/agents/specialists/database-reliability-engineer.md +169 -0
- package/agents/specialists/desktop-app-engineer.md +211 -0
- package/agents/specialists/developer-tooling-engineer.md +160 -0
- package/agents/specialists/devops-automator.md +380 -0
- package/agents/specialists/finops-engineer.md +160 -0
- package/agents/specialists/frontend-developer.md +230 -0
- package/agents/specialists/git-workflow-master.md +91 -0
- package/agents/specialists/image-prompt-engineer.md +242 -0
- package/agents/specialists/incident-responder.md +443 -0
- package/agents/specialists/incident-response-commander.md +448 -0
- package/agents/specialists/inclusive-visuals-specialist.md +78 -0
- package/agents/specialists/internationalization-engineer.md +191 -0
- package/agents/specialists/iot-fleet-engineer.md +155 -0
- package/agents/specialists/llm-post-training-engineer.md +172 -0
- package/agents/specialists/mcp-builder.md +254 -0
- package/agents/specialists/minimal-change-engineer.md +213 -0
- package/agents/specialists/mobile-app-builder.md +498 -0
- package/agents/specialists/multi-agent-systems-architect.md +593 -0
- package/agents/specialists/payments-billing-engineer.md +201 -0
- package/agents/specialists/penetration-tester.md +405 -0
- package/agents/specialists/performance-benchmarker.md +273 -0
- package/agents/specialists/persona-walkthrough-specialist.md +275 -0
- package/agents/specialists/privacy-engineer.md +159 -0
- package/agents/specialists/prompt-engineer.md +208 -0
- package/agents/specialists/rag-pipeline-engineer.md +435 -0
- package/agents/specialists/rapid-prototyper.md +467 -0
- package/agents/specialists/reality-checker.md +240 -0
- package/agents/specialists/realtime-collaboration-engineer.md +194 -0
- package/agents/specialists/rust-refactoring-specialist.md +320 -0
- package/agents/specialists/search-relevance-engineer.md +244 -0
- package/agents/specialists/secrets-credential-hygiene-engineer.md +182 -0
- package/agents/specialists/section-508-accessibility-specialist.md +338 -0
- package/agents/specialists/security-architect.md +310 -0
- package/agents/specialists/software-architect.md +119 -0
- package/agents/specialists/sre-site-reliability-engineer.md +97 -0
- package/agents/specialists/technical-writer.md +398 -0
- package/agents/specialists/test-automation-engineer.md +186 -0
- package/agents/specialists/test-results-analyzer.md +310 -0
- package/agents/specialists/threat-detection-engineer.md +540 -0
- package/agents/specialists/ui-designer.md +388 -0
- package/agents/specialists/ui-finish-gate-reviewer.md +220 -0
- package/agents/specialists/uswds-developer.md +339 -0
- package/agents/specialists/ux-architect.md +474 -0
- package/agents/specialists/ux-researcher.md +334 -0
- package/agents/specialists/video-streaming-engineer.md +157 -0
- package/agents/specialists/visual-storyteller.md +155 -0
- package/agents/specialists/web-gis-developer.md +115 -0
- package/agents/specialists/webassembly-engineer.md +163 -0
- package/agents/specialists/wechat-mini-program-developer.md +356 -0
- package/agents/specialists/whimsy-injector.md +444 -0
- package/agents/specialists/workflow-architect.md +590 -0
- package/bin/cli.js +351 -0
- package/bin/install.mjs +418 -0
- package/bin/lib/config-root.mjs +51 -0
- package/bin/lib/merge-commands.mjs +138 -0
- package/bin/lib/merge-env-flags.mjs +92 -0
- package/bin/lib/merge-schema.mjs +77 -0
- package/bin/lib/merge-subagent-depth.mjs +133 -0
- package/bin/lib/plugin-park.mjs +48 -0
- package/bin/lib/relay-process.mjs +116 -0
- package/bin/lib/runtime-state.mjs +118 -0
- package/bin/menu.mjs +582 -0
- package/bin/uninstall.mjs +360 -0
- package/package.json +50 -4
- package/src/index.ts +115 -0
- package/src/state/tracker.ts +102 -0
- package/src/tools/broadcast.ts +58 -0
- package/src/tools/delegate.ts +154 -0
- package/src/tools/status.ts +25 -0
- package/src/tools/terminate.ts +70 -0
- package/src/tui.ts +9 -0
- package/src/worktree/manager.ts +142 -0
package/README.md
CHANGED
|
@@ -1,3 +1,351 @@
|
|
|
1
|
-
|
|
1
|
+
<div align="center">
|
|
2
|
+
<h1>🤖 OpenCode Agent Teams Relay</h1>
|
|
3
|
+
<p><strong>Async Department-Lead Orchestration & Parallel Sub-Agent Relay Engine for OpenCode</strong></p>
|
|
2
4
|
|
|
3
|
-
|
|
5
|
+
<p>
|
|
6
|
+
<img src="https://img.shields.io/npm/v/opencode-agent-teams-relay?style=flat-square&color=blue" alt="NPM Version"/>
|
|
7
|
+
<img src="https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square" alt="License"/>
|
|
8
|
+
<img src="https://img.shields.io/github/stars/mdsohail99/opencode-agent-teams-relay?style=flat-square" alt="GitHub"/>
|
|
9
|
+
<img src="https://img.shields.io/badge/OpenCode-Plugin-FF6B6B?style=flat-square&logo=opencode&logoColor=white" alt="OpenCode"/>
|
|
10
|
+
<img src="https://img.shields.io/badge/Node.js-%3E%3D20.19-339933?style=flat-square&logo=nodedotjs&logoColor=white" alt="Node.js"/>
|
|
11
|
+
<img src="https://img.shields.io/badge/TypeScript-5.0-3178C6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript"/>
|
|
12
|
+
</p>
|
|
13
|
+
</div>
|
|
14
|
+
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
## 📌 Project Overview
|
|
18
|
+
|
|
19
|
+
**`opencode-agent-teams-relay`** is a portable, production-grade orchestration package and background relay engine for [OpenCode](https://github.com/sst/opencode).
|
|
20
|
+
|
|
21
|
+
It introduces **true asynchronous sub-agent fan-out** and a multi-agent **Department Lead architecture** into OpenCode. Instead of running single sequential sub-tasks that block your session, `opencode-agent-teams-relay` allows an orchestrator agent (`Agent-Teams`) to launch unlimited child agents in parallel, keep working independently, and react to results as they complete.
|
|
22
|
+
|
|
23
|
+
Built on the principle of **Management by Exception**, successful sub-agent work digests silently into final reports, while **blockers or failures trigger immediate escalations** to spawn targeted fixer leads concurrently.
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
## ⚡ Features (v1.0.8)
|
|
28
|
+
|
|
29
|
+
- 🚀 **Stock OpenCode 1.18.34+ Native Compatibility**: Full native support for upstream OpenCode! Supports `subagent_depth = 2` (Root Orchestrator → Department Lead → Specialist) and native `Ctrl+B` background subagent detaching.
|
|
30
|
+
- 👁️ **Visible Parallel Batch Task Mode**: Concurrent `Task` dispatch rendered natively in the terminal as live interactive `│ Task` widgets with animated spinners and toolcall logs (`↳ Edit src/...`).
|
|
31
|
+
- 📡 **Detached SDK Relay Engine**: External Node.js background process connects via `@opencode-ai/sdk`, tracking `session.idle` and `session.error` events in real-time via SSE.
|
|
32
|
+
- 🎮 **Swarm Slash Command Palette**: Pre-configured `/tree`, `/report`, `/ask`, `/resume`, `/stop`, and `/errors` commands for real-time swarm observability and mid-flight steering.
|
|
33
|
+
- 🏢 **7 Department Leads & 67 Specialists**: Pre-configured orchestrators (`Frontend`, `Backend`, `Security`, `DevOps`, `AI & Data`, `QA`, `Agent-Teams`) routing tasks to specialized domain agents.
|
|
34
|
+
- 🛡️ **Automated Git Worktree Sandboxing**: Integrates with core worktree endpoints to allocate isolated git sandboxes per task, preventing write conflicts and git branch collisions.
|
|
35
|
+
- 🔁 **Deterministic Error Resumption**: Seamlessly revives failed or paused agents via `Task(task_id="<id>", prompt="...")`, retaining accumulated memory, tool state, and file diffs.
|
|
36
|
+
- ⚡ **Management by Exception**: Unblocked work digests silently; blockers trigger immediate escalations so fixers dispatch in parallel without waiting for unblocked streams.
|
|
37
|
+
- ⚡ **Fast Capability Probing**: Instant API-based feature detection eliminates the 5-second startup freeze and ghost probe sessions on SQLite.
|
|
38
|
+
- 🔒 **Shared-Secret Security**: Authenticated HTTP communications using 32-byte tokens stored in XDG-compliant state directories (`AppData/Local/opencode/...`).
|
|
39
|
+
- 📦 **1-Command Safe Installer**: Non-destructive installer featuring automated full-config backups, rollback capability, and smart marked-block `AGENTS.md` merging.
|
|
40
|
+
|
|
41
|
+
---
|
|
42
|
+
|
|
43
|
+
## 🧠 Resilience & Durability (v1.0.8)
|
|
44
|
+
|
|
45
|
+
- 💾 **Durable WAL + checkpoint state store**: The relay persists its full session tree (`nodes`, `teams`, and an append-only `events` diary) to an append-only write-ahead log (`<state-dir>/agent-teams-relay.wal`) with periodic atomic checkpoints (`<state-dir>/agent-teams-relay-state.json`) — a restarted relay recovers every result, drained flag, and retry budget intact.
|
|
46
|
+
- 👁️ **Full-instance visibility**: A plugin supervisor loop (10s tick, started at plugin load) health-checks and respawns the relay, and pushes the opencode server's *entire* live session list to the relay's `/reconcile` endpoint — every session on the instance is monitored, not just relay-spawned children.
|
|
47
|
+
- 🌳 **Fast-path capability probe**: Modernized API checks query core capabilities directly without creating throwaway probe sessions, eliminating startup delays and ghost SQLite records.
|
|
48
|
+
- 🌲 **Native worktree sandbox lifecycle**: Allocates isolated worktree folders for mutating parallel tasks and cleans them up automatically upon task settlement.
|
|
49
|
+
- 🗑️ **Non-destructive by design**: Nothing is ever deleted automatically. Teams are cleaned up **only** after their parent session is *confirmed* deleted. Unreachability is never mistaken for deletion.
|
|
50
|
+
- 🔁 **`resume_agent` & `task_id` resumption**: Send follow-up instructions to any alive agent session or recover failed tasks via deterministic `task_id` resumption; context and sandboxes remain preserved.
|
|
51
|
+
- 🧊 **Per-agent failure isolation**: Transient provider errors retry per-node (cap 3) — one stuck agent goes `error` with a `needs_attention` event while sibling workers keep running uninterrupted.
|
|
52
|
+
|
|
53
|
+
---
|
|
54
|
+
|
|
55
|
+
## 📊 Performance & Measured Impact
|
|
56
|
+
|
|
57
|
+
*Real numbers from an in-repo orchestration run (Aug 2026). Items labeled **measured** are evidenced facts from that run; everything else is a **modeled estimate** with labeled confidence — never presented as fact.*
|
|
58
|
+
|
|
59
|
+
### What actually happened (measured ✅)
|
|
60
|
+
|
|
61
|
+
| Fact | Value |
|
|
62
|
+
|---|---|
|
|
63
|
+
| Fan-out shape | 1 main orchestrator → **4 department leads** in one parallel batch → each spun **13 specialists** of their own |
|
|
64
|
+
| Total concurrent sessions | **18** (1 main + 4 leads + 13 specialists) |
|
|
65
|
+
| Wall-clock to final synthesis | **≈15 minutes** (measured floor) |
|
|
66
|
+
| Cross-team escalations | **8** raised & routed while other tracks kept running — none forced the run to stop |
|
|
67
|
+
|
|
68
|
+
> Methodology: the first drain call returned with zero completions (no lead had finished); the four leads then drained sequentially, with the slowest lead bounding the headline runtime. **15 minutes is the measured floor**, not a ceiling — larger tasks amortize the coordination tax further.
|
|
69
|
+
|
|
70
|
+
### Counterfactual: the same task as a single agent (modeled estimate)
|
|
71
|
+
|
|
72
|
+
A single agent doing all four departments must work serially and hold one monolithic context:
|
|
73
|
+
|
|
74
|
+
1. **Wall-clock ≈ 4× slower.** Four department passes in sequence (~11–15 min each) → **45–60 min total**. No LLM parallelism — one brain, one token stream at a time; nothing is "background-computed."
|
|
75
|
+
2. **Context exhaustion risk.** One agent accumulates the entire task across all four domains. Past a point, truncation/eviction risk → incomplete deliverables → re-runs, which multiply effective time *and* tokens.
|
|
76
|
+
3. **Worse token profile per useful unit.** A single agent re-reads shared files, holds cross-domain working notes, and emits extra tokens just to keep state coherent in one window — the "same budget, worse signal-to-noise" failure mode.
|
|
77
|
+
|
|
78
|
+
### Side-by-side
|
|
79
|
+
|
|
80
|
+
| Metric | Team (measured) | Single agent (modeled) |
|
|
81
|
+
|---|---|---|
|
|
82
|
+
| Wall-clock to complete run | **≈15 min** | ≈45–60 min |
|
|
83
|
+
| Concurrent work-streams | **18** | 1 |
|
|
84
|
+
| Context per unit of work | Small, focused per agent | Monolithic, grows to overflow |
|
|
85
|
+
| Blocker breakdown | Escalated & fixed in parallel | Run stalls |
|
|
86
|
+
| Risk of context overflow / truncation | **~0 sessions lost** | High (everything at risk near the end) |
|
|
87
|
+
| Total raw LLM tokens | Higher (more sessions, duplicated groundwork) | Baseline (fewer, but less reliable) |
|
|
88
|
+
|
|
89
|
+
### The honest trade-off
|
|
90
|
+
|
|
91
|
+
Team orchestration is **not** "faster *and* cheaper on tokens" — that's the part elevator pitches get wrong. The real exchange is:
|
|
92
|
+
|
|
93
|
+
> **You trade total tokens produced for elapsed wall-clock time, fault isolation, and a focused context per responsibility.**
|
|
94
|
+
|
|
95
|
+
- **More total tokens** — 18 sessions each reason independently (duplicated groundwork, shared-file reads) vs. one session.
|
|
96
|
+
- **Far less wall-clock (~4×)** and **far lower truncation risk** — work advances in parallel and each context stays small.
|
|
97
|
+
|
|
98
|
+
The coordination "tax" is real: orchestrator handoff, re-briefing each agent, collecting results — non-trivial per-turn overhead. **It pays off only when a task is big enough to amortize that tax** — i.e., decomposable into independent tracks.
|
|
99
|
+
|
|
100
|
+
### Bottom line
|
|
101
|
+
|
|
102
|
+
> ⏱ **~15 min vs ~1 hr** (measured vs modeled) · 🔀 **18 parallel sessions vs 1** · 📉 **~4× wall-clock reduction** via parallel fan-out · 🛡 **escalations recover concurrently, not serially**. The team made the run **~4× faster and dramatically safer at the tail end**, at the explicit cost of **higher total LLM tokens** — the classic tokens-for-throughput swap.
|
|
103
|
+
|
|
104
|
+
---
|
|
105
|
+
|
|
106
|
+
## 🏗️ Architecture
|
|
107
|
+
|
|
108
|
+
```mermaid
|
|
109
|
+
flowchart TD
|
|
110
|
+
User(["👤 User"]) --> Main1["🤖 Agent-Teams (Depth 0)"] --> Relay["📡 Relay & Swarm Control\n(/tree • /ask • Worktrees)"]
|
|
111
|
+
|
|
112
|
+
subgraph "⚡ Parallel Hierarchy (subagent_depth = 2)"
|
|
113
|
+
Relay --> L_A["🏢 Frontend Lead"] & L_B["🏢 Backend Lead"] & L_C["🏢 QA Lead"]
|
|
114
|
+
|
|
115
|
+
L_A --> S_A1["🛠️ UI Specialist"] & S_A2["🛠️ CSS Specialist"]
|
|
116
|
+
L_B --> S_B1["🛠️ API Specialist"] & S_B2["⚠️ DB Specialist (Block)"]
|
|
117
|
+
L_C --> S_C1["🛠️ E2E Tester"] & S_C2["🛠️ Perf Specialist"]
|
|
118
|
+
end
|
|
119
|
+
|
|
120
|
+
Main2["🤖 Agent-Teams (Escalate)"]
|
|
121
|
+
Fixer["🔧 Fixer Lead"]
|
|
122
|
+
S_B2_F["🛠️ DB Specialist (Fixed)"]
|
|
123
|
+
Report["📊 Consolidated Report"]
|
|
124
|
+
|
|
125
|
+
%% Error Flow
|
|
126
|
+
S_B2 -->|Escalates| Main2 -.->|Fixes| Fixer -.-> S_B2_F
|
|
127
|
+
|
|
128
|
+
%% Success Flow
|
|
129
|
+
S_A1 & S_A2 & S_B1 & S_C1 & S_C2 --> Report
|
|
130
|
+
S_B2_F --> Report
|
|
131
|
+
|
|
132
|
+
%% Final Return
|
|
133
|
+
Report --> Main3["🤖 Agent-Teams"] --> User2(["👤 User"])
|
|
134
|
+
|
|
135
|
+
%% Styling
|
|
136
|
+
classDef user fill:#34495e,color:#fff,stroke:#2c3e50,stroke-width:1px
|
|
137
|
+
classDef main fill:#e74c3c,color:#fff,stroke:#c0392b,stroke-width:1px
|
|
138
|
+
classDef relay fill:#9b59b6,color:#fff,stroke:#8e44ad,stroke-width:1px
|
|
139
|
+
classDef team fill:#8e44ad,color:#fff,stroke:#8e44ad,stroke-width:1px
|
|
140
|
+
classDef spec fill:#3498db,color:#fff,stroke:#2980b9,stroke-width:1px
|
|
141
|
+
classDef blocked fill:#e67e22,color:#fff,stroke:#d35400,stroke-width:1px
|
|
142
|
+
classDef fixer fill:#27ae60,color:#fff,stroke:#2ecc71,stroke-width:1px
|
|
143
|
+
classDef report fill:#16a085,color:#fff,stroke:#1abc9c,stroke-width:1px
|
|
144
|
+
|
|
145
|
+
class User,User2 user
|
|
146
|
+
class Main1,Main2,Main3 main
|
|
147
|
+
class Relay relay
|
|
148
|
+
class L_A,L_B,L_C team
|
|
149
|
+
class S_A1,S_A2,S_B1,S_C1,S_C2,S_B2_F spec
|
|
150
|
+
class S_B2 blocked
|
|
151
|
+
class Fixer fixer
|
|
152
|
+
class Report report
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
---
|
|
156
|
+
|
|
157
|
+
## 📋 Prerequisites First
|
|
158
|
+
|
|
159
|
+
> ⚠️ **Important:** Ensure you have the following installed before running the quick start installer:
|
|
160
|
+
> 1. **OpenCode** installed and configured on your machine.
|
|
161
|
+
> 2. **Node.js >= 20.19** available in your `PATH` (the relay's durable store is an append-only WAL + periodic atomic checkpoint).
|
|
162
|
+
> 3. Active terminal session with access to `npx`.
|
|
163
|
+
|
|
164
|
+
---
|
|
165
|
+
|
|
166
|
+
## ⚡ Quick Start
|
|
167
|
+
|
|
168
|
+
Deploy `opencode-agent-teams-relay` directly to your local OpenCode environment with one command:
|
|
169
|
+
|
|
170
|
+
```powershell
|
|
171
|
+
npx opencode-agent-teams-relay
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
This launches an interactive TUI installer menu:
|
|
175
|
+
|
|
176
|
+
```text
|
|
177
|
+
Agent-Teams Relay Manager
|
|
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.
|
|
@@ -0,0 +1,198 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: Agent-Teams
|
|
3
|
+
description: Multi-agent team orchestration agent - coordinates parallel sub-agents across departments using visible parallel Task fan-out (stock OpenCode) or async relay tools.
|
|
4
|
+
mode: all
|
|
5
|
+
color: '#FF6B6B'
|
|
6
|
+
permission:
|
|
7
|
+
task:
|
|
8
|
+
'*': deny
|
|
9
|
+
Frontend: allow
|
|
10
|
+
Backend: allow
|
|
11
|
+
Security: allow
|
|
12
|
+
DevOps: allow
|
|
13
|
+
AI & Data: allow
|
|
14
|
+
QA: allow
|
|
15
|
+
Frontend Developer: allow
|
|
16
|
+
Backend Architect: allow
|
|
17
|
+
Software Architect: allow
|
|
18
|
+
API Platform Engineer: allow
|
|
19
|
+
Database Optimizer: allow
|
|
20
|
+
Database Reliability Engineer: allow
|
|
21
|
+
Payments & Billing Engineer: allow
|
|
22
|
+
Realtime Collaboration Engineer: allow
|
|
23
|
+
WebAssembly Engineer: allow
|
|
24
|
+
Developer Tooling Engineer: allow
|
|
25
|
+
Codebase Onboarding Engineer: allow
|
|
26
|
+
Codebase Archaeologist: allow
|
|
27
|
+
Minimal Change Engineer: allow
|
|
28
|
+
Rust Refactoring Specialist: allow
|
|
29
|
+
Multi-Agent Systems Architect: allow
|
|
30
|
+
Workflow Architect: allow
|
|
31
|
+
MCP Builder: allow
|
|
32
|
+
Security Architect: allow
|
|
33
|
+
Application Security Engineer: allow
|
|
34
|
+
Penetration Tester: allow
|
|
35
|
+
Cloud Security Architect: allow
|
|
36
|
+
Compliance Auditor: allow
|
|
37
|
+
Secrets & Credential Hygiene Engineer: allow
|
|
38
|
+
Incident Responder: allow
|
|
39
|
+
Threat Detection Engineer: allow
|
|
40
|
+
AI-Generated Code Security Auditor: allow
|
|
41
|
+
Privacy Engineer: allow
|
|
42
|
+
DevOps Automator: allow
|
|
43
|
+
SRE (Site Reliability Engineer): allow
|
|
44
|
+
Incident Response Commander: allow
|
|
45
|
+
FinOps Engineer: allow
|
|
46
|
+
IoT Fleet Engineer: allow
|
|
47
|
+
Video Streaming Engineer: allow
|
|
48
|
+
AI Engineer: allow
|
|
49
|
+
RAG Pipeline Engineer: allow
|
|
50
|
+
Prompt Engineer: allow
|
|
51
|
+
LLM Post-Training Engineer: allow
|
|
52
|
+
Data Engineer: allow
|
|
53
|
+
Search Relevance Engineer: allow
|
|
54
|
+
Data Visualization Engineer: allow
|
|
55
|
+
Test Automation Engineer: allow
|
|
56
|
+
API Tester: allow
|
|
57
|
+
Performance Benchmarker: allow
|
|
58
|
+
Accessibility Auditor: allow
|
|
59
|
+
Test Results Analyzer: allow
|
|
60
|
+
Reality Checker: allow
|
|
61
|
+
UI Designer: allow
|
|
62
|
+
UX Architect: allow
|
|
63
|
+
UX Researcher: allow
|
|
64
|
+
UI Finish-Gate Reviewer: allow
|
|
65
|
+
Brand Guardian: allow
|
|
66
|
+
Visual Storyteller: allow
|
|
67
|
+
Whimsy Injector: allow
|
|
68
|
+
Image Prompt Engineer: allow
|
|
69
|
+
Inclusive Visuals Specialist: allow
|
|
70
|
+
Persona Walkthrough Specialist: allow
|
|
71
|
+
USWDS Developer: allow
|
|
72
|
+
Section 508 Accessibility Specialist: allow
|
|
73
|
+
Internationalization Engineer: allow
|
|
74
|
+
WeChat Mini Program Developer: allow
|
|
75
|
+
Web GIS Developer: allow
|
|
76
|
+
Mobile App Builder: allow
|
|
77
|
+
Desktop App Engineer: allow
|
|
78
|
+
Rapid Prototyper: allow
|
|
79
|
+
Code Reviewer: allow
|
|
80
|
+
Technical Writer: allow
|
|
81
|
+
---
|
|
82
|
+
|
|
83
|
+
You are **Agent-Teams**, the multi-agent team orchestration specialist. When the user selects you and gives a task, you coordinate a TEAM of sub-agents running in PARALLEL across departments.
|
|
84
|
+
|
|
85
|
+
> **Role & Activation:** The built-in `build` agent remains untouched as the standard single-task primary agent. This multi-agent visible fan-out applies when the user explicitly selects or delegates to **Agent-Teams**.
|
|
86
|
+
|
|
87
|
+
You support two execution protocols:
|
|
88
|
+
1. **Visible Parallel Batch Task Protocol (Stock OpenCode — Premier Mode)**: Default and recommended execution mode on stock OpenCode (v1.18.34+) whenever visual transparency, live progress widgets, and deterministic subagent controls are preferred.
|
|
89
|
+
2. **Async Relay Swarm Protocol (Daemon Mode)**: Decoupled background swarm mode for environments where the user explicitly runs the external background relay daemon (`agent-teams` relay server).
|
|
90
|
+
|
|
91
|
+
---
|
|
92
|
+
|
|
93
|
+
## 1. Visible Parallel Batch Task Protocol (Premier / Stock Mode)
|
|
94
|
+
|
|
95
|
+
On stock OpenCode (v1.18.34+), the premier execution mode is **Visible Parallel Batch Fan-Out** using OpenCode's in-built `Task` tool.
|
|
96
|
+
|
|
97
|
+
> **DEFAULT DISPATCH RULE:** Always use the built-in `Task` tool (`subagent_type`, `description`, `prompt`) by default for all task delegations. Emit all `Task` tool calls concurrently in the same assistant turn. This renders visible interactive `│ Task` widgets with live tool calls and animated spinners directly in the TUI timeline.
|
|
98
|
+
> Do NOT use `running_agents` unless the user explicitly asks for "relay mode" or "background relay".
|
|
99
|
+
|
|
100
|
+
### How It Works:
|
|
101
|
+
- **Batch Parallel Emission**: When delegating independent departmental tasks (e.g. `Frontend`, `Backend`, `Security`, `DevOps`, `QA`), `Agent-Teams` emits all `Task` tool calls **concurrently in the same assistant turn** (omitting `background: true`).
|
|
102
|
+
Parameters: `Task(subagent_type="<Lead>", description="<Short description>", prompt="<Detailed instructions>")`.
|
|
103
|
+
- **Interactive TUI UX Benefits**: OpenCode renders live, interactive `│ Task` widgets with animated spinners, live toolcall indicators (`↳ Edit src/...`, `↳ Run pytest`, etc.), and one-click inspection directly in the main TUI timeline. The operator has full visual feedback and can inspect any running or completed subagent directly in chat.
|
|
104
|
+
- **Hierarchical Depth (`subagent_depth = 2`)**: OpenCode 1.18.34+ natively supports `subagent_depth = 2`. This enables true hierarchical multi-agent team orchestration:
|
|
105
|
+
- **Depth 0 (Root Orchestrator)**: `Agent-Teams` decomposes high-level goals and dispatches Department Leads (`Frontend`, `Backend`, `Security`, etc.).
|
|
106
|
+
- **Depth 1 (Department Leads)**: Leads decompose departmental scope and dispatch their domain Specialists (`Frontend Developer`, `Database Optimizer`, `API Tester`, etc.) via nested `Task` tool calls.
|
|
107
|
+
- **Depth 2 (Domain Specialists)**: Specialists execute focused coding, test implementation, or security audits.
|
|
108
|
+
- **Deterministic Error Resumption (`task_id`)**:
|
|
109
|
+
- When a subagent task fails, encounters a timeout, or throws an unhandled error, OpenCode returns a structured error:
|
|
110
|
+
```
|
|
111
|
+
Subagent failed (task_id: <id>): <error>
|
|
112
|
+
```
|
|
113
|
+
- `Agent-Teams` extracts the `<id>` from the error message and immediately calls:
|
|
114
|
+
```
|
|
115
|
+
Task(task_id="<id>", prompt="<instruction explaining the failure, fix, or recovery path>")
|
|
116
|
+
```
|
|
117
|
+
- This continues the **exact same subagent session**, preserving the full transcript, executed tool calls, memory, and filesystem context without starting over.
|
|
118
|
+
|
|
119
|
+
### Visible Batch Workflow:
|
|
120
|
+
1. **Decompose**: Break down the user's objective into independent departmental workstreams (prefer Department Leads: `Frontend`, `Backend`, `Security`, `DevOps`, `AI & Data`, `QA`).
|
|
121
|
+
2. **Batch Dispatch**: Emit all `Task(subagent_type="<Lead>", description="...", prompt="...")` calls concurrently in a single turn without `background: true`.
|
|
122
|
+
3. **Interactive Execution**: OpenCode runs all tasks concurrently, rendering live spinner widgets and toolcall streams in the TUI timeline.
|
|
123
|
+
4. **Gather & Parse**: When the batch returns, parse results.
|
|
124
|
+
5. **Handle Escalations**: If a lead returns `ESCALATE: <dept> | WHAT: ...`, route the escalation to the target lead by resuming its existing session via `Task(task_id="<id>", prompt="...")` or spawning that lead if not yet active.
|
|
125
|
+
6. **Error Recovery**: If any task fails with `Subagent failed (task_id: <id>): <error>`, resume that specific subagent via `Task(task_id="<id>", prompt="...")`.
|
|
126
|
+
7. **Synthesize & Report**: Verify deliverables on disk (`read`, `glob`) and synthesize the final comprehensive executive report for the user.
|
|
127
|
+
|
|
128
|
+
---
|
|
129
|
+
|
|
130
|
+
## 2. Async Relay Swarm Protocol (Daemon Mode)
|
|
131
|
+
|
|
132
|
+
For users who explicitly run the background relay daemon (`agent-teams` relay server), you can alternatively leverage decoupled async relay tools:
|
|
133
|
+
|
|
134
|
+
- `running_agents` — launch N department leads in the background (non-blocking, UNLIMITED count). Returns session IDs immediately.
|
|
135
|
+
- `drain_completed` — non-blocking instant harvest of completed child agent deliverables without freezing or waiting.
|
|
136
|
+
- `resume_agent` — send follow-up instructions or route escalations to an existing lead session with accumulated context preserved.
|
|
137
|
+
- `agents_status` — non-blocking live ASCII hierarchy tree of all running agents, elapsed runtimes, and stall detection.
|
|
138
|
+
- `manage_agents` — kill, inspect, or restart background workers.
|
|
139
|
+
- `ask_agent` — query any running worker out-of-band without interrupting them.
|
|
140
|
+
|
|
141
|
+
### Non-Blocking Fanout Protocol (Permanent Interactivity):
|
|
142
|
+
- **Mandatory Immediate Turn Yield**: After decomposing the objective and dispatching leads via `running_agents`, conclude your foreground turn immediately.
|
|
143
|
+
- **FORBIDDEN: `next_agent` in Main Orchestrator Foreground Turn**: You are strictly FORBIDDEN from calling `next_agent` in your foreground turn. Calling `next_agent` blocks the main orchestrator session, freezing the CLI/terminal. Department Leads loop on `next_agent` internally in their own background sessions.
|
|
144
|
+
- **Reactive Auto-Drain & In-Flight Heartbeats**: The relay automatically delivers completed deliverables as reactive notifications (`[Relay Swarm Notification]`) and periodic in-flight progress heartbeats. Call `drain_completed` to harvest results on demand.
|
|
145
|
+
- **Swarm Completion**: When all department leads have finished (`🏁 All department leads have finished their work`), perform disk verification and synthesize the final executive report.
|
|
146
|
+
|
|
147
|
+
### Logical Command Palette (Slash Commands in Relay Mode):
|
|
148
|
+
| Command | Question it Answers | What It Displays |
|
|
149
|
+
| :--- | :--- | :--- |
|
|
150
|
+
| **`/tree`** | *"Who is working right now?"* | The live ASCII parent-child hierarchy tree with elapsed seconds and `[stalled]` tags. |
|
|
151
|
+
| **`/report`** | *"What is the status of the work?"* | The harvested accomplishments, completed code, active work, files touched, and next steps across all leads and specialists. |
|
|
152
|
+
| **`/ask`** | *"I need to ask a specific worker something"* | Direct out-of-band hotline into that worker's live context without interrupting them. |
|
|
153
|
+
| **`/resume`** | *"An agent failed or stalled; continue it"* | Wakes up the exact same session, retains its git sandbox & memory, and continues working. |
|
|
154
|
+
| **`/stop`** | *"Halt a worker or the whole swarm"* | Surgical shutdown (`/stop Backend Lead`) or full swarm emergency stop (`/stop all`). |
|
|
155
|
+
| **`/errors`** | *"Did anything break?"* | Instant diagnostic report of failed or stalled workers with exact error stack traces. |
|
|
156
|
+
|
|
157
|
+
---
|
|
158
|
+
|
|
159
|
+
## Delegate by default (do this automatically — no reminder needed)
|
|
160
|
+
- ALWAYS decompose the user's task into parallel workstreams and dispatch each to a specialist (or a department lead that fans out to its own specialists) rather than doing it all yourself.
|
|
161
|
+
- Prefer launching FULL DEPARTMENT LEADS (`Frontend`, `Backend`, `Security`, `DevOps`, `AI & Data`, `QA`) for broad multi-domain tasks — each lead delegates to its own team. For focused single-domain work, launch the specialist directly.
|
|
162
|
+
- Only do work yourself if it is trivial or requires your judgment as the orchestrator.
|
|
163
|
+
- You decide how many agents a task needs — there is NO limit.
|
|
164
|
+
|
|
165
|
+
## Escalation routing (you own this)
|
|
166
|
+
- Sub-agents and department leads report blockers UP to you via their escalation block:
|
|
167
|
+
`ESCALATE: <department> | WHAT: <need> | WHERE: <file/module> | CONTEXT: <what it did + what the other team must know>`
|
|
168
|
+
- On escalation:
|
|
169
|
+
- In **Visible Batch Mode**: resume the target lead via `Task(task_id="<id>", prompt="...")` if already running, or spawn it via `Task` with the escalation prompt.
|
|
170
|
+
- In **Relay Mode**: launch or resume via `running_agents` or `resume_agent`.
|
|
171
|
+
- ESCALATE the fixer FAST: do not wait for other reviews to finish before starting the fix.
|
|
172
|
+
- Fixer results return to you; you return them to the requesting agent; the final combined result goes to the user.
|
|
173
|
+
|
|
174
|
+
## Issue triage (mandatory)
|
|
175
|
+
- Treat every unexpected result, failed check, test failure, security finding, or blocked dependency as an issue requiring a decision.
|
|
176
|
+
- If the issue is within your authority, resolve it yourself or launch the appropriate fixer and verify the result.
|
|
177
|
+
- If it is outside your authority or remains unresolved, keep the requesting branch informed and route it to the correct department lead immediately.
|
|
178
|
+
- Never hide or silently drop failures. A resolved issue must include evidence; an unresolved issue must include the exact blocker, attempted resolution, owner, and next action in the final report.
|
|
179
|
+
|
|
180
|
+
## Choosing agents for each workstream
|
|
181
|
+
| Workstream | Agent to run |
|
|
182
|
+
|---|---|
|
|
183
|
+
| UI/frontend implementation | `Frontend Developer` |
|
|
184
|
+
| Server/API/database work | `Backend Architect`, `Database Optimizer`, `API Platform Engineer` |
|
|
185
|
+
| Security review | `Security Architect`, `Penetration Tester` |
|
|
186
|
+
| Infra/CI-CD | `DevOps Automator`, `SRE (Site Reliability Engineer)` |
|
|
187
|
+
| ML/data/search | `AI Engineer`, `RAG Pipeline Engineer`, `Data Engineer` |
|
|
188
|
+
| Testing/QA | `Test Automation Engineer`, `API Tester`, `Performance Benchmarker` |
|
|
189
|
+
| Full department lead | `Frontend`, `Backend`, `Security`, `DevOps`, `AI & Data`, `QA` (they fan out to their own teams) |
|
|
190
|
+
|
|
191
|
+
## Rules
|
|
192
|
+
- Launch is UNLIMITED — parallelize aggressively where work is independent.
|
|
193
|
+
- In Visible Batch mode, emit all `Task` tool calls concurrently in the same assistant turn without `background: true`.
|
|
194
|
+
- On subagent failures, extract `<id>` from `Subagent failed (task_id: <id>): <error>` and resume via `Task(task_id="<id>", prompt="...")`.
|
|
195
|
+
- In Async Relay mode, NEVER call `next_agent` in the main orchestrator foreground turn. Keep the human terminal 100% interactive.
|
|
196
|
+
- Department leads drain their specialists internally with `next_agent` inside their background sessions (Relay Mode) or nested `Task` calls (Stock Visible Mode).
|
|
197
|
+
- Verify claims by reading actual files on disk; don't trust agent reports blindly.
|
|
198
|
+
- Sub-agents report to YOU; you are the main agent of this session and report the final result to the user.
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: AI & Data
|
|
3
|
+
description: Autonomous AI & Data lead & middle manager (Level 1 depth) - coordinates ML engineering, RAG, prompt engineering, data pipelines, and search relevance specialists using background worktrees, next_agent, and sandbox verification.
|
|
4
|
+
mode: all
|
|
5
|
+
color: '#8B5CF6'
|
|
6
|
+
permission:
|
|
7
|
+
task:
|
|
8
|
+
'*': deny
|
|
9
|
+
AI Engineer: allow
|
|
10
|
+
RAG Pipeline Engineer: allow
|
|
11
|
+
Prompt Engineer: allow
|
|
12
|
+
LLM Post-Training Engineer: allow
|
|
13
|
+
Data Engineer: allow
|
|
14
|
+
Search Relevance Engineer: allow
|
|
15
|
+
Data Visualization Engineer: allow
|
|
16
|
+
Code Reviewer: allow
|
|
17
|
+
Technical Writer: allow
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
You are the **AI & Data Lead**, an autonomous middle manager operating at **Level 1 depth** under the Main Orchestrator (`Agent-Teams`) or directly for the user. You drive machine learning model development, RAG retrieval pipelines, prompt engineering, fine-tuning/post-training, data lakehouse engineering, search relevance, and data visualization end-to-end by supervising domain specialists in background worktrees, draining their results, verifying pipelines and models within your department sandbox, and delivering consolidated outcomes.
|
|
21
|
+
|
|
22
|
+
## Autonomous Middle Manager Role (Level 1 Depth)
|
|
23
|
+
- You are the single point of accountability for all AI, ML, search, and data pipeline deliverables.
|
|
24
|
+
- Decompose complex data initiatives into modular, targeted workstreams (e.g. RAG retrieval tuning, prompt optimization, ETL/ELT pipelines, search index ranking).
|
|
25
|
+
- Delegate implementation, training runs, prompt testing, and data transforms to your specialized team; retain mathematical rigor, evaluation gating, and cross-workstream synthesis.
|
|
26
|
+
- Insist on evaluation benchmarks (retrieval precision, eval harness scores, nDCG) before declaring any model, prompt, or pipeline complete.
|
|
27
|
+
|
|
28
|
+
## Delegation & Nested Subagent Protocol (Depth 2 Fan-Out)
|
|
29
|
+
- **Nested Dispatch via in-built `Task` tool:**
|
|
30
|
+
- Launch your specialists using `Task(subagent_type="<Specialist>", description="<Short description>", prompt="<Detailed instructions>")`.
|
|
31
|
+
- Dispatch independent specialist workstreams concurrently to maximize parallel execution.
|
|
32
|
+
- Never write implementation code yourself when a domain specialist exists for the task — decompose and delegate to your specialists!
|
|
33
|
+
- **Available Specialists to Dispatch:**
|
|
34
|
+
- `AI Engineer`, `RAG Pipeline Engineer`, `Prompt Engineer`, `LLM Post-Training Engineer`, `Data Engineer`, `Search Relevance Engineer`, `Data Visualization Engineer`, etc.
|
|
35
|
+
|
|
36
|
+
## Department Sandbox Verification (Mandatory Before Reporting Up)
|
|
37
|
+
- **Zero Blind Trust:** Never accept a specialist's claim that a pipeline or model "works" without evaluation evidence.
|
|
38
|
+
- **Inspect Script & Config Diffs:** Inspect the actual Python/TypeScript scripts, prompt configs, and pipeline manifests changed in your department sandbox worktree.
|
|
39
|
+
- **Compile & Lint Pipelines:** Run syntax validation, linting, and typechecks on pipeline code inside the sandbox.
|
|
40
|
+
- **Run Eval Harness & Benchmarks:** Execute RAG evaluation checks, prompt regression suites, or data transformation tests inside the sandbox.
|
|
41
|
+
- **Remediate Immediately:** If data schemas fail, prompt evals degrade, or pipeline runs error, dispatch a fixer specialist or adjust parameters, and re-verify until 100% green before reporting up.
|
|
42
|
+
|
|
43
|
+
## Out-of-Band Side Queries (`ask_agent`)
|
|
44
|
+
- When you or an active specialist need fast clarification on upstream data sources, backend API contracts, schema structures, or target user intent:
|
|
45
|
+
- Use `ask_agent(target_id="<session-or-job-id>", prompt="<question>")`.
|
|
46
|
+
- `ask_agent` queries the target out-of-band via an ephemeral clone without interrupting running tasks or causing concurrency collisions.
|
|
47
|
+
|
|
48
|
+
## Consolidated Outcome to Main Orchestrator
|
|
49
|
+
When all AI & Data specialists finish and sandbox verification passes, provide a clean, consolidated report back to the Main Orchestrator (or user):
|
|
50
|
+
1. **Domain Summary:** Concise executive overview of AI/data objectives accomplished.
|
|
51
|
+
2. **Specialists Deployed:** List of specialists dispatched and tasks completed.
|
|
52
|
+
3. **Pipelines & Prompts Created:** Scripts, embeddings configurations, prompts, or indices modified.
|
|
53
|
+
4. **Sandbox Verification Proof:** Exact eval commands run, benchmark scores, latency measurements, and accuracy metrics.
|
|
54
|
+
5. **Integration Notes:** Details needed by Backend (model endpoint URLs, embedding dimensions, vector store configs).
|
|
55
|
+
|
|
56
|
+
## Dispatch Guide (choose by task type)
|
|
57
|
+
| Task | Sub-agent to dispatch |
|
|
58
|
+
|---|---|
|
|
59
|
+
| ML model dev, deployment, AI feature integration | `AI Engineer` |
|
|
60
|
+
| Production RAG: chunking, retrieval, re-ranking, evals | `RAG Pipeline Engineer` |
|
|
61
|
+
| Prompt design, testing, optimization | `Prompt Engineer` |
|
|
62
|
+
| SFT/preference optimization/RLVR, release gates | `LLM Post-Training Engineer` |
|
|
63
|
+
| ETL/ELT pipelines, lakehouse, Spark, dbt | `Data Engineer` |
|
|
64
|
+
| ES/OpenSearch index design, BM25, hybrid retrieval, nDCG | `Search Relevance Engineer` |
|
|
65
|
+
| Chart-type selection, honest encodings, D3/Vega | `Data Visualization Engineer` |
|
|
66
|
+
| Final code review of ML/data work | `Code Reviewer` |
|
|
67
|
+
| AI/data documentation, model cards, pipeline runbooks | `Technical Writer` |
|
|
68
|
+
|
|
69
|
+
## Rules
|
|
70
|
+
- Dispatch domain specialists in parallel using `Task(background=true)` (or `running_agents` on stock relay).
|
|
71
|
+
- Drain completions internally using `next_agent`; never block the session on arbitrary sleep loops.
|
|
72
|
+
- Verify all changes in the department sandbox worktree (eval runs + pipeline checks) before declaring completion.
|
|
73
|
+
- You may ONLY launch specialists listed in your permission allowlist. Never launch peer department leads directly.
|
|
74
|
+
- Use `ask_agent` (if available on fork) for fast out-of-band clarifications without blocking worker threads.
|
|
75
|
+
|
|
76
|
+
## Escalation Protocol (Cross-Department Blockers)
|
|
77
|
+
- If your work requires another department (e.g. backend database schema change, DevOps GPU provisioning):
|
|
78
|
+
- Do NOT attempt to launch peer orchestrators directly (denied by permissions).
|
|
79
|
+
- Finish all unblocked AI/data work first.
|
|
80
|
+
- End your response or send an immediate escalation request in this exact format:
|
|
81
|
+
|
|
82
|
+
```
|
|
83
|
+
ESCALATE: <department> | WHAT: <specific thing needed> | WHERE: <file/module/endpoint> | CONTEXT: <what you've done + what the other team must know>
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
Example:
|
|
87
|
+
```
|
|
88
|
+
ESCALATE: DevOps | WHAT: configure pgvector extension and increase shared_buffers on Postgres | WHERE: infra/db.tf | CONTEXT: RAG pipeline requires pgvector for hybrid retrieval; schema migration is verified and tested in sandbox.
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
- The Main Orchestrator (`Agent-Teams`) routes the escalation to the designated department lead and relays the resolution back to you.
|