@snarkipus/opencode-beads 1.0.1 → 1.1.0-beta.1

package/README.md

@@ -7,23 +7,31 @@
 
 [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 that completes one Bead per invocation. 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 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 beta/next candidate below 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.
 
-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. 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 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 branch prepares **1.1.0-beta.1**, an opt-in beta for npm dist-tag `next`; publication remains pending owner approval. 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.
+
+The beta registers 29 `oc-beads:<stem>` workflows plus `oc-beads:status` 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. Status 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. Status 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; this 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.
 
 ## Design
 
-The plugin's primary design is **context-preserving atomic delegation**:
+The beta/next candidate uses scope-bounded task execution:
 
 - The primary OpenCode thread retains planning context, decisions, and control.
-- `beads-task-agent` processes exactly one Bead per invocation, then closes, blocks, or returns.
-- Without an external orchestrator, this intentionally trades broad autonomy for Bead atomicity and context preservation.
-- An orchestrator may repeat `select → delegate one Bead → verify → select next`, but should not weaken the worker boundary.
+- An exact assignment or explicit one-bead mode stops with that item; read-only graph requests never authorize claims or writes.
+- An already-authorized batch or goal may continue within scope, with an atomic claim, append checkpoints, validation and acceptance evidence for each Bead. Discovery does not expand that authority.
+- Direct work or normal blocking delegation is chosen for the task. The actual executor actor follows claims, updates and heartbeats; handoffs are deliberate. Parent-owned acceptance and closure remain with the parent.
+- Denied authority, cancellation, permission waits, blockers and incomplete acceptance remain visible stops. Child results do not restart work. The [current bounded semantic evidence](docs/opencode-installed-model-continuation-vuy9.md) measures these outcomes, with failed validation and partial work preserved; broader model quality and multi-hour reliability remain unmeasured.
 
 ## Installation
 
-This plugin requires OpenCode 2 and `bd` 1.3.0 or later.
-
+The beta 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 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.
 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
@@ -31,19 +39,21 @@ This plugin requires OpenCode 2 and `bd` 1.3.0 or later.
    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`. This plugin has no separate skill lifecycle and does not write startup files.
+   `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`.
 
-2. Add the version-pinned plugin to `~/.config/opencode/opencode.json` for every project, or to a project's `.opencode/opencode.json`:
+2. After beta publication, add the 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.0.1"]
+     "plugins": ["@snarkipus/opencode-beads@1.1.0-beta.1"]
    }
    ```
 
+   To follow the beta channel after publication, 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.
+
    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.
 
-3. Check the install: `opencode debug agents` lists `beads-task-agent`.
+3. Check the install: `opencode debug agents` lists `beads-task-agent`; `/oc-beads:status` reports native registration and observed capabilities. Discover `beads` through execute on a host/agent with the required permissions.
 
 ### Plugin options
 
@@ -53,7 +63,7 @@ Plugin options use the object form:
 {
   "plugins": [
     {
-      "package": "@snarkipus/opencode-beads@1.0.1",
+      "package": "@snarkipus/opencode-beads@1.1.0-beta.1",
       "options": { "luna": true, "autoMigrate": false }
     }
   ]
@@ -63,8 +73,8 @@ Plugin options use the object form:
 | Option | Default | Effect |
 | --- | --- | --- |
 | `luna` | `false` | Also register the `beads-task-agent-luna` profile. |
-| `stealth` | `false` | Run `bd prime --stealth` (no git operations in the session-close protocol), like `bd setup claude --stealth`. `bd config set no-git-ops true` is the project-level equivalent. |
-| `taskAgentSteps` | `100` | Hard cap on task-agent steps per invocation, a backstop for "one bead, then return". `0` removes the cap. |
+| `stealth` | `false` | Add `--stealth` to `bd prime` (no git operations in the session-close protocol), like `bd setup claude --stealth`. `bd config set no-git-ops true` is the project-level equivalent. |
+| `taskAgentSteps` | `100` | Interruption cap on task-agent steps per invocation. `0` removes the cap; neither value changes authorized scope or establishes completion. |
 | `refreshAfterIdleMinutes` | `30` | Re-run `bd prime` when a session resumes after this much inactivity, as Claude Code does on resume. `0` disables idle refresh. |
 | `autoMigrate` | `false` | Let automatic `bd prime` open a store that may need a schema migration. See [Schema migration guard](#schema-migration-guard). |
 
@@ -89,25 +99,31 @@ The [Claude Code parity matrix](docs/claude-code-parity.md) records every `bd se
 
 ## Context injection
 
-The plugin runs full `bd prime` in the project directory and attaches its output to each model request through OpenCode's session context hook. The output is cached per session, so prime runs once per session rather than per request. It runs again after compaction (automatic or manual), when a session resumes after `refreshAfterIdleMinutes` of inactivity, and when the plugin reloads, mirroring the `startup`, `resume`, `clear`, and `compact` sources of Claude Code's `SessionStart` hook. Steady work keeps the same text, which keeps provider prompt caches warm. Attached context is not stored in the conversation, so compaction cannot drop it. Prime supplies the canonical current workflow, command guidance, and persistent memories; the plugin adds only compact OpenCode-specific safety and delegation guidance.
+The plugin runs `bd prime --full` in the project directory and attaches its output to each model request through OpenCode's session context hook. Guarded prime is cached per session, while actual actor and request-capability guidance is rendered for each request. Prime runs once per session rather than per request. It runs again after compaction (automatic or manual), when a session resumes after `refreshAfterIdleMinutes` of inactivity, and when the plugin reloads, mirroring the `startup`, `resume`, `clear`, and `compact` sources of Claude Code's `SessionStart` hook. Steady work keeps the same text, which keeps provider prompt caches warm. Attached context is not stored in the conversation, so compaction cannot drop it. `--full` matters: without it, `bd` switches to brief MCP reminders whenever Claude Code's settings list a Beads MCP server, and OpenCode has no Beads MCP tool. Prime supplies the canonical current workflow, command guidance, and persistent memories; the plugin adds only compact OpenCode-specific safety and delegation guidance.
 
 While prime is attached, two bd-managed `AGENTS.md` blocks only repeat it: the full-profile section `bd setup opencode` writes, and the Codex section `bd init` writes. The plugin replaces those marked blocks in the outgoing request with a one-line pointer, matching the minimal `CLAUDE.md` pointer Beads uses for Claude Code. `bd init`'s minimal section is left as is. Your `AGENTS.md` file and any text outside those markers are not changed, and nothing is replaced when prime is withheld or unavailable.
 
 Known regular subagents remain excluded, including `explore` and `general`, while `beads-task-agent` and `beads-task-agent-luna` remain eligible. If agent lookup fails, context injection fails open to preserve compatibility with unknown custom primary agents.
 
-If `bd` is unavailable or the project is uninitialized, nothing is added. If `bd prime` fails or times out, the agent gets a short `<beads-notice>` saying context is unavailable and to run `bd prime`, as Beads' Codex hooks report refresh failures. Either way the plugin retries after 30 seconds, and failures are also logged as `[opencode-beads]` warnings. The task agent retains a bounded standalone quick reference for `ready`, `show`, atomic claim, discovered follow-up, validate before closure, and close.
+If `bd` is unavailable or the project is uninitialized, nothing is added. If `bd prime` fails or times out, the agent gets a short `<beads-notice>` saying context is unavailable and to run `bd prime`, as Beads' Codex hooks report refresh failures. Either way the plugin retries after 30 seconds, and failures are also logged as `[opencode-beads]` warnings. The task agent retains standalone guidance for authorized scope, atomic claim, append checkpoints, validate before closure, and partial handoff under the caller's acceptance authority.
 
 ## Schema migration guard
 
 Beads 1.3 migrates an embedded store in place, irreversibly, the first time any command opens it, and `bd --readonly` does not prevent that. Because this plugin runs `bd prime` automatically, it would otherwise be the unattended first command after you upgrade `bd`.
 
-Before running prime, the plugin checks `bd version` and `bd where --json`, which never open the store, and reads `.beads/.local_version`. If the installed `bd` is older than 1.3.0, or the store was last opened by an older `bd`, the plugin withholds prime and gives the agent a notice telling it not to run `bd` and to ask you to act. To proceed, back up the `.beads` directory and run `bd migrate schema`; the plugin picks up the change on its next retry. Setting the `autoMigrate` option skips the store-version check.
+Before running prime, the plugin checks `bd version` and the configuration-only `bd context --json` probe, which do not open the store, and reads `.beads/.local_version`. If the installed `bd` is older than 1.3.1, or the store was last opened by an older `bd`, the plugin withholds prime and gives the agent a notice telling it not to run `bd` and to ask you to act. To proceed, back up the `.beads` directory and run `bd migrate schema`; the plugin picks up the change on its next retry. Setting the `autoMigrate` option skips the store-version check.
 
 `bd prime` itself does not update `.beads/.local_version`. A store migrated only by prime keeps the old marker until you run `bd migrate schema` (or any ordinary `bd` command), which is safe and idempotent.
 
 ## Beads workflows
 
-The plugin registers no slash commands; `bd setup claude` installs none either. Ask the agent to work with Beads, have it load the canonical `beads` skill that `bd init` installs at `.agents/skills/beads` (OpenCode lists it and loads it with its `skill` tool), or use the `bd` CLI and the generated [Beads CLI reference](https://beads.gascity.com/cli-reference/index) directly. Versions before 1.0.0 shipped `/beads:*` commands adapted from upstream's Claude Code plugin; they duplicated `bd prime` and the skill.
+Published stable 1.0.2 registers no slash commands; `bd setup claude` installs none either. Ask the agent to work with Beads, have it load the canonical `beads` skill that `bd init` installs at `.agents/skills/beads` (OpenCode lists it and loads it with its `skill` tool), or use the `bd` CLI and the generated [Beads CLI reference](https://beads.gascity.com/cli-reference/index) directly. Versions before 1.0.0 shipped `/beads:*` commands adapted from upstream's Claude Code plugin; they duplicated `bd prime` and the skill.
+
+## Removal and customization in the source candidate
+
+Remove the plugin's `plugins` entry to unload it. Cleanup aborts owned context/process work and its event observer, then awaits the scoped agent, skill, tool and hook disposers. It is idempotent and reports disposal failures. It never promises a final checkpoint after interruption. Reload starts with fresh session/location state. Package updates/removal belong to OpenCode's package lifecycle; this plugin has no installer or recursive asset watcher.
+
+Existing `oc-beads` skill IDs or names are checked and diagnosed in each rebuilt candidate; removing a customization allows the packaged skill to return. There is no permanent setup-time skill gate. Ordinary user configuration/file commands retain their later native precedence; same-name other-plugin conflicts follow native order rather than universal collision prevention. Disposing a registration removes only the package's transform; it does not delete user command/skill bodies, shared Beads skills, project data, startup files or global settings. Do not delete those files as plugin cleanup. Installed resource reads still require normal host permissions; bounded native external-directory ask/deny and actual model-use evidence is recorded in the acceptance reports. Missing/unreadable packaged guidance is diagnosed and its skill is withheld.
 
 ## Agent configuration
 
@@ -115,20 +131,20 @@ Entries under `agents` in OpenCode configuration override the plugin's task-agen
 
 ## Task agent
 
-`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.
+The beta/next `beads-task-agent` supports read-only status and graph analysis or execution within an assigned task, batch or goal. Analysis requests never mutate Beads. Exact assignments stop without substitution. Authorized batches may continue only within scope, with an explicit executor actor, atomic claim/readback, append checkpoints and relevant validation for each Bead. Discoveries do not authorize their execution; unresolved acceptance remains incomplete, and parent-owned closure stays with the parent.
 
-Its prompt and description are owned by this project. Upstream Beads ships a task agent only in its Claude Code marketplace plugin, as an autonomous multi-task loop; this adapter deliberately keeps the bounded one-Bead contract instead.
+Its prompt and description are owned by this project. Direct work and normal blocking delegation depend on the task, without a command-count threshold. The worker returns scope, actor/session, attempts, rationale, validation, durable references, blockers and next action. The caller reconciles acceptance; NO_TEXT, failure, cancellation, late results and step-cap interruption do not establish completion or authorize a restart.
 
 OpenCode lets the plugin enforce parts of that contract, beyond what Claude Code's hooks can do:
 
-- **No automatic commit, push, or sync.** The task agents' permissions require approval (`ask`) for `git commit`, `git push`, `bd dolt push`, `bd dolt pull`, and `bd sync`, on top of OpenCode's defaults. Compound commands are checked per command. A non-interactive run rejects them. Set the agent's `permissions` in OpenCode configuration to replace these rules.
+- **No automatic commit, push, or sync.** The task agents' permissions require approval (`ask`) for `git commit`, `git push`, `bd dolt push`, `bd dolt pull`, and `bd sync`, on top of OpenCode's defaults. Global options before the subcommand (`git -C dir push`, `bd --json dolt push`) are covered too, and compound commands are checked per command. This is a guardrail against routine sync, not a sandbox: scripts and aliases can still run these commands. A non-interactive run rejects them. Set the agent's `permissions` in OpenCode configuration to replace these rules.
 - **Step cap.** `taskAgentSteps` (default 100) limits a worker invocation; on its final step OpenCode removes tools and asks for a summary.
 - **Context in the worker.** The worker runs in its own child session and receives `bd prime` there too; Claude Code's `SessionStart` hooks do not reach subagents.
 - **Beads state across compaction.** Compaction requests in sessions with Beads context ask the summarizer to keep bead IDs, claim and status changes, discovered follow-ups, blockers, and pending validation.
 
 ### Opt-in Luna Max profile
 
-The default `beads-task-agent` leaves its model unset, so a subagent inherits the parent session's model. Set the plugin option `"luna": true` to also register `beads-task-agent-luna`, which uses `openai/gpt-6-luna#max` with exactly the same prompt, subagent mode, step cap, and permissions. Per-agent overrides remain independent: customizations to `beads-task-agent` are not copied to Luna. Both profiles receive full prime context and retain the same exact-one-Bead workflow.
+The default `beads-task-agent` leaves its model unset, so a subagent inherits the parent session's model. Set the plugin option `"luna": true` to also register `beads-task-agent-luna`, which uses `openai/gpt-6-luna#max` with exactly the same prompt, subagent mode, step cap, and permissions. Per-agent overrides remain independent: customizations to `beads-task-agent` are not copied to Luna. Both profiles receive full prime context and use the same scope and acceptance boundaries, including explicit one-bead mode when assigned. The profile makes no model-quality guarantee.
 
 Ask the primary agent to delegate to `beads-task-agent-luna` by name through the `subagent` tool. Default delegation guidance still names `beads-task-agent`; enabling Luna does not reroute existing calls or change the primary agent's model. Remove the option to unregister the profile.
 
@@ -138,23 +154,24 @@ Luna requires access to `openai/gpt-6-luna` and its `max` variant in your OpenCo
 
 The package vendors nothing from upstream. It depends on the installed `bd` CLI at runtime: `bd prime` supplies the current workflow, and the schema migration guard enforces the supported `bd` range.
 
-[`scripts/bd-contract.ts`](scripts/bd-contract.ts) checks a real `bd` against everything the plugin relies on: version parsing, `bd where --json`, the `.beads/.local_version` behavior the guard depends on (written by `bd init`, untouched by `bd prime`, refreshed by `bd migrate schema`), and every command the task-agent prompt names. CI runs it against the validated release from `package.json` (`beads.validated`). The scheduled `beads-contract` workflow runs it daily against the latest stable Beads release, and fails if that release breaks the contract or is newer than the validated one. When a new release appears, review its upgrade notes, then update `beads.validated` and the compatibility table. The [artifact policy](docs/beads-artifact-policy.md) records why upstream artifacts are not vendored.
+[`scripts/bd-contract.ts`](scripts/bd-contract.ts) checks a real `bd` against everything the plugin relies on: version parsing, `bd where --json`, the `.beads/.local_version` behavior the guard depends on (written by `bd init`, untouched by `bd prime`, refreshed by `bd migrate schema`), that `bd prime --full` keeps the full workflow when Claude Code has a Beads MCP server, and every command the task-agent prompt names. CI runs it against the validated release from `package.json` (`beads.validated`). The scheduled `beads-contract` workflow runs it daily against the latest stable Beads release, and fails if that release breaks the contract or is newer than the validated one. When a new release appears, review its upgrade notes, then update `beads.validated` and the compatibility table. The [artifact policy](docs/beads-artifact-policy.md) records why upstream artifacts are not vendored.
 
 ## Compatibility
 
 | Component | Expected range | Validated baseline |
 | --- | --- | --- |
-| OpenCode | 2.0.26 through 2.x | 2.0.26 |
-| `bd` CLI | 1.3.0 through 1.x | 1.3.1 |
+| OpenCode (beta/next candidate) | `>=2.1.1 <2.2` | 2.1.1 (bounded accepted evidence) |
+| 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 |
 
-The adapter type-checks against `@opencode/plugin` 2.0.26 and declares it as an optional peer from 2.0.26 through 2.x; the import is type-only, so OpenCode's own runtime is used. See the [OpenCode V2 contract](docs/opencode-sdk-contract.md). The `bd` baseline was reviewed against Beads v1.3.1 (commit `c1c4b642ac1c08d8c828007a1c2f96e47e43ef7c`).
+The beta/next candidate type-checks against `@opencode/plugin` 2.1.1 and declares an optional peer range of `>=2.1.1 <2.2`. It checks `ctx.app.version` at startup and reports an unsupported-host diagnostic before registering Beads agents or hooks. This source guard does not qualify the entire host range; exact 2.1.1 has bounded accepted evidence, and future 2.1 patches are admitted 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`).
 
 ## Troubleshooting
 
 - **No Beads context:** Run `bd prime`. Install `bd` if missing or run `bd init` if the project has no Beads workspace.
 - **Agent reports that `bd prime` failed or timed out:** Run `bd prime` in the project to see the error; the plugin retries every 30 seconds.
-- **Agent reports a Beads notice instead of context:** The schema migration guard withheld prime. Back up `.beads`, run `bd migrate schema`, and continue; or upgrade `bd` if the notice says it is older than 1.3.0.
+- **Agent reports a Beads notice instead of context:** The schema migration guard withheld prime. Back up `.beads`, run `bd migrate schema`, and continue; or upgrade `bd` if the notice says it is older than 1.3.1.
 - **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.
 - **Task agent asks before committing or pushing:** This is intentional; see [Task agent](#task-agent). Approve the command, or set the agent's `permissions` in OpenCode configuration.
 - **Unexpected definition:** Check OpenCode configuration for a colliding `beads-task-agent` definition. Explicit configuration wins.

package/assets/oc-beads/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: oc-beads
+description: >
+  Use Beads when work needs durable tracking across sessions, has dependencies or
+  blockers, needs a meaningful progress checkpoint, or must be resumed with its
+  prior attempts and decisions. Also use when searching or updating reusable
+  project knowledge. Follow the current project's instructions and the installed
+  bd CLI for supported operations.
+---
+
+# Beads work in OpenCode
+
+> Adapted from [Beads marketplace-main `SKILL.md` at commit `4a67d0d0288c1b4ee23e17fc896f47616931ba2d`](https://github.com/gastownhall/beads/blob/4a67d0d0288c1b4ee23e17fc896f47616931ba2d/plugins/beads/skills/beads/SKILL.md).
+
+Beads is the external issue and execution record. The installed `bd` CLI owns its
+commands and data. Repository and user instructions set the authority for each
+operation. The project's specification system (for example OpenSpec, when used)
+records intended behavior; project documents retain detailed rationale and
+evidence; Beads records execution, assignment, and acceptance.
+
+Use the current Beads context when the host provides it. If it is absent, retrieve
+current workflow context through the permissioned CLI only when that operation is
+authorized and no hold is active. Distinguish context that is missing, failed to
+load, or deliberately withheld. A migration or permission hold is a stop signal;
+do not bypass it by manually running `bd prime`. If execute is unavailable, use direct shell only when separately available and
+authorized. Native shell is direct-only and cannot be called inside execute. Do
+not assume an unstated tool name, approval, or setup step.
+
+When typed composition is available, discover current signatures through native
+`search({namespace: "beads"})`; each leaf retains its own permission checks.
+Follow [code-mode composition](resources/CODE_MODE.md) for bounded reads,
+projection, ordered writes, completeness, uncertainty and decline/Stop semantics.
+
+## Work within the assigned scope
+
+- Read the relevant issue and its dependencies before changing tracked state.
+- An assignment to one specific item is an exact assignment: finish that item,
+  report the outcome, and stop. Continue across a batch only when the user or
+  repository instructions explicitly authorize that batch or goal. Discovering
+  more work can justify reporting or recording a finding when authorized; it
+  does not expand the work you may perform.
+- For an authorized tracked task, claim atomically with the actual executor
+  actor. Keep that actor on every agent-authored Beads write and heartbeat:
+
+  ```sh
+  bd update '<id>' --claim --actor='<executor-actor>' --sandbox --json
+  bd heartbeat '<id>' --actor='<executor-actor>' --sandbox --json
+  ```
+
+  Use the host-rendered actor derived from your actual request session and agent,
+  matching typed write results. If unavailable, refuse writes until the host
+  supplies it; never copy a sample or impersonate another executor. Use a
+  readable, unambiguous identity, not the human Git identity or a model name.
+  Give delegated instructions the delegate's real actor and have the
+  executing worker claim its own authorized work. A deliberate handoff changes
+  ownership; parent review does not.
+- Read back `created_by` (audit author), `owner` (record/account ownership), and
+  `assignee` (executor) separately. Leave new work unassigned unless assignment
+  is intentional. Preserve historical authorship; document provenance
+  corrections in notes instead of rewriting it.
+- Direct work is suitable for small, clear tasks. Delegate when separate work
+  benefits from another executor or independent review, and state the scope,
+  evidence expected, actor, and stop condition. There is no required
+  command-count threshold or one-issue-per-invocation loop.
+
+## Keep useful progress
+
+At a meaningful change in direction, record what was attempted, what happened,
+why the next step follows, any blocker, and the concrete next action. Append to
+the issue's notes so useful earlier learning remains available:
+
+```sh
+bd update '<id>' --append-notes="Tried …; result …; because …; blocker …; next …" --actor='<executor-actor>' --sandbox --json
+```
+
+Use `--append-notes` for checkpoints. Replacing notes is a deliberate edit, not
+the routine checkpoint path. Keep records concise and evidence-based; do not
+store credentials, raw dumps, or guesses as facts. Do not write just to meet a
+count or frequency target when nothing material changed. If a write fails or its
+result is uncertain, report that state and inspect before retrying.
+
+## Separate task notes from reusable knowledge
+
+Attempts, issue-specific test results, decisions, and the next action belong on
+the issue. Use persistent Beads memory only for validated project knowledge that
+will likely help beyond this issue. Search for existing knowledge first, then
+update it deliberately with scope and evidence; a temporary failure usually
+belongs in the task record rather than global memory. Recall before updating an
+existing stable key: writing the same key replaces its content in place.
+
+```sh
+bd memories '<keyword>'
+bd recall '<known-key>'
+bd remember "Validated learning, where it applies, and supporting evidence" --key='<stable-key>' --actor='<executor-actor>' --sandbox
+```
+
+Do not dump all memories into every handoff or delete old knowledge as routine
+cleanup. Use the current CLI help for exact memory options.
+
+Do not initialize or reroute a store, synchronize it, change permissions, or enable automation as a side effect.
+Those separate administrative operations require explicit authorization.
+Examples assume a project policy prohibiting automatic remote updates and include
+`--sandbox`; it only suppresses Dolt auto-push and provides no migration safety.
+
+## Validation, handoff, and stopping
+
+Before marking work complete, compare the result with its acceptance criteria and
+run the relevant authorized validation. Keep failed or unrun checks explicit.
+Close an issue only when closure is within your authority and its own acceptance
+is met. If a parent, owner, or human controls acceptance, return evidence and
+leave that decision to them. A discovered issue does not become authorized work
+just because it is linked.
+
+For a handoff, provide the current state, material attempts and outcomes,
+rationale, validation evidence, blockers, next action, and useful issue or memory
+references. Preserve enough context to continue without replaying a failed
+approach. Stop when the exact assignment is done, authority is absent, a hold is
+active, or a required guarantee cannot be established.
+
+## Supporting guidance
+
+These resources are separate so advanced or reference material can be opened
+only when relevant. Every selected support file is linked explicitly because a
+host may display only a limited automatic file list.
+
+### Daily work
+
+- [Boundaries: durable tracking and short-lived work](resources/BOUNDARIES.md)
+- [Current CLI reference sources](resources/CLI_REFERENCE.md)
+- [Dependency direction and provenance](resources/DEPENDENCIES.md)
+- [Issue creation and useful fields](resources/ISSUE_CREATION.md)
+- [Common execution patterns](resources/PATTERNS.md)
+- [Resumability and recovery notes](resources/RESUMABILITY.md)
+- [Meaningful workflows and checkpoints](resources/WORKFLOWS.md)
+- [OpenCode and Beads integration patterns](resources/INTEGRATION_PATTERNS.md)
+- [Current troubleshooting and stop conditions](resources/TROUBLESHOOTING.md)
+
+### Advanced, on demand
+
+- [Agent beads, executor identity, and unsupported slot APIs](resources/AGENTS.md)
+- [Asynchronous gates](resources/ASYNC_GATES.md)
+- [Molecule and wisp patterns](resources/CHEMISTRY_PATTERNS.md)
+- [Molecule and formula reference](resources/MOLECULES.md)
+- [Static reference data](resources/STATIC_DATA.md)
+- [Worktree routing](resources/WORKTREES.md)
+
+### Rationale
+
+- [ADR-0001: keep exact CLI syntax dynamic](adr/0001-bd-prime-as-source-of-truth.md)

package/assets/oc-beads/adr/0001-bd-prime-as-source-of-truth.md

@@ -0,0 +1,40 @@
+# ADR-0001: Keep exact CLI syntax dynamic
+
+## Status
+
+Accepted for this guidance corpus.
+
+## Context
+
+The upstream Beads skill and its resources have useful decision guidance, but
+they are not a generated reference for every installed `bd` release. Copying
+flags and command forms throughout prose lets examples age independently of the
+CLI. A successful `bd prime` or command exit is also not proof that a particular
+record was found, a memory was returned, or a write was acknowledged.
+
+## Decision
+
+- Keep cognitive and workflow guidance in `SKILL.md` and its on-demand resources.
+- Use `bd prime` for current workflow context and `bd '<command>' --help` for
+  exact syntax. Do not duplicate a broad CLI reference here.
+- Respect an explicit context, permission, or migration hold. A manual prime is
+  not a fallback around a hold.
+- Keep examples limited to supported CLI forms verified against the installed
+  help. When an operation is unavailable, say what supported path or limitation
+  applies instead of inventing a flag or tool.
+- Treat host registration, package inclusion, installed resource access, and
+  behavioral qualification as separate evidence. The presence of these source
+  assets does not establish those outcomes.
+
+## Consequences
+
+This keeps the startup guidance short and moves depth to linked resources. CLI
+help can still be incomplete or ambiguous, so examples and compatibility claims
+need review against their relevant Beads release. No claim that drift is
+impossible is made. Advanced features remain opt-in and do not enable automation,
+store initialization, synchronization, or permission changes by themselves.
+
+## Source attribution
+
+Adapted from [Beads marketplace-main ADR-0001 at commit
+`4a67d0d0288c1b4ee23e17fc896f47616931ba2d`](https://github.com/gastownhall/beads/blob/4a67d0d0288c1b4ee23e17fc896f47616931ba2d/plugins/beads/skills/beads/adr/0001-bd-prime-as-source-of-truth.md).

package/assets/oc-beads/resources/AGENTS.md

@@ -0,0 +1,43 @@
+# Agent beads and executor identity
+
+> Adapted from [Beads marketplace-main `AGENTS.md`](https://github.com/gastownhall/beads/blob/4a67d0d0288c1b4ee23e17fc896f47616931ba2d/plugins/beads/skills/beads/resources/AGENTS.md).
+
+## Keep the concepts separate
+
+Beads executor attribution, issue assignment, and specialized agent/role beads
+serve different purposes. For ordinary delegated work, use the authorized issue
+and assign or claim it for the actual executor. Supply that executor's explicit
+actor on each Beads write and heartbeat. Do not substitute the parent, human Git
+identity, or model name for the worker identity.
+
+Read `created_by`, `owner`, and `assignee` as separate fields. `created_by` is
+audit authorship, `owner` identifies the record/account owner, and `assignee`
+identifies the executor. A claim does not rewrite historical authorship. Record
+known provenance corrections in append-style notes.
+
+## Specialized agent/role beads are optional
+
+The upstream resource describes a richer agent state machine and named slots.
+In the inspected Beads 1.3.1 CLI, `bd agent --help` and `bd slot --help` both
+return unknown-command errors. The installed CLI does support ordinary issue
+assignment, atomic task claims, and `bd heartbeat` for a claimed issue lease.
+Those are useful executor conventions, not a one-to-one implementation of
+agent/role beads, their state machine, or slot queries.
+
+The upstream model describes lifecycle labels such as idle, spawning,
+running/working, done, stuck, stopped, and dead, and slots such as a current-work
+hook or a role. Treat these as design concepts from the source material, not
+states or slot records this CLI can create or query.
+
+Do not assume `bd agent` or `bd slot` is available and do not invent replacement
+flags. Workflows that require those specialized APIs must stop or use a separately
+approved, documented system. Routine Beads work does not need agent beads,
+Witness, a slot service, or a new orchestration layer.
+
+## When a separate agent record could help
+
+Only consider specialized agent records when a project already has a supported
+coordination design that needs durable role capabilities, liveness, or multiple
+named assignments. Establish who owns those records and how they are retired
+before writing any. A heartbeat on an assigned issue refreshes that issue's
+claim lease; it is not a general process monitor.

package/assets/oc-beads/resources/ASYNC_GATES.md

@@ -0,0 +1,63 @@
+# Asynchronous gates
+
+> Adapted from [Beads marketplace-main `ASYNC_GATES.md`](https://github.com/gastownhall/beads/blob/4a67d0d0288c1b4ee23e17fc896f47616931ba2d/plugins/beads/skills/beads/resources/ASYNC_GATES.md).
+
+An async gate models a wait condition that blocks a later step. It does not do
+the work, grant permission, or make a human decision. Use one only when an
+authorized workflow needs a durable wait relationship; ordinary blockers can
+remain issue dependencies.
+
+## Gate kinds
+
+The pinned guidance distinguishes a human decision from a condition that can
+be checked:
+
+| Kind | Successful condition | Failure or timeout behavior |
+| --- | --- | --- |
+| `human` | Explicit human decision, recorded by manual resolution. | A `--timeout` can be stored as metadata but is not enforced by `bd gate check`; silence is not consent. |
+| `timer` | The timeout has elapsed when an authorized executor runs `bd gate check --type=timer --actor='<executor-actor>' --sandbox --json`. | Otherwise it remains pending. |
+| `gh:run` | Run is completed with success (the pinned guidance also treats skipped as resolved). | Completed failure or cancellation escalates; the gate remains open for a decision. |
+| `gh:pr` | Pull request is merged. | Closed without merge escalates; the gate remains open for a decision. |
+| `bead` | The referenced issue is closed, when supported by the installed create path. | An open target remains pending. |
+
+The installed `bd gate check --help` confirms timer evaluation and GitHub
+success/failure conditions. The pinned source says a human gate's stored timeout
+is not enforced by `check`. The installed `bd gate create --help` lists human,
+timer, `gh:run`, and `gh:pr`; it does not list `bead` as a create type. Check
+current help before relying on a gate type; this guidance does not qualify host
+behavior.
+
+## Inspect and resolve deliberately
+
+Use `bd gate --help` and `bd gate '<subcommand>' --help` for current syntax. The
+installed help supports this deliberate human-decision flow:
+
+```sh
+# An authorized executor creates the wait condition.
+bd gate create --type=human --blocks='<issue-id>' \
+  --reason="Needs owner review" --actor='<executor-actor>' --sandbox --json
+bd gate list --json
+bd gate show '<gate-id>'
+
+# The actual human runs this command only after making the decision.
+bd gate resolve '<gate-id>' --reason="Reviewed; decision recorded" \
+  --actor='<actual-human-actor>' --sandbox --json
+```
+
+Read both the gate and blocked issue before changing either. An agent must never
+supply a human actor or resolve a human gate on the human's behalf. Never infer
+consent from silence. A failed CI run or unmerged closed pull request is a failure
+to investigate, not a successful gate. If an authorized executor runs a check, keep its actor explicit and
+inspect the resulting state before continuing.
+
+Do not create gates automatically for every handoff, approval, test, or issue.
+Do not add polling, watchers, or approval automation as a side effect of reading
+this resource. Gates and issue dependencies are distinct: use a gate for a
+documented async condition, and an issue dependency for work ordering.
+
+## Stop conditions
+
+Stop if the gate cannot be read, its referenced event cannot be verified, a
+human decision is required, or the current CLI lacks the required gate action.
+Report the gate ID, observed state, evidence, and the decision needed. Never
+route around a permission denial by calling a different interface.

package/assets/oc-beads/resources/BOUNDARIES.md

@@ -0,0 +1,57 @@
+# Boundaries: durable tracking and short-lived work
+
+> Adapted from [Beads marketplace-main `BOUNDARIES.md`](https://github.com/gastownhall/beads/blob/4a67d0d0288c1b4ee23e17fc896f47616931ba2d/plugins/beads/skills/beads/resources/BOUNDARIES.md).
+
+Use Beads for work whose ownership, dependencies, blocker, history, or next
+session matters to the project. Keep a short linear breakdown in the current
+conversation when it is only an execution aid and no repository rule requires a
+durable issue. Do not make a second Markdown task list the durable project record.
+
+## Choose the right record
+
+| Situation | Record | Why |
+| --- | --- | --- |
+| Short, linear steps that will finish in this session | Conversation checklist, if useful | Keeps execution visible without creating durable issue noise. |
+| Work needs an owner, blocker, dependency, acceptance, or later resume | Existing or authorized Bead | Preserves execution history and handoff context. |
+| Validated learning is likely to help on future issues | Relevant Beads memory | Reusable knowledge is separate from a task's attempts. |
+| Intended behavior and acceptance contract | Project's specification system (for example OpenSpec, when used) | Keeps the project specification authoritative. |
+| Detailed rationale, source evidence, or qualification result | Project documentation | Gives durable evidence a stable home. |
+| Temporary command output | Current session; summarize only if it changes a decision | Avoids storing noise. |
+| Host explicitly exposes experimental todo support and the user/project opts in | Host-owned transient checklist | Optional convenience only; it is not installed or enabled here. |
+
+OpenCode 2.1 experimental todo support is opt-in and host-owned. Do not require
+it, turn it on, or assume Claude's `TodoWrite` exists in every host. If no
+session checklist is available, keep a brief checklist in the conversation or
+use an authorized Bead when the work is durable.
+
+Do not create a new Bead for every command, transient retry, small nit, or
+document. Create or update a record when the work is genuinely durable and you
+have authority to do so. Existing assignment and project policy take priority
+over any general heuristic here.
+
+Ask: “Could I resume this after two weeks away?” If the answer needs context
+that would otherwise be lost, preserve it in the appropriate authorized record.
+
+## Transition when the work grows
+
+It is reasonable to begin with a transient checklist for “update the retry
+message and run its focused test.” If the test uncovers an independent data-loss
+case, a prerequisite, or work that must continue next session, stop treating the
+checklist as the durable record. If authorized, create or update the appropriate
+Bead with the attempted fix, test evidence, discovered blocker, acceptance, and
+next step; link new work to its source where useful. Keep the checklist only for
+the remaining steps in this session. Without authority to create or change a
+Bead, preserve the discovery in the assigned record if permitted, then report
+and stop at the scope boundary.
+
+## Preserve the authority boundary
+
+A ready issue is available work, not permission. A single-item assignment ends
+after that item; continue only inside an explicitly authorized batch or goal.
+Finding related work does not authorize acting on it. Link or report discoveries
+only within the authority already granted.
+
+For a tracked item, preserve its execution identity and history. Claim
+atomically when authorized, use an explicit actor on writes, and append material
+progress rather than replacing previous notes. A task record does not own the
+Beads database or authorize sync, setup, permission changes, or Git operations.

package/assets/oc-beads/resources/CHEMISTRY_PATTERNS.md

@@ -0,0 +1,44 @@
+# Molecule and wisp patterns
+
+> Adapted from [Beads marketplace-main `CHEMISTRY_PATTERNS.md`](https://github.com/gastownhall/beads/blob/4a67d0d0288c1b4ee23e17fc896f47616931ba2d/plugins/beads/skills/beads/resources/CHEMISTRY_PATTERNS.md).
+
+Molecules and wisps are advanced ways to organize repeated or temporary work.
+They are optional. A normal issue and its dependencies are usually enough for
+one task. Do not introduce a molecule workflow simply because it is available.
+
+## Choose by phase and lifetime
+
+| Need | Record | Lifetime |
+| --- | --- | --- |
+| One-off owned work with no reusable workflow | Normal issue and dependencies | Durable issue history. |
+| Repeated multi-step work whose children and audit trail should persist | Formula/proto instantiated as a persistent molecule | Reusable source, then durable execution records. |
+| Authorized short-lived research, review, triage, or operations with low audit value | Wisp from an existing formula/proto | Ephemeral; useful findings must be promoted before cleanup. |
+
+Treat formulas/protos as reusable workflow sources, molecules as instantiated
+work, and wisps as the temporary phase. Do not use a wisp when the full trail
+must persist or assume that a formula will stay inside the exact assignment.
+
+Before using a formula, inspect the available formula and its steps. Decide what
+evidence should survive and who owns each child. Do not let a template silently
+expand an exact assignment into unrelated work.
+
+An approved one-time review can use an existing review formula: capture evidence
+and uncertainty in its wisp, promote validated actionable findings to a durable
+record, then discard only noise with no future value. A bounded research spike
+can preserve sources, rejected hypotheses, and a conclusion the same way. These
+are optional work patterns, not authority to create a formula, spawn workers, or
+start a background patrol.
+
+## Preserve useful results
+
+At the end of a wisp, retain validated findings, rejected hypotheses, sources,
+and resulting authorized work in the appropriate durable record. Discard only
+noise that has no future value. A digest should not turn unverified notes into
+facts. `bd mol squash` creates a durable digest; `bd mol burn` deletes a wisp
+without a digest. Use either only when that lifecycle is authorized and current
+help confirms the operation.
+
+Use `bd mol --help`, `bd formula --help`, and relevant subcommand help for exact
+syntax. Creating a proto, molecule, wisp, or child issue is a Beads write and
+requires the actual executor actor. These features do not start workers, set
+permissions, or enable background automation by themselves.

package/assets/oc-beads/resources/CLI_REFERENCE.md

@@ -0,0 +1,20 @@
+# CLI reference
+
+> Adapted from [Beads marketplace-main `CLI_REFERENCE.md`](https://github.com/gastownhall/beads/blob/4a67d0d0288c1b4ee23e17fc896f47616931ba2d/plugins/beads/skills/beads/resources/CLI_REFERENCE.md).
+
+This resource deliberately does not copy the full command catalog. The installed
+`bd` binary and active repository policy determine current syntax.
+
+- Use `bd prime` for current agent workflow context, only when authorized and
+  not blocked by a context or migration hold.
+- Use `bd '<command>' --help` for a command's current flags and behavior.
+- Use `bd --help` to discover commands available in the installed binary.
+- Use `--json` when structured output is useful and supported by that command.
+- Supply `--actor='<executor-actor>'` on every agent-authored write, claim, and
+  heartbeat. Do not rely on `git user.name`, `$USER`, or an inherited global
+  actor.
+
+If a command or flag in an old example is absent from current help, do not guess
+its spelling or use a hidden interface. State the limitation and use a supported
+equivalent only when it preserves the requested outcome and authority. A static
+resource cannot prove installed host behavior or package delivery.