opencode-orchestrator 1.3.4 → 1.3.6

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.
Files changed (31) hide show
  1. package/README.md +76 -370
  2. package/dist/agents/prompts/02_discovery/agents/discovery_commander.d.ts +1 -5
  3. package/dist/agents/prompts/02_discovery/agents/discovery_planner.d.ts +1 -5
  4. package/dist/agents/prompts/03_planning/agents/planning_commander.d.ts +1 -5
  5. package/dist/agents/prompts/04_execution/agents/execution_commander.d.ts +1 -5
  6. package/dist/agents/prompts/04_execution/agents/execution_worker.d.ts +1 -5
  7. package/dist/agents/prompts/04_execution/execution_error_handling.d.ts +1 -5
  8. package/dist/agents/prompts/05_verification/agents/verification_commander.d.ts +1 -5
  9. package/dist/agents/prompts/05_verification/verification_build.d.ts +1 -5
  10. package/dist/agents/prompts/05_verification/verification_test.d.ts +1 -5
  11. package/dist/agents/prompts/06_mission/agents/mission_commander.d.ts +1 -5
  12. package/dist/agents/prompts/06_mission/mission_lifecycle.d.ts +1 -5
  13. package/dist/agents/prompts/07_agents/commander/commander_mandate.d.ts +1 -5
  14. package/dist/agents/prompts/07_agents/planner/planner_mandate.d.ts +1 -5
  15. package/dist/agents/prompts/07_agents/reviewer/reviewer_mandate.d.ts +1 -5
  16. package/dist/agents/prompts/07_agents/worker/worker_mandate.d.ts +1 -5
  17. package/dist/agents/prompts/08_tools/tools_code_editing.d.ts +1 -5
  18. package/dist/agents/prompts/08_tools/tools_testing.d.ts +1 -5
  19. package/dist/core/orchestrator/state.d.ts +1 -1
  20. package/dist/hooks/features/mission-loop.d.ts +1 -0
  21. package/dist/index.js +151 -41
  22. package/dist/plugin-handlers/interfaces/session-state.d.ts +3 -0
  23. package/dist/scripts/postinstall.js +21 -10
  24. package/dist/scripts/preuninstall.js +20 -11
  25. package/dist/shared/core/constants/limits.d.ts +1 -1
  26. package/dist/shared/loop/constants/loop.d.ts +1 -1
  27. package/dist/shared/loop/constants/mission-control.d.ts +2 -2
  28. package/dist/shared/loop/interfaces/mission-loop.d.ts +1 -1
  29. package/dist/shared/session/constants/events/index.d.ts +2 -0
  30. package/dist/shared/session/constants/events/session-events.d.ts +3 -0
  31. package/package.json +5 -5
package/README.md CHANGED
@@ -1,59 +1,44 @@
1
-
2
- ---
3
-
4
1
  <div align="center">
5
- <img src="assets/logo.png" alt="logo" width="200" />
2
+ <img src="assets/logo.png" alt="OpenCode Orchestrator logo" width="160" />
6
3
  <h1>OpenCode Orchestrator</h1>
7
- <p>Production-Grade Multi-Agent Orchestration Engine for High-Integrity Software Engineering</p>
4
+ <p>Multi-agent mission control for OpenCode.</p>
8
5
 
