@snarkipus/opencode-beads 0.9.2 → 0.9.4
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/README.md +42 -75
- package/package.json +1 -1
- package/vendor/manifest.json +2 -2
package/README.md
CHANGED
|
@@ -2,124 +2,91 @@
|
|
|
2
2
|
|
|
3
3
|
[Beads](https://github.com/gastownhall/beads) issue tracker integration for [OpenCode](https://opencode.ai).
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
`@snarkipus/opencode-beads` is a maintained OpenCode adapter that provides full `bd prime` context injection, vendored `/beads:*` workflows, and a bounded task agent. It does not replace Beads: the installed `bd` CLI remains authoritative for issues, project initialization, skills, migrations, backups, and Dolt synchronization.
|
|
6
6
|
|
|
7
7
|
The project originated as [Josh Thomas's `opencode-beads`](https://github.com/joshuadavidthomas/opencode-beads) and continues under the MIT license. This fork is maintained by Matt Jackson and tracks reviewed upstream Beads releases while adapting their plugin artifacts to OpenCode's CLI-only execution model.
|
|
8
8
|
|
|
9
|
-
##
|
|
10
|
-
|
|
11
|
-
Install the `bd` CLI once on the host:
|
|
9
|
+
## Design
|
|
12
10
|
|
|
13
|
-
|
|
14
|
-
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash
|
|
15
|
-
```
|
|
11
|
+
The plugin's primary design is **context-preserving atomic delegation**:
|
|
16
12
|
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
```json
|
|
22
|
-
{
|
|
23
|
-
"plugin": ["@snarkipus/opencode-beads@0.9.2"]
|
|
24
|
-
}
|
|
25
|
-
```
|
|
13
|
+
- The primary OpenCode thread retains planning context, decisions, and control.
|
|
14
|
+
- `beads-task-agent` processes exactly one Bead per invocation, then closes, blocks, or returns.
|
|
15
|
+
- Without an external orchestrator, this intentionally trades broad autonomy for Bead atomicity and context preservation.
|
|
16
|
+
- An orchestrator may repeat `select → delegate one Bead → verify → select next`, but should not weaken the worker boundary.
|
|
26
17
|
|
|
27
|
-
|
|
18
|
+
## Installation
|
|
28
19
|
|
|
29
|
-
|
|
20
|
+
Install the [`bd` CLI](https://github.com/gastownhall/beads/blob/main/docs/getting-started/installation.md) once on the host, then initialize each project:
|
|
30
21
|
|
|
31
22
|
```bash
|
|
32
|
-
git init
|
|
23
|
+
git init # only when the directory is not already a Git worktree
|
|
33
24
|
bd init
|
|
34
25
|
```
|
|
35
26
|
|
|
36
|
-
|
|
27
|
+
`bd init` owns project initialization and creates the canonical shared Beads skill at `.agents/skills/beads`, which OpenCode discovers. This plugin has no separate skill lifecycle and does not write startup files.
|
|
37
28
|
|
|
38
|
-
|
|
29
|
+
Add the version-pinned plugin to `~/.config/opencode/opencode.json`:
|
|
39
30
|
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
31
|
+
```json
|
|
32
|
+
{
|
|
33
|
+
"plugin": ["@snarkipus/opencode-beads@0.9.4"]
|
|
34
|
+
}
|
|
44
35
|
```
|
|
45
36
|
|
|
46
|
-
|
|
37
|
+
Restart OpenCode. Update the pin explicitly when upgrading; an unpinned package entry is less reproducible.
|
|
47
38
|
|
|
48
|
-
|
|
39
|
+
### 0.9.3 recovery notice
|
|
49
40
|
|
|
50
|
-
|
|
51
|
-
scratch="$(mktemp -d)"
|
|
52
|
-
git -C "$scratch" init
|
|
53
|
-
(cd "$scratch" && bd init)
|
|
54
|
-
mkdir -p .agents/skills
|
|
55
|
-
cp -R "$scratch/.agents/skills/beads" .agents/skills/beads
|
|
56
|
-
rm -rf "$scratch"
|
|
57
|
-
```
|
|
41
|
+
Version 0.9.3 contained command guidance from the withdrawn upstream Beads v1.2.1 release. This plugin did not bundle the `bd` binary or implement database migrations, but it could invoke a consumer-installed v1.2.1 binary through `bd prime`. Even one v1.2.1 execution could migrate the database. Upgrade the plugin package to 0.9.4; if v1.2.1 was installed and may have run, also follow the [upstream database recovery guidance](https://github.com/gastownhall/beads/blob/v1.2.2/docs/RECOVERY-1.2.1.md).
|
|
58
42
|
|
|
59
|
-
|
|
43
|
+
## Context injection
|
|
60
44
|
|
|
61
|
-
|
|
45
|
+
The plugin runs full `bd prime` when a primary-agent session first receives a message and after compaction. Prime supplies the canonical current workflow, command guidance, and persistent memories; the plugin adds only compact OpenCode-specific safety and delegation guidance.
|
|
62
46
|
|
|
63
|
-
|
|
64
|
-
- **Commands** - Vendored Beads workflows available under the `/beads:*` namespace
|
|
65
|
-
- **Task agent** - Autonomous issue completion via `beads-task-agent` subagent
|
|
47
|
+
Known regular subagents remain excluded, including `explore` and `general`, while `beads-task-agent` remains eligible. If agent lookup fails, context injection fails open to preserve compatibility with unknown custom primary agents.
|
|
66
48
|
|
|
67
|
-
|
|
49
|
+
If `bd` is unavailable, the project is uninitialized, or prime fails or returns no content, injection is silently skipped and remains retryable. Vendored commands stay available, and the task agent retains a bounded standalone quick reference for `ready`, `show`, atomic claim, discovered follow-up, validate before closure, and close.
|
|
68
50
|
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
### Context behavior
|
|
51
|
+
## Commands
|
|
72
52
|
|
|
73
|
-
|
|
53
|
+
Vendored workflows are registered under `/beads:*`, including `/beads:ready`, `/beads:create`, and `/beads:show`. The plugin does not generate a command for every `bd` subcommand; use the CLI and the generated [Beads CLI reference](https://beads.gascity.com/cli-reference/index) for the complete surface.
|
|
74
54
|
|
|
75
|
-
|
|
55
|
+
Explicit command and agent definitions in OpenCode configuration take precedence over plugin definitions with the same name. Exact `beads:*` or `beads-task-agent` collisions produce a grouped, rate-limited warning without preventing non-conflicting definitions from loading.
|
|
76
56
|
|
|
77
|
-
##
|
|
57
|
+
## Task agent
|
|
78
58
|
|
|
79
|
-
|
|
59
|
+
`beads-task-agent` supports read-only status and graph analysis or one-Bead completion. Analysis requests never mutate Beads. Completion requests inspect and process one caller-selected or highest-priority ready Bead, quarantine work discovered during that invocation, validate before closure, and return after closing or blocking the selected Bead.
|
|
80
60
|
|
|
81
|
-
|
|
61
|
+
Its runtime prompt is a fork-owned bounded OpenCode adaptation. The vendored upstream task-agent artifact supplies metadata, provenance, and compatibility validation; it is not executed as upstream's autonomous multi-task loop.
|
|
82
62
|
|
|
83
|
-
##
|
|
63
|
+
## Vendored content
|
|
84
64
|
|
|
85
|
-
|
|
65
|
+
[`scripts/sync-beads.sh`](scripts/sync-beads.sh) copies the reviewed upstream command templates and task-agent artifact into `vendor/`. [`vendor/manifest.json`](vendor/manifest.json) pins the upstream tag and commit and records source paths, sorted inventory, byte lengths, and SHA-256 checksums. A deterministic adaptation layer translates reviewed host-specific instructions to OpenCode's CLI-only model.
|
|
86
66
|
|
|
87
|
-
|
|
67
|
+
Do not edit vendored files directly. Sync and package validation reject provenance, checksum, inventory, schema, or reviewed-transformation drift. Adapter behavior lives in `src/`; general Beads behavior and documentation remain upstream.
|
|
88
68
|
|
|
89
69
|
## Compatibility
|
|
90
70
|
|
|
91
|
-
The compatibility ranges and validated baselines for this release are:
|
|
92
|
-
|
|
93
71
|
| Component | Expected range | Validated baseline |
|
|
94
72
|
| --- | --- | --- |
|
|
95
73
|
| OpenCode | 1.18.3 through 1.x | 1.18.15 |
|
|
96
|
-
| `bd` CLI | 1.0.5 through 1.x | 1.
|
|
74
|
+
| `bd` CLI | 1.0.5 through 1.x | 1.2.2 |
|
|
97
75
|
| Bun | >=1.3.14 | 1.3.14 |
|
|
98
76
|
|
|
99
|
-
The
|
|
100
|
-
|
|
101
|
-
## Vendored Content
|
|
102
|
-
|
|
103
|
-
Files under `vendor/` are copied from the upstream Beads plugin by [`scripts/sync-beads.sh`](scripts/sync-beads.sh). The current inventory includes the complete upstream command-template directory and task agent, rather than a duplicate of the much larger `bd` CLI. [`vendor/manifest.json`](vendor/manifest.json) records the stable upstream tag and commit, source paths, sorted inventory, byte lengths, and SHA-256 checksums. A deterministic adaptation layer translates known MCP- or Claude-specific instructions to OpenCode's CLI-only model when prompts load; sync fails if provenance, checksums, inventory, or reviewed transformations differ. Do not edit vendored files directly: the next sync replaces them. Adapter behavior lives in `src/`, while general Beads behavior and documentation remain upstream.
|
|
104
|
-
|
|
105
|
-
The vendor manifest, task agent, and every recorded command file are required package content. Their exact upstream source paths, inventory, byte lengths, and hashes are strict package inputs. Plugin loading fails with the artifact path and validation reason if required content is missing or malformed. Command frontmatter supports `description`, `argument-hint`, `agent`, `model`, and `subtask`; task-agent frontmatter supports `description`, `mode: subagent`, `model`, `temperature`, `top_p`, `disable`, `color`, and `maxSteps`. Unsupported fields or shapes fail validation so upstream changes receive explicit review. Reinstall the package or rerun the sync script from a source checkout rather than repairing generated files by hand.
|
|
77
|
+
The adapter builds against paired `@opencode-ai/plugin` and `@opencode-ai/sdk` 1.18.15 releases and declares compatible optional peers from 1.18.3 through stable 1.x. Command and agent provenance is synced from Beads v1.2.2 at commit `6c124203e771433a3550c348771a5b5e27fd3c21`.
|
|
106
78
|
|
|
107
79
|
## Troubleshooting
|
|
108
80
|
|
|
109
|
-
- **No Beads context:** Run `bd prime
|
|
110
|
-
- **Canonical skill
|
|
111
|
-
- **
|
|
112
|
-
- **
|
|
113
|
-
- **
|
|
114
|
-
- **
|
|
115
|
-
- **Behavior changed after an upgrade:** Compare `opencode --version`, `bd version`, and `bun --version` with the compatibility table, then check the [Beads releases](https://github.com/gastownhall/beads/releases) and this project's changelog.
|
|
81
|
+
- **No Beads context:** Run `bd prime`. Install `bd` if missing or run `bd init` if the project has no Beads workspace.
|
|
82
|
+
- **Canonical skill missing:** For a new workspace, run `bd init`. For an existing workspace, follow current upstream Beads guidance; this plugin does not install or repair skills.
|
|
83
|
+
- **Vendor initialization error:** Reinstall the package. In a source checkout, rerun vendor sync and validation; the error identifies the malformed or missing artifact.
|
|
84
|
+
- **Unexpected definition:** Check OpenCode configuration for a colliding `beads:*` command or `beads-task-agent` definition. Explicit configuration wins.
|
|
85
|
+
- **Regular subagent has no context:** This is intentional. Delegate Beads work to `beads-task-agent` or run the required `bd` command explicitly.
|
|
86
|
+
- **Behavior changed after upgrade:** Compare `opencode --version`, `bd version`, and `bun --version` with the compatibility table, then inspect [Beads releases](https://github.com/gastownhall/beads/releases) and this project's changelog.
|
|
116
87
|
|
|
117
88
|
## License
|
|
118
89
|
|
|
119
|
-
opencode-beads is licensed under the MIT license. See
|
|
120
|
-
|
|
121
|
-
---
|
|
122
|
-
|
|
123
|
-
opencode-beads is not built by, or affiliated with, the OpenCode team.
|
|
90
|
+
opencode-beads is licensed under the MIT license. See [`LICENSE`](LICENSE).
|
|
124
91
|
|
|
125
|
-
OpenCode is ©2025 Anomaly.
|
|
92
|
+
opencode-beads is not built by or affiliated with the OpenCode team. OpenCode is ©2025 Anomaly.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@snarkipus/opencode-beads",
|
|
3
|
-
"version": "0.9.
|
|
3
|
+
"version": "0.9.4",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "A maintained OpenCode integration for the Beads issue tracker, including context injection, vendored workflows, and a task agent.",
|
|
6
6
|
"author": "Matt Jackson",
|
package/vendor/manifest.json
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"schemaVersion": 1,
|
|
3
3
|
"repository": "https://github.com/gastownhall/beads.git",
|
|
4
|
-
"tag": "v1.
|
|
5
|
-
"commit": "
|
|
4
|
+
"tag": "v1.2.2",
|
|
5
|
+
"commit": "6c124203e771433a3550c348771a5b5e27fd3c21",
|
|
6
6
|
"sources": [
|
|
7
7
|
{
|
|
8
8
|
"source": "plugins/beads/agents/task-agent.md",
|