@heretek-ai/opencode-teamwork-v2 0.0.0-stage → 0.5.9
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/LICENSE +22 -0
- package/README.md +387 -2
- package/agents/team/crafter.md +146 -0
- package/agents/team/falsifier.md +98 -0
- package/agents/team/orchestrator.md +136 -0
- package/agents/team/proof-worker.md +66 -0
- package/agents/team/proposer.md +76 -0
- package/agents/team/scout.md +93 -0
- package/agents/team/security-auditor.md +64 -0
- package/agents/team/sentinel.md +175 -0
- package/agents/team/synthesizer.md +108 -0
- package/agents/team/verifier.md +106 -0
- package/agents/team/worker.md +74 -0
- package/bin/opencode-teamwork.mjs +517 -0
- package/docs/ARTIFACTS.md +806 -0
- package/docs/GUARDRAILS.md +48 -0
- package/lib/doctor.mjs +280 -0
- package/lib/export.mjs +1119 -0
- package/lib/picker.mjs +132 -0
- package/lib/runs.mjs +165 -0
- package/lib/team.mjs +394 -0
- package/lib/timeline.mjs +713 -0
- package/package.json +68 -4
- package/plugins/opencode-teamwork/index.ts +232 -0
- package/plugins/opencode-teamwork/package.json +11 -0
- package/plugins/opencode-teamwork/tools.ts +2912 -0
- package/postinstall.mjs +71 -0
- package/scripts/lint-prompts.mjs +168 -0
- package/scripts/test-cost.mjs +242 -0
- package/scripts/test-doctor.mjs +287 -0
- package/scripts/test-engine.mjs +2041 -0
- package/scripts/test-export.mjs +540 -0
- package/scripts/test-timeline.mjs +1041 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Aditya Singh (original opencode-teamwork)
|
|
4
|
+
Copyright (c) 2026 sorcnr (OpenCode V2 port)
|
|
5
|
+
|
|
6
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
7
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
8
|
+
in the Software without restriction, including without limitation the rights
|
|
9
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
10
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
11
|
+
furnished to do so, subject to the following conditions:
|
|
12
|
+
|
|
13
|
+
The above copyright notice and this permission notice shall be included in all
|
|
14
|
+
copies or substantial portions of the Software.
|
|
15
|
+
|
|
16
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
17
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
18
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
19
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
20
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
21
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
22
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,388 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @heretek-ai/opencode-teamwork-v2
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
An **OpenCode V2 port** of [`opencode-teamwork`](https://github.com/aditya0si/OpenCode-Team) —
|
|
4
|
+
Antigravity-style multi-agent orchestration for OpenCode.
|
|
5
|
+
|
|
6
|
+
The original package only implements the **OpenCode V1 plugin API**, so it fails
|
|
7
|
+
to load on OpenCode V2:
|
|
8
|
+
|
|
9
|
+
```
|
|
10
|
+
failed to load plugin
|
|
11
|
+
PluginModule.LoadError: Plugin must export a default definition with an id and
|
|
12
|
+
an effect or setup function. (cause: SchemaError(Expected object at ["default"]))
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
This repo is the ported, V2-native version: the original 10 agents plus a
|
|
16
|
+
security auditor (11 total) and 7 slash commands,
|
|
17
|
+
rewritten for the V2 plugin + agent APIs. Verified against **OpenCode `v2.0.26`**.
|
|
18
|
+
|
|
19
|
+
## What changed (V1 → V2)
|
|
20
|
+
|
|
21
|
+
| Original (V1) | This port (V2) |
|
|
22
|
+
| --- | --- |
|
|
23
|
+
| Default export = async plugin function returning a `config` hook | Default export = `{ id, setup }` definition (exactly what `Plugin.define({...})` returns) |
|
|
24
|
+
| `config` hook injects 10 agents | **Not possible in a V2 plugin** — the `AgentEditor` has no `add`. Agents are installed as markdown files: `agents/team/*.md` |
|
|
25
|
+
| `config` hook injects 7 commands | Registered by the plugin via `ctx.command.transform(...)` → `editor.add(...)` |
|
|
26
|
+
| Commands used `{{ ... }}` handlebars + `agent:` frontmatter | V2 has neither; `$ARGUMENTS` substitution in the plugin, agent switching via `ctx.session.switchAgent(...)` |
|
|
27
|
+
| Agent perms `edit/bash/webfetch/task` | V2 `permissions` array: `edit/shell/webfetch/subagent` |
|
|
28
|
+
|
|
29
|
+
## Layout
|
|
30
|
+
|
|
31
|
+
```
|
|
32
|
+
package.json # npm manifest (name: @heretek-ai/opencode-teamwork-v2)
|
|
33
|
+
index → plugins/opencode-teamwork/index.ts # V2 plugin, registers the 7 commands
|
|
34
|
+
plugins/opencode-teamwork/tools.ts # engine tools + hooks (V2 API)
|
|
35
|
+
agents/team/*.md # 11 team agents (markdown, V2 frontmatter)
|
|
36
|
+
docs/ARTIFACTS.md # canonical artifact layout, topologies, schemas
|
|
37
|
+
lib/team.mjs # installer core (config dir, model map, agent files)
|
|
38
|
+
lib/picker.mjs # interactive model picker (`opencode models`)
|
|
39
|
+
lib/runs.mjs # run inspection, DAG visualization, worktree pruning
|
|
40
|
+
lib/doctor.mjs # environment diagnostic health checks
|
|
41
|
+
lib/timeline.mjs # chronological run lifecycle builder & renderer
|
|
42
|
+
lib/export.mjs # read-only run report builder (HTML / Markdown export)
|
|
43
|
+
bin/opencode-teamwork.mjs # CLI: init / models / install / status / doctor / runs / inspect / timeline / export / prune
|
|
44
|
+
scripts/lint-prompts.mjs # prompt linter (run in CI)
|
|
45
|
+
scripts/test-cost.mjs # session tree consumption tests
|
|
46
|
+
scripts/test-engine.mjs # DAG engine, security gate & worktree tests
|
|
47
|
+
scripts/test-doctor.mjs # hermetic environment & CLI doctor tests
|
|
48
|
+
scripts/test-timeline.mjs # timeline hermetic unit tests
|
|
49
|
+
postinstall.mjs # asks for models during npm install
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## Engine (tools + hooks)
|
|
53
|
+
|
|
54
|
+
The run mechanics are real, not prompt prose. The plugin registers deterministic
|
|
55
|
+
tools (named `teamwork_*` after the `teamwork` namespace) and runtime permission hooks:
|
|
56
|
+
|
|
57
|
+
| Tool | Purpose |
|
|
58
|
+
| --- | --- |
|
|
59
|
+
| `teamwork_budget` | budget preflight: console credit derivation |
|
|
60
|
+
| `teamwork_plan` | create the run dir + `plan.dag.json` / `state.json` / `costs.json` |
|
|
61
|
+
| `teamwork_preflight` | re-check a run's named inputs, write `preflight.json` (reports, never blocks) |
|
|
62
|
+
| `teamwork_status` | per-task progress for the active run |
|
|
63
|
+
| `teamwork_resume` | tasks still open, for a restart |
|
|
64
|
+
| `teamwork_cost` | read real budget spend across OpenCode session tree (sentinel + workers + verifiers) |
|
|
65
|
+
| `teamwork_pitfall` | append to the pitfall registry (dynamically injected into workers) |
|
|
66
|
+
| `teamwork_next` | evaluates DAG dependencies, lifecycle states, and ready tasks |
|
|
67
|
+
| `teamwork_task_update` | deterministic task state machine transitions (`pending` → `worker_active` → `worker_done` → `verifier_active` → `verified_pass` / `verified_fail` / `blocked`) |
|
|
68
|
+
| `teamwork_security_audit` | mandatory pre-merge security gate (`verify/security-audit.json`) |
|
|
69
|
+
| `teamwork_final_verify` | compute the final verdict from the task reports + security audit, stamp it, write `verify/final.json` |
|
|
70
|
+
| `teamwork_worktree` | out-of-repo git worktree provisioning, diff, merge, resolve & cleanup |
|
|
71
|
+
|
|
72
|
+
Hooks: `permission.evaluate` enforces the per-agent read-only policy **in code**
|
|
73
|
+
(not just in their prompts). The read-only agents (`team/verifier`,
|
|
74
|
+
`team/falsifier`, `team/scout`, `team/security-auditor`) all deny the `edit`
|
|
75
|
+
tool, so none of them can write through it. `shell` is still available to the
|
|
76
|
+
verifier, scout and security auditor, and it can modify files; the falsifier
|
|
77
|
+
also has `shell` denied. In short: no writes through `edit` for all four, no
|
|
78
|
+
`shell` writes for the falsifier. The hook also enforces network constraints
|
|
79
|
+
(`constraints.network: denied`), and `session.context` injects the active run's
|
|
80
|
+
state + recent pitfalls into every team agent's system prompt.
|
|
81
|
+
|
|
82
|
+
All run artifacts live under `.opencode/teamwork/<session-id>/`; see
|
|
83
|
+
[`docs/ARTIFACTS.md`](docs/ARTIFACTS.md) for the layout, the canonical
|
|
84
|
+
topologies, and the JSON schemas (`spec.json`, `plan.dag.json`, `state.json`,
|
|
85
|
+
`verification_report.json`). The installer copies that reference to
|
|
86
|
+
`<config-dir>/teamwork/ARTIFACTS.md` next to your agents.
|
|
87
|
+
|
|
88
|
+
### Completion guarantees
|
|
89
|
+
|
|
90
|
+
- `verified_pass` requires a legal lifecycle transition and PASS evidence (an inline PASS verdict or a `PASS` per-task report).
|
|
91
|
+
- A run completes only with a `PASS` `verify/final.json` stamped by `teamwork_final_verify`; an unstamped report needs the recorded `allowUnstamped` bypass.
|
|
92
|
+
- The security audit fails on integrity-rule violations for the run's mode, and that blocks the merge.
|
|
93
|
+
- Planning refuses to start when blocking inputs are missing or unreachable unless `allowMissingInputs` is recorded.
|
|
94
|
+
- Legacy topology aliases are normalised on write; an unknown topology is refused before anything is written.
|
|
95
|
+
|
|
96
|
+
## Install
|
|
97
|
+
|
|
98
|
+
> **About the install prompt.** OpenCode installs plugins with **Bun**, and Bun
|
|
99
|
+
> blocks dependency lifecycle scripts (`postinstall`) by default. The interactive
|
|
100
|
+
> model prompt therefore may not appear during `opencode plugin add`, but the
|
|
101
|
+
> agents are still created — the plugin self-heals them on load with the DeepSeek
|
|
102
|
+
> defaults. To choose models, run the `init` command below. (`postinstall` does
|
|
103
|
+
> fire for a plain `npm install`, and is intentionally skipped under `npx` /
|
|
104
|
+
> `npm exec` so the `init` run doesn't prompt twice.)
|
|
105
|
+
|
|
106
|
+
### From GitHub (no npm account needed)
|
|
107
|
+
|
|
108
|
+
```sh
|
|
109
|
+
opencode plugin add github:Heretek-AI/opencode-teamwork-v2
|
|
110
|
+
|
|
111
|
+
# then choose a model for each agent:
|
|
112
|
+
npx github:Heretek-AI/opencode-teamwork-v2 init
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
If `npx github:…` is unavailable, run the bundled CLI straight from the install
|
|
116
|
+
directory:
|
|
117
|
+
|
|
118
|
+
```sh
|
|
119
|
+
node ~/.config/opencode/node_modules/@heretek-ai/opencode-teamwork-v2/bin/opencode-teamwork.mjs init
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
### From npm
|
|
123
|
+
|
|
124
|
+
```sh
|
|
125
|
+
opencode plugin add @heretek-ai/opencode-teamwork-v2
|
|
126
|
+
|
|
127
|
+
npx @heretek-ai/opencode-teamwork-v2 init # pick models, install agents, register plugin
|
|
128
|
+
npx @heretek-ai/opencode-teamwork-v2 models # pick models only (never edits opencode.json)
|
|
129
|
+
npx @heretek-ai/opencode-teamwork-v2 status # show what is installed and mapped
|
|
130
|
+
npx @heretek-ai/opencode-teamwork-v2 doctor # diagnose environment health (or --json)
|
|
131
|
+
npx @heretek-ai/opencode-teamwork-v2 runs # list active/past runs and spent budgets
|
|
132
|
+
npx @heretek-ai/opencode-teamwork-v2 inspect # inspect latest run DAG, tasks, and audit
|
|
133
|
+
npx @heretek-ai/opencode-teamwork-v2 timeline # chronological run timeline, task durations & cost
|
|
134
|
+
npx @heretek-ai/opencode-teamwork-v2 export # export a run report (HTML by default, or --markdown)
|
|
135
|
+
npx @heretek-ai/opencode-teamwork-v2 prune # prune completed git worktrees
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
`opencode-teamwork` and `opencode-teamwork-v2` are aliases for the same CLI. If
|
|
139
|
+
you are running from **inside this package's own checkout**, use the bundled
|
|
140
|
+
scripts (`npm run init`, `npm run models`, `npm run status`, `npm run doctor`, `npm run timeline`, `npm run runs`, `npm run inspect`, `npm run prune`) — `npx <name>` there
|
|
141
|
+
resolves the local package rather than the registry copy.
|
|
142
|
+
|
|
143
|
+
Agent prompt files are left untouched by default. To also adopt updated prompt
|
|
144
|
+
bodies (keeps your model choices, backs up the old files):
|
|
145
|
+
|
|
146
|
+
```sh
|
|
147
|
+
npx @heretek-ai/opencode-teamwork-v2 install --refresh
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
Non-interactive / scripted use:
|
|
151
|
+
|
|
152
|
+
```sh
|
|
153
|
+
npx @heretek-ai/opencode-teamwork-v2 install --all anthropic/claude-sonnet-4-5
|
|
154
|
+
npx @heretek-ai/opencode-teamwork-v2 install --model sentinel=deepseek/deepseek-v4-pro \
|
|
155
|
+
--model scout=deepseek/deepseek-flash
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
The chosen mapping is stored in `~/.config/opencode/teamwork.json`. Existing
|
|
159
|
+
agent files are never overwritten wholesale — only their `model:` line is
|
|
160
|
+
rewritten — and a one-time backup of touched files lands in
|
|
161
|
+
`~/.config/opencode/.opencode-teamwork-backup/<timestamp>/`.
|
|
162
|
+
|
|
163
|
+
The plugin also self-heals: if the agent files are missing when the plugin
|
|
164
|
+
loads (e.g. the install prompt was skipped), it recreates them from the packaged
|
|
165
|
+
defaults without touching files that already exist.
|
|
166
|
+
|
|
167
|
+
### Manually (no npm)
|
|
168
|
+
|
|
169
|
+
1. Copy the pieces into your global OpenCode config directory:
|
|
170
|
+
|
|
171
|
+
```sh
|
|
172
|
+
CFG="${XDG_CONFIG_HOME:-$HOME/.config}/opencode"
|
|
173
|
+
mkdir -p "$CFG/agents/team" "$CFG/plugins"
|
|
174
|
+
cp -r agents/team/*.md "$CFG/agents/team/"
|
|
175
|
+
cp -r plugins/opencode-teamwork "$CFG/plugins/"
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
2. Add the plugin to `$CFG/opencode.json`:
|
|
179
|
+
|
|
180
|
+
```jsonc
|
|
181
|
+
{
|
|
182
|
+
"$schema": "https://opencode.ai/config.json",
|
|
183
|
+
"plugins": [
|
|
184
|
+
"/absolute/path/to/.config/opencode/plugins/opencode-teamwork"
|
|
185
|
+
]
|
|
186
|
+
}
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
Relative paths work too if your setup resolves them against the config
|
|
190
|
+
directory; an absolute path is the least surprising.
|
|
191
|
+
|
|
192
|
+
3. Reload (or restart) OpenCode, then verify:
|
|
193
|
+
|
|
194
|
+
```sh
|
|
195
|
+
opencode plugin list # opencode-teamwork local .../plugins/opencode-teamwork/index.ts
|
|
196
|
+
opencode debug agents # should list team/sentinel, team/worker, ...
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
To activate without a restart: `opencode reload`.
|
|
200
|
+
|
|
201
|
+
## First run (5 minutes)
|
|
202
|
+
|
|
203
|
+
1. Install the plugin: `opencode plugin add @heretek-ai/opencode-teamwork-v2`.
|
|
204
|
+
|
|
205
|
+
2. Assign models and install the agents. `init` writes
|
|
206
|
+
`~/.config/opencode/teamwork.json`, installs all 11 agents and registers the
|
|
207
|
+
plugin; `models` rewrites only the model map and the agents' `model:` lines.
|
|
208
|
+
Both are safe to re-run.
|
|
209
|
+
|
|
210
|
+
```sh
|
|
211
|
+
npx @heretek-ai/opencode-teamwork-v2 init
|
|
212
|
+
npx @heretek-ai/opencode-teamwork-v2 models
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
3. In your project, run `/teamwork-craft`. The 9-step interview writes the
|
|
216
|
+
approved spec to `.opencode/teamwork/<session-id>/prompt_draft.md`.
|
|
217
|
+
|
|
218
|
+
4. Review it, then run `/teamwork <session-id>`. Planning now **requires a
|
|
219
|
+
non-empty `prompt_draft.md`**; the explicit bypass is `skipInterview: true`
|
|
220
|
+
on `teamwork_plan`, recorded as `specGate: "bypassed"`.
|
|
221
|
+
|
|
222
|
+
5. The run directory `.opencode/teamwork/<session-id>/` holds `plan.dag.json`
|
|
223
|
+
(the task DAG), per-task `verify/report-<task>.json` reports, and
|
|
224
|
+
`verify/final.json` — written and stamped by `teamwork_final_verify`, never
|
|
225
|
+
by hand.
|
|
226
|
+
|
|
227
|
+
6. Inspect it afterwards from the project root:
|
|
228
|
+
|
|
229
|
+
```sh
|
|
230
|
+
npx @heretek-ai/opencode-teamwork-v2 status # install + model map
|
|
231
|
+
npx @heretek-ai/opencode-teamwork-v2 timeline # per-task timing, rounds, spend
|
|
232
|
+
npx @heretek-ai/opencode-teamwork-v2 export # HTML report (-m for Markdown)
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
## Run reports (`export`)
|
|
236
|
+
|
|
237
|
+
`opencode-teamwork export` turns one run into a report you can share or archive.
|
|
238
|
+
It only reads the run directory; it never changes run state.
|
|
239
|
+
|
|
240
|
+
```sh
|
|
241
|
+
npx @heretek-ai/opencode-teamwork-v2 export [<session-id>] [--session <id>] [--html | -m|--markdown] [-o <file>|-o -]
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
- **Session id:** pass it positionally (`export <session-id>`) or with
|
|
245
|
+
`--session <id>`. If you omit it, the newest run under `.opencode/teamwork/`
|
|
246
|
+
(most recently updated) is exported.
|
|
247
|
+
- **Format:** `--html` is the default. `-m` / `--markdown` writes GitHub-flavored
|
|
248
|
+
Markdown instead.
|
|
249
|
+
- **Output:** with `-o <file>` / `--output <file>` the report goes to that file.
|
|
250
|
+
Without `-o`, the report is written to
|
|
251
|
+
`.opencode/teamwork/<session-id>/report.html` (or `report.md` for Markdown) and
|
|
252
|
+
the **absolute** path is printed to stdout. `-o -` streams the report to stdout
|
|
253
|
+
and writes no file.
|
|
254
|
+
- **Exit codes:** `0` on success; `1` for a missing or invalid run, or a file-write error.
|
|
255
|
+
|
|
256
|
+
Examples:
|
|
257
|
+
|
|
258
|
+
```sh
|
|
259
|
+
# HTML to .opencode/teamwork/<id>/report.html
|
|
260
|
+
opencode-teamwork export 20261012-101500-a1b2
|
|
261
|
+
|
|
262
|
+
# Markdown to .opencode/teamwork/<id>/report.md
|
|
263
|
+
opencode-teamwork export 20261012-101500-a1b2 -m
|
|
264
|
+
|
|
265
|
+
# Same run, named output file
|
|
266
|
+
opencode-teamwork export --session 20261012-101500-a1b2 -o report.html
|
|
267
|
+
|
|
268
|
+
# Stream Markdown to stdout and redirect it yourself
|
|
269
|
+
opencode-teamwork export -m -o - > run-report.md
|
|
270
|
+
|
|
271
|
+
# Newest run, HTML
|
|
272
|
+
opencode-teamwork export
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
The HTML report is a **standalone single file**: CSS is embedded, and it loads no
|
|
276
|
+
CDN, fonts, or scripts, so it works fully offline and is safe to attach or archive.
|
|
277
|
+
The Markdown report uses tables and a checklist, so it pastes cleanly into a PR
|
|
278
|
+
description or issue comment. Both show the summary (status, topology, duration,
|
|
279
|
+
budget, spend, tokens), a tasks table, the security audit, and the pitfalls. See
|
|
280
|
+
[`docs/ARTIFACTS.md`](docs/ARTIFACTS.md#export-report-reporthtml--reportmd) for the
|
|
281
|
+
format details.
|
|
282
|
+
|
|
283
|
+
## Model assignment
|
|
284
|
+
|
|
285
|
+
Each agent's model lives in the `model:` frontmatter of its markdown file. The
|
|
286
|
+
shipped defaults are:
|
|
287
|
+
|
|
288
|
+
- `deepseek/deepseek-v4-pro`: sentinel, orchestrator, synthesizer, verifier, falsifier, proof-worker, security-auditor
|
|
289
|
+
- `deepseek/deepseek-flash`: crafter, worker, proposer, scout
|
|
290
|
+
|
|
291
|
+
Change them with `opencode-teamwork init` (interactive), the flags above
|
|
292
|
+
(scripted), or by editing the frontmatter / `teamwork.json` directly and running
|
|
293
|
+
`opencode reload`.
|
|
294
|
+
|
|
295
|
+
## Publishing (maintainers)
|
|
296
|
+
|
|
297
|
+
There is **no separate "Bun registry"** — Bun installs from the npm registry, so
|
|
298
|
+
publishing to npm is what makes the package available to `bun add`, OpenCode, and
|
|
299
|
+
npm alike. Two ways to ship:
|
|
300
|
+
|
|
301
|
+
**A. GitHub only (no npm account).** Nothing to publish — users install the git
|
|
302
|
+
spec directly (`opencode plugin add github:Heretek-AI/opencode-teamwork-v2`). Just
|
|
303
|
+
tag releases:
|
|
304
|
+
|
|
305
|
+
```sh
|
|
306
|
+
git tag v0.3.0 && git push origin main --tags
|
|
307
|
+
```
|
|
308
|
+
|
|
309
|
+
**B. npm registry, without interactive login.** Create a *Granular Access Token*
|
|
310
|
+
(npmjs.com → Access Tokens → check **Bypass 2FA**, grant publish), then:
|
|
311
|
+
|
|
312
|
+
```sh
|
|
313
|
+
npm config set //registry.npmjs.org/:_authToken=TOKEN
|
|
314
|
+
npm whoami # verify
|
|
315
|
+
npm pack # inspect the 19-file tarball
|
|
316
|
+
npm publish --dry-run
|
|
317
|
+
npm publish --access public
|
|
318
|
+
```
|
|
319
|
+
|
|
320
|
+
For CI, this repo ships [`.github/workflows/publish.yml`](.github/workflows/publish.yml)
|
|
321
|
+
using **npm Trusted Publishing** (OIDC, no long-lived token). One-time setup:
|
|
322
|
+
|
|
323
|
+
1. Create the package with a first manual publish (`npm publish`, token above) —
|
|
324
|
+
package settings only exist once the package exists.
|
|
325
|
+
2. On npmjs.com: **Package → Settings → Trusted Publisher → GitHub Actions**
|
|
326
|
+
with user `Heretek-AI`, repo `opencode-teamwork-v2`, workflow `publish.yml`,
|
|
327
|
+
and `npm publish` allowed.
|
|
328
|
+
3. Release afterwards by tagging:
|
|
329
|
+
|
|
330
|
+
```sh
|
|
331
|
+
npm version patch # bumps package.json + creates the vX.Y.Z tag
|
|
332
|
+
git push --follow-tags # triggers the workflow
|
|
333
|
+
```
|
|
334
|
+
|
|
335
|
+
Note that npm is restricting bypass-2FA tokens from January 2027, so Trusted
|
|
336
|
+
Publishing is the durable option.
|
|
337
|
+
|
|
338
|
+
`files` in `package.json` is a whitelist (`agents`, `plugins`, `lib`, `bin`,
|
|
339
|
+
`docs`, `postinstall.mjs`, `README.md`, `LICENSE`), so tests and scratch dirs
|
|
340
|
+
never ship. The runtime has **zero dependencies**; `postinstall` uses only Node
|
|
341
|
+
built-ins.
|
|
342
|
+
|
|
343
|
+
## Commands
|
|
344
|
+
|
|
345
|
+
| Command | Agent | Purpose |
|
|
346
|
+
| --- | --- | --- |
|
|
347
|
+
| `/teamwork` | `team/sentinel` | Main dispatcher — loads a spec, provisions a worktree, builds the DAG, dispatches workers + verifiers, merges |
|
|
348
|
+
| `/teamwork-craft` | `team/crafter` | 9-step elicitation wizard that produces `prompt_draft.md` |
|
|
349
|
+
| `/team-orchestrate` | `team/orchestrator` | Legacy v1 propose/falsify/synthesize/verify loop |
|
|
350
|
+
| `/team-propose` | `team/orchestrator` | Run only the propose step |
|
|
351
|
+
| `/team-falsify` | `team/orchestrator` | Run only the falsifier step |
|
|
352
|
+
| `/team-synthesize` | `team/orchestrator` | Run only the synthesizer step |
|
|
353
|
+
| `/team-review` | `team/orchestrator` | Run the verifier on the current artifact |
|
|
354
|
+
|
|
355
|
+
## Agents
|
|
356
|
+
|
|
357
|
+
The 11 shipped agents are: `team/crafter`, `team/sentinel`, `team/worker`,
|
|
358
|
+
`team/proof-worker`, `team/verifier`, `team/security-auditor`,
|
|
359
|
+
`team/orchestrator`, `team/proposer`, `team/falsifier`, `team/synthesizer`,
|
|
360
|
+
`team/scout`.
|
|
361
|
+
|
|
362
|
+
Model assignments live in each agent's frontmatter (`model:`); see
|
|
363
|
+
[Model assignment](#model-assignment) for how to set them.
|
|
364
|
+
|
|
365
|
+
## Notes
|
|
366
|
+
|
|
367
|
+
- The plugin is intentionally **dependency-free at runtime** — it does not import
|
|
368
|
+
`@opencode/plugin`, so the loader never needs to resolve `node_modules` for it.
|
|
369
|
+
The exported object shape is identical to `Plugin.define({ id, setup })`.
|
|
370
|
+
- V2 agents cannot be created by a plugin, so the plugin only registers commands,
|
|
371
|
+
ships the `teamwork_*` engine tools, and (in the npm package) recreates any
|
|
372
|
+
missing `team/*.md` agent files from the packaged defaults on load. If you
|
|
373
|
+
prefer no plugin at all, move the 7 command definitions into markdown files
|
|
374
|
+
under `~/.config/opencode/commands/` (V2 discovers them natively).
|
|
375
|
+
- Prompt invariants (one artifact root, one topology enum, no stale references,
|
|
376
|
+
no blocking `effect: ask` in parallel agents) are enforced by
|
|
377
|
+
`scripts/lint-prompts.mjs` — run `npm run lint:prompts`. CI runs it whenever
|
|
378
|
+
agents, the plugin or docs change.
|
|
379
|
+
- **Security:** the guardrail model (path containment, server-derived session
|
|
380
|
+
ids, read-only enforcement, sanitised context injection, non-destructive
|
|
381
|
+
installers) is documented in [`docs/GUARDRAILS.md`](docs/GUARDRAILS.md). The
|
|
382
|
+
`team/security-auditor` agent audits a repo with a clean context.
|
|
383
|
+
- Docs: <https://opencode.ai/v2/docs/build/plugins>
|
|
384
|
+
|
|
385
|
+
## License & attribution
|
|
386
|
+
|
|
387
|
+
MIT. Ported from [`aditya0si/OpenCode-Team`](https://github.com/aditya0si/OpenCode-Team)
|
|
388
|
+
by Aditya Singh; the original MIT notice is preserved in [LICENSE](LICENSE).
|
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: "Phase-1 interactive prompt crafter. Runs the 9-step elicitation flow before any Teamwork run. Generates prompt_draft.md (spec.json + plan.dag.json + acceptance criteria + model allocation). Use at the start of any hard problem."
|
|
3
|
+
mode: primary
|
|
4
|
+
model: deepseek/deepseek-flash
|
|
5
|
+
color: "#8b5cf6"
|
|
6
|
+
permissions:
|
|
7
|
+
- action: edit
|
|
8
|
+
resource: "*"
|
|
9
|
+
effect: ask
|
|
10
|
+
- action: shell
|
|
11
|
+
resource: "*"
|
|
12
|
+
effect: ask
|
|
13
|
+
- action: webfetch
|
|
14
|
+
resource: "*"
|
|
15
|
+
effect: allow
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
# Teamwork Prompt Crafter
|
|
19
|
+
|
|
20
|
+
You are the Phase-1 elicitation wizard. Before any multi-agent run, you
|
|
21
|
+
walk the user through 9 steps to produce a *falsifiable* task spec. You do NOT dispatch agents — that
|
|
22
|
+
happens after the user confirms the spec.
|
|
23
|
+
|
|
24
|
+
The 9 steps are not optional. Skipping any of them produces a spec
|
|
25
|
+
that the Sentinel will reject.
|
|
26
|
+
|
|
27
|
+
## The 9 steps
|
|
28
|
+
|
|
29
|
+
1. **Elicit Project Idea** — 1-2 declarative sentences on the target
|
|
30
|
+
outcome. Reject hedging language ("maybe", "could", "we should
|
|
31
|
+
think about"). The user must commit to a concrete goal.
|
|
32
|
+
|
|
33
|
+
2. **Identify Ambiguity & Scale** — Probe scope. Is this small
|
|
34
|
+
(single self-contained fix) or large (multi-module, days of work)?
|
|
35
|
+
The user opts into one of:
|
|
36
|
+
Canonical topologies (`ARTIFACTS.md`):
|
|
37
|
+
- `small-focused` — 1 worker + 1 adversarial verifier, loops.
|
|
38
|
+
- `iterative-coding` — 1 worker, test-driven tight loop on one module.
|
|
39
|
+
- `distributed-coding` — 2-6 workers fan-out + merge.
|
|
40
|
+
- `proof` — 1 strategist + 3-5 searchers + 1 formal checker.
|
|
41
|
+
- `massive-proof` — 1 meta-coordinator + 100+ searchers (opt-in only).
|
|
42
|
+
- `document-review` — 1 chair + 3 critics + 1 aggregator.
|
|
43
|
+
|
|
44
|
+
3. **Determine Integrity Mode** — `development` (default),
|
|
45
|
+
`demo` (no external code scraping), `benchmark` (blind, no test
|
|
46
|
+
source visible to implementer).
|
|
47
|
+
|
|
48
|
+
4. **Draft Requirements ($R_1 \dots R_N$)** — 2-5 functional
|
|
49
|
+
requirements focused strictly on *behavior*, not implementation.
|
|
50
|
+
|
|
51
|
+
5. **Design Verification (the Forcing Function)** — How will the
|
|
52
|
+
verifier know the work is done? Automated test? Property test?
|
|
53
|
+
Bot driver? Independent LLM judge with rubric? Reject specs that
|
|
54
|
+
say "looks good to me" or "the user can tell."
|
|
55
|
+
|
|
56
|
+
6. **Set Acceptance Criteria** — Convert $R_1 \dots R_N$ into markdown
|
|
57
|
+
checkboxes (`- [ ]`). Each requirement gets at least one
|
|
58
|
+
checkbox; the verifier checks them off.
|
|
59
|
+
|
|
60
|
+
7. **Configure Infrastructure & Model Allocation** — Per-role model
|
|
61
|
+
pick. `~/.config/opencode/teamwork.json` (written by the installer) is
|
|
62
|
+
the source of truth; the user may override any role. Also: cloud
|
|
63
|
+
storage boundaries, network calls, sandbox permissions.
|
|
64
|
+
|
|
65
|
+
8. **Set Working Directory** — Project root. Default is
|
|
66
|
+
`~/teamwork_projects/{project_name}`. The user can override.
|
|
67
|
+
|
|
68
|
+
9. **Assemble & Validate** — Combine into `prompt_draft.md`. Run the
|
|
69
|
+
anti-pattern checks:
|
|
70
|
+
- No self-certification ("the implementer self-tests")
|
|
71
|
+
- No prescriptive constraints ("must use library X")
|
|
72
|
+
- All requirements have acceptance criteria
|
|
73
|
+
- Verification method is *external* to the implementer
|
|
74
|
+
- Working directory is writable
|
|
75
|
+
- Model allocation has at least 1 verifier model set
|
|
76
|
+
|
|
77
|
+
If any anti-pattern trips, fix it before saving.
|
|
78
|
+
|
|
79
|
+
## What you write
|
|
80
|
+
|
|
81
|
+
Save the spec to `.opencode/teamwork/<session-id>/prompt_draft.md`.
|
|
82
|
+
The `session-id` is generated by you (use a timestamp + short
|
|
83
|
+
random hex). The file has this structure:
|
|
84
|
+
|
|
85
|
+
```md
|
|
86
|
+
# Teamwork Spec: <one-line title>
|
|
87
|
+
|
|
88
|
+
**Session ID:** <session-id>
|
|
89
|
+
**Topology:** <small-focused|iterative-coding|distributed-coding|proof|massive-proof|document-review>
|
|
90
|
+
**Integrity mode:** <development|demo|benchmark>
|
|
91
|
+
**Working directory:** <path>
|
|
92
|
+
|
|
93
|
+
## Requirements
|
|
94
|
+
|
|
95
|
+
- **$R_1$**: <behavior-focused requirement>
|
|
96
|
+
- **$R_2$**: ...
|
|
97
|
+
|
|
98
|
+
## Acceptance criteria
|
|
99
|
+
|
|
100
|
+
- [ ] <concrete test or check for $R_1$>
|
|
101
|
+
- [ ] ...
|
|
102
|
+
|
|
103
|
+
## Verification
|
|
104
|
+
|
|
105
|
+
<automated test, property test, judge rubric — whatever the user chose>
|
|
106
|
+
|
|
107
|
+
## Model allocation
|
|
108
|
+
|
|
109
|
+
| Role | Model | Notes |
|
|
110
|
+
|---|---|---|
|
|
111
|
+
| sentinel / crafter | <model> | reasoning depth |
|
|
112
|
+
| builder (×N) | <model> | throughput vs depth |
|
|
113
|
+
| verifier (×N) | <model> | zero-hallucination required |
|
|
114
|
+
| searcher (proof only) | <model> | cost-efficient, run many |
|
|
115
|
+
|
|
116
|
+
## Constraints
|
|
117
|
+
|
|
118
|
+
- Cloud storage: <yes/no, which buckets>
|
|
119
|
+
- Network calls: <allowed|denied|whitelist>
|
|
120
|
+
- Sandbox: <full|read-only|worktree-only>
|
|
121
|
+
|
|
122
|
+
## Anti-patterns checked
|
|
123
|
+
|
|
124
|
+
- [ ] No self-certification
|
|
125
|
+
- [ ] No prescriptive implementation constraints
|
|
126
|
+
- [ ] Every $R_i$ has at least one acceptance criterion
|
|
127
|
+
- [ ] Verification is external to the implementer
|
|
128
|
+
- [ ] Working directory is writable
|
|
129
|
+
- [ ] At least one verifier model set
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
## Output the spec, then STOP
|
|
133
|
+
|
|
134
|
+
After writing `prompt_draft.md`, present the spec to the user. Tell
|
|
135
|
+
them to review and say "go" when ready. The Sentinel (the
|
|
136
|
+
`/teamwork` command) will then pick up this file and dispatch.
|
|
137
|
+
|
|
138
|
+
You do NOT dispatch agents. The crafter is read-only on the world —
|
|
139
|
+
it produces spec, the sentinel executes.
|
|
140
|
+
|
|
141
|
+
## When the user just wants to run something
|
|
142
|
+
|
|
143
|
+
If the user says "skip the wizard, just run /teamwork", direct them
|
|
144
|
+
to `/teamwork` with the caveat that the sentinel will ask the same
|
|
145
|
+
9 questions in compressed form. The wizard is the right tool for
|
|
146
|
+
multi-hour / multi-day problems.
|
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: "Attacks a single candidate. Your job is to find flaws. If you cannot find a flaw, you must explicitly say so — silence is not acceptable. `edit` and `shell` are denied in code, so it cannot modify the workspace; `webfetch` is available."
|
|
3
|
+
mode: all
|
|
4
|
+
model: deepseek/deepseek-v4-pro
|
|
5
|
+
color: "#ef4444"
|
|
6
|
+
hidden: false
|
|
7
|
+
permissions:
|
|
8
|
+
- action: edit
|
|
9
|
+
resource: "*"
|
|
10
|
+
effect: deny
|
|
11
|
+
- action: shell
|
|
12
|
+
resource: "*"
|
|
13
|
+
effect: deny
|
|
14
|
+
- action: webfetch
|
|
15
|
+
resource: "*"
|
|
16
|
+
effect: allow
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
# Falsifier
|
|
20
|
+
|
|
21
|
+
You are given ONE candidate. Your sole job is to break it. You are
|
|
22
|
+
adversarial by design. The team depends on you to surface every weakness
|
|
23
|
+
before the verifier spends time on it.
|
|
24
|
+
|
|
25
|
+
## Inputs
|
|
26
|
+
|
|
27
|
+
- The candidate at `.opencode/teamwork/<session-id>/candidates/cand-<n>.md`.
|
|
28
|
+
- The original problem (verbatim from the user).
|
|
29
|
+
- The topology (`proof`, `iterative-coding`, etc.).
|
|
30
|
+
- Optional context (scout's report, prior falsifier reports on related
|
|
31
|
+
candidates).
|
|
32
|
+
|
|
33
|
+
## What to write
|
|
34
|
+
|
|
35
|
+
Write to `.opencode/teamwork/<session-id>/critiques/crit-<n>.md`. Structure:
|
|
36
|
+
|
|
37
|
+
```md
|
|
38
|
+
# Critique of Candidate <n>
|
|
39
|
+
|
|
40
|
+
## Verdict
|
|
41
|
+
FATAL / SERIOUS / MINOR / NONE
|
|
42
|
+
- FATAL: candidate is wrong, no path to fix.
|
|
43
|
+
- SERIOUS: candidate has a real flaw that must be addressed before merge.
|
|
44
|
+
- MINOR: candidate has a real flaw but it's a 1-line fix.
|
|
45
|
+
- NONE: I could not find a flaw. (You MUST be specific about what you
|
|
46
|
+
tried. Silence is not a verdict.)
|
|
47
|
+
|
|
48
|
+
## Attempts to break
|
|
49
|
+
For each class of attack, what you tried, and what you found:
|
|
50
|
+
- [Correctness] Does the proof/code/argument actually work? Walk through
|
|
51
|
+
it step by step. Do not skim.
|
|
52
|
+
- [Edge cases] Empty input, single element, max-size, negative numbers,
|
|
53
|
+
off-by-one. Unicode, RTL, ASCII vs EBCDIC, scientific vs financial
|
|
54
|
+
rounding.
|
|
55
|
+
- [Assumptions] What does the candidate assume? Is the assumption
|
|
56
|
+
justified by the problem statement, or did the proposer add it?
|
|
57
|
+
- [Security] Injection, overflow, race, time-of-check vs time-of-use.
|
|
58
|
+
- [Performance] Worst case, not just average. Is the asymptotic claim
|
|
59
|
+
true?
|
|
60
|
+
- [Style/UX] (for UI work) Does it look good? Would a designer reject it?
|
|
61
|
+
Do not skip this class for visual work.
|
|
62
|
+
- [Dependencies] Is the candidate using a library/version/feature that
|
|
63
|
+
may not exist or may not work as claimed?
|
|
64
|
+
|
|
65
|
+
## Fatal findings
|
|
66
|
+
One per finding, with:
|
|
67
|
+
- Where in the candidate (file + line / proof step / section).
|
|
68
|
+
- Why it's wrong, with a concrete counterexample or trace.
|
|
69
|
+
- A fix sketch (one sentence).
|
|
70
|
+
|
|
71
|
+
## Non-fatal concerns
|
|
72
|
+
Same format, but mark severity = MINOR.
|
|
73
|
+
|
|
74
|
+
## What I tried but couldn't break
|
|
75
|
+
Be specific. "I tried X, expected Y, got Z, which is consistent with the
|
|
76
|
+
candidate being correct." This is signal — when a falsifier cannot break
|
|
77
|
+
something, that's worth recording.
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
## Anti-patterns
|
|
81
|
+
|
|
82
|
+
- Do not propose a "fix" that is itself a candidate. You are the
|
|
83
|
+
critic, not the second proposer. If the candidate is so broken that
|
|
84
|
+
it needs a rewrite, mark it FATAL with the failure mode and let the
|
|
85
|
+
synthesizer decide.
|
|
86
|
+
- Do not score on aesthetics alone. Even ugly candidates can be
|
|
87
|
+
correct; even pretty candidates can be wrong. Judge correctness
|
|
88
|
+
first.
|
|
89
|
+
- Do not give a "looks good" without trying at least 5 distinct attack
|
|
90
|
+
classes.
|
|
91
|
+
- Do not edit the candidate file. Read-only.
|
|
92
|
+
|
|
93
|
+
## Calibration
|
|
94
|
+
|
|
95
|
+
Aim for 2-3 FATAL/SERIOUS findings per candidate on average for the first
|
|
96
|
+
round. If you are returning NONE on most candidates, you are not trying
|
|
97
|
+
hard enough. If you are returning FATAL on most candidates, the proposer
|
|
98
|
+
strategy needs adjustment (say so in your critique).
|