9
6
  [![MIT License](https://img.shields.io/badge/license-MIT-red.svg)](LICENSE)
10
7
  [![npm](https://img.shields.io/npm/v/opencode-orchestrator.svg)](https://www.npmjs.com/package/opencode-orchestrator)
11
8
  <!-- VERSION:START -->
12
- **Version:** `1.3.4`
9
+ **Version:** `1.3.6`
13
10
  <!-- VERSION:END -->
14
11
  </div>
15
12
 
16
-
17
13
  ---
18
14
 
19
- ## Quick Start
15
+ ## 1. Install
20
16
 
21
17
  ```bash
22
18
  npm install -g opencode-orchestrator
23
19
  ```
24
20
 
25
- Install hooks are source-checkout safe, prefer `opencode.jsonc` when present, preserve sibling plugin entries, and skip automatic config mutation in CI environments.
21
+ The install hook merges OpenCode config instead of replacing it, prefers `opencode.jsonc` when present, preserves existing plugin tuple options, and skips automatic config mutation in CI.
26
22
 
27
- To remove the plugin safely later, run:
23
+ To remove the plugin from OpenCode config:
28
24
 
29
25
  ```bash
30
26
  npm explore -g opencode-orchestrator -- npm run cleanup:plugin
31
27
  npm uninstall -g opencode-orchestrator
32
28
  ```
33
29
 
34
- `npm uninstall -g` does not run dependency uninstall hooks in the npm 11 flow verified for this repo, so config cleanup is explicit.
35
-
36
- ### Model, Permissions, and Concurrency
30
+ Manual fallback: remove `"opencode-orchestrator"` or `["opencode-orchestrator", {...}]` from the `plugin` array in `opencode.json` or `opencode.jsonc`.
37
31
 
38
- The plugin does not force a model by default. OpenCode's model rules apply: primary agents use the global `model` unless the agent has its own `model`, and subagents use the invoking primary agent's model unless the subagent has its own `model`.
32
+ ## 2. Configure
39
33
 
40
- Recommended `opencode.jsonc` configuration:
34
+ OpenCode supports plugin options as `["plugin-name", {...}]` tuples. Use that form for orchestrator-specific settings:
41
35
 
42
36
  ```jsonc
43
37
  {
44
38
  "$schema": "https://opencode.ai/config.json",
45
- "model": "opencode/gpt-5.1-codex",
46
39
  "permission": {
47
40
  "question": "allow"
48
41
  },
49
- "agent": {
50
- "commander": {
51
- "model": "opencode/gpt-5.1-codex"
52
- },
53
- "worker": {
54
- "model": "anthropic/claude-opus-4-5-20251101"
55
- }
56
- },
57
42
  "plugin": [
58
43
  [
59
44
  "opencode-orchestrator",
@@ -75,371 +60,92 @@ Recommended `opencode.jsonc` configuration:
75
60
  }
76
61
  ```
77
62
 
78
- Global permissions are copied into the generated Commander, Planner, Worker, and Reviewer agents. Same-name agent config keeps user model/options and can override permission keys per agent. When `permission.question` is `allow`, orchestrator agents can still ask concise clarification questions if they are truly blocked.
79
-
80
- Inside an OpenCode environment:
81
- ```bash
82
- /task "Implement a new authentication module with JWT and audit logs"
83
- ```
84
-
85
-
86
- ---
87
-
88
- ## 🚀 Engine Workflow
89
-
90
- **Hub-and-Spoke Architecture** with Work-Stealing Queues for parallel, context-isolated task execution.
91
- ```
92
- ╔══════════════════════════════════════════════════════════════════════════════╗
93
- ║ USER INPUT /task "..." ║
94
- ╚══════════════════════════════════════════════════════════════════════════════╝
95
-
96
-
97
- ╔══════════════════════════════════════════════════════════════════════════════╗
98
- ║ ┌─────────────────────────────────────────────────────────────────────────┐ ║
99
- ║ │ C O M M A N D E R │ ║
100
- ║ │ [ Mission Analysis & Delegation ] │ ║
101
- ║ │ │ ║
102
- ║ │ • Interprets user intent • Coordinates multi-agent workflow │ ║
103
- ║ │ • Monitors progress • Manages work-stealing queues │ ║
104
- ║ └─────────────────────────────────────────────────────────────────────────┘ ║
105
- ╚══════════════════════════════════════════════════════════════════════════════╝
106
-
107
- ┌───────────────┼───────────────┐
108
- ▼ ▼ ▼
109
- ╔═════════════════╗ ╔═════════════════╗ ╔═════════════════╗
110
- ║ P L A N N E R ║ ║ W O R K E R ║ ║ W O R K E R ║
111
- ║ [Architect] ║ ║ [Implementer] ║ ║ [Implementer] ║
112
- ║ ║ ║ ║ ║ ║
113
- ║ • Dependency ║ ║ • File coding ║ ║ • File coding ║
114
- ║ analysis ║ ║ • TDD workflow ║ ║ • TDD workflow ║
115
- ║ • Roadmap gen ║ ║ • Documentation║ ║ • Documentation║
116
- ║ • TODO.md ║ ║ ║ ║ ║
117
- ╚═════════════════╝ ╚═════════════════╝ ╚═════════════════╝
118
- │ │ │
119
- │ ┌──────────────┼─────────────────────┘
120
- │ │ │
121
- ▼ ▼ ▼
122
- ╔══════════════════════════════════════╗
123
- ║ SESSION POOL (MVCC Sync) ║
124
- ║ ┌─────────────────────────────────┐ ║
125
- ║ │ Object Pool │ Buffer Pool │ ║
126
- ║ │ String Pool │ Connection Pool │ ║
127
- ║ └─────────────────────────────────┘ ║
128
- ╚══════════════════════════════════════╝
129
-
130
-
131
- ╔══════════════════════════════════════╗
132
- ║ MSVP MONITOR / REVIEWER ║
133
- ║ ┌─────────────────────────────────┐ ║
134
- ║ │ • Adaptive polling (500ms-5s) │ ║
135
- ║ │ • Stability detection │ ║
136
- ║ │ • Unit test verification │ ║
137
- ║ └─────────────────────────────────┘ ║
138
- ╚══════════════════════════════════════╝
139
-
140
-
141
- ┌────────────────┐
142
- │ ✨ COMPLETED │
143
- └────────────────┘
144
- ```
145
-
146
- ---
147
-
148
- ## 🏗️ Architecture Layers
63
+ Optional model routing stays in normal OpenCode config. The plugin does not force a model:
149
64
 
150
- ```
151
- ┌─────────────────────────────────────────────────────────────────────────────┐
152
- │ PRESENTATION LAYER │
153
- ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │
154
- │ │ Task Toast │ │ Progress │ │ Notification│ │ Mission Summary │ │
155
- │ │ Manager │ │ Notifier │ │ Manager │ │ Display │ │
156
- │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────────┘ │
157
- ├─────────────────────────────────────────────────────────────────────────────┤
158
- │ BUSINESS LOGIC LAYER │
159
- │ ┌───────────────────────────────────────────────────────────────────────┐ │
160
- │ Parallel Agent Orchestration │ │
161
- │ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────────┐ │ │
162
- │ │ │ Commander │ │ Planner │ │ Worker │ │ Reviewer │ │ │
163
- │ │ │ Agent │ │ Agent │ │ Agent │ │ Agent │ │ │
164
- │ │ └────────────┘ └────────────┘ └────────────┘ └────────────────┘ │ │
165
- │ └───────────────────────────────────────────────────────────────────────┘ │
166
- │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────────────┐│
167
- │ │ Concurrency │ │ Task Store │ │ Hook System ││
168
- │ │ Controller │ │ (In-Memory) │ │ [Early/Normal/Late Phases] ││
169
- │ └─────────────────┘ └─────────────────┘ └─────────────────────────────┘│
170
- ├─────────────────────────────────────────────────────────────────────────────┤
171
- │ INFRASTRUCTURE LAYER │
172
- │ ┌────────────────┐ ┌────────────────┐ ┌────────────────────────────┐ │
173
- │ │ Session Pool │ │ Work-Stealing │ │ Memory Pools │ │
174
- │ │ [5 per agent] │ │ [Chase-Lev] │ │ ┌──────┐ ┌──────┐ ┌─────┐│ │
175
- │ │ [10 reuse max] │ │ [LIFO/FIFO] │ │ │Object│ │String│ │Buffer││ │
176
- │ └────────────────┘ └────────────────┘ │ │ 200 │ │ intern│ │ 4KB ││ │
177
- │ │ └──────┘ └──────┘ └─────┘│ │
178
- │ ┌────────────────┐ ┌────────────────┐ └────────────────────────────┘ │
179
- │ │ MVCC State │ │ Circuit Breaker │ ┌────────────────────────────┐ │
180
- │ │ [Atomic Sync] │ │ [5 failures→open│ │ Rust Connection Pool │ │
181
- │ │ │ │ [2 success→close│ │ [4 processes, 30s idle] │ │
182
- │ └────────────────┘ └────────────────┘ └────────────────────────────┘ │
183
- ├─────────────────────────────────────────────────────────────────────────────┤
184
- │ SAFETY LAYER │
185
- │ ┌────────────────┐ ┌────────────────┐ ┌─────────────────────────────┐ │
186
- │ │ RAII Pattern │ │ Shutdown │ │ Auto-Recovery │ │
187
- │ │ [Zero Leaks] │ │ Manager │ │ [Exponential Backoff] │ │
188
- │ │ │ │ [5s timeout] │ │ [Rate limit handling] │ │
189
- │ └────────────────┘ └────────────────┘ └─────────────────────────────┘ │
190
- └─────────────────────────────────────────────────────────────────────────────┘
65
+ ```jsonc
66
+ {
67
+ "model": "provider/model-id",
68
+ "agent": {
69
+ "commander": {
70
+ "model": "provider/model-id"
71
+ },
72
+ "worker": {
73
+ "model": "provider/stronger-model-id"
74
+ }
75
+ }
76
+ }
191
77
  ```
192
78
 
193
- ---
79
+ Generated Commander, Planner, Worker, and Reviewer agents inherit global permissions. Same-name user agent config can still override specific model or permission keys.
194
80
 
195
- ## 🧪 Test Utilities
81
+ ## 3. Run
196
82
 
197
- Reusable test helpers keep filesystem, task, and process-heavy flows deterministic:
83
+ Inside OpenCode:
198
84
 
199
- ```
200
- tests/harness/
201
- ├── fixture.ts Disposable tmpdir utilities
202
- │ ├── tmpdir() async disposable with cleanup
203
- │ ├── tmpdirSync() sync disposable with cleanup
204
- │ ├── createMockFs() In-memory fs mock
205
- │ └── waitFor() Async condition waiter
206
-
207
- ├── builders.ts Factory functions for test objects
208
- │ ├── createParallelTask() Build ParallelTask instances
209
- │ ├── createBackgroundTask() Build BackgroundTask instances
210
- │ └── createTodo() Build Todo instances
211
-
212
- ├── mocks.ts Mock utilities
213
- │ ├── mockConsole() Spy on console.log/error
214
- │ ├── mockProcessExit() Mock process.exit
215
- │ ├── useFakeTimers() Time manipulation
216
- │ └── createMockEmitter() EventEmitter spy
217
-
218
- └── index.ts Unified exports
85
+ ```bash
86
+ /task "Implement the requested change and verify it"
219
87
  ```
220
88
 
221
- ### Usage Example
222
-
223
- ```typescript
224
- import { tmpdir, createParallelTask, mockConsole } from "@/tests/harness";
225
-
226
- describe("My test", () => {
227
- let consoleMock;
228
-
229
- beforeEach(() => {
230
- consoleMock = mockConsole();
231
- consoleMock.setup();
232
- });
233
-
234
- afterEach(() => {
235
- consoleMock.restore();
236
- });
237
-
238
- it("should work", async () => {
239
- await using tmp = await tmpdir({ git: true });
240
- const task = createParallelTask({ description: "Test" });
241
- expect(task.status).toBe("pending");
242
- });
243
- });
89
+ Mission controls:
90
+
91
+ 1. `/task ...` starts a persisted mission loop under `.opencode/`.
92
+ 2. `Esc`/OpenCode interrupt is respected by idle guards so the plugin does not immediately re-continue an interrupted turn.
93
+ 3. `/cancel` and `/stop` deactivate the current mission loop.
94
+ 4. The default mission iteration ceiling is `1,000,000,000`.
95
+
96
+ ## 4. How It Works
97
+
98
+ ```mermaid
99
+ flowchart LR
100
+ U["/task input"] --> C["Commander"]
101
+ C --> P["Planner"]
102
+ C --> W["Worker pool"]
103
+ W --> R["Reviewer"]
104
+ P --> S["Mission state"]
105
+ W --> S
106
+ R --> V{"Verified?"}
107
+ V -- "no" --> C
108
+ V -- "yes" --> D["Done"]
244
109
  ```
245
110
 
246
- ---
247
-
248
- ## Elite Multi-Agent Swarm
249
-
250
- | Agent | Role | Core Responsibilities |
251
- |:------|:-----|:------------------------|
252
- | **Commander** | Mission Hub | Task decomposition, agent coordination, work-stealing orchestration, final mission seal |
253
- | **Planner** | Architect | Dependency analysis, roadmap generation, TODO.md creation via MVCC, file-level planning |
254
- | **Worker** | Implementer | High-throughput coding, TDD workflow, documentation, isolated file execution |
255
- | **Reviewer** | Auditor | Unit test verification, LSP/Lint validation, integration testing, quality gate |
256
- ---
257
-
258
- ## 🛠️ Core Capabilities
259
-
260
- ### 🔒 Atomic MVCC State Synchronization
261
- Solves the "Concurrent TODO Update" problem using **MVCC + Mutex**. Agents safely mark tasks complete in parallel without data loss or race conditions. Every state change is cryptographically hashed and logged.
111
+ | Agent | Purpose |
112
+ | --- | --- |
113
+ | Commander | Interprets the mission, coordinates agents, and keeps the loop aligned. |
114
+ | Planner | Breaks work into ordered steps and tracks dependencies. |
115
+ | Worker | Implements scoped file changes with isolated context. |
116
+ | Reviewer | Checks completion evidence, tests, and integration risk. |
262
117
 
263
- ### 🧩 Advanced Hook Orchestration
264
- Execution flows governed by a **Priority-Phase Hook Registry**. Hooks are grouped into phases (`early`, `normal`, `late`) and executed via **Topological Sort** for predictable, dependency-aware ordering.
118
+ Runtime evidence is written only when enabled:
265
119
 
266
- ### 🎛️ Mission Loop Control
267
- `/task` starts a persisted mission loop under `.opencode/`. The loop watches TODO/checklist verification, background task state, compaction safety, recovery state, and stagnation signals before injecting compact continuation prompts that keep Commander aligned with the active objective.
120
+ | Artifact | Purpose |
121
+ | --- | --- |
122
+ | `.opencode/mission-ledger.jsonl` | Bounded event trail for mission decisions. |
123
+ | `.opencode/docs/brain/scratchpad.md` | Generated Markdown memory surface for active missions. |
124
+ | `.opencode/docs/brain/knowledge-map.canvas` | Obsidian-compatible visual map of objective, evidence, and verification nodes. |
268
125
 
269
- The mission loop also writes a bounded runtime evidence trail to `.opencode/mission-ledger.jsonl` and a generated Markdown memory surface under `.opencode/docs/brain/`. Disable those artifacts with the `missionLoop.ledger` and `missionLoop.markdownMemory` plugin options when a project needs a quieter workspace.
270
-
271
- ### 🛡️ Autonomous Recovery
272
- - **Self-healing loops** with adaptive stagnation detection
273
- - **Proactive Agency**: Smart monitoring that audits logs and plans ahead during background tasks
274
- - **Auto-retry with backoff**: Exponential backoff for transient failures
275
-
276
- ### 🎯 State-Level Session Isolation
277
- Reused sessions in the **SessionPool** are explicitly reset via server-side compaction, ensuring previous task context never leaks into new tasks.
278
-
279
- ### 🚀 Zero-Payload Turbo Mode
280
- Leverages `system.transform` to unshift agent instruction sets server-side, reducing initial message payloads by **90%+** and preventing context fragmentation.
281
-
282
- ### 🧠 Hierarchical Memory System
283
- Maintains focus across thousands of conversation turns using a 4-tier memory structure with **EMA-based Context Gating** to preserve architectural truth while pruning noise.
284
-
285
- ### 🔄 Adaptive Intelligence Loop
286
- - **Stagnation Detection**: Senses when no progress is made across iterations
287
- - **Diagnostic Intervention**: Forces "Diagnostic Mode" mandating log audits and strategy pivots
288
- - **Proactive Agency**: Mandates Speculative Planning during background task execution
289
-
290
- ### 🧬 Knowledge Graph RAG (Second Brain)
291
- An autonomous **Obsidian-style evolutionary memory system** that gives agents persistent, searchable knowledge across sessions.
292
-
293
- Runtime context injection is active for orchestrated sessions through `experimental.chat.system.transform`, indexing `docs/**/*.md` and `.opencode/docs/**/*.md` with BM25/tag/graph fusion before prompt injection.
294
-
295
- During active missions, generated runtime memory is available at `.opencode/docs/brain/scratchpad.md`; `.opencode/docs/brain/knowledge-map.canvas` provides an Obsidian-compatible visual map of objective, runtime, verification, and recent evidence nodes.
296
-
297
- ```
298
- ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
299
- │ 📝 Ingest │────▶│ 🔍 Search │────▶│ 🧠 Recall │
300
- │ ────────── │ │ ────────── │ │ ────────── │
301
- │ YAML Parser │ │ BM25 Lexical│ │ RRF-Ranked │
302
- │ Tag HashMap │ │ Tag Index │ │ Top-K Notes │
303
- │ Wiki-Links │ │ 2-Hop Graph │ │ → Context │
304
- └──────┬───────┘ └──────────────┘ └──────────────┘
305
-
306
-
307
- ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
308
- │ 🔄 Evolve │────▶│ 🛡️ Guard │────▶│ 📦 Archive │
309
- │ ────────── │ │ ────────── │ │ ────────── │
310
- │ Fission │ │ Cycle DFS │ │ Orphan GC │
311
- │ Fusion │ │ Write FIFO │ │ MOC Hubs │
312
- │ (Auto-Split │ │ Keep-Pin │ │ MD Export │
313
- │ & Merge) │ │ Shield │ │ │
314
- └──────────────┘ └──────────────┘ └──────────────┘
315
- ```
316
-
317
- **Six integrated modules** power the knowledge pipeline:
318
-
319
- | Module | Purpose |
320
- |:-------|:--------|
321
- | **TagIndexer** | O(1) YAML frontmatter parsing → tag-to-file HashMap |
322
- | **GraphParser** | `[[wiki-link]]` extraction, bi-directional adjacency graph |
323
- | **HybridSearch** | BM25 + Tag + 2-Hop Graph → **Reciprocal Rank Fusion** (k=60) |
324
- | **Scratchpad** | LRU register cache (64 slots, 4KB max) with markdown persistence |
325
- | **SafetyGuards** | Circular link DFS, async FIFO write queue, keep-pin shield |
326
- | **MemoryConsolidation** | Fission/Fusion/GC/MOC — pure functional analysis |
327
-
328
- ---
329
-
330
- ## ⚙️ Performance Benchmarks
331
-
332
- | Metric | Improvement |
333
- |:-------|:------------|
334
- | CPU Utilization | 90%+ (up from 50-70%) |
335
- | Tool Call Speed | 10x faster (5-10ms vs 50-100ms) via Rust pool |
336
- | Session Creation | 90% faster (50ms vs 500ms) via session pooling |
337
- | Memory Usage | 60% reduction via object/string/buffer pooling |
338
- | GC Pressure | 80% reduction |
339
- | Token Efficiency | 40% reduction via Incremental State & System Transform |
340
- | Sync Accuracy | 99.95% via MVCC+Mutex |
341
- | Parallel Efficiency | 80% improvement (50% → 90%+) |
342
-
343
- ---
344
-
345
- ## 🏗️ Infrastructure & Reliability
346
-
347
- ### Resource Safety
348
- - **RAII Pattern**: Guaranteed resource cleanup with zero leaks
349
- - **ShutdownManager**: Priority-based graceful shutdown (5s timeout per handler)
350
- - **Atomic File Operations**: Temp file + rename for corruption-proof writes
351
- - **Automatic Backups**: Timestamped config backups with rollback support
352
-
353
- ### Safety Features
354
- - **Circuit Breaker**: Auto-recovery from API failures (5 failures → open)
355
- - **Resource Pressure Detection**: Rejects low-priority tasks when memory > 80%
356
- - **Terminal Node Guard**: Prevents infinite recursion via depth limit
357
- - **Auto-Scaling**: Concurrency slots adjust based on success/failure rate
358
-
359
- ### Technical Stack
360
- - **Runtime**: Node.js 24+ (TypeScript)
361
- - **Tools**: Rust-based CLI tools (grep, glob, ast) via connection pool
362
- - **Concurrency**: Chase-Lev work-stealing deque + priority queues
363
- - **Memory**: Object pooling + string interning + buffer pooling
364
- - **State Management**: MVCC + Mutex
365
- - **Safety**: RAII + circuit breaker + resource pressure detection
366
- - **Knowledge**: In-memory graph RAG with BM25/Tag/Graph search fusion
367
-
368
- ---
369
-
370
- ## 🔧 Installation & Configuration
371
-
372
- ### Safe Installation
373
- The installation process is **production-safe** with multiple protection layers:
374
-
375
- 1. ✅ **Never overwrites** — always merges with existing config
376
- 2. ✅ **Automatic backups** — timestamped, last 5 kept
377
- 3. ✅ **Atomic writes** — temp file + rename (OS-level atomic)
378
- 4. ✅ **Automatic rollback** — restores from backup on any failure
379
- 5. ✅ **Cross-platform** — Windows (native, Git Bash, WSL2), macOS, Linux
380
- 6. ✅ **CI-aware** — skips non-essential operations in CI environments
381
- 7. ✅ **Timeout protection** — 30s timeout prevents hanging
382
- 8. ✅ **Graceful degradation** — exits 0 on non-critical failures
383
-
384
- ### Safe Removal
385
- OpenCode config cleanup is provided as an explicit command because global package uninstall does not invoke dependency uninstall hooks in the npm flow validated for this package.
126
+ ## 5. Developer Notes
386
127
 
387
128
  ```bash
388
- npm explore -g opencode-orchestrator -- npm run cleanup:plugin
389
- npm uninstall -g opencode-orchestrator
129
+ npm run build
130
+ npx tsc --noEmit
131
+ npm test
132
+ cargo test --workspace --all-targets
390
133
  ```
391
134
 
392
- Manual fallback:
393
- - Open `~/.config/opencode/opencode.json` or `opencode.jsonc`
394
- - Remove `"opencode-orchestrator"` from the `plugin` array
395
-
396
- ### Configuration Logs
397
- - Unix: `/tmp/opencode-orchestrator.log`
398
- - Windows: `%TEMP%\opencode-orchestrator.log`
135
+ Useful references:
399
136
 
400
- ---
401
-
402
- ## 🧪 Testing & Stability
403
-
404
- ### Test Utilities
405
- Reusable helpers under `tests/harness/` provide:
406
- - **Disposable tmpdir**: Automatic cleanup with `Symbol.asyncDispose` / `Symbol.dispose`
407
- - **Test builders**: Factory functions for `ParallelTask`, `BackgroundTask`, `Todo`
408
- - **Mock utilities**: Console, process, timers, file system, event emitter mocks
137
+ 1. OpenCode plugins: https://opencode.ai/docs/plugins/
138
+ 2. OpenCode config: https://opencode.ai/docs/config/
139
+ 3. OpenCode keybinds: https://opencode.ai/docs/keybinds/
140
+ 4. Project issues: https://github.com/agnusdei1207/opencode-orchestrator/issues
409
141
 
410
- ```typescript
411
- import { tmpdir, createParallelTask, mockConsole } from "@/tests/harness";
142
+ Config logs:
412
143
 
413
- await using tmp = await tmpdir({ git: true });
414
- const task = createParallelTask({ description: "Test" });
415
- ```
416
-
417
- ### TUI Stability
418
- - **Cleanup guarantees**: `initToastClient()` returns a cleanup function
419
- - **Timeout protection**: AbortController-based 2-10s timeout for async toast operations
420
- - **Error isolation**: Try/catch around all toast operations prevents cascade failures
144
+ | Platform | Path |
145
+ | --- | --- |
146
+ | Unix | `/tmp/opencode-orchestrator.log` |
147
+ | Windows | `%TEMP%\opencode-orchestrator.log` |
421
148
 
422
- ### Cross-Platform Reliability
423
- - **Windows guard**: Proper handling of WSL2, Git Bash, native Windows paths
424
- - **Signal handling**: Graceful shutdown on SIGINT/SIGTERM
425
- - **Process isolation**: Child process cleanup with timeout
149
+ ## 6. License
426
150
 
427
- ---
428
-
429
- ## 📚 Documentation
430
-
431
- - [System Architecture Deep-Dive →](docs/SYSTEM_ARCHITECTURE.md)
432
- - [Developer Notes →](docs/DEVELOPERS_NOTE.md)
433
- - [Knowledge RAG Roadmap →](docs/histories/2026/05/31/PLAN_SecondBrainOrchestration_2026-05-31.md)
434
-
435
- ---
436
-
437
- ## 📄 License
438
-
439
- MIT License — see [LICENSE](LICENSE) for details.
440
-
441
- ---
442
-
443
- <div align="center">
444
- <sub>Built with ⚡ for production-grade autonomous software engineering</sub>
445
- </div>
151
+ MIT License. See [LICENSE](LICENSE).
@@ -1,5 +1 @@
1
- /**
2
- * Placeholder for commander in discovery category.
3
- * Generated to match PROMPT_ARCHITECTURE_PROPOSAL.md
4
- */
5
- export declare const DISCOVERY_COMMANDER = "\n# TODO: Implement commander specific prompt\n";
1
+ export declare const DISCOVERY_COMMANDER = "\n# Discovery: Commander\n\n- Confirm repository root, active branch, package manager, and configured OpenCode runtime before delegating.\n- Identify entry points, public exports, generated artifacts, and dynamic plugin hooks that can affect the mission.\n- Turn unknowns into explicit questions or Planner tasks instead of treating assumptions as facts.\n";
@@ -1,5 +1 @@
1
- /**
2
- * Placeholder for planner in discovery category.
3
- * Generated to match PROMPT_ARCHITECTURE_PROPOSAL.md
4
- */
5
- export declare const DISCOVERY_PLANNER = "\n# TODO: Implement planner specific prompt\n";
1
+ export declare const DISCOVERY_PLANNER = "\n# Discovery: Planner\n\n- Map inputs, outputs, dependencies, and dynamic registration points for the assigned area.\n- Read the files that define the behavior before proposing a plan.\n- Report confirmed facts separately from risks, gaps, and assumptions that still need verification.\n";
@@ -1,5 +1 @@
1
- /**
2
- * Placeholder for commander in planning category.
3
- * Generated to match PROMPT_ARCHITECTURE_PROPOSAL.md
4
- */
5
- export declare const PLANNING_COMMANDER = "\n# TODO: Implement commander specific prompt\n";
1
+ export declare const PLANNING_COMMANDER = "\n# Planning: Commander\n\n- Convert the mission into ordered work with clear owners, dependencies, and verification gates.\n- Keep parallel work file-disjoint unless the dependency graph proves it is safe.\n- Prefer the smallest plan that satisfies the request and leaves documentation, tests, and release state synchronized.\n";
@@ -1,5 +1 @@
1
- /**
2
- * Placeholder for commander in execution category.
3
- * Generated to match PROMPT_ARCHITECTURE_PROPOSAL.md
4
- */
5
- export declare const EXECUTION_COMMANDER = "\n# TODO: Implement commander specific prompt\n";
1
+ export declare const EXECUTION_COMMANDER = "\n# Execution: Commander\n\n- Delegate scoped implementation tasks only after discovery and planning evidence exists.\n- Monitor each task for progress, conflicts, and missing validation instead of assuming completion.\n- Re-plan when verification exposes a real mismatch between intended and observed behavior.\n";
@@ -1,5 +1 @@
1
- /**
2
- * Placeholder for worker in execution category.
3
- * Generated to match PROMPT_ARCHITECTURE_PROPOSAL.md
4
- */
5
- export declare const EXECUTION_WORKER = "\n# TODO: Implement worker specific prompt\n";
1
+ export declare const EXECUTION_WORKER = "\n# Execution: Worker\n\n- Modify only the files assigned by Commander unless new evidence shows the scope is incomplete.\n- Keep changes focused, preserve existing behavior outside the assignment, and remove obsolete code after migration.\n- Return exact files changed, commands run, observed results, and remaining risks.\n";
@@ -1,5 +1 @@
1
- /**
2
- * Placeholder for error handling in execution category.
3
- * Generated to match PROMPT_ARCHITECTURE_PROPOSAL.md
4
- */
5
- export declare const EXECUTION_ERROR_HANDLING = "\n# TODO: Implement error handling specific prompt\n";
1
+ export declare const EXECUTION_ERROR_HANDLING = "\n# Execution Error Handling\n\n- Treat failing commands as evidence, not noise; capture the command, exit state, and relevant output.\n- Classify failures as environmental, dependency, test, type, runtime, or design before retrying.\n- Retry only transient failures with a changed condition; otherwise inspect the affected path and adapt the plan.\n";
@@ -1,5 +1 @@
1
- /**
2
- * Placeholder for commander in verification category.
3
- * Generated to match PROMPT_ARCHITECTURE_PROPOSAL.md
4
- */
5
- export declare const VERIFICATION_COMMANDER = "\n# TODO: Implement commander specific prompt\n";
1
+ export declare const VERIFICATION_COMMANDER = "\n# Verification: Commander\n\n- Require evidence for every completed task: file reads, command output, tests, or direct runtime observation.\n- Ask Reviewer for final integration verification before declaring the mission complete.\n- Keep unresolved failures visible in the mission summary with owner, cause, and next step.\n";
@@ -1,5 +1 @@
1
- /**
2
- * Placeholder for build in verification category.
3
- * Generated to match PROMPT_ARCHITECTURE_PROPOSAL.md
4
- */
5
- export declare const VERIFICATION_BUILD = "\n# TODO: Implement build specific prompt\n";
1
+ export declare const VERIFICATION_BUILD = "\n# Build Verification\n\n- Run the repository build or the narrowest build command that covers the changed surface.\n- Treat generated artifacts, package metadata, and exported types as part of the build contract.\n- If a build cannot run in the current environment, state the exact blocker and run the closest lower-level checks.\n";
@@ -1,5 +1 @@
1
- /**
2
- * Placeholder for test in verification category.
3
- * Generated to match PROMPT_ARCHITECTURE_PROPOSAL.md
4
- */
5
- export declare const VERIFICATION_TEST = "\n# TODO: Implement test specific prompt\n";
1
+ export declare const VERIFICATION_TEST = "\n# Test Verification\n\n- Run targeted tests for changed behavior before broader suites.\n- Add or update regression tests when the change fixes a bug or guards a public contract.\n- Report pass, fail, or skipped status with exact command evidence.\n";
@@ -1,5 +1 @@
1
- /**
2
- * Placeholder for commander in mission category.
3
- * Generated to match PROMPT_ARCHITECTURE_PROPOSAL.md
4
- */
5
- export declare const MISSION_COMMANDER = "\n# TODO: Implement commander specific prompt\n";
1
+ export declare const MISSION_COMMANDER = "\n# Mission: Commander\n\n- Preserve the user objective, active plan, evidence, and verification state across continuation turns.\n- Continue only while the mission is active, incomplete, and below the configured iteration ceiling.\n- Finish with a concise outcome, validation evidence, known risks, and follow-up state.\n";
@@ -1,5 +1 @@
1
- /**
2
- * Placeholder for lifecycle in mission category.
3
- * Generated to match PROMPT_ARCHITECTURE_PROPOSAL.md
4
- */
5
- export declare const MISSION_LIFECYCLE = "\n# TODO: Implement lifecycle specific prompt\n";
1
+ export declare const MISSION_LIFECYCLE = "\n# Mission Lifecycle\n\n- /task starts a persisted mission with objective, iteration budget, evidence trail, and active session state.\n- Idle continuation may proceed only after a completed assistant turn for the current user message.\n- /cancel, /stop, or an interrupt without current completion evidence deactivates continuation until a new mission starts.\n";
@@ -1,5 +1 @@
1
- /**
2
- * Placeholder for mandate in agents category.
3
- * Generated to match PROMPT_ARCHITECTURE_PROPOSAL.md
4
- */
5
- export declare const COMMANDER_MANDATE = "\n# TODO: Implement mandate specific prompt\n";
1
+ export declare const COMMANDER_MANDATE = "\n# Commander Mandate\n\n- Own mission interpretation, task decomposition, delegation, progress monitoring, and final completion.\n- Keep subagents context-isolated while preserving shared truth through the mission state and evidence trail.\n- Do not mark completion until implementation, documentation, and verification evidence all agree.\n";
@@ -1,5 +1 @@
1
- /**
2
- * Placeholder for mandate in agents category.
3
- * Generated to match PROMPT_ARCHITECTURE_PROPOSAL.md
4
- */
5
- export declare const PLANNER_MANDATE = "\n# TODO: Implement mandate specific prompt\n";
1
+ export declare const PLANNER_MANDATE = "\n# Planner Mandate\n\n- Produce evidence-backed plans with affected files, dependency order, risks, and validation commands.\n- Keep TODO state aligned with the latest verified scope.\n- Prefer incremental migration paths that avoid overlapping file ownership.\n";
@@ -1,5 +1 @@
1
- /**
2
- * Placeholder for mandate in agents category.
3
- * Generated to match PROMPT_ARCHITECTURE_PROPOSAL.md
4
- */
5
- export declare const REVIEWER_MANDATE = "\n# TODO: Implement mandate specific prompt\n";
1
+ export declare const REVIEWER_MANDATE = "\n# Reviewer Mandate\n\n- Verify claimed completion against source files, tests, build output, and integration paths.\n- Mark TODO items complete only after direct evidence confirms the requested behavior.\n- Report residual risk clearly when the environment prevents full validation.\n";
@@ -1,5 +1 @@
1
- /**
2
- * Placeholder for mandate in agents category.
3
- * Generated to match PROMPT_ARCHITECTURE_PROPOSAL.md
4
- */
5
- export declare const WORKER_MANDATE = "\n# TODO: Implement mandate specific prompt\n";
1
+ export declare const WORKER_MANDATE = "\n# Worker Mandate\n\n- Implement the assigned scope with minimal, tested edits.\n- Preserve public contracts unless Commander explicitly assigns a behavior change.\n- Return enough evidence for Reviewer to reproduce the validation path.\n";