clikit-plugin 0.3.11 → 0.3.13

package/dist/tools/augment.d.ts

@@ -0,0 +1,45 @@
+export type AugmentRewriteMode = "plain" | "execution-contract";
+export type AugmentTaskIntent = "implement" | "debug" | "refactor" | "review" | "research" | "docs" | "test-fix" | "explain" | "general";
+export type PromptLeverageIntensity = "Light" | "Standard" | "Deep";
+export interface PromptLeverageBlocks {
+    objective: string;
+    context: string;
+    workStyle: string;
+    toolRules: string;
+    outputContract: string;
+    verification: string;
+    doneCriteria: string;
+}
+export interface AugmentPromptOptions {
+    mode?: AugmentRewriteMode | "auto";
+}
+export interface AugmentRefinementInput {
+    original: string;
+    enhanced: string;
+    intent: AugmentTaskIntent;
+    mode: AugmentRewriteMode;
+    intensity: PromptLeverageIntensity;
+    blocks: PromptLeverageBlocks;
+}
+export interface AugmentRefinementOptions extends AugmentPromptOptions {
+    refine?: (input: AugmentRefinementInput) => Promise<string | undefined>;
+}
+export interface AugmentPromptResult {
+    original: string;
+    enhanced: string;
+    intent: AugmentTaskIntent;
+    mode: AugmentRewriteMode;
+    intensity: PromptLeverageIntensity;
+    blocks: PromptLeverageBlocks;
+    enhancementSource?: "deterministic" | "llm";
+    fallbackReason?: string;
+}
+export declare function detectTaskIntent(draft: string): AugmentTaskIntent;
+export declare function resolveRewriteMode(configuredMode: AugmentRewriteMode | "auto", intent: AugmentTaskIntent): AugmentRewriteMode;
+export declare function inferIntensity(draft: string, intent: AugmentTaskIntent): PromptLeverageIntensity;
+export declare function buildPromptLeverageBlocks(draft: string, intent: AugmentTaskIntent, intensity: PromptLeverageIntensity): PromptLeverageBlocks;
+export declare function augmentPrompt(draft: string, options?: AugmentPromptOptions): AugmentPromptResult;
+export declare function augmentPromptWithRefinement(draft: string, options?: AugmentRefinementOptions): Promise<AugmentPromptResult>;
+export declare function formatExecutionContract(draft: string, blocks: PromptLeverageBlocks): string;
+export declare function formatPlainRewrite(draft: string, intent: AugmentTaskIntent, outputContract: string): string;
+//# sourceMappingURL=augment.d.ts.map

package/dist/tools/augment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"augment.d.ts","sourceRoot":"","sources":["../../src/tools/augment.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,oBAAoB,CAAC;AAEhE,MAAM,MAAM,iBAAiB,GACzB,WAAW,GACX,OAAO,GACP,UAAU,GACV,QAAQ,GACR,UAAU,GACV,MAAM,GACN,UAAU,GACV,SAAS,GACT,SAAS,CAAC;AAEd,MAAM,MAAM,uBAAuB,GAAG,OAAO,GAAG,UAAU,GAAG,MAAM,CAAC;AAEpE,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,CAAC,EAAE,kBAAkB,GAAG,MAAM,CAAC;CACpC;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,IAAI,EAAE,kBAAkB,CAAC;IACzB,SAAS,EAAE,uBAAuB,CAAC;IACnC,MAAM,EAAE,oBAAoB,CAAC;CAC9B;AAED,MAAM,WAAW,wBAAyB,SAAQ,oBAAoB;IACpE,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,sBAAsB,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;CACzE;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,IAAI,EAAE,kBAAkB,CAAC;IACzB,SAAS,EAAE,uBAAuB,CAAC;IACnC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,iBAAiB,CAAC,EAAE,eAAe,GAAG,KAAK,CAAC;IAC5C,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAmJD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,iBAAiB,CAajE;AAED,wBAAgB,kBAAkB,CAChC,cAAc,EAAE,kBAAkB,GAAG,MAAM,EAC3C,MAAM,EAAE,iBAAiB,GACxB,kBAAkB,CAMpB;AAED,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,iBAAiB,GACxB,uBAAuB,CAOzB;AAED,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,iBAAiB,EACzB,SAAS,EAAE,uBAAuB,GACjC,oBAAoB,CAUtB;AAED,wBAAgB,aAAa,CAC3B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,oBAAyB,GACjC,mBAAmB,CAuBrB;AAED,wBAAsB,2BAA2B,CAC/C,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAAC,mBAAmB,CAAC,CAqC9B;AAED,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,oBAAoB,GAC3B,MAAM,CAgBR;AAED,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,iBAAiB,EACzB,cAAc,EAAE,MAAM,GACrB,MAAM,CAkBR"}

