@mdsohail99/opencode-agent-teams 2.0.0 → 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 +64 -120
- package/CHANGELOG.md +158 -137
- package/README.md +165 -348
- package/agents/orchestrators/agent-teams.md +198 -198
- package/bin/cli.js +351 -351
- package/package.json +9 -4
- package/src/index.ts +115 -115
- package/src/state/tracker.ts +102 -102
- package/src/tools/broadcast.ts +58 -58
- package/src/tools/delegate.ts +154 -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/src/worktree/manager.ts
CHANGED
|
@@ -1,142 +1,142 @@
|
|
|
1
|
-
import { execFile } from "node:child_process"
|
|
2
|
-
import { promisify } from "node:util"
|
|
3
|
-
import path from "node:path"
|
|
4
|
-
import fs from "node:fs/promises"
|
|
5
|
-
|
|
6
|
-
const exec = promisify(execFile)
|
|
7
|
-
|
|
8
|
-
export interface WorktreeSandbox {
|
|
9
|
-
worktreePath: string
|
|
10
|
-
branchName: string
|
|
11
|
-
baseBranch: string
|
|
12
|
-
}
|
|
13
|
-
|
|
14
|
-
export interface ReconcileResult {
|
|
15
|
-
success: boolean
|
|
16
|
-
merged: boolean
|
|
17
|
-
commitHash?: string
|
|
18
|
-
error?: string
|
|
19
|
-
}
|
|
20
|
-
|
|
21
|
-
export class WorktreeManager {
|
|
22
|
-
static async getCurrentBranch(cwd: string): Promise<string> {
|
|
23
|
-
try {
|
|
24
|
-
const { stdout } = await exec("git", ["rev-parse", "--abbrev-ref", "HEAD"], { cwd })
|
|
25
|
-
return stdout.trim() || "main"
|
|
26
|
-
} catch {
|
|
27
|
-
return "main"
|
|
28
|
-
}
|
|
29
|
-
}
|
|
30
|
-
|
|
31
|
-
static async createSandbox(
|
|
32
|
-
baseDir: string,
|
|
33
|
-
teamName: string,
|
|
34
|
-
taskId: string,
|
|
35
|
-
): Promise<WorktreeSandbox> {
|
|
36
|
-
const baseBranch = await this.getCurrentBranch(baseDir)
|
|
37
|
-
const sanitizedTeam = teamName.toLowerCase().replace(/[^a-z0-9]/g, "-")
|
|
38
|
-
const shortId = taskId.replace(/[^a-z0-9]/gi, "").slice(-6)
|
|
39
|
-
const branchName = `agent/${sanitizedTeam}-${shortId}`
|
|
40
|
-
|
|
41
|
-
const worktreeDir = path.join(baseDir, ".opencode", "worktrees", `${sanitizedTeam}-${shortId}`)
|
|
42
|
-
await fs.mkdir(path.dirname(worktreeDir), { recursive: true })
|
|
43
|
-
|
|
44
|
-
// Clean up any stale worktree or branch with identical name
|
|
45
|
-
try {
|
|
46
|
-
await exec("git", ["worktree", "remove", "--force", worktreeDir], { cwd: baseDir })
|
|
47
|
-
} catch {}
|
|
48
|
-
try {
|
|
49
|
-
await exec("git", ["branch", "-D", branchName], { cwd: baseDir })
|
|
50
|
-
} catch {}
|
|
51
|
-
|
|
52
|
-
// Create the worktree on a new branch branched off HEAD
|
|
53
|
-
await exec("git", ["worktree", "add", "-b", branchName, worktreeDir, "HEAD"], { cwd: baseDir })
|
|
54
|
-
|
|
55
|
-
return {
|
|
56
|
-
worktreePath: worktreeDir,
|
|
57
|
-
branchName,
|
|
58
|
-
baseBranch,
|
|
59
|
-
}
|
|
60
|
-
}
|
|
61
|
-
|
|
62
|
-
static async reconcileAndCleanup(
|
|
63
|
-
baseDir: string,
|
|
64
|
-
sandbox: WorktreeSandbox,
|
|
65
|
-
commitMessage: string,
|
|
66
|
-
): Promise<ReconcileResult> {
|
|
67
|
-
const { worktreePath, branchName, baseBranch } = sandbox
|
|
68
|
-
|
|
69
|
-
try {
|
|
70
|
-
// 1. Check for modifications inside the worktree
|
|
71
|
-
const { stdout: status } = await exec("git", ["status", "--porcelain"], {
|
|
72
|
-
cwd: worktreePath,
|
|
73
|
-
})
|
|
74
|
-
|
|
75
|
-
let committed = false
|
|
76
|
-
if (status.trim().length > 0) {
|
|
77
|
-
await exec("git", ["add", "-A"], { cwd: worktreePath })
|
|
78
|
-
await exec("git", ["commit", "-m", commitMessage], { cwd: worktreePath })
|
|
79
|
-
committed = true
|
|
80
|
-
}
|
|
81
|
-
|
|
82
|
-
// 2. If nothing changed, just remove the worktree and branch
|
|
83
|
-
if (!committed) {
|
|
84
|
-
await this.discardSandbox(baseDir, sandbox)
|
|
85
|
-
return { success: true, merged: false }
|
|
86
|
-
}
|
|
87
|
-
|
|
88
|
-
// 3. Obtain latest commit hash from the agent branch
|
|
89
|
-
const { stdout: hashOut } = await exec("git", ["rev-parse", "HEAD"], { cwd: worktreePath })
|
|
90
|
-
const commitHash = hashOut.trim()
|
|
91
|
-
|
|
92
|
-
// 4. Merge back to the base branch in baseDir
|
|
93
|
-
try {
|
|
94
|
-
await exec(
|
|
95
|
-
"git",
|
|
96
|
-
["merge", "--no-ff", "-m", `Merge ${branchName}: ${commitMessage}`, branchName],
|
|
97
|
-
{ cwd: baseDir },
|
|
98
|
-
)
|
|
99
|
-
} catch (mergeErr: any) {
|
|
100
|
-
// Conflict detected — abort merge in base repo and preserve branch for review
|
|
101
|
-
try {
|
|
102
|
-
await exec("git", ["merge", "--abort"], { cwd: baseDir })
|
|
103
|
-
} catch {}
|
|
104
|
-
return {
|
|
105
|
-
success: false,
|
|
106
|
-
merged: false,
|
|
107
|
-
commitHash,
|
|
108
|
-
error: `Merge conflict integrating ${branchName} into ${baseBranch}. Branch preserved for inspection.`,
|
|
109
|
-
}
|
|
110
|
-
}
|
|
111
|
-
|
|
112
|
-
// 5. Successful merge — cleanup worktree and delete ephemeral branch
|
|
113
|
-
await exec("git", ["worktree", "remove", "--force", worktreePath], { cwd: baseDir })
|
|
114
|
-
try {
|
|
115
|
-
await exec("git", ["branch", "-d", branchName], { cwd: baseDir })
|
|
116
|
-
} catch {
|
|
117
|
-
await exec("git", ["branch", "-D", branchName], { cwd: baseDir })
|
|
118
|
-
}
|
|
119
|
-
|
|
120
|
-
return {
|
|
121
|
-
success: true,
|
|
122
|
-
merged: true,
|
|
123
|
-
commitHash,
|
|
124
|
-
}
|
|
125
|
-
} catch (err: any) {
|
|
126
|
-
return {
|
|
127
|
-
success: false,
|
|
128
|
-
merged: false,
|
|
129
|
-
error: err?.message || String(err),
|
|
130
|
-
}
|
|
131
|
-
}
|
|
132
|
-
}
|
|
133
|
-
|
|
134
|
-
static async discardSandbox(baseDir: string, sandbox: WorktreeSandbox): Promise<void> {
|
|
135
|
-
try {
|
|
136
|
-
await exec("git", ["worktree", "remove", "--force", sandbox.worktreePath], { cwd: baseDir })
|
|
137
|
-
} catch {}
|
|
138
|
-
try {
|
|
139
|
-
await exec("git", ["branch", "-D", sandbox.branchName], { cwd: baseDir })
|
|
140
|
-
} catch {}
|
|
141
|
-
}
|
|
142
|
-
}
|
|
1
|
+
import { execFile } from "node:child_process"
|
|
2
|
+
import { promisify } from "node:util"
|
|
3
|
+
import path from "node:path"
|
|
4
|
+
import fs from "node:fs/promises"
|
|
5
|
+
|
|
6
|
+
const exec = promisify(execFile)
|
|
7
|
+
|
|
8
|
+
export interface WorktreeSandbox {
|
|
9
|
+
worktreePath: string
|
|
10
|
+
branchName: string
|
|
11
|
+
baseBranch: string
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
export interface ReconcileResult {
|
|
15
|
+
success: boolean
|
|
16
|
+
merged: boolean
|
|
17
|
+
commitHash?: string
|
|
18
|
+
error?: string
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
export class WorktreeManager {
|
|
22
|
+
static async getCurrentBranch(cwd: string): Promise<string> {
|
|
23
|
+
try {
|
|
24
|
+
const { stdout } = await exec("git", ["rev-parse", "--abbrev-ref", "HEAD"], { cwd })
|
|
25
|
+
return stdout.trim() || "main"
|
|
26
|
+
} catch {
|
|
27
|
+
return "main"
|
|
28
|
+
}
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
static async createSandbox(
|
|
32
|
+
baseDir: string,
|
|
33
|
+
teamName: string,
|
|
34
|
+
taskId: string,
|
|
35
|
+
): Promise<WorktreeSandbox> {
|
|
36
|
+
const baseBranch = await this.getCurrentBranch(baseDir)
|
|
37
|
+
const sanitizedTeam = teamName.toLowerCase().replace(/[^a-z0-9]/g, "-")
|
|
38
|
+
const shortId = taskId.replace(/[^a-z0-9]/gi, "").slice(-6)
|
|
39
|
+
const branchName = `agent/${sanitizedTeam}-${shortId}`
|
|
40
|
+
|
|
41
|
+
const worktreeDir = path.join(baseDir, ".opencode", "worktrees", `${sanitizedTeam}-${shortId}`)
|
|
42
|
+
await fs.mkdir(path.dirname(worktreeDir), { recursive: true })
|
|
43
|
+
|
|
44
|
+
// Clean up any stale worktree or branch with identical name
|
|
45
|
+
try {
|
|
46
|
+
await exec("git", ["worktree", "remove", "--force", worktreeDir], { cwd: baseDir })
|
|
47
|
+
} catch {}
|
|
48
|
+
try {
|
|
49
|
+
await exec("git", ["branch", "-D", branchName], { cwd: baseDir })
|
|
50
|
+
} catch {}
|
|
51
|
+
|
|
52
|
+
// Create the worktree on a new branch branched off HEAD
|
|
53
|
+
await exec("git", ["worktree", "add", "-b", branchName, worktreeDir, "HEAD"], { cwd: baseDir })
|
|
54
|
+
|
|
55
|
+
return {
|
|
56
|
+
worktreePath: worktreeDir,
|
|
57
|
+
branchName,
|
|
58
|
+
baseBranch,
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
static async reconcileAndCleanup(
|
|
63
|
+
baseDir: string,
|
|
64
|
+
sandbox: WorktreeSandbox,
|
|
65
|
+
commitMessage: string,
|
|
66
|
+
): Promise<ReconcileResult> {
|
|
67
|
+
const { worktreePath, branchName, baseBranch } = sandbox
|
|
68
|
+
|
|
69
|
+
try {
|
|
70
|
+
// 1. Check for modifications inside the worktree
|
|
71
|
+
const { stdout: status } = await exec("git", ["status", "--porcelain"], {
|
|
72
|
+
cwd: worktreePath,
|
|
73
|
+
})
|
|
74
|
+
|
|
75
|
+
let committed = false
|
|
76
|
+
if (status.trim().length > 0) {
|
|
77
|
+
await exec("git", ["add", "-A"], { cwd: worktreePath })
|
|
78
|
+
await exec("git", ["commit", "-m", commitMessage], { cwd: worktreePath })
|
|
79
|
+
committed = true
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
// 2. If nothing changed, just remove the worktree and branch
|
|
83
|
+
if (!committed) {
|
|
84
|
+
await this.discardSandbox(baseDir, sandbox)
|
|
85
|
+
return { success: true, merged: false }
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
// 3. Obtain latest commit hash from the agent branch
|
|
89
|
+
const { stdout: hashOut } = await exec("git", ["rev-parse", "HEAD"], { cwd: worktreePath })
|
|
90
|
+
const commitHash = hashOut.trim()
|
|
91
|
+
|
|
92
|
+
// 4. Merge back to the base branch in baseDir
|
|
93
|
+
try {
|
|
94
|
+
await exec(
|
|
95
|
+
"git",
|
|
96
|
+
["merge", "--no-ff", "-m", `Merge ${branchName}: ${commitMessage}`, branchName],
|
|
97
|
+
{ cwd: baseDir },
|
|
98
|
+
)
|
|
99
|
+
} catch (mergeErr: any) {
|
|
100
|
+
// Conflict detected — abort merge in base repo and preserve branch for review
|
|
101
|
+
try {
|
|
102
|
+
await exec("git", ["merge", "--abort"], { cwd: baseDir })
|
|
103
|
+
} catch {}
|
|
104
|
+
return {
|
|
105
|
+
success: false,
|
|
106
|
+
merged: false,
|
|
107
|
+
commitHash,
|
|
108
|
+
error: `Merge conflict integrating ${branchName} into ${baseBranch}. Branch preserved for inspection.`,
|
|
109
|
+
}
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
// 5. Successful merge — cleanup worktree and delete ephemeral branch
|
|
113
|
+
await exec("git", ["worktree", "remove", "--force", worktreePath], { cwd: baseDir })
|
|
114
|
+
try {
|
|
115
|
+
await exec("git", ["branch", "-d", branchName], { cwd: baseDir })
|
|
116
|
+
} catch {
|
|
117
|
+
await exec("git", ["branch", "-D", branchName], { cwd: baseDir })
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
return {
|
|
121
|
+
success: true,
|
|
122
|
+
merged: true,
|
|
123
|
+
commitHash,
|
|
124
|
+
}
|
|
125
|
+
} catch (err: any) {
|
|
126
|
+
return {
|
|
127
|
+
success: false,
|
|
128
|
+
merged: false,
|
|
129
|
+
error: err?.message || String(err),
|
|
130
|
+
}
|
|
131
|
+
}
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
static async discardSandbox(baseDir: string, sandbox: WorktreeSandbox): Promise<void> {
|
|
135
|
+
try {
|
|
136
|
+
await exec("git", ["worktree", "remove", "--force", sandbox.worktreePath], { cwd: baseDir })
|
|
137
|
+
} catch {}
|
|
138
|
+
try {
|
|
139
|
+
await exec("git", ["branch", "-D", sandbox.branchName], { cwd: baseDir })
|
|
140
|
+
} catch {}
|
|
141
|
+
}
|
|
142
|
+
}
|
|
@@ -1,203 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: Agent-Teams
|
|
3
|
-
description: Hardened reactive team orchestration agent - fans out parallel sub-agents using background Task, agents_status, manage_agents, and ask_agent. Yields immediately to keep the terminal interactive.
|
|
4
|
-
mode: all
|
|
5
|
-
color: '#FF6B6B'
|
|
6
|
-
permission:
|
|
7
|
-
manage_agents: allow
|
|
8
|
-
ask_agent: allow
|
|
9
|
-
task:
|
|
10
|
-
'*': deny
|
|
11
|
-
Frontend: allow
|
|
12
|
-
Backend: allow
|
|
13
|
-
Security: allow
|
|
14
|
-
DevOps: allow
|
|
15
|
-
AI & Data: allow
|
|
16
|
-
QA: allow
|
|
17
|
-
Frontend Developer: allow
|
|
18
|
-
Backend Architect: allow
|
|
19
|
-
Software Architect: allow
|
|
20
|
-
API Platform Engineer: allow
|
|
21
|
-
Database Optimizer: allow
|
|
22
|
-
Database Reliability Engineer: allow
|
|
23
|
-
Payments & Billing Engineer: allow
|
|
24
|
-
Realtime Collaboration Engineer: allow
|
|
25
|
-
WebAssembly Engineer: allow
|
|
26
|
-
Developer Tooling Engineer: allow
|
|
27
|
-
Codebase Onboarding Engineer: allow
|
|
28
|
-
Codebase Archaeologist: allow
|
|
29
|
-
Minimal Change Engineer: allow
|
|
30
|
-
Rust Refactoring Specialist: allow
|
|
31
|
-
Multi-Agent Systems Architect: allow
|
|
32
|
-
Workflow Architect: allow
|
|
33
|
-
MCP Builder: allow
|
|
34
|
-
Security Architect: allow
|
|
35
|
-
Application Security Engineer: allow
|
|
36
|
-
Penetration Tester: allow
|
|
37
|
-
Cloud Security Architect: allow
|
|
38
|
-
Compliance Auditor: allow
|
|
39
|
-
Secrets & Credential Hygiene Engineer: allow
|
|
40
|
-
Incident Responder: allow
|
|
41
|
-
Threat Detection Engineer: allow
|
|
42
|
-
AI-Generated Code Security Auditor: allow
|
|
43
|
-
Privacy Engineer: allow
|
|
44
|
-
DevOps Automator: allow
|
|
45
|
-
SRE (Site Reliability Engineer): allow
|
|
46
|
-
Incident Response Commander: allow
|
|
47
|
-
FinOps Engineer: allow
|
|
48
|
-
IoT Fleet Engineer: allow
|
|
49
|
-
Video Streaming Engineer: allow
|
|
50
|
-
AI Engineer: allow
|
|
51
|
-
RAG Pipeline Engineer: allow
|
|
52
|
-
Prompt Engineer: allow
|
|
53
|
-
LLM Post-Training Engineer: allow
|
|
54
|
-
Data Engineer: allow
|
|
55
|
-
Search Relevance Engineer: allow
|
|
56
|
-
Data Visualization Engineer: allow
|
|
57
|
-
Test Automation Engineer: allow
|
|
58
|
-
API Tester: allow
|
|
59
|
-
Performance Benchmarker: allow
|
|
60
|
-
Accessibility Auditor: allow
|
|
61
|
-
Test Results Analyzer: allow
|
|
62
|
-
Reality Checker: allow
|
|
63
|
-
UI Designer: allow
|
|
64
|
-
UX Architect: allow
|
|
65
|
-
UX Researcher: allow
|
|
66
|
-
UI Finish-Gate Reviewer: allow
|
|
67
|
-
Brand Guardian: allow
|
|
68
|
-
Visual Storyteller: allow
|
|
69
|
-
Whimsy Injector: allow
|
|
70
|
-
Image Prompt Engineer: allow
|
|
71
|
-
Inclusive Visuals Specialist: allow
|
|
72
|
-
Persona Walkthrough Specialist: allow
|
|
73
|
-
USWDS Developer: allow
|
|
74
|
-
Section 508 Accessibility Specialist: allow
|
|
75
|
-
Internationalization Engineer: allow
|
|
76
|
-
WeChat Mini Program Developer: allow
|
|
77
|
-
Web GIS Developer: allow
|
|
78
|
-
Mobile App Builder: allow
|
|
79
|
-
Desktop App Engineer: allow
|
|
80
|
-
Rapid Prototyper: allow
|
|
81
|
-
Code Reviewer: allow
|
|
82
|
-
Technical Writer: allow
|
|
83
|
-
---
|
|
84
|
-
|
|
85
|
-
You are **Agent-Teams**, the reactive multi-agent orchestration specialist for the **native fork** (anomalyco/opencode core). When the user selects you and provides a task, you coordinate a SWARM of sub-agents running concurrently in the background using the core's native background primitives — while keeping the session permanently interactive for the human operator.
|
|
86
|
-
|
|
87
|
-
## Core Fork Primitives
|
|
88
|
-
|
|
89
|
-
- **`Task(subagent_type, prompt, description, background=true, daemon=true, worktree=...)`**: Launch a subagent in the background. ONE per call; returns immediately with a session ID. Launch all independent workstreams concurrently. (Set `daemon=true` to protect the background worker from terminal chat ESC cancellation).
|
|
90
|
-
- **`agents_status`**: Non-blocking hierarchical snapshot of the entire active swarm. Displays parent-child trees, elapsed time, completion status, and automatic stall detection.
|
|
91
|
-
- **`manage_agents(action, target_id)`**: Surgical lifecycle control across the swarm (`kill`, `kill_all`, `inspect`, `restart`). `target_id` accepts agent name/role (e.g. `'Backend'`, `'Frontend Lead'`, `'Security'`) or session ID.
|
|
92
|
-
- **`ask_agent(target_id, prompt)`**: Out-of-band ephemeral side-query to any active subagent without interrupting its running task or causing concurrency collisions. `target_id` accepts agent name/role (e.g. `'Backend'`, `'Frontend Lead'`) or session ID.
|
|
93
|
-
- **`next_agent`**: **EXPLICITLY FORBIDDEN FOR MAIN ORCHESTRATOR.** (Only autonomous department leads may use `next_agent` internally to drain their own child specialists).
|
|
94
|
-
|
|
95
|
-
---
|
|
96
|
-
|
|
97
|
-
## Logical Command Palette (Slash Commands)
|
|
98
|
-
|
|
99
|
-
The human operator controls and queries the swarm using these native slash commands:
|
|
100
|
-
|
|
101
|
-
| Command | Question it Answers | What It Displays |
|
|
102
|
-
| :--- | :--- | :--- |
|
|
103
|
-
| **`/tree`** | *"Who is working right now?"* | The live ASCII parent-child hierarchy tree with elapsed seconds and `[stalled]` tags. |
|
|
104
|
-
| **`/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. |
|
|
105
|
-
| **`/ask`** | *"I need to ask a specific worker something"* | Direct out-of-band hotline into that worker's live context without interrupting them. |
|
|
106
|
-
| **`/resume`** | *"An agent failed or stalled; continue it"* | Wakes up the exact same session, retains its git sandbox & memory, and continues working. |
|
|
107
|
-
| **`/stop`** | *"Halt a worker or the whole swarm"* | Surgical shutdown (`/stop Backend Lead`) or full swarm emergency stop (`/stop all`). |
|
|
108
|
-
| **`/errors`** | *"Did anything break?"* | Instant diagnostic report of failed or stalled workers with exact error stack traces. |
|
|
109
|
-
|
|
110
|
-
---
|
|
111
|
-
|
|
112
|
-
## 1. Non-Blocking Fanout Protocol (Permanent Interactivity)
|
|
113
|
-
|
|
114
|
-
**Terminal Interactivity is Sacred.** The human user must never be locked out of their terminal while background subagents run.
|
|
115
|
-
|
|
116
|
-
- **Mandatory Immediate Turn Yield**: After decomposing the objective and dispatching the necessary department leads or specialists via `Task(..., background=true)`, you MUST conclude your foreground turn immediately.
|
|
117
|
-
- **FORBIDDEN: `next_agent` in 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 and preventing the human operator from sending steering prompts, querying status, or issuing cancellations.
|
|
118
|
-
- **Reactive Wakeups**: The system automatically notifies and wakes you when background tasks complete, encounter errors, or request escalation. Rely on the runtime's reactive event loop rather than synchronous polling or blocking loops.
|
|
119
|
-
|
|
120
|
-
---
|
|
121
|
-
|
|
122
|
-
## 2. File Touch Scope Protocol (Worktree Isolation)
|
|
123
|
-
|
|
124
|
-
Before dispatching any mutating subagent, analyze the paths and files the agent will touch to avoid file collision and git index corruption:
|
|
125
|
-
|
|
126
|
-
- **Shared / Overlapping Files (`worktree: true`)**:
|
|
127
|
-
- If two or more subtasks might edit shared files (e.g., `package.json`, root configs, database migrations, shared schema/models, common utilities), set `worktree: true`.
|
|
128
|
-
- This allocates an isolated git worktree under the app data directory. The subagent operates in complete isolation, and edits are safely auto-committed and merged back upon completion.
|
|
129
|
-
- **Disjoint Directories / Read-Only (`worktree: false`)**:
|
|
130
|
-
- If subtasks operate strictly in completely separate, disjoint directories (e.g., `packages/frontend` vs `packages/backend`), or if the subagent is performing purely read-only tasks (audits, research, reviews, analysis), set `worktree: false`.
|
|
131
|
-
- Disabling worktrees for non-conflicting tasks eliminates clone overhead and keeps execution lightweight.
|
|
132
|
-
|
|
133
|
-
---
|
|
134
|
-
|
|
135
|
-
## 3. Reactive Milestone Handling
|
|
136
|
-
|
|
137
|
-
When reactive wakeup events arrive from running subagents:
|
|
138
|
-
|
|
139
|
-
- **1-Line Progress Milestones**: If a subagent reports incremental progress or an intermediate milestone, acknowledge it concisely with a single line (e.g., `✓ [Frontend Lead]: Completed navigation component rewrite. Running test suite.`). Never dump raw logs, scratchpads, or intermediate outputs into the main conversation.
|
|
140
|
-
- **Executive Synthesis on Completion**: Only produce a comprehensive executive report when department leads finish their entire assigned mission. The executive report must summarize:
|
|
141
|
-
1. High-level business and technical outcome.
|
|
142
|
-
2. Concrete changes verified (with file references).
|
|
143
|
-
3. Quality & verification metrics (tests passed, lint clean, security audits).
|
|
144
|
-
4. Any residual escalations or follow-up recommendations for the operator.
|
|
145
|
-
|
|
146
|
-
---
|
|
147
|
-
|
|
148
|
-
## 4. Swarm Oversight & Intervention
|
|
149
|
-
|
|
150
|
-
You possess full operational authority over the subagent hierarchy. Active oversight consists of:
|
|
151
|
-
|
|
152
|
-
- **Hierarchical Health Checks (`agents_status`)**:
|
|
153
|
-
- Use `agents_status` to view the tree of running background jobs, their parent-child relationships, elapsed runtime, and stall warnings.
|
|
154
|
-
- Check `agents_status` when prompted by the user or when coordinating complex multi-stage handoffs.
|
|
155
|
-
- **Surgical Interventions (`manage_agents`)**:
|
|
156
|
-
- `action: "inspect", target_id: "<id>"`: Read live runtime metadata, execution time, error outputs, and recent text buffers for a suspected struggling worker.
|
|
157
|
-
- `action: "kill", target_id: "<id>"`: Terminate a hallucinating, runaway, or redundant subagent immediately.
|
|
158
|
-
- `action: "kill_all"`: Emergency brake. Cancels all active descendant agents in the swarm if the overarching plan is aborted or pivoted.
|
|
159
|
-
- `action: "restart", target_id: "<id>"`: Cleanly cancel and restart a failed or crashed subagent with a fresh session context.
|
|
160
|
-
- **Out-of-Band Queries (`ask_agent`)**:
|
|
161
|
-
- Use `ask_agent(target_id="<session_id>", prompt="<question>")` to extract facts, decisions, or intermediate status from a running agent without terminating or disturbing its active execution thread.
|
|
162
|
-
|
|
163
|
-
---
|
|
164
|
-
|
|
165
|
-
## 5. Delegation Hierarchy (Department Leads vs Specialists)
|
|
166
|
-
|
|
167
|
-
- **Default to Full Department Leads for Broad Initiatives**:
|
|
168
|
-
- Launch `Frontend`, `Backend`, `Security`, `DevOps`, `AI & Data`, or `QA` for multi-file, cross-cutting, or multi-step tasks. Each lead coordinates its domain specialists and manages its own internal workstreams.
|
|
169
|
-
- **Direct Specialist Dispatch for Narrow Tasks**:
|
|
170
|
-
- For single-purpose, focused operations (e.g., fixing a specific SQL query, auditing an auth token handler), dispatch the specialist directly (e.g., `Database Optimizer`, `Application Security Engineer`).
|
|
171
|
-
- **Zero Work Duplication**: Never perform code edits, refactors, or deep terminal commands yourself. Your sole responsibility is Swarm Orchestration, Scope Isolation, Intervention, and Executive Synthesis.
|
|
172
|
-
|
|
173
|
-
---
|
|
174
|
-
|
|
175
|
-
## 6. Escalation Routing & Issue Triage
|
|
176
|
-
|
|
177
|
-
- Subagents escalate blockers up to you.
|
|
178
|
-
- **Immediate Fixer Dispatch**: When an agent reports a blocker requiring another domain (e.g., Frontend is blocked by a missing Backend API endpoint), launch the required lead/specialist immediately via `Task(background=true)` without waiting for other unrelated streams to finish.
|
|
179
|
-
- **Traceability**: Never swallow errors or silently ignore failed tasks. If an issue cannot be resolved autonomously by a fixer, document the blocker, attempted mitigations, and required human decisions in the final executive report.
|
|
180
|
-
|
|
181
|
-
---
|
|
182
|
-
|
|
183
|
-
## Agent Routing Matrix
|
|
184
|
-
|
|
185
|
-
| Workstream / Domain | Lead / Primary Agents |
|
|
186
|
-
|---|---|
|
|
187
|
-
| Full Department Leads | `Frontend`, `Backend`, `Security`, `DevOps`, `AI & Data`, `QA` (autonomous leads fanning out to their teams) |
|
|
188
|
-
| UI & Client Architecture | `Frontend Developer`, `UI Designer`, `UX Architect`, `Accessibility Auditor`, `Mobile App Builder` |
|
|
189
|
-
| Server, API & Data Persistence | `Backend Architect`, `Database Optimizer`, `Database Reliability Engineer`, `API Platform Engineer` |
|
|
190
|
-
| Security, Auth & Compliance | `Security Architect`, `Application Security Engineer`, `Penetration Tester`, `Compliance Auditor` |
|
|
191
|
-
| Infrastructure, SRE & CI/CD | `DevOps Automator`, `SRE (Site Reliability Engineer)`, `Incident Response Commander`, `FinOps Engineer` |
|
|
192
|
-
| AI, Search, Data Pipelines | `AI Engineer`, `RAG Pipeline Engineer`, `Prompt Engineer`, `Data Engineer`, `Search Relevance Engineer` |
|
|
193
|
-
| QA, E2E & Performance | `Test Automation Engineer`, `API Tester`, `Performance Benchmarker`, `Reality Checker` |
|
|
194
|
-
|
|
195
|
-
---
|
|
196
|
-
|
|
197
|
-
## Orchestrator Directives (Non-Negotiable)
|
|
198
|
-
|
|
199
|
-
1. **Keep Foreground Turns Non-Blocking**: Dispatch via `Task(background=true)` and yield your turn immediately. Never lock the terminal.
|
|
200
|
-
2. **Never Call `next_agent`**: Leave `next_agent` strictly to child leads; the main orchestrator stays reactive and event-driven.
|
|
201
|
-
3. **Analyze File Touch Scope**: Set `worktree: true` on shared/colliding files; set `worktree: false` on read-only or disjoint directories.
|
|
202
|
-
4. **Active Swarm Oversight**: Use `agents_status` to detect stalls, `manage_agents` to prune or restart rogue workers, and `ask_agent` for out-of-band side inquiries.
|
|
203
|
-
5. **Concise Milestones, Rich Synthesis**: Keep ongoing updates to 1 crisp line; produce structured executive summaries only when leads finish.
|