@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/AGENTS.md
CHANGED
|
@@ -1,123 +1,67 @@
|
|
|
1
1
|
<!-- agent-teams-orchestration:start -->
|
|
2
|
-
# Department Team-Lead Orchestration (Agent-Teams
|
|
3
|
-
|
|
4
|
-
The agent system is organized
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
## OpenCode
|
|
17
|
-
OpenCode
|
|
18
|
-
- **Depth 0 (Root Orchestrator):** `
|
|
19
|
-
- **Depth 1 (Department Leads):** Department Leads (`
|
|
20
|
-
- **Depth 2 (
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
2. Decide the owner:
|
|
35
|
-
- Is that department's lead ALREADY running (an active/prior task_id in this session)?
|
|
36
|
-
→ Route the escalation to THAT existing lead (resume its task_id with the context).
|
|
37
|
-
- Not running → spawn that lead via the Task tool with the escalation as its prompt.
|
|
38
|
-
3. NEVER spawn a second instance of a department lead that's already running —
|
|
39
|
-
reusing the running lead prevents two writers editing the same module (conflict).
|
|
40
|
-
4. Hand the resolution back to the originating team so it can continue.
|
|
41
|
-
5. Keep a running mental registry of which leads are active in this session.
|
|
42
|
-
|
|
43
|
-
## Visible Parallel Batch `Task` Fan-Out (Recommended Visible Mode)
|
|
44
|
-
On Stock OpenCode, the premier execution mode for `Agent-Teams` (and whenever visual transparency is preferred) is **Visible Parallel Batch Task Fan-Out**:
|
|
45
|
-
- **Batch Concurrent Emission**: When independent departmental workstreams exist (e.g. Frontend UI, Backend API, QA verification), `Agent-Teams` emits all `Task` tool calls **concurrently in the same assistant turn** (omitting `background: true`). Parameters: `Task(subagent_type="<Lead>", description="<Short description>", prompt="<Detailed prompt>")`.
|
|
46
|
-
- **Interactive TUI UX**: OpenCode renders live interactive `│ Task` widgets with animated spinners, live toolcall indicators (`↳ Edit src/...`, `↳ Run pytest`), and one-click inspection directly in the main TUI timeline.
|
|
47
|
-
- **Nested Visibility (`subagent_depth = 2`)**: Department Leads (Depth 1) also dispatch their Specialists (Depth 2) via nested `Task` tool calls, maintaining live visibility down through the subagent tree.
|
|
48
|
-
|
|
49
|
-
## Fan-out is ESCALATION-DRIVEN by default — main agent may parallelize when it fits
|
|
50
|
-
The DEFAULT for single-agent sessions (or when departments have sequential dependencies) is one lead at a time: spawn a lead, and only spawn another department when a running lead escalates and explicitly requests it. This is correct whenever the cross-department dependency is only discovered DURING the work (e.g. QA finds a backend bug mid-testing). Concurrency is produced by the RESUME pattern, not by pre-spawning teams.
|
|
51
|
-
|
|
52
|
-
### When the main agent MAY parallelize (spawn leads in the same message)
|
|
53
|
-
Parallel spawn is allowed when the main agent can already see, from the user's
|
|
54
|
-
request, that two departments have INDEPENDENT work that can run at the same time
|
|
55
|
-
with no write conflict — e.g. frontend UI + backend API are both clearly needed AND
|
|
56
|
-
touch different modules. Use judgment: if the tracks are coupled or one waits on the
|
|
57
|
-
other, do NOT parallelize — use the default one-lead + escalation flow instead.
|
|
58
|
-
|
|
59
|
-
### The default flow — single-lead with on-demand escalation
|
|
60
|
-
1. Main agent spawns the ONE lead whose task is the user's request (e.g. QA).
|
|
61
|
-
2. The lead does all its independent work, then returns `ESCALATE: <dept> | ...`
|
|
62
|
-
only if it actually hit a blocker requiring another department.
|
|
63
|
-
3. ONLY THEN does the main agent spawn (or resume) the requested department lead.
|
|
64
|
-
4. When the fix returns, the main agent resumes the requesting lead to finish.
|
|
65
|
-
|
|
66
|
-
### Yield-and-resume (how concurrency happens without pre-spawning)
|
|
67
|
-
When a lead escalates mid-task:
|
|
68
|
-
1. Lead does all work that does NOT depend on the other department (e.g. QA runs
|
|
69
|
-
all tests except test X), then returns early with
|
|
70
|
-
`ESCALATE: <dept> | ... | CONTEXT: I've done A,B,C; only X is blocked`.
|
|
71
|
-
It does NOT block or wait — its session ends cleanly (main agent keeps task_id).
|
|
72
|
-
2. Main agent, in ONE parallel batch, BOTH:
|
|
73
|
-
- resumes the requesting lead's task_id ("keep going on anything else you can; X pending"), AND
|
|
74
|
-
- spawns the needed lead ("fix X for the QA team").
|
|
75
|
-
If the requesting lead has no more independent work, skip the resume and only spawn.
|
|
76
|
-
3. When the fixing lead returns, main agent resumes the requesting lead's task_id
|
|
77
|
-
with the fix → it finishes the blocked item.
|
|
78
|
-
4. Never keep a lead idle: if a lead can do more work while another department fixes
|
|
79
|
-
its blocker, RESUME it to keep working rather than leaving it paused.
|
|
80
|
-
5. When the escalation is a mid-task discovery (like our QA → Backend test case),
|
|
81
|
-
do NOT start both leads together — the dependent lead starts first, escalates,
|
|
82
|
-
and only then is the second lead spawned. Parallel spawn is reserved for work
|
|
83
|
-
the main agent can see is independent from the start.
|
|
84
|
-
|
|
85
|
-
### Resumption discipline & Deterministic Error Recovery
|
|
86
|
-
- Resuming a lead by `task_id` preserves its session context — it knows what it already did.
|
|
87
|
-
- **Deterministic Error Resumption Format**: When a subagent fails, encounters a timeout, or throws an unhandled error, OpenCode returns:
|
|
88
|
-
```
|
|
89
|
-
Subagent failed (task_id: <id>): <error>
|
|
2
|
+
# Department Team-Lead Orchestration (Agent-Teams v2 Pattern)
|
|
3
|
+
|
|
4
|
+
The agent system is organized into departments, each led by an orchestrator (Department Lead):
|
|
5
|
+
`backend`, `frontend`, `security`, `qa`, `devops`, `ai-data`.
|
|
6
|
+
The primary entry point is the root orchestrator: `agent-teams`.
|
|
7
|
+
|
|
8
|
+
## Two Operational Modes:
|
|
9
|
+
1. **Agent-Teams Mode (Primary / Swarm Mode):**
|
|
10
|
+
`agent-teams` IS the root delegating orchestrator and central **Escalation Resolver**. It receives high-level user requests, fans out work to department leads, catches cross-department escalations, routes blockers to fixer leads, and synthesizes the final consolidated result.
|
|
11
|
+
2. **Specialized Single-Lead Mode:**
|
|
12
|
+
When a user directly invokes a department lead (e.g. `@backend` or `@frontend`), that lead acts as the primary agent for the session and fans out to its domain specialists directly.
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
## OpenCode v2 Hierarchical Swarms (`experimental.subagent_depth = 2`)
|
|
17
|
+
OpenCode v2 natively supports nested subagents up to `subagent_depth = 2` (configured in `opencode.json` via `"experimental": { "subagent_depth": 2 }`):
|
|
18
|
+
- **Depth 0 (Root Orchestrator):** `agent-teams` orchestrates high-level departmental workflows, monitors progress, and resolves cross-department blockers.
|
|
19
|
+
- **Depth 1 (Department Leads):** Department Leads (`backend`, `frontend`, `security`, `qa`, `devops`, `ai-data`) receive departmental scopes and dispatch specialists via `team_delegate` or native `subagent` tools.
|
|
20
|
+
- **Depth 2 (Domain Specialists):** 68 domain specialists (e.g. `backend-architect`, `frontend-developer`, `database-optimizer`, `api-tester`, `a11y-auditor`) execute focused implementation, testing, or auditing tasks inside isolated Git worktrees.
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## Core Architecture: Hub-and-Spoke with Delegating Agent as Resolver
|
|
25
|
+
|
|
26
|
+
### Rule 1: No Lead Launches Another Lead Directly
|
|
27
|
+
- Each department lead's scope is strictly confined to its own domain specialists.
|
|
28
|
+
- Leads cannot launch peer department leads directly. This prevents circular execution loops and write collisions.
|
|
29
|
+
|
|
30
|
+
### Rule 2: Management by Exception & Structured Escalation
|
|
31
|
+
- If a lead hits a cross-functional blocker (e.g. QA finds an unhandled backend route error, or Frontend needs a new authentication endpoint), it yields immediately with a structured escalation:
|
|
32
|
+
```text
|
|
33
|
+
ESCALATE: <department> | WHAT: <need> | WHERE: <file/module> | CONTEXT: <what it did + what the other team must know>
|
|
90
34
|
```
|
|
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
|
-
|
|
35
|
+
- **Escalate Early:** Yield the escalation as soon as the blocker is identified while continuing any unblocked parallel work.
|
|
36
|
+
|
|
37
|
+
### Rule 3: The Delegating Agent is the Central Resolver
|
|
38
|
+
When `agent-teams` receives an `ESCALATE: <dept>` result from a lead:
|
|
39
|
+
1. **Identify the Fixer:** Checks if that department lead is already active in the session registry.
|
|
40
|
+
- If already running: Resumes that lead's existing session with the escalation context.
|
|
41
|
+
- If not running: Spawns the required department lead via `team_delegate` in a dedicated Git worktree.
|
|
42
|
+
2. **One-Writer-Per-Module Discipline:** Never spawn duplicate instances of the same department lead on the same module.
|
|
43
|
+
3. **Context Handoff:** Once the fixing lead verifies the resolution and auto-merges the worktree, `agent-teams` passes the resolution back to the originating lead to complete its blocked work.
|
|
44
|
+
|
|
45
|
+
---
|
|
46
|
+
|
|
47
|
+
## Swarm Concurrency & Git Worktree Sandboxing
|
|
48
|
+
|
|
49
|
+
1. **Parallel Independent Fan-Out:**
|
|
50
|
+
When independent departmental requirements exist (e.g. Backend API endpoints in `src/routes/` and Frontend UI in `src/components/`), `agent-teams` dispatches both leads concurrently in the same turn.
|
|
51
|
+
2. **Isolated Git Worktrees (`worktree: true`):**
|
|
52
|
+
Mutating tasks execute in dedicated `swarm/<team>-<task_id>` branches within isolated worktrees. Once changes are verified, they are committed and merged back into the base working branch automatically.
|
|
53
|
+
3. **Strict Read-Only Mode (`worktree: false`):**
|
|
54
|
+
For architectural audits, code reviews, and testability evaluations, tasks execute in-place read-only without creating worktree directories or Git commits.
|
|
55
|
+
|
|
56
|
+
---
|
|
57
|
+
|
|
58
|
+
## Swarm Control Tools & Slash Commands
|
|
59
|
+
|
|
60
|
+
In OpenCode v2, orchestration runs 100% in-process via `@opencode/plugin` and `@opencode/client`:
|
|
61
|
+
- `team_delegate` — Dispatches tasks to department specialists with optional Git worktree sandboxing.
|
|
62
|
+
- `team_status` — Inspects the live hierarchical status tree, active workers, and Git worktrees.
|
|
63
|
+
- `team_broadcast` — Broadcasts steering guidance to active teammates simultaneously.
|
|
64
|
+
- `team_terminate` — Gracefully halts running workers and cleans up temporary worktrees.
|
|
65
|
+
|
|
66
|
+
Slash commands (`/team`, `/team-status`, `/team-stop`) provide real-time TUI progress monitoring and emergency swarm control.
|
|
123
67
|
<!-- agent-teams-orchestration:end -->
|