package/dist/tools/index.d.ts

@@ -2,4 +2,5 @@ export { memoryRead, memorySearch, memoryGet, memoryTimeline, memoryUpdate, memo
 export { createObservation, getObservationsByType, getObservationsByBead, linkObservations, type ObservationParams, type ObservationResult, } from "./observation";
 export { contextSummary, type ContextSummaryParams, type ContextSummaryResult, } from "./context-summary";
 export { cassMemoryContext, cassMemoryMark, cassMemoryReflect, cassMemoryDoctor, cassMemoryOutcome, cassIsAvailable, cassResetCache, type CassMemoryContextParams, type CassMemoryMarkParams, type CassMemoryReflectParams, type CassMemoryOutcomeParams, type CassMemoryDoctorParams, type CassMemoryExecOptions, type CassMemoryResult, } from "./cass-memory";
+export { augmentPrompt, buildPromptLeverageBlocks, detectTaskIntent, formatExecutionContract, formatPlainRewrite, inferIntensity, resolveRewriteMode, type AugmentPromptOptions, type AugmentPromptResult, type AugmentRewriteMode, type AugmentTaskIntent, type PromptLeverageBlocks, type PromptLeverageIntensity, } from "./augment";
 //# sourceMappingURL=index.d.ts.map

package/dist/tools/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,UAAU,EACV,YAAY,EACZ,SAAS,EACT,cAAc,EACd,YAAY,EACZ,WAAW,EACX,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,GACvB,MAAM,UAAU,CAAC;AAGlB,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,qBAAqB,EACrB,gBAAgB,EAChB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,GACvB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,cAAc,EACd,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,GAC1B,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,EAC5B,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,GACtB,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,UAAU,EACV,YAAY,EACZ,SAAS,EACT,cAAc,EACd,YAAY,EACZ,WAAW,EACX,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,GACvB,MAAM,UAAU,CAAC;AAGlB,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,qBAAqB,EACrB,gBAAgB,EAChB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,GACvB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,cAAc,EACd,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,GAC1B,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,EAC5B,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,GACtB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,aAAa,EACb,yBAAyB,EACzB,gBAAgB,EAChB,uBAAuB,EACvB,kBAAkB,EAClB,cAAc,EACd,kBAAkB,EAClB,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,GAC7B,MAAM,WAAW,CAAC"}

package/dist/tui.d.ts

@@ -0,0 +1,4 @@
+import type { TuiPluginModule } from "@opencode-ai/plugin/tui";
+declare const CliKitTuiPlugin: TuiPluginModule;
+export default CliKitTuiPlugin;
+//# sourceMappingURL=tui.d.ts.map

package/dist/tui.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tui.d.ts","sourceRoot":"","sources":["../src/tui.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAE/D,QAAA,MAAM,eAAe,EAAE,eAStB,CAAC;AAEF,eAAe,eAAe,CAAC"}

package/dist/tui.js

@@ -0,0 +1,38 @@
+// @bun
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __toESM = (mod, isNodeMode, target) => {
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod))
+    if (!__hasOwnProp.call(to, key))
+      __defProp(to, key, {
+        get: () => mod[key],
+        enumerable: true
+      });
+  return to;
+};
+var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __require = import.meta.require;
+
+// src/tui.ts
+var CliKitTuiPlugin = {
+  id: "clikit-tui",
+  async tui() {}
+};
+var tui_default = CliKitTuiPlugin;
+export {
+  tui_default as default
+};

package/memory/_templates/discussion.md

@@ -4,7 +4,7 @@ Use this template when documenting clarified intent before `/create`.
 
 **Output path:** `.opencode/memory/discussions/YYYY-MM-DD-<topic>.md`
 
-This template is optimized for **pre-create discussion**: the report should reduce guessing for `/create`, `/research`, and `/start` by separating locked intent from unresolved technical work.
+This template is optimized for an **interview-style pre-create discussion**: the report should reduce guessing for `/create`, `/research`, and `/start` by separating what the interview already resolved from what still needs downstream work.
 
 ---
 
