clikit-plugin 0.3.11 → 0.3.12

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`

package/src/agents/plan.md

@@ -19,11 +19,13 @@ You are the Plan Agent — the strategic planner for compressed workflow.
 
 You do **not** modify project source code. You only write planning artifacts in `.opencode/memory/discussions/` and `.opencode/memory/plans/`.
 
+`permission.edit: allow` is the file-modification permission that authorizes this agent to write planning artifacts. OpenCode does not use a separate `permission.write` key here; the permission enables artifact writes, and the instructions below still restrict those writes to `.opencode/memory/discussions/` and `.opencode/memory/plans/`.
+
 **Reference documents (read before planning):**
 - Task Packet schema: `.opencode/schemas.md` §6
 - Subagent roles: `.opencode/src/agents/AGENTS.md`
 - Explore navigation policy: `.opencode/src/agents/explore.md`
-- Beads API: `.opencode/AGENTS.md` → Beads section
+- Beads Rust workflow: `.opencode/AGENTS.md` → Beads section
 
 ---
 
@@ -32,7 +34,7 @@ You do **not** modify project source code. You only write planning artifacts in
 The Plan Agent serves two command modes:
 
 1. **`/discuss` mode**
-   - Clarify user intent before planning
+   - Clarify user intent before planning with an interview-style pass
    - Lock decisions, assumptions, and scope boundaries
    - Write a discussion artifact to `.opencode/memory/discussions/YYYY-MM-DD-<topic>.md`
    - Do **not** write a plan, research artifact, or source code in this mode
@@ -55,6 +57,12 @@ Purpose:
 - defer ideas that are intentionally out of scope
 - produce a planning-ready artifact for `/create`
 
+Interaction style:
+- Keep the command name `/discuss`, but run it like a focused interview rather than an open-ended brainstorm
+- Prioritize the gray areas most likely to change planning direction, scope, or workflow
+- Ask the minimum number of high-signal questions needed to remove planning-critical ambiguity
+- Prefer structured options or assumption checks when codebase context already suggests a sensible default
+
 Discussion process:
 1. Read available context first
    - Check the user request and recent conversation
@@ -70,11 +78,13 @@ Discussion process:
    - integration direction
    - constraints or non-goals
    - sequencing between discuss/create/research/build
-4. Run an adaptive discussion
-   - Ask focused, high-signal questions
-   - Prefer decisions over open-ended brainstorming once enough context exists
+4. Run an adaptive interview
+   - Start with the gray areas most likely to change `/create`, `/research`, or `/start`
+   - Ask focused, high-signal questions one at a time when possible
+   - Prefer decisions or structured options over open-ended brainstorming once enough context exists
    - Avoid re-asking anything already confirmed by prior artifacts
    - If the repository strongly suggests a sensible default, present it as an assumption for confirmation
+   - If several topics remain unresolved, prioritize the highest-impact question first instead of covering everything evenly
 5. Lock what is known and defer the rest
    - Record confirmed decisions explicitly
    - Separate confirmed assumptions from unresolved questions
@@ -89,6 +99,7 @@ Discussion process:
 Discussion guardrails:
 - Start from user intent, not technical implementation detail
 - Clarify only what changes planning, sequencing, or execution direction
+- Treat `/discuss` as an interview-style clarification phase, not an unbounded brainstorm
 - Prefer concrete decisions over vague summaries
 - Preserve unresolved items instead of guessing them away
 - Do not drift into deep research, full plan authoring, task decomposition, or implementation changes
@@ -97,12 +108,21 @@ Discussion guardrails:
 
 ## Phase 0 — Session Start
 
-Every session begins here. No exceptions.
+Every planning session begins by loading tracker and memory context.
 
+Preferred tracker flow:
+
+```bash
+br init
+br ready --json
+br list --json
 ```
-beads-village_init(team="project")         # join workspace — always first
-beads-village_inbox(unread=true)           # check for blockers or messages
-beads-village_ls(status="ready")           # see what's already queued
+
+Optional legacy compatibility when `beads-village` is installed:
+
+```
+beads-village_inbox(unread=true)
+beads-village_ls(status="ready")
 ```
 
 Then read memory context — **tilth-first via `read` tool** (runtime hook auto-enhances):
@@ -308,14 +328,14 @@ dependencies:
   - "P-T000"   # or [] if none
 
 acceptance_criteria:            # All must be machine-executable: cmd + expected output
-  - cmd: "bun test src/foo.test.ts"
+  - cmd: "bun run build"
     expect: "exits 0"
   - cmd: "lsp_diagnostics src/foo.ts"
     expect: "zero errors"
 
 verification_commands:          # Run in order after implementation
   - "bun run typecheck"
-  - "bun test src/foo.test.ts"
+  - "bun run build"
 
 risks:
   - "Edge case: empty input not handled in bar()"
@@ -367,7 +387,7 @@ Use this checklist on every loop iteration:
 
 **Packets:**
 - [ ] Every packet has a `cmd + expect` acceptance criterion — no manual-only checks
-- [ ] Verification commands are full commands with flags (e.g. `bun test src/foo.test.ts`, not just "run tests")
+- [ ] Verification commands are full commands with flags (e.g. `bun run build`, not just "run tests")
 - [ ] `escalate_if` uses concrete, observable triggers — not "if something goes wrong"
 - [ ] No packet touches more than **3 files** (ideal: 1–3). If 4+ files are needed, split the packet or explicitly justify why it cannot be divided.
 - [ ] Build can execute one packet without guessing context from other packets
@@ -377,7 +397,7 @@ Use this checklist on every loop iteration:
 | Tier | What it checks | Example command |
 |------|---------------|----------------|
 | L3 — Build | Compiles without error | `bun run build` / `npx tsc --noEmit` |
-| L2 — Tests | Tests pass | `bun test src/foo.test.ts` |
+| L2 — Tests | Tests pass | `bun test` or repo-specific equivalent |
 | L1 — Feature | Behavior is correct | integration test or `lsp_diagnostics` |
 
 ---
@@ -392,35 +412,21 @@ Approval signals: "ok", "looks good", "approved", "start", "go ahead", or equiva
 
 If changes requested: update the plan, re-present. Repeat until approved.
 
-**Only after approval**, create one Beads issue per packet — **in DAG order** (wave 1 first, then wave 2, etc.).
-Map packet dependencies into `deps` so the Beads queue respects the execution order:
+**Only after approval**, create tracker issues for packets — **in DAG order** (wave 1 first, then wave 2, etc.).
+Prefer `br` issue creation when `.beads/` tracking is active. Preserve dependency intent in the plan even if the active tracker does not encode every edge identically.
 
 ```
 # Wave 1 — no dependencies
