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

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

@@ -0,0 +1,78 @@
+# Beads in native code mode
+
+Use the actual request capability block. When the beads namespace is registered
+and execute is visible, use native `search({namespace: "beads"})` to discover
+current signatures. Catalog discovery and each operation's permissions determine
+what is callable; execute visibility alone does not establish leaf availability.
+Do not copy a signature catalog from prose or invent tools. If execute is denied,
+code-mode-only Beads operations disappear. Permissioned direct shell is a fallback
+only when available, authorized and no guard hold applies. Native shell is
+**direct-only**: never call `tools.shell` inside execute. Repository editing,
+tests and Git run in separate direct shell turns.
+
+## Read, choose, then act
+
+Start with bounded discovery and inspect scope and `complete`. `true` refers to
+that query, `false` means truncated or partial, and `null` means completeness is
+unknown. Ready, list, search and blocked have different supported filters;
+unsupported combinations are rejected. Blocked and edge reads can return unknown
+completeness. Unknown or failed edges never prove that work is unblocked.
+
+Get chosen IDs together (at most 25); the adapter performs sequential single-ID
+reads. Inspect per-ID failures and `complete`; an all-failed get is failed, not
+missing. There is no snapshot-consistency or transaction promise. For independent
+reads, use small bounded fan-out (for example at most eight candidates with
+`Promise.allSettled`), retain rejected/failed outcomes as unknowns, and return a
+projection of relevant fields. Return memory keys first, then recall selected
+keys. A found empty memory differs from a missing key; memories retains a
+key-to-value map, including a successful empty map.
+
+Selecting a candidate does not authorize claiming it. Read scope, prior attempts,
+acceptance and dependencies before acting. Await an authorized claim and stop
+dependent work unless it acknowledges the actual executor as assignee in
+`in_progress`. A claim never hides a second readback prompt; use get explicitly
+when needed. `not-claimed` requires evidenced non-claim, and `uncertain` requires
+current-state inspection before considering another write.
+
+## Ordered writes and honest outcomes
+
+Await dependent writes in order; inspect each result before the next call. Do not
+parallelize claim, note, update, close or dependent creates. Each invocation has
+its own canonical permission resources and `save: []`: an "always" response may
+apply to that call only, so ask may prompt again. Saved shell grants remain
+subject to denies. Orchestrator authority does not bypass host permission prompts.
+Do not catch a rejected operation and continue its dependent writes. Plain
+permission decline on OpenCode 2.1.1 may still permit later independently
+permissioned work or model steps; it does not promise whole-program termination.
+Explicit Stop/Cancel is distinct and its installed qualification remains separate.
+
+Use note for append checkpoints. Selected-field update excludes ownership changes
+and closure. Close needs caller-authorized acceptance evidence; it is never an
+automatic workflow step. Create generates an ID and does not automatically assign
+an executor. An uncertain create retains its identifying query/title: search and
+read back before considering a manual retry, to avoid duplicates.
+
+Every typed write returns the host-derived actor. Use that same rendered actor
+for direct shell writes, claims and heartbeats with command-scoped `--actor` or
+`BEADS_ACTOR`, and `--sandbox` to suppress automatic Dolt push. No global actor
+configuration, model-controlled actor argument or human Git fallback. A child
+uses its own actual session/agent actor and claims only authorized work; parent
+review does not transfer assignment. Audit author (`created_by`), account owner
+(`owner`) and executor (`assignee`) are separate observations; missing fields
+remain unknown. Attribution is not permission or authentication.
+
+Only authoritative CLI evidence acknowledges a write. Started interrupted,
+timed-out or malformed writes may have landed: retain target, actor and original
+diagnostic, then inspect durable state under fresh authorization. Do not blindly
+retry, force, commit or synchronize. A landed but uncommitted memory retains
+`commit_error`/`commit_indeterminate`; it is not committed durability. Fulfilled
+Promises, outer execute completion and compaction summaries do not establish
+successful persistence. Write inputs remain in host trace metadata.
+
+Full prime remains the canonical workflow reference. Meaningful checkpoints
+carry attempts, measured outcomes, rationale, blockers and next action. Important
+recovery, external changes and child returns require fresh relevant state;
+acknowledged writes do not require a generic redundant read of their own result.
+Preserve distinct repository/user authority, guard holds and exact scope. Missing
+capability or failed context is reported honestly, without manual-prime bypass,
+implicit sync, automatic retries or a replacement workflow manager.

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