@@ -22,6 +22,7 @@ bead_id: [optional]
 **Goal:** [What outcome the user wants]
 **Why now:** [Why this needs to be clarified before planning]
 **Assumptions:** [Any assumptions made due to incomplete context, or "None"]
+**Interview focus:** [Which gray areas the discussion prioritized first]
 
 ---
 
@@ -34,6 +35,8 @@ bead_id: [optional]
 
 ## Locked Decisions
 
+Record only decisions that the interview actually resolved. If a topic stayed uncertain, move it to **Open Questions** instead of implying certainty.
+
 ### Decision 1: [Title]
 - **Decision:** [Confirmed choice]
 - **Why it matters:** [Why `/create` or `/research` must preserve it]
@@ -48,6 +51,8 @@ bead_id: [optional]
 
 ## Confirmed Assumptions
 
+Use this section for defaults accepted during the interview because prior artifacts or codebase evidence made them reasonable.
+
 - **Assumption:** [What was assumed]
   - **Confirmed by:** [user / artifact / codebase pattern]
   - **Notes:** [Any caveat]
@@ -56,6 +61,8 @@ bead_id: [optional]
 
 ## Open Questions
 
+Use this section for planning-critical ambiguity that the interview intentionally left unresolved.
+
 - **Question:** [Unresolved item]
   - **Why unresolved:** [Reason]
   - **Next owner:** `/create` | `/research` | user
@@ -88,4 +95,5 @@ bead_id: [optional]
 ## Planning Notes
 
 - [Specific instruction `/create` should preserve in the plan]
+- [If useful: which question order or interview framing worked best for this topic]
 ```

package/package.json

@@ -1,18 +1,22 @@
 {
   "name": "clikit-plugin",
-  "version": "0.3.11",
-  "description": "OpenCode plugin — 7 agents, 14 commands, 26 skills, 11 hooks",
+  "version": "0.3.13",
+  "description": "Workflow layer for OpenCode — agents, commands, hooks, memory, and verification",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {
-    "clikit": "./dist/cli.js"
+    "clikit": "dist/cli.js"
   },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./tui": {
+      "types": "./dist/tui.d.ts",
+      "import": "./dist/tui.js"
+    },
     "./schema.json": "./dist/clikit.schema.json"
   },
   "files": [
@@ -20,16 +24,17 @@
     "src/agents",
     "skill",
     "command",
-    "memory",
+    "memory/_templates",
+    "memory/project",
     "AGENTS.md",
     "README.md"
   ],
   "scripts": {
-    "build": "bun build src/index.ts src/cli.ts --outdir dist --target bun --format esm && tsc --emitDeclarationOnly && cp src/clikit.schema.json dist/clikit.schema.json",
-    "clean": "rm -rf dist",
+    "build": "bun build src/index.ts src/cli.ts src/tui.ts --outdir dist --target bun --format esm && tsc --emitDeclarationOnly && cp src/clikit.schema.json dist/clikit.schema.json",
+    "clean": "node -e \"const fs=require('fs'); fs.rmSync('dist',{recursive:true,force:true});\"",
     "lint": "tsc --noEmit",
     "prepublishOnly": "bun run clean && bun run build",
-    "postpublish": "rm -rf ~/.cache/opencode/node_modules/clikit-plugin && rm -f ~/.cache/opencode/bun.lock && echo '✓ Cleared OpenCode plugin cache — next start will install fresh'",
+    "postpublish": "node -e \"const fs=require('fs'); const os=require('os'); const path=require('path'); const root=path.join(os.homedir(),'.cache','opencode'); fs.rmSync(path.join(root,'node_modules','clikit-plugin'),{recursive:true,force:true}); fs.rmSync(path.join(root,'bun.lock'),{force:true}); console.log('✓ Cleared OpenCode plugin cache — next start will install fresh');\"",
     "typecheck": "tsc --noEmit",
     "verify": "bun run lint && bun run build",
     "dev": "bun run build --watch"

package/skill/beads/SKILL.md

@@ -1,33 +1,42 @@
 ---
 name: beads
-description: Use for multi-agent task coordination, file locking, and dependency management via beads-village MCP tools.
+description: Use for multi-agent task coordination with `br` and optional legacy beads-village helpers.
 ---
 
 # Beads
 
-**AI agents: always use `beads-village_*` MCP tools — never shell `bd` commands.**
+**Preferred tracker:** `br` (`beads_rust`) with `.beads/` storage.
+
+Use `br` CLI first for task state. Use `beads-village_*` only as optional legacy compatibility when reservations, inbox-style messaging, or existing local workflows still depend on it.
 
 ## Session Cycle
 
 ```
