@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 CHANGED
@@ -1,123 +1,67 @@
1
1
  <!-- agent-teams-orchestration:start -->
2
- # Department Team-Lead Orchestration (Agent-Teams pattern)
3
-
4
- The agent system is organized as departments, each led by an orchestrator (team lead):
5
- Frontend, Backend, Security, DevOps, AI & Data, QA. Each lead fans out to its own
6
- sub-agent team via the Task tool. Leads are `mode: all` (Tab-switchable + Task-launchable).
7
-
8
- TWO MODES:
9
- - **Normal mode (any agent except Agent-Teams):** the ACTIVE agent is the main agent
10
- of its session. If you are a department lead, your "main agent" is whoever spawned
11
- you (Agent-Teams or the active Tab agent) — escalate to THAT, not to a global "supervisor".
12
- - **Agent-Teams mode:** Agent-Teams IS the main agent/router of the session. It
13
- receives escalations from its teams and routes to fixers itself (it can launch any
14
- agent). It reports the final result to the user.
15
-
16
- ## OpenCode 1.18.34+ Native Hierarchical Depth (`subagent_depth = 2`)
17
- OpenCode 1.18.34+ natively supports nested subagents up to `subagent_depth = 2` (configured in `config.json` via `"subagent_depth": 2`):
18
- - **Depth 0 (Root Orchestrator):** `Agent-Teams` (or active Tab session) orchestrates high-level departmental workflows.
19
- - **Depth 1 (Department Leads):** Department Leads (`Frontend`, `Backend`, `Security`, `DevOps`, `AI & Data`, `QA`) receive departmental goals and launch their specialists via nested `Task` tool calls.
20
- - **Depth 2 (Department Specialists):** Domain specialists (e.g. `Frontend Developer`, `Database Optimizer`, `API Tester`) execute focused implementation, testing, or auditing tasks.
21
- - **Stock Agent Compatibility:** The built-in `build` agent remains untouched as the standard single-task primary agent; multi-agent hierarchical fan-out applies when the user selects `Agent-Teams`.
22
-
23
- ## Core rule: hub-and-spoke — NO lead launches another lead
24
- - Each orchestrator's `permission.task` allowlist contains ONLY its own team members.
25
- Leads cannot launch other leads (this is mechanically enforced).
26
- - If a lead needs another department, it returns a structured escalation in this format:
27
- `ESCALATE: <department> | WHAT: <need> | WHERE: <file/module> | CONTEXT: <what it did + what the other team must know>`
28
- - ESCALATE EARLY: return the escalation as soon as the blocker is detected, not after
29
- finishing all work — the receiving main agent starts the fixer while you continue
30
- unblocked work.
31
-
32
- ## You are the MAIN AGENT (Agent-Teams or Build) — how to handle escalations
33
- 1. When any sub-agent's result contains `ESCALATE: <dept> | ...`, parse it.
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
- The orchestrator extracts `<id>` and calls `Task(task_id="<id>", prompt="<instruction explaining the failure, fix, or recovery path>")`. This continues the **exact same subagent session**, preserving all previously executed tool calls, code diffs, conversation history, and working memory.
92
- - Multiple Task calls in one message run concurrently (proven: 20 subagents in parallel).
93
- - Escalation is non-destructive: the lead's independent output is kept; only the blocked
94
- item waits.
95
-
96
- ### Async fan-out plugin (agent-teams, relay-backed)
97
- For true async fan-out (react to the FIRST finisher while others still run), use the
98
- `agent-teams` plugin tools. The plugin is a thin HTTP proxy to a per-instance relay
99
- server (an external opencode SDK client):
100
- - `running_agents` — launch N sub-agent sessions in the background in parallel (non-blocking, UNLIMITED
101
- count). Returns session IDs immediately. Results return to the caller (chain preserved).
102
- - `next_agent` — block until ONE running session finishes; return its result.
103
- Other sessions keep running. Call repeatedly to drain results as each finishes.
104
- - `agents_status` — non-blocking snapshot of all running sessions' status/output. Use periodically to check execution progress across team members.
105
-
106
- **Multi-instance safety:** one relay per opencode server instance. Each opencode
107
- TUI/session has a unique serverUrl; the relay port is derived from that URL, so
108
- every terminal/project/session gets its own isolated relay. Multiple opencode
109
- sessions can run simultaneously and each spawns its own sub-agent teams.
110
- The main agent keeps working independently while its team sub-agents run.
111
-
112
- Used by leads to fan out their team, and by the main agent when it manages multiple
113
- in-flight leads and needs to react to the first finisher. Sub-agents never report to
114
- the main agent directly — always follow the chain: sub-agent -> lead -> main agent.
115
-
116
- ## One-writer-per-module discipline
117
- When a lead delegates a file/module to another department (via escalation), that
118
- module's ownership transfers. The originating lead must NOT edit the same module
119
- until the other department returns it. Apply this in all dispatch prompts.
120
-
121
- ## If true parallel teams are needed
122
- Use separate git worktrees (one per department), not parallel writers on the same files.
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 -->