@@ -0,0 +1,82 @@
+# Dependency types and direction
+
+> Adapted from [Beads marketplace-main `DEPENDENCIES.md`](https://github.com/gastownhall/beads/blob/4a67d0d0288c1b4ee23e17fc896f47616931ba2d/plugins/beads/skills/beads/resources/DEPENDENCIES.md).
+
+Beads dependencies describe relationships between issues. Confirm direction
+before writing: in the current `bd create` help, a bare ID, `'depends-on:<id>'`, or
+`'blocked-by:<id>'` makes the new issue depend on that ID; `'blocks:<id>'` reverses
+that direction. For existing issues, the installed `bd dep add --help` confirms
+the dependent comes first and the prerequisite second (default type: `blocks`).
+
+## Choose a relationship by meaning
+
+| Question | Relationship | Effect to preserve |
+| --- | --- | --- |
+| Can B start before A is complete? | `blocks` (A blocks B) | Hard ordering constraint; the dependent waits. |
+| Is B part of A's planned work? | `parent-child` (A parent, B child) | Decomposition and ownership; not an ordering edge. |
+| Did work on A uncover B? | `discovered-from` (B from A) | Discovery provenance; not permission to start B. |
+| Are A and B connected but independently actionable? | `related` | Informational association, not a blocker. |
+
+For a new dependent issue, current `bd create --help` says that
+`--deps='depends-on:<prerequisite-id>'` means **this new issue depends on that
+prerequisite**. For example, an API task can depend on a schema task like this:
+
+```sh
+bd create "Implement API" --type=task \
+  --parent='<epic-id>' \
+  --deps='depends-on:<schema-task-id>' \
+  --actor='<executor-actor>' --sandbox --json
+```
+
+The command above makes the API task a child of an epic while also adding a
+separate hard blocker on schema setup. Read back both edges: hierarchy answers
+“what work belongs here?”; a blocker answers “what must finish first?”. Add a
+hard block only when a real prerequisite exists.
+
+### Add and check existing-issue edges
+
+X needs Y means X depends on Y: dependent first, prerequisite second.
+
+```sh
+bd dep add '<dependent-id>' '<prerequisite-id>' --actor='<executor-actor>' --sandbox --json
+bd blocked --json
+bd dep list '<dependent-id>' --json
+```
+
+Phase trap: “Phase 1 before Phase 2” means Phase 2 needs Phase 1.
+Wrong: `bd dep add '<phase-1-id>' '<phase-2-id>' --actor='<executor-actor>' --sandbox --json` would block Phase 1.
+Right: `bd dep add '<phase-2-id>' '<phase-1-id>' --actor='<executor-actor>' --sandbox --json` blocks Phase 2 on Phase 1.
+Readback: `bd blocked` should show the dependent waiting while its prerequisite
+is open; `bd dep list` defaults to dependencies (down), so it should list that
+prerequisite, never the dependent's later work. These reads do not authorize work.
+
+### Diamond and parallel merge
+
+```text
+                  setup
+                 /     \
+            API work   UI work
+                 \     /
+                 integration tests
+
+setup blocks API work and UI work; each implementation blocks the merge tests.
+The two implementations can proceed in parallel after setup.
+```
+
+`related` is useful for an optional improvement that should remain independently
+ready. A discovery cascade is different: B may be discovered from A, and C from
+B, preserving how the questions emerged. `discovered-from` does not make that
+cascade required work, grant authority, or create a hard blocker.
+
+Use the narrowest accurate relation. Do not use a hard blocker for a preference,
+shared topic, or unverified assumption. Avoid cycles and redundant edges. Before
+adding or changing an edge, inspect both issues and verify which one depends on
+which. Afterward, read the graph back when the relationship affects readiness.
+
+Dependency direction is especially easy to reverse when creating a child or
+recording discovery. The current CLI help is authoritative for syntax; this page
+preserves relationship meaning, not every command form. Agent-authored graph
+writes require an explicit executor actor. A ready result is only a scheduling
+view: it does not override assignment, task scope, or authorization. The
+installed CLI describes hard blockers as affecting readiness; inspect the graph
+after a meaningful edit rather than inferring it from the prose alone.

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

@@ -0,0 +1,74 @@
+# Integrating Beads with project workflow
+
+> Adapted from [Beads marketplace-main `INTEGRATION_PATTERNS.md`](https://github.com/gastownhall/beads/blob/4a67d0d0288c1b4ee23e17fc896f47616931ba2d/plugins/beads/skills/beads/resources/INTEGRATION_PATTERNS.md).
+
+Use Beads to preserve execution state, not to replace every other source of
+intent or evidence. A useful division is:
+
+| Need | Source of truth |
+| --- | --- |
+| Intended behavior, requirements, and acceptance contract | Project's specification system (for example OpenSpec, when used) |
+| Detailed rationale, measurements, source references, and qualification evidence | Project documentation |
+| Execution ownership, dependencies, blockers, progress notes, and status | Beads |
+| Short checklist for today's already-authorized steps | Current session or optional host-owned todo, if available |
+
+Link those records when the relationship helps a future reader. Do not duplicate
+an entire design or test log in Beads; append a concise checkpoint with the
+result, why it matters, and where the detailed evidence lives.
+
+## Worked linkage: plan, review, then execute
+
+This is a project-policy example, not a universal Beads requirement. Use the
+project's chosen planning and review rules; the pattern below is optional where
+no such policy exists.
+
+For example, an OpenSpec change, in a project that uses it, can own the behavior
+and acceptance criteria for a new export option. Put detailed trade-offs and test
+evidence in a linked project document. A quick planning draft needs no separate Bead. For substantial
+multi-session or delegated planning, create one bounded planning Bead, distinct
+from the implementation epic, and reference the OpenSpec change and evidence
+document there.
+
+When review is independently owned and substantive, use one bounded review
+Bead linked to the planning work and the exact candidate revision. Record the
+reviewer's actual actor/session, verdict, findings, and evidence. Reuse that
+same review Bead for correction and recheck cycles; do not create a ticket per
+document, retry, or transient nit. Implementation issues track the authorized
+execution work. The chosen specification system and docs remain the spec/evidence
+sources, not duplicate task trackers; planning or review completion does not
+authorize implementation or prove parent acceptance. A ready Bead is not dispatch authority.
+
+## Milestones and recovery
+
+Read existing issue notes and relevant project memory before choosing a next
+step. At a material milestone, append attempted work, result, rationale, changed
+decision, blocker, and next action. Use the explicit executor actor. If the
+operation does not materially change the work context, no redundant write is
+needed.
+
+```sh
+bd update '<execution-id>' \
+  --append-notes="Tried X; observed Y in tests/export.test.ts; chose Z because …; blocker …; next …" \
+  --actor='<executor-actor>' --sandbox --json
+```
+
+For delegation, send the worker the exact authorized scope and its actual actor.
+Ask for the attempt, outcome, evidence, rationale, blocker, next step, and any
+durable record references. The parent reconciles the return against the original
+intent and acceptance before continuing or closing. Delegation is discretionary;
+do not route work based on a command count.
+
+OpenCode 2.1 experimental todo support remains opt-in and host-owned. Use it only
+when that host feature is actually available and the user/project chooses it;
+do not enable it or present it as a universal `TodoWrite` tool. It can hold a
+temporary execution checklist, not replace the project's specification system,
+project evidence, or Beads.
+
+## Keep durable and transient information distinct
+
+Task-specific findings stay with the task. Reusable memory is reserved for
+validated knowledge likely to apply elsewhere. Transient shell output and
+temporary execution checklists stay local unless they change a decision or must
+survive resumption. Existing user and repository instructions remain in force;
+an integration does not grant new authority to create issues, mutate other
+records, or broaden a task.

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

@@ -0,0 +1,45 @@
+# Creating useful issues
+
+> Adapted from [Beads marketplace-main `ISSUE_CREATION.md`](https://github.com/gastownhall/beads/blob/4a67d0d0288c1b4ee23e17fc896f47616931ba2d/plugins/beads/skills/beads/resources/ISSUE_CREATION.md).
+
+Create a durable issue when work needs its own assignment, dependencies,
+multi-session history, or acceptance record, and only when the existing authority
+allows creation. Do not create one for every retry, note, or discovered idea.
+Discovery may be reported without being worked; a `discovered-from` edge does
+not authorize the new issue.
+
+## Write for the next executor
+
+- **Title:** a specific outcome or problem.
+- **Description:** why the work exists, relevant context, and boundaries.
+- **Design:** the intended approach and important constraints.
+- **Acceptance:** observable conditions that define completion.
+- **Notes:** current progress and later checkpoints, appended as work proceeds.
+
+Do not treat a proposed approach as an acceptance test. Avoid secrets, copied
+logs, vague “investigate” titles without a question, and unsupported promises.
+Leave new work unassigned unless an assignment is intentional. If a human owns
+the work, assign that person deliberately; an agent actor is not proof of
+permission.
+
+Keep design and acceptance distinct: design records a candidate approach and
+trade-offs that may change; acceptance states a testable outcome that remains
+true if the implementation changes. For example, “reuse the current parser if
+it handles quoted fields” is design; “quoted commas and quotes round-trip in the
+export” is acceptance. Put the former in `--design` and the latter in
+`--acceptance`.
+
+Current syntax comes from `bd create --help`. A write must use the actual
+executor actor, for example:
+
+```sh
+bd create "Clarify retry behavior" --type=task --priority=2 \
+  --description="Record the user-visible issue and affected path." \
+  --design="Trace the current behavior and document the supported correction." \
+  --acceptance="The behavior and validation evidence are recorded." \
+  --actor='<executor-actor>' --sandbox --json
+```
+
+Before creating linked work, inspect the parent and verify dependency direction.
+Keep planning and implementation ownership distinct when the project assigns
+them to different people.

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

@@ -0,0 +1,65 @@
+# Molecules, formulas, and wisps
+
+> Adapted from [Beads marketplace-main `MOLECULES.md`](https://github.com/gastownhall/beads/blob/4a67d0d0288c1b4ee23e17fc896f47616931ba2d/plugins/beads/skills/beads/resources/MOLECULES.md).
+
+The current CLI describes formulas as workflow sources, protos as reusable
+templates, molecules as instantiated work, and wisps as ephemeral workflows.
+Use these only when their lifecycle solves a real project need; a normal issue
+graph is clearer for one-off work.
+
+## Decide before instantiating
+
+| Question | Choose |
+| --- | --- |
+| Is this one-off work with a clear owner and no template need? | A normal issue graph. |
+| Must each step and its audit history remain durable? | Persistent molecule with durable audit history from an inspected formula/proto. |
+| Is the work short-lived and low-audit, with an agreed way to preserve findings? | Wisp, only with explicit lifecycle authority. |
+| Is the workflow repeatable and already validated? | Consider distilling a formula after preserving its evidence and lessons. |
+
+Inspect the formula's gates, dependencies, variables, and children before
+creating work. Confirm that every step fits the authorized scope. Keep generated
+children aligned with the intended parent acceptance; closed children do not
+prove the parent outcome.
+
+## Example: approved review wisp
+
+When a bounded review is authorized as temporary and an existing review proto
+fits the scope, create the wisp, inspect its instantiated steps, and retain only
+validated findings:
+
+```sh
+bd mol wisp create '<review-proto-id>' --var 'candidate=<revision>' \
+  --actor='<executor-actor>' --sandbox --json
+bd mol show '<wisp-id>'
+```
+
+If the review produced reusable evidence or actionable findings, summarize and
+promote the result to a durable digest:
+
+```sh
+bd mol squash '<wisp-id>' \
+  --summary="Candidate <revision>: verified findings and evidence references" \
+  --actor='<executor-actor>' --sandbox --json
+```
+
+If the wisp contains only noise with no future value, burn it only when that
+deletion is explicitly authorized; this leaves no digest:
+
+```sh
+bd mol burn '<wisp-id>' --actor='<executor-actor>' --sandbox --json
+```
+
+These verbs and phase effects are confirmed by installed subcommand help. A
+wisp is ephemeral and not synced via Git; do not use it as the only home for
+required acceptance evidence. A digest is a summary, not proof that findings
+were independently validated or that a parent issue is accepted.
+
+Distilling a formula is useful only after a workflow has proved repeatable.
+Retain validation and lessons in the reusable template, not accidental details
+from one run. Bonding workflows can create large graphs; inspect the result and
+ownership before proceeding. Do not pour, bond, squash, burn, or distill as
+automatic setup or background orchestration.
+
+Use `bd formula --help` and `bd mol --help`, then each relevant subcommand's
+help, for current syntax. These are state changes; keep the actual executor
+actor explicit.

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

@@ -0,0 +1,43 @@
+# Common execution patterns
+
+> Adapted from [Beads marketplace-main `PATTERNS.md`](https://github.com/gastownhall/beads/blob/4a67d0d0288c1b4ee23e17fc896f47616931ba2d/plugins/beads/skills/beads/resources/PATTERNS.md).
+
+## Start with the actual request
+
+Read the assigned issue, parent decisions, relevant dependencies, and current
+notes. Distinguish the requested result from a suggested implementation. A
+ready issue or an open side quest does not itself authorize work.
+
+## Record a side discovery without expanding scope
+
+When a new concern appears, preserve enough evidence to explain it. If recording
+it is authorized, create a concise issue and link its provenance. Continue only
+if the current authorization explicitly includes it. Otherwise finish the
+assigned work, report the discovery, and stop.
+
+## Resume a multi-session task
+
+Read the latest appended checkpoint and relevant reusable memory. Reconfirm the
+state from the issue or current evidence instead of assuming the prior next step
+still applies. Preserve rejected approaches so the next executor does not repeat
+them.
+
+For research or debugging, keep the hypothesis, the attempt, and the evidence
+that changed the conclusion together. A rejected hypothesis is useful when its
+failure is explained; an unexplained “tried X” is not. If the changed conclusion
+creates separate durable work, record its source only when authorized. Discovery
+does not by itself make that work a blocker or assign it to the current executor.
+
+## Change status and close carefully
+
+Use the installed CLI's valid transitions. Claim only the item you are
+authorized to execute; keep the actual executor actor on claim, updates, and
+heartbeats. Before closure, compare the deliverable with acceptance criteria and
+record validation results. If a blocker or failed check remains, report it and
+leave the state accurate. If someone else owns acceptance, return the evidence
+instead of closing on their behalf.
+
+There is no mandatory one-issue-per-session cadence. Keep each Bead's evidence
+clear, while following an explicitly authorized multi-item batch where one was
+granted. Use `bd '<command>' --help` for current syntax; do not use old MCP-only
+examples or replace notes during ordinary checkpoints.

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

@@ -0,0 +1,83 @@
+# Resumability and recovery
+
+> Adapted from [Beads marketplace-main `RESUMABILITY.md`](https://github.com/gastownhall/beads/blob/4a67d0d0288c1b4ee23e17fc896f47616931ba2d/plugins/beads/skills/beads/resources/RESUMABILITY.md).
+
+A future executor needs the state of the work, not a transcript. At meaningful
+transitions preserve:
+
+1. what was attempted and why;
+2. the observed result and evidence location;
+3. the decision or hypothesis that changed;
+4. what remains blocked or uncertain; and
+5. one concrete next action within the assigned scope.
+
+Append this checkpoint to the issue so earlier attempts remain visible. Do not
+copy full logs, secrets, or unverified conclusions. An abrupt process stop can
+prevent a final write, so checkpoint after important results instead of relying
+on end-of-session cleanup.
+
+## Example: make a thin checkpoint resumable
+
+### Before checkpoint
+
+```text
+Tried the export change; the test still fails.
+```
+
+### After checkpoint
+
+```text
+Attempted: split export rows on commas.
+Observed evidence: tests/export.test.ts, case quoted-comma still fails;
+  fixture: tests/fixtures/quoted-comma.csv.
+Rationale: commas inside quoted fields are data, so splitting cannot work.
+Blocker: confirm whether the existing parser exposes a streaming API.
+Next: inspect the parser contract, then add a regression test before changing it.
+```
+
+The second checkpoint carries the approach, observed evidence and its location,
+the decision it supports, the remaining uncertainty, and one next action. Use a
+small handoff shape when the example is too detailed:
+
+### Minimal handoff template
+
+```text
+Task and scope:
+Attempt and result (evidence/reference):
+Decision and rationale:
+Blocker or uncertainty:
+Next authorized step:
+```
+
+Add a tested minimal command or code snippet only when the next executor needs
+it to reproduce a hard-to-infer result or response shape. Mark what was actually
+run and where. Otherwise link to the relevant test or document and summarize the
+result. Do not paste raw logs, giant JSON dumps, credentials, or speculative
+snippets; acceptance describes the observable outcome, while notes retain
+implementation discoveries and rationale.
+
+## Resume safely
+
+For a cold start or after compaction, recover the assigned work rather than
+selecting fresh work from `bd ready`:
+
+```sh
+bd list --status=in_progress --assignee='<executor-actor>' --json
+bd show '<issue-id>' --long --json
+```
+
+Use your actual assignment actor for the assignee filter. If the assignment
+already gives an exact issue ID, show that issue directly; an empty list is not
+permission to claim another task. Read the latest appended checkpoint and earlier
+notes for attempts, evidence, decisions, blockers, and the next authorized step.
+Retrieve only relevant reusable memory, then verify current assignment, status,
+dependencies, and time-sensitive evidence before acting. The issue notes explain
+work on this item; memory carries validated learning beyond it. Neither should
+override current user or repository instructions.
+
+Treat missing context, failed retrieval, and deliberately withheld context as
+different outcomes. A permission or migration hold is not an invitation to run a
+manual fallback. If a write timed out, read the issue before retrying; the first
+write may have landed. Preserve uncertainty explicitly until it is resolved.
+
+Use the current CLI syntax from `bd prime` and command help when authorized.

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

@@ -0,0 +1,19 @@
+# Static reference data
+
+> Adapted from [Beads marketplace-main `STATIC_DATA.md`](https://github.com/gastownhall/beads/blob/4a67d0d0288c1b4ee23e17fc896f47616931ba2d/plugins/beads/skills/beads/resources/STATIC_DATA.md).
+
+Beads is primarily for work with ownership, status, dependencies, and a useful
+lifecycle. Avoid turning every glossary term, configuration value, or mostly
+static reference entry into an open work issue. Use documentation or an existing
+project knowledge system when it provides clearer name-based browsing.
+
+Validated reusable conventions can belong in Beads memory when they are likely
+to help future work and do not already exist. Search first, record scope and
+evidence, and correct stale knowledge deliberately. Do not use memory as a dump
+of all project facts or as a substitute for authoritative specifications.
+
+If a team has a real need for structured reference entities with relationships
+and ownership, design that use separately. Keep it separated from active work
+where possible and verify the installed CLI's search and query capabilities
+before choosing it. This advanced pattern does not authorize a new database,
+initialization, or schema change.

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

@@ -0,0 +1,49 @@
+# Troubleshooting and stop conditions
+
+> Curated replacement for [Beads marketplace-main `TROUBLESHOOTING.md`](https://github.com/gastownhall/beads/blob/4a67d0d0288c1b4ee23e17fc896f47616931ba2d/plugins/beads/skills/beads/resources/TROUBLESHOOTING.md). Legacy repair examples are not carried forward where they imply setup, server changes, or automatic repair.
+
+## Context is absent, failed, or withheld
+
+First identify which state actually occurred. If no context was provided, retrieve
+current CLI context only when permitted and no hold is active. If retrieval
+failed, report the error and preserve the task's last known state. If a migration
+or permission guard withheld context, stop; do not run `bd prime`, a different
+CLI surface, or another agent as a bypass.
+
+## A command or flag is unknown
+
+Use `bd --help` and `bd '<command>' --help` to inspect the installed CLI. Do not
+guess a flag from an old example, invoke a similarly named command, or assume an
+MCP interface. If a workflow depends on an unavailable command, explain the
+limitation and use a documented replacement only when it preserves the needed
+semantics. The specialized `bd agent` and `bd slot` commands are absent from the
+inspected CLI; see [AGENTS.md](AGENTS.md).
+
+## Store, migration, or routing problem
+
+If the CLI reports no store, an outdated schema, an unexpected location, or a
+redirect, do not initialize, migrate, reroute, repair, or synchronize it
+automatically. Preserve the diagnostic and ask the authorized owner to choose a
+supported recovery. The plugin's context guard is not permission to bypass the
+same restriction through a shell command.
+
+## Permission denial or external access prompt
+
+Respect the decision. Do not switch to another tool, path, or identity to obtain
+the same denied result. If a referenced guidance file is unreachable, state that
+and continue only if the remaining task can be done safely and accurately.
+
+## Empty result, failed read, or uncertain write
+
+An empty successful query differs from an error. Report the actual result, not
+the exit code alone. After a timeout or interrupted write, inspect the issue or
+memory before retrying; the write may have landed. Do not blindly repeat a
+create, claim, remember, or close operation.
+
+## Lost claim or blocked task
+
+Read the current assignee, status, and lease before continuing. If another actor
+owns it or the claim was reclaimed, stop writes and coordinate a deliberate
+handoff. Never force-reassign yourself or fall back to the human Git identity.
+Record unresolved acceptance, missing evidence, and the next authorized action
+in the handoff.

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

@@ -0,0 +1,64 @@
+# Workflows and checkpoints
+
+> Adapted from [Beads marketplace-main `WORKFLOWS.md`](https://github.com/gastownhall/beads/blob/4a67d0d0288c1b4ee23e17fc896f47616931ba2d/plugins/beads/skills/beads/resources/WORKFLOWS.md). The append policy below resolves conflicting upstream examples: checkpoints append; replacing notes is deliberate.
+
+## Begin with the current context
+
+Use current Beads context if it was supplied. Read the target issue, dependencies,
+existing notes, and relevant memory before choosing an action. Confirm the exact
+assignment and authority. Do not treat `ready` output as an assignment or
+permission to work every listed item.
+
+For an authorized task, claim it atomically with the actual executor actor. Keep
+that actor on all subsequent writes and heartbeats. Direct execution is fine for
+small tasks; use delegation where it improves the work, carrying a bounded scope
+and the real delegate actor. Do not impose a one-item-per-invocation loop or
+delegate by command count.
+
+## Checkpoint at useful transitions
+
+Append when a failed approach changes the next step, a finding is validated, a
+decision changes, work becomes blocked, a child returns, or a session may stop.
+Include the attempt, result, why it matters, evidence, blocker, and next action.
+Use `--append-notes`, for example:
+
+```sh
+bd update '<id>' --append-notes="Validated …; evidence …; next …" --actor='<executor-actor>' --sandbox --json
+```
+
+This is an append. Do not use the replacing `--notes` field as the default
+checkpoint. If nothing material changed, do not write a redundant note just to
+meet a quota. Avoid credentials, raw logs, and claims unsupported by evidence.
+
+## Capture reusable knowledge selectively
+
+Task details and short-lived failures belong with the issue. Search existing
+memory before recording a validated lesson that will likely help elsewhere.
+Include its scope and evidence, use the actual executor actor for memory writes,
+and amend stale knowledge intentionally. Do not save every task outcome as
+global memory.
+
+## Validate and hand off
+
+Check the issue's acceptance conditions, run authorized relevant validation,
+and record exact results. If a parent or human owns acceptance, return the
+evidence without closing for them. A delegate returns attempts, results,
+rationale, validation, blockers, next action, and useful record references; the
+parent reconciles before continuing. If the task was an exact assignment, stop
+there. Explicitly authorized batches may continue within their stated scope;
+new discoveries never expand it.
+
+When context is held or a required guarantee is missing, stop the affected path
+and state the limitation. Do not switch to a manual prime, unregistered tool,
+automatic setup, sync, or permission change to complete it.
+
+## Planning and independently owned review
+
+Follow project-owned planning and review policy. Track substantive multi-session
+or delegated planning in one bounded planning item, separate from implementation;
+a quick draft need not get its own ticket. Give substantive independently owned
+review one bounded review item linked to planning and the exact candidate. Reuse
+the same review item through corrections and rechecks. Record actual reviewer
+actor/session, verdict, findings and evidence without retroactive claims.
+Planning/review closure needs its own evidence and owner acceptance; readiness
+alone never authorizes dispatch, implementation, release or deployment.

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

@@ -0,0 +1,19 @@
+# Worktree routing
+
+> Adapted from [Beads marketplace-main `WORKTREES.md`](https://github.com/gastownhall/beads/blob/4a67d0d0288c1b4ee23e17fc896f47616931ba2d/plugins/beads/skills/beads/resources/WORKTREES.md).
+
+A worktree can isolate code changes while retaining a repository's shared Beads
+database. The installed CLI documents common-directory discovery for its
+worktree command. Do not assume that every unrelated checkout, redirected
+workspace, or custom route shares the same store.
+
+Use a worktree only when isolation helps and its creation is authorized. Before
+changing issues, confirm which repository and Beads location the CLI resolved.
+Keep the assignment and explicit executor actor the same across the worktree;
+Git identity is not a Beads actor. Do not initialize a separate store, change
+routes, or copy database state to make a task appear ready.
+
+Use `bd worktree --help` and relevant subcommand help for current commands and
+safety checks. Inspect local changes before removal, preserve work that is not
+yours, and remove only a worktree whose cleanup is authorized. This resource
+does not create or clean up a worktree automatically.