-init → ls(ready) → show → claim → reserve(files) → work → done
+br init → br ready --json → br show <id> --json → br update <id> --status in_progress --claim → work → br close <id> --reason "Completed" --json → br sync --flush-only
 ```
 
-## Core Tools
-
-| Tool | Purpose |
-|------|---------|
-| `beads-village_init(team=…)` | **First call every session** |
-| `beads-village_ls(status="ready")` | List unblocked tasks |
-| `beads-village_show(id)` | Read task details |
-| `beads-village_claim()` | Claim next ready task |
-| `beads-village_add(title, typ, pri, tags, deps)` | Create issue |
-| `beads-village_reserve(paths, reason)` | Lock files before editing |
-| `beads-village_done(id, msg)` | Complete + auto-release locks |
-| `beads-village_msg(subj, global=true, to="all")` | Broadcast |
-| `beads-village_inbox(unread=true)` | Read messages |
-| `beads-village_status(include_agents=true)` | Workspace overview |
-| `beads-village_sync()` | Git push/pull |
+## Preferred Commands
+
+| Command | Purpose |
+|---------|---------|
+| `br init` | Initialize `.beads/` if missing |
+| `br ready --json` | List unblocked tasks |
+| `br show <id> --json` | Read task details |
+| `br create --title ... --description ... --type ... --priority ...` | Create issue |
+| `br update <id> --status in_progress --claim` | Claim/start work |
+| `br close <id> --reason "Completed" --json` | Complete work |
+| `br sync --flush-only` | Flush `.beads/` state before commit/push |
+| `br sync --import-only` | Re-import `.beads/` state after pull/rebase |
+
+## Optional Legacy MCP Helpers
+
+| Tool | Use only when... |
+|------|------------------|
+| `beads-village_reserve(paths, reason)` | You need explicit file reservations in a shared workspace |
+| `beads-village_reservations()` | You need to inspect existing locks |
+| `beads-village_inbox(unread=true)` | Your team still uses village-style messaging |
+| `beads-village_status(include_agents=true)` | You need legacy workspace/agent discovery |
+| `beads-village_msg(...)` | You need a compatibility broadcast path |
 
 ## Issue Schema
 
@@ -35,7 +44,7 @@ init → ls(ready) → show → claim → reserve(files) → work → done
 typ:  task | bug | feature | epic | chore
 pri:  0=critical  1=high  2=normal  3=low  4=backlog
 tags: fe | be | devops | qa
-deps: ["bv-id"]  or  ["discovered-from:bv-id"]
+deps: ["br-id"]  or  ["discovered-from:br-id"]
 ```
 
 ## When to Create Issues
@@ -43,13 +52,4 @@ deps: ["bv-id"]  or  ["discovered-from:bv-id"]
 - Trivial (< 2 min, 1-line): skip, just do it
 - Non-trivial (2+ min, 2+ files): create issue first, then work
 
-## v1.3 API — Correct Names
-
-| ❌ Old | ✅ Correct |
-|--------|-----------|
-| `beads-village_ready` | `beads-village_ls(status="ready")` |
-| `beads-village_broadcast` | `beads-village_msg(global=true, to="all")` |
-| `beads-village_discover` | `beads-village_status(include_agents=true)` |
-
-See [references/api-reference.md](references/api-reference.md) for full tool params and examples.
-- MCP: `beads-village` — see [mcp.json](mcp.json)
+Legacy `beads-village` remains optional compatibility only. Do not make it a hard prerequisite in new workflows.

package/skill/beads/mcp.json

