@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 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
- # Temporary Holding Version
1
+ # @heretek-ai/opencode-teamwork-v2
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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).