Skip to content

Prepare stable opencode-beads 2.0.0 release #41

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
snarkipus merged 1 commit into from
Nov 9, 2026
Merged

Prepare stable opencode-beads 2.0.0 release #41

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 20 additions & 1 deletion CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,24 @@ and this project attempts to adhere to [Semantic Versioning](https://semver.org/

## [Unreleased]

## [2.0.0]

### Changed

- Graduate the qualified native Beads integration from beta to the stable line: eleven permissioned operations, 29 workflow commands plus `oc-beads:diagnostics`, packaged guidance and scope-bounded task execution.
- **Breaking:** require OpenCode `>=2.2.6 <2.3`; upgrade OpenCode before selecting 2.0.0. No parallel 2.1 compatibility layer or automatic migration is provided; existing exact 1.x/beta pins remain available. Beads minimum remains 1.3.1.
- Reflect actual request capabilities: native composition when available, directly exposed Beads leaves when execute is unavailable, and independently permissioned direct shell. Preserve per-operation rejection, actor attribution and Stop/Cancel.

### Fixed

- Restore durable workflow and once-captured diagnostic instructions after OpenCode 2.2 projects messages without metadata: resolve one native current-context snapshot map by retained user-message ID, with location/cancellation/generation checks and no new cache or side store.
- Reconcile README installation, migration and compatibility guidance with the accepted exact OpenCode 2.2.6 qualification. Runtime and packaged guidance are unchanged from the final Opus-reviewed candidate; version/README metadata create a new release artifact.

### Known limitations

- Native compaction followed by switching to a model unable to replay the native window can leave older command instructions or captured diagnostics inaccessible. Report unavailable guidance instead of reconstructing it; Beads issue data is unaffected. Upstream #57424 / `opencode-beads-o66` remain unresolved.
- A declined nested operation need not end the entire composition; later operations retain independent permissions. Explicit Stop/Cancel is the cancellation boundary.

## [1.1.0-beta.5]

### Fixed
Expand Down Expand Up @@ -360,7 +378,8 @@ Documentation-only release; the plugin code is unchanged from 1.0.0. It updates

- Josh Thomas <josh@joshthomas.dev> (maintainer)

[unreleased]: https://github.com/snarkipus/opencode-beads/compare/v1.1.0-beta.5...HEAD
[unreleased]: https://github.com/snarkipus/opencode-beads/compare/v2.0.0...HEAD
[2.0.0]: https://github.com/snarkipus/opencode-beads/releases/tag/v2.0.0
[1.1.0-beta.5]: https://github.com/snarkipus/opencode-beads/releases/tag/v1.1.0-beta.5
[1.1.0-beta.4]: https://github.com/snarkipus/opencode-beads/releases/tag/v1.1.0-beta.4
[1.1.0-beta.3]: https://github.com/snarkipus/opencode-beads/releases/tag/v1.1.0-beta.3
Expand Down
38 changes: 22 additions & 16 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,27 +7,32 @@

[Beads](https://github.com/gastownhall/beads) issue tracker integration for [OpenCode](https://opencode.ai).

`@snarkipus/opencode-beads` is a maintained OpenCode adapter that gives OpenCode 2 the integration `bd setup claude` gives Claude Code: `bd prime` workflow context on every request, refreshed after compaction and when a session resumes, plus a bounded task agent. Published 1.0.2 completes one Bead per invocation; the published beta/next release follows the authorized scope. It does not replace Beads: the installed `bd` CLI remains authoritative for issues, project initialization, skills, migrations, backups, and Dolt synchronization.
`@snarkipus/opencode-beads` is a maintained OpenCode adapter that supplies `bd prime` workflow context, native permissioned Beads tools, compact workflow commands and a scope-bounded task agent. Exact assignments stop with their item; an already-authorized batch may continue within its bounds. The installed `bd` CLI remains authoritative for issues, project initialization, shared skills, migrations and Dolt synchronization; the plugin does not replace it.

This is an independent project maintained by Matt Jackson under the MIT license. It began as a fork of [Josh Thomas's `opencode-beads`](https://github.com/joshuadavidthomas/opencode-beads), and the original work remains credited to its author. 1.0 rebuilt the plugin for OpenCode 2, and development now continues here independently. It vendors nothing from upstream Beads; instead, every Beads release is checked against the `bd` behavior the plugin relies on (see [Tracking upstream Beads](#tracking-upstream-beads)).

This release is **1.1.0-beta.5**, an opt-in beta targeting npm dist-tag `next`; its integration diagnostic command is `oc-beads:diagnostics`. Beta.1 used `oc-beads:status`; the rename is documented below. The beta's normal public entrypoint enables the eleven qualified operations in the native `beads` code-mode namespace on supported hosts: find, get, edges, memories, recall, claim, note, selected-field update, close, create and remember. No wrapper, internal dependency injection, manual skill copy or activation setting is needed. The opt-in is selecting the beta artifact. The published stable 1.0.2 package is unchanged.
Version **2.0.0** is the stable integration line for OpenCode `>=2.2.6 <2.3`. The normal public entrypoint enables the eleven qualified operations in the native `beads` code-mode namespace: find, get, edges, memories, recall, claim, note, selected-field update, close, create and remember. No wrapper, internal dependency injection, manual skill copy or activation setting is needed. The integration diagnostic command is `oc-beads:diagnostics`. Existing exact 1.x and beta pins remain available; installations are not upgraded automatically.

The beta registers 29 `oc-beads:<stem>` workflows plus `oc-beads:diagnostics` through ordinary native command registration and owns its packaged `oc-beads` skill at the installed path, with all 15 corpus resources plus CODE_MODE and ADR (17 links). User configuration/file commands retain native precedence on load and rebuild; removing an override restores the package definition. Other plugin conflicts follow native ordering. Diagnostics reports observed registration and name/description mismatches; identical-description overrides and public owner identity remain unobservable.
The plugin registers 29 `oc-beads:<stem>` workflows plus `oc-beads:diagnostics` through ordinary native command registration and owns its packaged `oc-beads` skill at the installed path, with all 15 corpus resources plus CODE_MODE and ADR (17 links). User configuration/file commands retain native precedence on load and rebuild; removing an override restores the package definition. Other plugin conflicts follow native ordering. Diagnostics reports observed registration and name/description mismatches; identical-description overrides and public owner identity remain unobservable.

Typed registration requires the host tool, permission and session interfaces. The integration diagnostic command reports unavailable interfaces honestly; actual request capabilities, catalog discovery and per-operation permissions determine which operations can run. Native shell remains direct-only and cannot be called inside execute. Structured results preserve partial, failed and uncertain outcomes, and writes retain the actual session-and-agent Beads actor. Read [CODE_MODE.md](assets/oc-beads/resources/CODE_MODE.md) for composition and recovery.

All 16 implementation tasks have parent acceptance on exact OpenCode 2.1.1 / Beads 1.3.1. The [final acceptance record](docs/code-mode-final-acceptance-vuy9.md) and [bounded installed/model evaluation](docs/opencode-installed-model-continuation-vuy9.md) retain their historical candidates and probes; the published beta adds the public entrypoint and release-channel wiring. **Known limitation:** plain decline of a nested permission request does not stop the entire composition; a later independent operation can ask again. Use explicit Stop/Cancel to stop the composition. No token-saving, cross-provider checkpoint portability or multi-hour reliability claim is made.
Exact OpenCode 2.2.6 has accepted native-host qualification plus one genuine OpenAI Sol High workflow; see the [qualification and final Opus review record](docs/opencode-22-qualification-5rj2.md). The 2.0.0 metadata preparation preserves that qualified runtime and all packaged guidance byte-for-byte. The [earlier acceptance record](docs/code-mode-final-acceptance-vuy9.md) retains the historical OpenCode 2.1.1 evidence. **Known permission behavior:** a rejected nested operation does not promise termination of the entire composition; each later operation retains its own permission check. Use explicit Stop/Cancel to stop the composition. No token-saving, cross-provider checkpoint portability or multi-hour reliability claim is made.

### Unreleased OpenCode 2.2.6 source adaptation
### Upgrading to 2.0.0

This checkout contains an unreleased source candidate targeting `@opencode/plugin` 2.2.6 and host admission `>=2.2.6 <2.3`. It is still package version `1.1.0-beta.5`; the published beta.5 artifact and its `>=2.1.1 <2.2` compatibility range have not changed. The candidate has not passed live host qualification and does not alter operator configuration or Beads data.
Upgrade OpenCode before changing the plugin pin: 2.0.0 requires `>=2.2.6 <2.3`, with no 2.1 compatibility layer. Then replace the existing plugin entry rather than stacking a second version, and check `/oc-beads:diagnostics` for the loaded package/host identities and actual capabilities. OpenCode upgrades and plugin installation remain operator-owned actions.

**Known workflow-guidance limitation:** after native conversation compaction on model A, switching to model B that cannot replay A's native context can make earlier workflow instruction snapshots and captured diagnostics unavailable. The candidate restores them only when OpenCode's current native session context contains matching user-message IDs; otherwise it reports the workflow guidance unavailable and continues with the ordinary request. This is the model-switch case tracked by [upstream issue #57424](https://github.com/anomalyco/opencode/issues/57424) and local deficiency `opencode-beads-o66`; it remains unresolved. The limitation affects prompt guidance only: it does not change or repair the Beads issue database or its stored data.
- Staying on OpenCode 2.1? Keep the exact beta.5 pin rather than following `latest`; beta.5 retains its historical `>=2.1.1 <2.2` range. Stable 1.0.2 remains a historical option for its separately qualified host.
- Moving from stable 1.0.2? Task execution now follows the explicitly authorized scope instead of imposing one Bead per invocation. Exact assignments still stop with their item; discovery never grants authority.
- Beta.1 used `oc-beads:status`; 2.0.0 uses `oc-beads:diagnostics`. Existing user overrides are not silently renamed.
- The accepted snapshot-recovery deficiency below remains unresolved; upgrading does not reconstruct inaccessible historical guidance.

**Known workflow-guidance limitation:** after native conversation compaction on model A, switching to model B that cannot replay A's native context can make earlier workflow instruction snapshots and captured diagnostics unavailable. The plugin resolves them only when OpenCode's current native session context contains matching user-message IDs; otherwise it reports the workflow guidance unavailable and continues with the ordinary request. This is the model-switch case tracked by [upstream issue #57424](https://github.com/anomalyco/opencode/issues/57424) and local deficiency `opencode-beads-o66`; it remains unresolved. The limitation affects prompt guidance only: it does not change or repair the Beads issue database or its stored data.

## Design

The published beta/next release uses scope-bounded task execution:
The 2.0 integration uses scope-bounded task execution:

- The primary OpenCode thread retains planning context, decisions, and control.
- An exact assignment or explicit one-bead mode stops with that item; read-only graph requests never authorize claims or writes.
Expand All @@ -37,25 +42,26 @@ The published beta/next release uses scope-bounded task execution:

## Installation

The published beta.5 requires OpenCode `>=2.1.1 <2.2` and `bd` 1.3.1 or later. Exact OpenCode 2.1.1 has bounded native, Stop and installed/model evidence; other admitted 2.1 patches are not inferred qualified. The unreleased source candidate instead admits `>=2.2.6 <2.3`; that range is a source target, not host qualification. The external `bd` CLI and project initialization remain prerequisites; the plugin does not install or upgrade them. Stable 1.0.2 remains separately qualified against OpenCode 2.0.26.
Version 2.0.0 requires OpenCode `>=2.2.6 <2.3` and `bd` 1.3.1 or later. Exact OpenCode 2.2.6 has bounded native and genuine-model evidence; a compatible range is admission, not proof that every future patch was tested. Native qualification used Beads 1.3.4 while the existing supported-minimum contract evidence remains 1.3.1. The external `bd` CLI and project initialization remain prerequisites; the plugin does not install or upgrade them.

1. Install the [`bd` CLI](https://github.com/gastownhall/beads/blob/main/docs/getting-started/installation.md) once on the host, then initialize each project:

```bash
git init # only when the directory is not already a Git worktree
bd init
```

`bd init` owns project initialization and creates the canonical shared Beads skill at `.agents/skills/beads`, which OpenCode discovers. It also writes a minimal Beads section to `AGENTS.md` that points to `bd prime`, the same pointer Beads gives Claude Code in `CLAUDE.md`. The published stable package relies on that shared skill. The beta additionally owns its packaged `oc-beads` skill; it does not write startup files or change `.agents/skills/beads/SKILL.md`.
`bd init` owns project initialization and creates the canonical shared Beads skill at `.agents/skills/beads`, which OpenCode discovers. It also writes a minimal Beads section to `AGENTS.md` that points to `bd prime`, the same pointer Beads gives Claude Code in `CLAUDE.md`. The plugin additionally owns its packaged `oc-beads` skill; it does not write startup files or change `.agents/skills/beads/SKILL.md`.

2. Add the published, version-pinned plugin to `~/.config/opencode/opencode.json` for every project, or to a project's `.opencode/opencode.json`:

```json
{
"plugins": ["@snarkipus/opencode-beads@1.1.0-beta.5"]
"plugins": ["@snarkipus/opencode-beads@2.0.0"]
}
```

To follow the published beta channel, use `"plugins": ["@snarkipus/opencode-beads@next"]` instead. To stay on stable, use `"plugins": ["@snarkipus/opencode-beads@latest"]` (currently 1.0.2); do not select the beta. Stable promotion requires separate approval.
To follow stable releases, use `"plugins": ["@snarkipus/opencode-beads@latest"]` and check the resolved version before upgrading. `"plugins": ["@snarkipus/opencode-beads@next"]` is a separate historical beta channel, not a promise of a newer or compatible release. An exact version pin is recommended.

OpenCode loads configuration changes automatically. Update the pin explicitly when upgrading; an unpinned package entry is less reproducible. OpenCode 1.x plugins are not supported; use 0.10.x or earlier there.

Expand All @@ -69,7 +75,7 @@ Plugin options use the object form:
{
"plugins": [
{
"package": "@snarkipus/opencode-beads@1.1.0-beta.5",
"package": "@snarkipus/opencode-beads@2.0.0",
"options": { "luna": true, "autoMigrate": false }
}
]
Expand Down Expand Up @@ -198,13 +204,13 @@ The package vendors nothing from upstream. It depends on the installed `bd` CLI

| Component | Expected range | Validated baseline |
| --- | --- | --- |
| OpenCode (published beta.5) | `>=2.1.1 <2.2` | 2.1.1 (bounded accepted evidence) |
| OpenCode (unreleased source candidate) | `>=2.2.6 <2.3` | 2.2.6 (source target; host gate pending) |
| OpenCode (historical beta.5) | `>=2.1.1 <2.2` | 2.1.1 (bounded accepted evidence) |
| OpenCode (2.0.0) | `>=2.2.6 <2.3` | 2.2.6 (accepted native and genuine-model qualification) |
| OpenCode (stable 1.0.2 historical) | 2.0.26 | 2.0.26 |
| `bd` CLI | 1.3.1 through 1.x | 1.3.1 |
| Bun (OpenCode host runtime) | >=1.3.14 | 1.4.2 |

Published beta.5 type-checks against `@opencode/plugin` 2.1.1 and declares an optional peer range of `>=2.1.1 <2.2`. This checkout's unreleased source candidate type-checks against 2.2.6 and declares `>=2.2.6 <2.3`; its source admission guard does not qualify that host range. Exact 2.1.1 has bounded accepted evidence for the published beta, and future 2.1 patches are admitted there as candidates rather than tested versions. The stable 1.0.2 qualification on 2.0.26 is historical. See the [OpenCode V2 contract](docs/opencode-sdk-contract.md). The `bd` baseline was reviewed against Beads v1.3.1 (commit `c1c4b642ac1c08d8c828007a1c2f96e47e43ef7c`).
Version 2.0.0 type-checks against `@opencode/plugin` 2.2.6 and declares optional peer range `>=2.2.6 <2.3`. Exact 2.2.6 has accepted bounded qualification; admission does not qualify future patches. Beta.5 remains historically scoped to `>=2.1.1 <2.2`, with exact 2.1.1 evidence. Stable 1.0.2 qualification on 2.0.26 is historical. See the [OpenCode V2 contract](docs/opencode-sdk-contract.md) and [current qualification](docs/opencode-22-qualification-5rj2.md). The `bd` baseline was reviewed against Beads v1.3.1 (commit `c1c4b642ac1c08d8c828007a1c2f96e47e43ef7c`).

## Troubleshooting

Expand Down
2 changes: 1 addition & 1 deletion docs/opencode-22-qualification-5rj2.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ Durable raw evidence and offline analyzers are under `/opt/data/research/opencod

## Limitations retained

- **Frozen README status:** `README.md:24` still says the candidate has not passed live host qualification, and its compatibility-table row at line 202 says `2.2.6 (source target; host gate pending)`. Those are frozen packed text, superseded by this summary for archive SHA-256 `072d9c29ef89fa2697109be072798e79cf4af622111266de40ef65e7950ac836`. Update both README statements and their `tests/docs.test.ts` compatibility-row assertion in the separately authorized 2.0.0 metadata change; do not mutate or silently repackage this qualified archive.
- **Historical frozen README status:** The qualified canary archive retains the old README statements at lines 24 and 202 saying qualification was pending; this summary supersedes them for digest `072d9c29ef89fa2697109be072798e79cf4af622111266de40ef65e7950ac836`. The separately tracked 2.0.0 metadata preparation reconciles the current README and its compatibility assertions. It does not mutate or silently repackage the original qualified archive.

- **`opencode-beads-o66` remains unresolved and upstream-blocked.** After native compaction on A then switching to non-replayable B, old ordinary transcript commands can lack accessible saved snapshots. The controlled native run verified the selected outcome: explicit unavailable-guidance disclosure, expansion of accessible snapshots, and no invented historical instructions. This is a verified limitation, not restored old snapshots or a fixed deficiency. README and the active specification retain it.
- Stop aborted the selected waiting operation and prevented its write, but the old host permission entry remained listed through session deletion. That stronger retirement observation remains failed historical evidence; no target execution, bypass or adapter repair requirement is inferred. The genuine run's final execution/permission inventories were empty.
Expand Down
Loading
Loading