@@ -3,7 +3,7 @@
     "beads-village": {
       "type": "local",
       "command": ["npx", "-y", "beads-village"],
-      "description": "Multi-agent task coordination, file locking, issue tracking",
+      "description": "Optional legacy Beads Village compatibility for reservations and messaging",
       "tools": [
         "beads-village_init",
         "beads-village_add",

package/skill/beads/references/api-reference.md

@@ -1,4 +1,7 @@
-# Beads API Reference
+# Legacy Beads Village API Reference
+
+This reference documents the optional `beads-village_*` MCP helpers only.
+For primary task tracking, use `br` CLI first.
 
 ## Full Tool Parameters
 
@@ -38,7 +41,7 @@ importance: string
 thread:     string
 ```
 
-## Example: Build Agent Session
+## Example: Legacy Compatibility Session
 
 ```
 beads-village_init(team="myproject")
@@ -56,9 +59,11 @@ beads-village_done(id="bv-42", msg="Fixed null check in token validation")
 beads-village_sync()
 ```
 
-## File Locking Protocol
+## File Locking Protocol (optional legacy)
 
 1. `beads-village_reservations()` — check what's locked before editing
 2. `beads-village_reserve(paths=[…])` — lock your files
 3. TTL default: 10 min — extend for longer tasks
 4. `beads-village_done()` — auto-releases all locks, no manual release needed
+
+When possible, prefer the `br` workflow documented in `skill/beads/SKILL.md` and use these helpers only when your local runtime still depends on Beads Village.

package/src/agents/AGENTS.md

@@ -2,6 +2,8 @@
 
 Each `.md` file in this directory defines an agent. The frontmatter sets model, tools, and permissions. The markdown body becomes the agent's system prompt. Loaded by `index.ts` using gray-matter.
 
+> Permission model note: `tools.*` exposes capability, while `permission.*` authorizes whether that capability may run. For file changes, OpenCode uses `permission.edit` as the canonical file-modification permission for `edit`, `write`, `patch`, and `multiedit`, so do not expect a separate `permission.write` key even when an agent frontmatter includes `tools.write: true`.
+
 ## Agent Roles
 
 | Agent | Role | Mode | Modifies Code? |
@@ -58,23 +60,23 @@ On-demand specialists (invoke only when needed):
 
 ## Beads Task Management
 
-Agents use **Beads** (`beads-village_*` MCP tools) for persistent task tracking.
+Agents prefer **Beads Rust** (`br`) for persistent task tracking. `beads-village_*` MCP tools are optional legacy helpers, not a mandatory dependency.
 
-**Policy:** Beads is used for non-trivial work. Trivial fixes (typo, single-line) skip Beads and execute immediately.
+**Policy:** Non-trivial work should use `.beads/` tracking when available. Trivial fixes (typo, single-line) skip Beads and execute immediately.
 
 **Core cycle:**
 ```
-beads-village_init → beads-village_status/include_agents → beads-village_inbox → beads-village_ls(status="ready") → beads-village_show(id) → beads-village_add (if needed) → beads-village_claim → beads-village_reservations → beads-village_reserve → work → verify → beads-village_done → beads-village_sync
+br init → br ready --json → br show/list --json → br create (if needed) → br update --status in_progress --claim → work → verify → br close → br sync --flush-only
 ```
 
 Execution happens one **Task Packet** at a time.
 
-- **@build**: Creates issues for non-trivial tasks, claims and closes on completion
-- **@build**: Reads issue context before claiming, reserves packet files, verifies evidence, and syncs on completion
-- **@plan**: Creates issues for every plan task after plan approval
-- **Subagents**: Read-only — do not create/modify Beads issues
+- **@build**: Creates issues for non-trivial tasks, claims/starts them, verifies evidence, and closes them on completion
+- **@build**: May use optional `beads-village_reserve` locks when the MCP is installed, but must not assume they exist
+- **@plan**: Creates task-tracking issues after plan approval when the workflow calls for it
+- **Subagents**: Read-only — do not create/modify `.beads/` task state unless explicitly instructed by a primary agent workflow
 
-`todowrite` is for in-session UI display only. Beads persists across sessions.
+`todowrite` is for in-session UI display only. `.beads/` persists across sessions.
 
 ## Delegation Rules
 

package/src/agents/build.md

@@ -38,7 +38,7 @@ permission:
 You are the Build Agent — the primary executor and orchestrator. You own the full execution lifecycle: intake → bootstrap → context → implement → verify → close.
 
 **Reference documents (read these before modifying behavior):**
-- Beads policy & API: `.opencode/AGENTS.md` → Beads section, `.opencode/skill/beads/SKILL.md`
+- Beads Rust policy & workflow: `.opencode/AGENTS.md` → Beads section, `.opencode/skill/beads/SKILL.md`
 - Explore/navigation policy: `.opencode/src/agents/explore.md`
 - Shared-workspace workflow (legacy skill path): `.opencode/skill/using-git-worktrees/SKILL.md`
 - Task Packet schema: `.opencode/schemas.md` 
@@ -84,7 +84,7 @@ Every message enters here first. Route silently before acting.
 
 ---
 
-## Phase 1 — Beads + Shared Workspace Bootstrap
+## Phase 1 — Task Tracking + Shared Workspace Bootstrap
 
 **Required for non-trivial code work. Skip for trivial (< 2 min, 1-line) fixes and read-only tasks.**
 
@@ -93,58 +93,58 @@ Every message enters here first. Route silently before acting.
 
 > Reference: `.opencode/AGENTS.md`, `skill/beads/SKILL.md`
 
-### Two layers — understand the difference
+### Preferred tracker model
 
 | Layer | Role | Interface |
 |-------|------|-----------|
-| **bd (control plane)** | Create/update/query issues and reflect shared-workspace task state. | `bd` CLI — shell commands |
-| **beads-village (execution loop)** | Init session, claim, lock files, execute, close. | `beads-village_*` MCP tools |
+| **`br` CLI (primary)** | Create, inspect, claim/start, close, and sync task state in `.beads/`. | `br` shell commands |
+| **`beads-village_*` MCP (optional legacy)** | Reservations, inbox-style messaging, and compatibility workflows when already installed. | `beads-village_*` tools |
 
-> **AI agents use `beads-village_*` MCP tools — never shell `bd` commands for claiming/locking/closing.**
+> Use `br` as the default tracker. Use `beads-village_*` only when the local runtime already provides it and you need compatibility features like reservations or inbox messaging.
 
 ---
 
-### 1.1 beads-village — Join workspace (always first)
+### 1.1 Initialize tracker state
+
+```bash
+br init                              # ensure .beads/ exists
+br ready --json                      # see claimable work
+br list --json                       # inspect current task inventory
+git status --short --branch          # inspect local state before editing
+```
+
+Optional legacy compatibility checks when the MCP exists:
 
 ```
-beads-village_init(team="project")          # ALWAYS first — every session, no exceptions
-beads-village_status(include_agents=true)   # who's active, workspace overview
-beads-village_inbox(unread=true)            # messages or blockers from other agents
-beads-village_ls(status="ready")            # what issues are unblocked and claimable
+beads-village_status(include_agents=true)
+beads-village_inbox(unread=true)
+beads-village_reservations()
 ```
 
 ---
 
-### 1.2 bd — Control plane (find or create issue)
+### 1.2 Find or create the tracked issue
 
-If the task matches an existing ready issue → go to §1.3 (claim).
+If the task already maps to an existing ready issue → go to §1.3.
 
-If no existing issue covers this task, create one:
+If no tracked issue covers this non-trivial task, create one:
 
-```
-beads-village_add(
-  title="<concise task title>",
-  typ="task|bug|feature|chore",
-  pri=<0=critical · 1=high · 2=normal · 3=low>,
-  tags=["be"|"fe"|"devops"|...],
-  desc="<goal, context, files expected>"
-)
+```bash
+br create --title "<concise task title>" --description "<goal, context, files expected>" --type task --priority <0-4>
 ```
 
-**No bd issue → no execution for non-trivial tasks.**
+**No tracked issue → no execution for non-trivial tasks when `br` is available.**
 
 ---
 
-### 1.3 beads-village — Claim (read context first, then claim)
+### 1.3 Claim / start the issue
 
-```
-beads-village_show(<issue-id>)   # read full context BEFORE claiming
-beads-village_claim()            # claims the next ready task in the queue
+```bash
+br show <issue-id> --json                              # read full context BEFORE starting
+br update <issue-id> --status in_progress --claim      # claim / start work
 ```
 
-> ⚠️ `beads-village_claim()` claims by queue position, not by ID.
-> After calling it, immediately confirm via `beads-village_show` that the task you received is the one you intended.
-> If a different task was claimed, release it and coordinate with the user or other agents.
+If the tracker shows a different scope than expected, stop and coordinate before editing.
 
 ### 1.4 Shared workspace — guard the default-branch checkout
 
@@ -169,24 +169,16 @@ Shared-workspace rules:
 
 **No worktree is required or desired for non-trivial execution.**
 
-### 1.5 beads-village — File locking
+### 1.5 Optional file locking
 
-Check existing locks before touching anything:
+If legacy reservations are available, inspect and reserve before editing:
 
 ```
 beads-village_reservations()
+beads-village_reserve(paths=["<file1>", "<file2>"], reason="<issue-id>")
 ```
 
-Lock the files in scope:
-
-```
-beads-village_reserve(
-  paths=["<file1>", "<file2>"],
-  reason="<issue-id>"
-)
-```
-
-Locks auto-release when `beads-village_done` is called.
+If reservations are not available, use explicit `files_in_scope`, `git status`, and handoff discipline as the coordination primitive instead of blocking execution.
 
 ---
 
@@ -267,7 +259,7 @@ Work one packet at a time. Complete fully before starting the next.
 
 ### Rules
 
-- Only touch files declared in `files_in_scope` and reserved via `beads-village_reserve`
+- Only touch files declared in `files_in_scope`; if legacy reservations are available, reserve them before editing
 - If implementation requires a file outside scope: **stop and escalate** — do not self-expand
 - Follow any runtime workflow override injected at session start
 - Never suppress type errors (`as any`, `@ts-ignore`, `@ts-expect-error`)
@@ -302,8 +294,12 @@ Then persist the blocker — in this exact order:
    - what was tried (approach 1 and 2)
    - exact error output from each attempt
    - current state of changed files
-2. **Broadcast the blocker** so other agents don't re-claim the task:
+2. **Broadcast the blocker** so other agents do not duplicate the work:
    ```
+   # Preferred tracker update
+   br show <issue-id> --json
+
+   # Optional legacy broadcast when beads-village exists
    beads-village_msg(
      subj="<issue-id> blocked",
      body="<error summary + handoff path>",
@@ -339,7 +335,7 @@ All checks under both A and B must pass before outputting the Evidence Bundle.
 
 ### 4.2 Evidence Bundle (mandatory output)
 
-Before calling `beads-village_done`, output this block verbatim:
+Before closing the active tracked issue, output this block verbatim:
 
 ```
 ## Evidence Bundle
@@ -369,24 +365,26 @@ If any check in A or B fails: do **not** output the bundle — return to Phase 3
 
 ## Phase 5 — Close & Sync
 
-### 5.1 beads-village — Close execution loop
+### 5.1 Close execution loop
 
+```bash
+br close <issue-id> --reason "Completed" --json
 ```
-beads-village_done(
-  id="<issue-id>",
-  msg="<what was done, key files touched, any notable decisions>"
-)
-```
 
-This closes the execution loop and auto-releases all file locks.
+If optional legacy reservations were used, release or let them expire after completion.
+
+### 5.2 Sync tracker state
+
+After close, sync `.beads/` state so the shared workspace reflects the latest tracker data:
 
-### 5.2 bd — Control plane sync
+```bash
+br sync --flush-only
+```
 
-After done, sync state so other agents see the update:
+Optional legacy broadcast when the MCP exists:
 
 ```
-beads-village_sync()                         # push git-backed state to remote
-beads-village_msg(                           # optional: broadcast if blocking others
+beads-village_msg(
   subj="<issue-id> done",
   body="<summary>",
   global=true, to="all"
@@ -406,7 +404,7 @@ git push                         # publish shared-checkout updates after verific
 If a session ends before the task is complete, run `/handoff` — see `command/handoff.md` for the full procedure.
 
 Rules specific to mid-task handoff:
-- **Do not** call `beads-village_done` — leave the issue open so the next session can claim it
+- **Do not** call `br close` — leave the issue open so the next session can continue it
 - The shared workspace state stays intact for continuation
 
 ---
@@ -414,13 +412,13 @@ Rules specific to mid-task handoff:
 ## Guardrails
 
 **Always:**
-- Phase 1 (bd issue + shared-workspace checks) before any **non-trivial** code change
+- Phase 1 (tracked issue + shared-workspace checks) before any **non-trivial** code change
 - Output Evidence Bundle before closing
 - Work one packet at a time
 - Stay inside reserved file scope
 
 **Never:**
-- Execute non-trivial work without a bd issue
+- Execute non-trivial work without a tracked issue when `br` is available
 - Create a git worktree or per-task branch for routine non-trivial execution unless the user explicitly asks for it
 - Suppress type errors (`as any`, `@ts-ignore`)
 - Silently expand scope beyond `files_in_scope`