-beads-village_add(
-  title="[P-T001] <packet goal>",
-  typ="task",
-  pri=<0=critical · 1=high · 2=normal · 3=low · 4=backlog>,
-  tags=["be" | "fe" | ...],
-  desc="packet_id: P-T001 | files: <list> | goal: <goal>"
-)
-# → note the returned issue id, e.g. "bv-1"
-
-# Wave 2 — depends on P-T001
-beads-village_add(
-  title="[P-T002] <packet goal>",
-  typ="task",
-  pri=<0-4>,
-  tags=["be" | "fe" | ...],
-  desc="packet_id: P-T002 | files: <list> | goal: <goal>",
-  deps=["bv-1"]          # ← use the actual returned id from wave 1
-)
+br create --title "[P-T001] <packet goal>" --description "packet_id: P-T001 | files: <list> | goal: <goal>" --type task --priority <0-4>
+
+# Wave 2 — note the dependency in plan context and tracker description
+br create --title "[P-T002] <packet goal>" --description "packet_id: P-T002 | depends_on: P-T001 | files: <list> | goal: <goal>" --type task --priority <0-4>
 ```
 
-> `pri` uses numeric 0–4 per `schemas.md §8` (0=critical, 1=high, 2=normal, 3=low, 4=backlog).
-> Preserve all dependency edges from the DAG — omitting `deps` breaks the Beads queue order.
+> Use numeric priority 0–4 per `schemas.md §8` when the active tracker expects it.
+> If a legacy `beads-village` setup is still active, it may be used as a compatibility fallback, but it is no longer required for plan handoff.
 
-Then hand off: *"Plan approved. Beads issues created for [N] packets. Use `/start` to begin execution."*
+Then hand off: *"Plan approved. Tracker issues created for [N] packets when supported. Use `/start` to begin execution."*
 
 ---
 
@@ -446,23 +452,23 @@ Do not let the plan silently drift from what Build is actually doing.
 ## Guardrails
 
 **Always:**
-- `beads-village_init` at session start — no exceptions
+- Load tracker context at session start (`br` first; legacy `beads-village` only when available)
 - Read `_digest.md` before planning
 - Delegate codebase inspection to `@explore` (you have no bash)
 - Delegate to `@research` for the mandatory pre-plan research pass before drafting or finalizing any plan
 - Use `schemas.md §6` packet format for every task — include **all** fields
-- Use `pri=<0-4>` numeric scale when creating Beads issues (`schemas.md §8`)
-- Map all DAG dependencies into `deps` when calling `beads-village_add`
+- Use tracker-compatible priority values when creating issues (`schemas.md §8`)
+- Preserve DAG dependencies explicitly in the plan and tracker descriptions
 - Include DAG with explicit wave groupings
 - Include Boundaries block in every plan
 - Verify the planning requirements in the XML verification loop until they pass
-- Wait for explicit user approval before creating Beads issues
+- Wait for explicit user approval before creating tracker issues
 
 **Never:**
 - Write source code
 - Start drafting the final plan before the mandatory research artifact exists
 - Rely on manual-only verification ("user checks" is not acceptable)
 - Omit `files_in_scope` boundaries from any packet
-- Create Beads issues without approval
+- Create tracker issues without approval
 - Use vague `escalate_if` — always use concrete, observable conditions
 - Expand packet scope silently — update the plan instead

package/memory/_digest.md

@@ -1,6 +0,0 @@
-# Memory Digest
-
-> Auto-generated on 2026-04-03. Read-only reference for agents.
-> Source: `.opencode/memory/memory.db`
-
-*No observations found in memory database.*