@mdsohail99/opencode-agent-teams 0.0.0-stage → 2.0.1
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 +67 -0
- package/CHANGELOG.md +158 -0
- package/LICENSE +21 -0
- package/README.md +167 -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/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/package.json +55 -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/AGENTS.md
ADDED
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
<!-- agent-teams-orchestration:start -->
|
|
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 (`subagent_depth = 2`)
|
|
17
|
+
OpenCode v2 natively supports nested subagents up to `subagent_depth = 2` (configured in `opencode.json` via `"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>
|
|
34
|
+
```
|
|
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.
|
|
67
|
+
<!-- agent-teams-orchestration:end -->
|
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,158 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to **`opencode-agent-teams-relay`** will be documented in this file.
|
|
4
|
+
|
|
5
|
+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
|
6
|
+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v1.0.0.html).
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## [2.0.1] - 2026-10-22
|
|
11
|
+
|
|
12
|
+
### Added & Documented
|
|
13
|
+
- **Hub-and-Spoke Delegating Agent as Escalation Resolver:** Formally documented and codified the central escalation resolution workflow in README.md and AGENTS.md (no lead-to-lead calls, early ESCALATE yielding, worktree sandboxing per blocker, and context handoff back to caller).
|
|
14
|
+
- **In-Process Swarm Test Suite:** Added test/v2-swarm.spec.ts testing global hierarchy tracking, tool dispatch (team_status, team_broadcast, team_terminate), and worktree sandboxing.
|
|
15
|
+
- **Repository Standardization:** Completely pruned legacy v1 relay daemon files, obsolete fork agents, and temporary scratch documentation. Added test and typecheck npm scripts.
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
## [2.0.0] - 2026-10-22
|
|
20
|
+
|
|
21
|
+
### Changed & Re-Architected (Major)
|
|
22
|
+
- **100% Native OpenCode v2 Architecture:** Complete rewrite as an in-process plugin utilizing official `@opencode/plugin@2.1.1` and `@opencode/client@2.1.1` APIs.
|
|
23
|
+
- **Relay Daemon Completely Deprecated:** Removed external Node.js relay server, port 20129/25800 listener, socket tokens, and orphaned process reaping. Zero background processes or port overhead.
|
|
24
|
+
- **Simplified Agent Identifiers:** Renamed all Department Leads from `orchestrator-*.md` to clean, native IDs (`agent-teams`, `backend`, `frontend`, `security`, `qa`, `devops`, `ai-data`).
|
|
25
|
+
- **Dynamic In-Memory Registration:** Replaced hardcoded commands and prompt blocks in `opencode.json` and `AGENTS.md` with runtime transforms (`ctx.command.transform`, `ctx.agent.transform`). Global configs stay clean.
|
|
26
|
+
- **Modernized Swarm Tools:** Introduced semantic tools (`team_delegate`, `team_status`, `team_broadcast`, `team_terminate`) with direct Git worktree sandboxing and automatic merge-back.
|
|
27
|
+
- **New Interactive CLI:** Added interactive terminal TUI menu in `bin/cli.js` with manifest-tracked clean uninstall and global-by-default targeting.
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
## [1.0.8] - 2026-10-10
|
|
32
|
+
|
|
33
|
+
### Added
|
|
34
|
+
- **OpenCode 1.18.34+ Stock Native Hierarchical Depth (`subagent_depth = 2`):** Configured natively at root in `opencode.json` across both `full` and `agents` install modes, enabling Depth 0 (Root Orchestrator) → Depth 1 (Department Leads) → Depth 2 (Specialists) out of the box on upstream stock OpenCode.
|
|
35
|
+
- **Visible Parallel Batch Task Mode:** Optimized orchestrators to emit concurrent `Task` calls in the same assistant turn. OpenCode natively renders live interactive `│ Task` widgets with animated spinners and toolcall indicators (`↳ Edit src/...`).
|
|
36
|
+
- **Swarm Slash Command Palette:** Injected `/tree`, `/report`, `/ask`, `/resume`, `/stop`, and `/errors` commands into `opencode.json` for live ASCII org-chart tracking, mid-flight worker steering, and emergency stopping.
|
|
37
|
+
- **Fast-Path Capability Probing:** Modernized `probeInlineSupport()` in `plugins/agent-teams.ts` to query `/experimental/capabilities` directly instead of creating throwaway `__agent_teams_subtask_probe__` sessions, eliminating the 5-second startup lag and ghost session leaks on SQLite.
|
|
38
|
+
- **Native Git Worktree Sandboxing:** Integrated `relay/agent-teams-relay.mjs` with OpenCode 1.18.34+ native worktree endpoints (`POST /experimental/worktree/create` and `remove`), allocating isolated git sandboxes per mutating task to prevent write collisions.
|
|
39
|
+
- **Deterministic Error Resumption:** Standardized `Task(task_id="<id>", prompt="...")` for recovering failed tasks (`Subagent failed (task_id: <id>): <error>`), preserving all accumulated context, tools, and code diffs.
|
|
40
|
+
- **Total Sandbox & XDG Isolation:** Set `$env:XDG_CONFIG_HOME` in sandbox and test launcher scripts to guarantee 100% clean isolation from machine-global user profile configs.
|
|
41
|
+
|
|
42
|
+
### Fixed
|
|
43
|
+
- **Subagent Completion Stall Resolution:** Added a synthetic tool-action summary fallback in `readSessionOutput()` (`relay/agent-teams-relay.mjs`) when turns conclude with tool executions (`edit`, `write`, `bash`) rather than conversational text. Unblocks the `session.idle` handler and routes the session to `done` immediately.
|
|
44
|
+
- **Resilient 404 Notification Queue Handling:** Implemented a 3-attempt retry loop with 4-second backoff in `drainParentNotifications()` (`relay/agent-teams-relay.mjs`). Prevents transient 404 responses during parent status checks or `promptAsync` delivery from permanently deleting the orchestrator's notification queue.
|
|
45
|
+
- **Cross-Session Target Scoping in Resume & Restart:** Passed `parentID: context.sessionID` in `resume_agent` and `manage_agents restart` (`plugins/agent-teams.ts`) and configured default resume prompts (`"Resume and continue from where you left off."`). Resolves targets strictly to the current active session, preventing accidental resumption of stale historical ghost agents.
|
|
46
|
+
- **Session Preservation on Operator Kill:** Replaced `deleteServerSession` with `abortServerSession` across `manage_agents kill` and `kill_all` (`relay/agent-teams-relay.mjs`). Aborts in-flight execution upstream while preserving SQLite session records and WAL history intact for subsequent resumption.
|
|
47
|
+
- **Enriched Out-of-Band `/ask` Snapshots:** Formatted tool calls, arguments, outputs, and thinking snippets into the ephemeral transcript snapshot in `agent-teams-relay.mjs`, ensuring operator inquiries reflect active background work and tool execution rather than appearing idle.
|
|
48
|
+
|
|
49
|
+
## [1.0.6] - 2026-09-04
|
|
50
|
+
|
|
51
|
+
### Added
|
|
52
|
+
- **Reactive Orchestrator Protocol (`orchestrator-agent-teams.md`):** Mandated non-blocking fanout where the Main Orchestrator dispatches department leads asynchronously via `Task(background=true)` and immediately yields the turn to the user (permanently preserving terminal interactivity). Forbids calling `next_agent` in foreground turns.
|
|
53
|
+
- **File Touch Scope Protocol:** Adds explicit decision rules for worktree isolation: `worktree: true` when subagents touch shared files (`package.json`, shared schemas); `worktree: false` for disjoint directories or read-only tasks to eliminate disk I/O and temporary git branch overhead.
|
|
54
|
+
- **Swarm Management & Side Query Directives:** Equipped the Orchestrator with `agents_status` (hierarchical tree snapshots and stall detection), `manage_agents` (`kill`, `kill_all`, `inspect`, `restart`), and `ask_agent` for out-of-band side queries.
|
|
55
|
+
- **Autonomous Department Leads (Level 1 Depth):** Upgraded all 6 Department Leads (`Backend`, `Frontend`, `DevOps`, `QA`, `AI & Data`, `Security`) to autonomous middle managers that supervise specialists in background worktrees, run compile/typecheck/test verification gates inside department sandboxes, and report consolidated outcomes upward.
|
|
56
|
+
|
|
57
|
+
### Fixed
|
|
58
|
+
- **Root `subagent_depth` Schema Alignment:** Configured `subagent_depth = 2` directly at the root level of `opencode.json` in `bin/lib/merge-subagent-depth.mjs` and `install.ps1` to align with the official OpenCode V2 schema (`https://opencode.ai/config.json`) and SDK types. Eliminates editor schema validation warnings (`Property subagent_depth is not allowed`) while auto-migrating any misplaced `experimental.subagent_depth` back to root and pruning empty `experimental` blocks.
|
|
59
|
+
|
|
60
|
+
## [1.0.5] - 2026-09-03
|
|
61
|
+
|
|
62
|
+
### Fixed
|
|
63
|
+
- **OpenCode V2 Subagent Depth Alignment:** Updated installer logic (`bin/lib/merge-subagent-depth.mjs` and `install.ps1`) to configure `experimental.subagent_depth = 2` matching the official OpenCode V2 (`v1.18.x+`) schema (`https://opencode.ai/config.json`).
|
|
64
|
+
- **Legacy Config Auto-Migration:** Automatically detects legacy root `subagent_depth` in existing user configs, migrates it into `experimental.subagent_depth`, and removes the root key to eliminate schema validation errors while preserving custom user values and existing experimental keys.
|
|
65
|
+
|
|
66
|
+
## [1.0.4] - 2026-08-20
|
|
67
|
+
|
|
68
|
+
### Added
|
|
69
|
+
- **Durable WAL + checkpoint state store.** The relay persists its entire picture of the world (`nodes`, `teams`, plus an append-only `events` diary) to `<state-dir>/agent-teams-relay.wal` (append-only write-ahead log) with periodic atomic checkpoints to `<state-dir>/agent-teams-relay-state.json` — every state transition is mirrored transactionally, and a relay that is killed and restarted replays its full state, including completed results, drained flags, and retry budgets. The in-memory Maps remain the runtime source of truth for logic; the store survives restarts. (`relay/agent-teams-relay.mjs`)
|
|
70
|
+
- **Full-instance visibility (`/reconcile`).** A new plugin-side **supervisor loop** (started at plugin load, not on tool calls) checks relay health every 10s, respawns a dead relay, and pushes the opencode server's *entire* live session list to the relay's new `/reconcile` endpoint — so the relay tracks every session on the instance (including human-started ones), not just children it spawned itself, and corrects drifted statuses. (`plugins/agent-teams.ts`, `relay/agent-teams-relay.mjs`)
|
|
71
|
+
- **Confirmed-deletion cascade.** Deletion is now triggered **only** by a confirmed parent deletion — either the SSE `session.deleted` event or a parent missing from two consecutive reconciliation passes *and* an explicit `session.get` returning 404. Unreachability is never treated as deletion. Pending `/await-any` waiters are resolved with `disposed` status; child sessions are deleted with an audit trail in the `events` diary.
|
|
72
|
+
- **30-day confirmed-orphan sweep.** A low-frequency safety net (`ORPHAN_SWEEP_INTERVAL_MS`, default 24h cadence) revisits stale nodes but only cascades them through the same confirmed-deletion gate — never on age alone.
|
|
73
|
+
- **Event-diary retention.** The append-only `events` table is pruned on boot and on the maintenance tick (default 24h): rows older than 90 days are removed (`EVENT_RETENTION_DAYS` to override, e.g. for tests).
|
|
74
|
+
- **`/resume` + `resume_agent` tool.** Any existing, still-alive session can receive a follow-up instruction and continue with its accumulated context; status/drained/result reset and a fresh completion promise is registered so `next_agent`/`agents_status` pick it back up. Network failure to the upstream server returns `502 upstream_unreachable` (never treated as "not found").
|
|
75
|
+
- **Per-agent failure isolation.** Retry budgets are now **per-node** (`retry_count`, capped at 3): one agent exhausting its budget goes `error` with a `needs_attention` event while every sibling keeps working. The global circuit breaker is reserved solely for SSE-transport failures; `/reset-circuit {sessionID}` revives a single node's budget. (`relay/agent-teams-relay.mjs`)
|
|
76
|
+
- **Test suite growth:** 28 automated tests (relay lifecycle, reconcile, cascade, orphan sweep, resume, failure isolation, installer scenarios 1–6) via `node --test`.
|
|
77
|
+
|
|
78
|
+
### Changed
|
|
79
|
+
- **Architectural Upgrade: Replaced HTTP Heartbeat Polling with OS Kernel Process Supervision.** Relays no longer issue `GET /global/health` probes over local HTTP connections to check parent liveness. Instead, the plugin passes `PARENT_PID` to the relay, which monitors the parent OpenCode Process ID directly via OS Kernel liveness checks (`process.kill(parentPid, 0)`). Zero false-positive relay exits during CPU or AI spikes. As long as the parent OpenCode process exists in the OS process table, the relay stays 100% alive indefinitely (even if idle for days). The moment the user closes the parent OpenCode application or terminal, the kernel monitor detects process termination (`ESRCH`) and shuts down the relay immediately. (`relay/agent-teams-relay.mjs`, `plugins/agent-teams.ts`)
|
|
80
|
+
- **Single config root + disabled-plugin parking.** Both install modes now target `~/.config/opencode` — one config world, no more separate `.config/ocd` for agents-only. In `agents` (native-fork) mode the plugin is **parked** into `plugins-disabled/agent-teams.ts`, outside the core's `{plugin,plugins}/*.{ts,js}` autodiscovery, so the fork's compiled-in `Task`/`next_agent`/`agents_status` run collision-free (no tool collision between the plugin and the native fork). `full` mode restores it into `plugins/`, removes any parked copy, and strips stale `subagent_depth`. Legacy `.config/ocd` installs are still auto-detected for reinstall/uninstall. (`bin/install.mjs`, `bin/menu.mjs`, `bin/uninstall.mjs`, `install.ps1`, `bin/lib/config-root.mjs`, new `bin/lib/plugin-park.mjs`)
|
|
81
|
+
- **Runtime floor raised to `node >= 20.19`** (for the WAL + checkpoint durable store). (`package.json`)
|
|
82
|
+
- **State & Runtime Cleanup Alignment:** Synchronized runtime state allowlists across `bin/lib/runtime-state.mjs` and `install.ps1` to cover the WAL + checkpoint state files (`agent-teams-relay.wal`, `agent-teams-relay-state.json` and transient `.tmp` variants) and temporary tokens (`token.tmp`).
|
|
83
|
+
- `scripts/test-relay-cascade.mjs` replaces the obsolete `test-relay-dispose.mjs` integration script.
|
|
84
|
+
|
|
85
|
+
### Removed
|
|
86
|
+
- `/dispose` endpoint and `evictStale()` (the 30-minute TTL eviction) — both replaced by the confirmed-deletion cascade above. Nothing is ever deleted automatically without a confirmed parent deletion.
|
|
87
|
+
|
|
88
|
+
### Fixed
|
|
89
|
+
- **Auxiliary-server split-brain on startup.** When the real opencode server wasn't answering yet at plugin load (boot race), the plugin immediately spawned a second `opencode serve` and pointed the relay at it — the relay silently watched the wrong server while `/reconcile` pushes to the real one failed. The upstream probe now retries (~5s window) before any auxiliary fallback, the fallback is logged when it does happen, and the supervisor **self-heals**: once pushes reach the real server again, an aux-backed relay is killed and respawned on the real URL (lossless — the WAL + checkpoint store replays state). (`plugins/agent-teams.ts`)
|
|
90
|
+
- **Relay heartbeat exit threshold raised from 12 → 36 (3 minutes) and made env-tunable.** Previously, aux-backed relays (spawned when the real opencode upstream was down) exited after only 12 × 5 s = 60 seconds of upstream unreachability. Under heavy parallel AI workloads, the aux `opencode serve` process becomes transiently unreachable for longer than 60 s, causing the relay to self-terminate. The plugin then re-ran `ensureRelay`, found the upstream still down, and spawned a *new* aux server on a new random port — triggering a new relay on a new port. Every cycle broke `next_agent`'s long-poll connection. 8+ relay/aux pairs were created in a single session. Default is now 36 failures (3 minutes). `HEARTBEAT_MAX_FAILURES` env var allows custom tuning without code changes. (`relay/agent-teams-relay.mjs`)
|
|
91
|
+
- **`next_agent` now retries `/await-any` up to 5 times across relay restarts.** When the relay is respawned mid-poll the HTTP connection drops. The execute handler now retries with a 2 s pause + `ensureRelay` health re-check between attempts, so a relay that restarted and recovered its persisted state is found on the next attempt. (`plugins/agent-teams.ts`)
|
|
92
|
+
- **`reconcileMissedCompletions` called immediately at relay boot.** Previously this ran only after the SSE event stream connected (which can take several seconds). An `/await-any` call arriving in that window could block to timeout even if sub-agents already finished while the relay was down. Now the recovery runs right after `openDatabase()` / `loadDurableState()` so persisted completions are resolved before the first tool call is served. (`relay/agent-teams-relay.mjs`)
|
|
93
|
+
- **Relay health check no longer gates on `eventsReady`.** `/health` now always returns `ok: true` when the relay process is alive (i.e. it responded). `eventsReady` remains in the payload as an informational field about the SSE stream. Previously, any transient SSE reconnect caused the plugin's `health()` check to return `false`, which deleted the relay cache entry and tried to respawn a relay that was already running — a duplicate that then immediately exited on `EADDRINUSE`. (`relay/agent-teams-relay.mjs`, `plugins/agent-teams.ts`)
|
|
94
|
+
- **Ghost `__agent_teams_subtask_probe__` sessions no longer appear in the session list.** `probeVersionFastPath()` now conservatively returns `tooOld: true` whenever the core version cannot be determined (endpoint unhealthy, no `version` field, unparseable string, or network error). On stock opencode 1.2.27 the version is not published on `/global/health`, so the fast-path now short-circuits before creating any throwaway session — the probe session creation is skipped entirely. (`plugins/agent-teams.ts`)
|
|
95
|
+
- **Probe session DELETE is delayed 5 s.** When the full probe path does run (native fork ≥ 1.18.x), the `finally` cleanup now waits 5 seconds before issuing the DELETE. An immediate DELETE on a session that just received `prompt_async` fails silently on some cores, leaving a ghost session in the list. The delay gives the session time to reach idle. (`plugins/agent-teams.ts`)
|
|
96
|
+
- **Relay reconcile skips probe sessions.** `handleReconcileSessions()` now filters out any session whose title is `__agent_teams_subtask_probe__` before folding it into the node tree. Previously these sessions accumulated in the relay's durable store across restarts and triggered unnecessary status-API polling on every reconcile pass. (`relay/agent-teams-relay.mjs`)
|
|
97
|
+
- **Fixed `serverUrl` undefined hashing to port 25821 on startup.** Added `isValidServerUrl()` validation to prevent attempting relay startup or spawning auxiliary servers on undefined server URLs. (`plugins/agent-teams.ts`)
|
|
98
|
+
|
|
99
|
+
---
|
|
100
|
+
|
|
101
|
+
## [1.0.3] - 2026-08-09
|
|
102
|
+
|
|
103
|
+
### Changed
|
|
104
|
+
- **Mode-aware config directory:** the installer now targets `.config/ocd` in `agents` mode (native fork) and `.config/opencode` in `full` mode (stock opencode), so both modes can coexist on the same machine without clobbering each other's state. (`bin/install.mjs`, `install.ps1`)
|
|
105
|
+
- `install.ps1` uses `$PSScriptRoot` for the package root and `$USERPROFILE` first for the home dir (more robust under non-standard shells).
|
|
106
|
+
|
|
107
|
+
### Fixed
|
|
108
|
+
- **Mode-aware `subagent_depth` merge in `install.ps1`:** `full` mode now strips a stale `subagent_depth` key instead of writing it (the stock core rejects the unrecognized key and refuses to start); `agents` mode creates `opencode.json` with `subagent_depth=2` when missing.
|
|
109
|
+
- **Hidden console on Windows:** the relay process now spawns a hidden console at startup (`hide_console.ps1`), so the background relay no longer pops a terminal window.
|
|
110
|
+
|
|
111
|
+
---
|
|
112
|
+
|
|
113
|
+
## [1.0.2] - 2026-08-07
|
|
114
|
+
|
|
115
|
+
### Added
|
|
116
|
+
- README: **"Performance & Measured Impact"** section — real measured numbers from an in-repo orchestration run (18 concurrent sessions, ~15 min wall-clock to synthesis, 8 concurrent escalations), with explicit **measured vs modeled** labeling and the honest tokens-for-throughput trade-off.
|
|
117
|
+
|
|
118
|
+
---
|
|
119
|
+
|
|
120
|
+
## [1.0.1] - 2026-08-07
|
|
121
|
+
|
|
122
|
+
### Fixed
|
|
123
|
+
- `subagent_depth` merge is now **mode-aware**: the key is only applied in `agents` mode (native fork core, which understands it). `full` mode (stock opencode core) no longer writes it — the stable core rejects `subagent_depth` as an unrecognized key and refuses to start. Full-mode installs/reverts also **strip** a stale `subagent_depth` to self-heal configs broken by an earlier agents-mode install.
|
|
124
|
+
|
|
125
|
+
---
|
|
126
|
+
|
|
127
|
+
## [1.0.0] - 2026-08-07
|
|
128
|
+
|
|
129
|
+
Initial public release — async department-lead orchestration and parallel sub-agent relay for OpenCode.
|
|
130
|
+
|
|
131
|
+
### Added
|
|
132
|
+
- 🚀 **Async Parallel Fan-Out:** `running_agents` tool launches unlimited child sessions in parallel without freezing the OpenCode TUI; results collected with `next_agent` (drain) / `agents_status` (snapshot).
|
|
133
|
+
- 📡 **Detached SDK Relay Engine:** External Node.js background process (relay/agent-teams-relay.mjs) connecting via `@opencode-ai/sdk`, tracking `session.idle` / `session.error` events via SSE.
|
|
134
|
+
- 🏢 **7 Department Leads & 67 Specialists:** Pre-configured orchestrators (`Agent-Teams`, `Frontend`, `Backend`, `Security`, `DevOps`, `AI & Data`, `QA`) routing tasks to specialized domain agents.
|
|
135
|
+
- ⚡ **Management by Exception:** Unblocked work digests silently; blockers trigger immediate escalations so fixer leads dispatch in parallel.
|
|
136
|
+
- 🛡️ **Relay Resilience & Self-Healing:**
|
|
137
|
+
- Heartbeat tolerates transient upstream blips (5 consecutive failures before exit) instead of dying on a single one.
|
|
138
|
+
- Stale-team eviction never deletes teams with running/undrained children.
|
|
139
|
+
- Plugin re-probes relay health on every tool call and respawns a dead relay.
|
|
140
|
+
- Token persisted atomically (tmp+rename+fsync, `0o600`) after a successful listen; capped exponential reconnect backoff; missed completions reconciled on resubscribe.
|
|
141
|
+
- 🔄 **Auto-Continue on Transient Provider Errors:** `reasoning_content ... must be passed back` (DeepSeek thinking mode), `AI_JSONParseError` / `JSON parsing failed`, and `[503] request queue is full` are automatically resumed with a minimal "continue" prompt instead of failing the task (bounded retries, genuine failures still surface).
|
|
142
|
+
- 🧵 **Inline Sub-Agent Mode:** `running_agents({ inline: true })` renders a child as a native `│ Task` widget with automatic fallback to the relay path on cores that don't support subtask parts.
|
|
143
|
+
- ⚙️ **Two-Mode Installer:** `full` (agents + AGENTS.md + plugin + relay + npm dep) and `agents` / `--agents-only` (agents + AGENTS.md only, for native-fork users). Writes a `.installed-mode` marker.
|
|
144
|
+
- 🗑️ **Mode-Aware Uninstall:** removes only the artifacts the installed mode manages; preserves other user plugins, `opencode.json`, `package.json`, and `node_modules`. `status` reports the installed mode.
|
|
145
|
+
- 📦 **Safe Installer:** non-destructive with full timestamped backups, rollback, and marked-block `AGENTS.md` merging; keeps the last 5 backups.
|
|
146
|
+
- 🔒 **Shared-Secret Security:** 32-byte token authentication; unique hash-derived relay ports per server URL (20000–50000) for multi-session isolation.
|
|
147
|
+
|
|
148
|
+
### Changed
|
|
149
|
+
- `install.ps1` is mode-aware (`-AgentsOnly`).
|
|
150
|
+
- README documents installation modes; `MANIFEST.txt` lists both.
|
|
151
|
+
|
|
152
|
+
### Removed
|
|
153
|
+
- (n/a — initial release)
|
|
154
|
+
|
|
155
|
+
### Fixed
|
|
156
|
+
- Relay no longer exits on a single transient upstream heartbeat failure.
|
|
157
|
+
- Token file no longer world-readable, and is written only after the relay is listening (no clobber on port collisions).
|
|
158
|
+
- Sub-agent sessions hitting transient provider errors resume automatically instead of dying.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to sunshine conditions below:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,168 @@
|
|
|
1
|
-
|
|
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.1.1-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.1.1`).
|
|
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** (`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
|
+
```mermaid
|
|
30
|
+
flowchart TD
|
|
31
|
+
User(["🧑💻 Developer"]) -->|opencode| OC["OpenCode v2 Engine"]
|
|
32
|
+
|
|
33
|
+
subgraph Plugin["Agent-Teams v2 Plugin (In-Process)"]
|
|
34
|
+
OC --> Root["Depth 0: agent-teams (Root Orchestrator)"]
|
|
35
|
+
|
|
36
|
+
Root -->|Fan-Out / Escalate| Dept1["Depth 1: Backend Lead"]
|
|
37
|
+
Root -->|Fan-Out / Escalate| Dept2["Depth 1: Frontend Lead"]
|
|
38
|
+
Root -->|Fan-Out / Escalate| Dept3["Depth 1: Security Lead"]
|
|
39
|
+
Root -->|Fan-Out / Escalate| Dept4["Depth 1: QA Lead"]
|
|
40
|
+
|
|
41
|
+
Dept1 -->|team_delegate\nworktree: true| Spec1["Depth 2: Backend Architect\n(Git Worktree: swarm/backend-...)"]
|
|
42
|
+
Dept2 -->|team_delegate\nworktree: true| Spec2["Depth 2: Frontend Developer\n(Git Worktree: swarm/frontend-...)"]
|
|
43
|
+
Dept3 -->|team_delegate\nworktree: false| Spec3["Depth 2: AppSec Engineer\n(In-Place Read-Only Audit)"]
|
|
44
|
+
end
|
|
45
|
+
|
|
46
|
+
Spec1 -->|Verified & Tested| Merge1["Auto-Commit & Auto-Merge\ninto Active Branch"]
|
|
47
|
+
Spec2 -->|Verified & Tested| Merge2["Auto-Commit & Auto-Merge\ninto Active Branch"]
|
|
48
|
+
|
|
49
|
+
Merge1 --> Summary["Consolidated Executive Report\nto User"]
|
|
50
|
+
Merge2 --> Summary
|
|
51
|
+
Spec3 --> Summary
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
---
|
|
55
|
+
|
|
56
|
+
### 🔄 Hub-and-Spoke: The Delegating Agent as Escalation Resolver
|
|
2
57
|
|
|
3
|
-
|
|
58
|
+
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:
|
|
59
|
+
|
|
60
|
+
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.
|
|
61
|
+
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:
|
|
62
|
+
```text
|
|
63
|
+
ESCALATE: <dept> | WHAT: <need> | WHERE: <file/module> | CONTEXT: <work done + blocker details>
|
|
64
|
+
```
|
|
65
|
+
3. **The Delegating Agent Resolves:** The root orchestrator (`agent-teams`) acts as the central **Escalation Resolver**:
|
|
66
|
+
- It intercepts the escalation without terminating the caller.
|
|
67
|
+
- It checks whether the target department lead is already running (to reuse active session memory) or spawns it inside an isolated Git worktree (`swarm/...`).
|
|
68
|
+
- 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.
|
|
69
|
+
|
|
70
|
+
---
|
|
71
|
+
|
|
72
|
+
## ✨ Key Features in v2
|
|
73
|
+
|
|
74
|
+
* **🚀 100% In-Process Native Plugin**: Built directly on `@opencode/plugin@2.1.1` and `@opencode/client@2.1.1`. No external relay daemons, no background servers, no socket tokens, and zero orphaned processes.
|
|
75
|
+
* **🌳 2-Level Hierarchical Swarms (`subagent_depth = 2`)**: Out-of-the-box support for nested multi-agent trees:
|
|
76
|
+
* **Depth 0**: Root Orchestrator (`agent-teams`)
|
|
77
|
+
* **Depth 1**: Department Leads (`backend`, `frontend`, `security`, `qa`, `devops`, `ai-data`)
|
|
78
|
+
* **Depth 2**: 68 Curated Domain Specialists (`backend-architect`, `api-tester`, `a11y-auditor`, `threat-detection-engineer`, etc.)
|
|
79
|
+
* **🛡️ 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.
|
|
80
|
+
* **🛠️ Swarm Control Tooling**:
|
|
81
|
+
* `team_delegate`: Dispatch tasks with optional Git worktree sandboxing.
|
|
82
|
+
* `team_status`: Inspect live progress, deliverables, and active Git worktrees.
|
|
83
|
+
* `team_broadcast`: Steer running teammates with instructions simultaneously.
|
|
84
|
+
* `team_terminate`: Gracefully halt workers and discard unneeded worktrees.
|
|
85
|
+
* **⌨️ 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`.
|
|
86
|
+
* **🎨 Clean Interactive TUI Installer**: Running the CLI with no arguments launches a full-featured terminal menu to inspect status, install globally, or cleanly uninstall.
|
|
87
|
+
* **🧹 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.
|
|
88
|
+
|
|
89
|
+
---
|
|
90
|
+
|
|
91
|
+
## ⚡ Quickstart & Installation
|
|
92
|
+
|
|
93
|
+
### Option 1: Automatic Installer (Global - Recommended)
|
|
94
|
+
|
|
95
|
+
Run the interactive setup tool:
|
|
96
|
+
|
|
97
|
+
```bash
|
|
98
|
+
npx @mdsohail99/opencode-agent-teams
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
This automatically:
|
|
102
|
+
1. Configures your global `~/.config/opencode/opencode.json` with `"subagent_depth": 2` and registers the plugin.
|
|
103
|
+
2. Copies the 75 curated Department Leads and Specialists into `~/.config/opencode/agents/`.
|
|
104
|
+
|
|
105
|
+
---
|
|
106
|
+
|
|
107
|
+
### Option 2: Declarative Config
|
|
108
|
+
|
|
109
|
+
Add the plugin to your global `~/.config/opencode/opencode.json` (or your project's `./opencode.json`):
|
|
110
|
+
|
|
111
|
+
```json
|
|
112
|
+
{
|
|
113
|
+
"$schema": "https://opencode.ai/config.json",
|
|
114
|
+
"subagent_depth": 2,
|
|
115
|
+
"plugins": [
|
|
116
|
+
"@mdsohail99/opencode-agent-teams"
|
|
117
|
+
]
|
|
118
|
+
}
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
---
|
|
122
|
+
|
|
123
|
+
## 🎮 How to Use in OpenCode
|
|
124
|
+
|
|
125
|
+
1. **Launch OpenCode**:
|
|
126
|
+
```bash
|
|
127
|
+
opencode
|
|
128
|
+
```
|
|
129
|
+
2. **Select Agent-Teams**:
|
|
130
|
+
* Press **`Ctrl + x`** followed by **`a`**, then select `agent-teams`.
|
|
131
|
+
* *Or* press **`Shift + Tab`** to cycle agents.
|
|
132
|
+
* *Or* mention `@agent-teams` directly in your prompt.
|
|
133
|
+
|
|
134
|
+
### Example Prompts:
|
|
135
|
+
|
|
136
|
+
#### 1. Full-Stack Parallel Feature Build (Isolated Worktrees)
|
|
137
|
+
> *"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`."*
|
|
138
|
+
- **What happens:** Backend and Frontend each receive dedicated Git worktrees. Both code simultaneously. Changes are auto-tested and merged back into your active branch.
|
|
139
|
+
|
|
140
|
+
#### 2. Comprehensive Read-Only Architectural Audit
|
|
141
|
+
> *"Run an architectural audit across this repository. Strict read-only mode: inspect API routes, state management, and edge cases in parallel without creating files."*
|
|
142
|
+
- **What happens:** The Orchestrator dispatches `backend`, `frontend`, and `security` in-place, returning an integrated Executive Findings Report.
|
|
143
|
+
|
|
144
|
+
---
|
|
145
|
+
|
|
146
|
+
## 🕹️ Swarm Slash Commands
|
|
147
|
+
|
|
148
|
+
| Command | Action |
|
|
149
|
+
| :--- | :--- |
|
|
150
|
+
| **`/team`** | Displays a live ASCII hierarchy tree showing which agents are running, active worktrees, and elapsed times. |
|
|
151
|
+
| **`/team-status`** | Synthesizes current progress and deliverables across all active departments. |
|
|
152
|
+
| **`/team-stop`** | Gracefully terminates active background workers and cleans up their worktrees. |
|
|
153
|
+
|
|
154
|
+
---
|
|
155
|
+
|
|
156
|
+
## 🗑️ Clean Uninstallation
|
|
157
|
+
|
|
158
|
+
To remove Agent-Teams globally without touching any custom user agents or personal config:
|
|
159
|
+
|
|
160
|
+
```bash
|
|
161
|
+
npx @mdsohail99/opencode-agent-teams uninstall
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
---
|
|
165
|
+
|
|
166
|
+
## 📄 License
|
|
167
|
+
|
|
168
|
+
MIT © [Sohail Mohammed](https://github.com/mdsohail99)
|
|
@@ -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.
|