clikit-plugin 0.3.11 → 0.3.12

package/AGENTS.md

@@ -77,7 +77,6 @@ Load `session-management` skill for full threshold handling (including handoff t
 bun install        # dependencies
 bun run build      # compile plugin
 bun run typecheck  # type check
-bun run test       # unit tests
 bun run verify     # full local verification
 bun run dev        # watch mode
 ```
@@ -108,23 +107,21 @@ tilth CLI → read → grep → glob
 
 This is a documented agent rule, not a hard runtime block.
 
-## Issue Tracking with bd (beads)
+## Issue Tracking with Beads Rust (`br`)
 
-**IMPORTANT**: This project uses **bd (beads)** for ALL issue tracking. Do NOT use markdown TODOs, task lists, or other tracking methods.
+**IMPORTANT**: This project now prefers **Beads Rust** (`br`) with local `.beads/` storage for persistent task tracking. Do NOT use markdown TODOs or ad-hoc task lists as the source of truth.
 
-### Two Interfaces
+### Preferred Interface
 
 | Interface | Who Uses It | How |
 |-----------|-------------|-----|
-| **`bd` CLI** | User in terminal | `bd create`, `bd ready`, `bd close` |
-| **`beads-village_*` MCP** | AI agents in OpenCode | `beads-village_add`, `beads-village_claim` |
-
-**AI agents must use `beads-village_*` MCP tools — never shell `bd` commands.**
+| **`br` CLI** | User and agents | `br init`, `br ready --json`, `br create`, `br update`, `br close`, `br sync` |
+| **`beads-village_*` MCP** | Optional legacy compatibility | Use only if already installed and explicitly needed for reservations/messages |
 
 ### Agent Core Cycle
 
 ```
-beads-village_init → status/inbox → ls(ready) → show → add (if needed) → claim → reservations → reserve → work → verify → done → 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
 ```
 
 In compressed workflow, the execution unit is a **Task Packet**:
@@ -137,36 +134,32 @@ In compressed workflow, the execution unit is a **Task Packet**:
 
 | Tool | Purpose |
 |------|---------|
-| `beads-village_init` | Join workspace — call FIRST every session |
-| `beads-village_add(title, typ, pri, tags, deps)` | Create issue |
-| `beads-village_claim` | Claim next ready task (filtered by role) |
-| `beads-village_reserve(paths, reason)` | Lock files before editing |
-| `beads-village_done(id, msg)` | Complete task, auto-release locks |
-| `beads-village_ls(status="ready")` | List claimable tasks |
-| `beads-village_show(id)` | Get task details |
-| `beads-village_status(include_agents=true)` | Workspace overview + agent discovery |
-| `beads-village_msg(subj, global=true, to="all")` | Broadcast to team |
-| `beads-village_inbox(unread=true)` | Read messages |
-| `beads-village_sync` | Push/pull git changes |
-
-### v1.3 API Changes (avoid old names)
-
-| ❌ Old (broken) | ✅ 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)` |
+| `br init` | Initialize `.beads/` for the project |
+| `br ready --json` | List unblocked claimable work |
+| `br create --title ... --description ... --type ... --priority ...` | Create issue |
+| `br update <id> --status in_progress --claim` | Claim / start work |
+| `br show <id> --json` | Read task details |
+| `br list --json` | Inspect task inventory |
+| `br close <id> --reason "Completed" --json` | Close completed work |
+| `br sync --flush-only` | Flush `.beads/` state before git commit/push |
+| `br sync --import-only` | Re-import `.beads/` state after pull/rebase |
+
+### Legacy compatibility note
+
+- `beads-village_*` is no longer the default required workflow in this repo.
+- If a local setup still depends on `beads-village` for reservations or inbox-style coordination, treat it as optional compatibility, not the primary task tracker.
+- This repo does **not** currently provide a full MCP replacement for `br`; use the CLI-first workflow above.
 
 ### Policy
 
 - Trivial (< 2 min, 1-line fix): skip Beads, just do it
-- Non-trivial: create issue first → claim → work → done
-- `todowrite` = in-session UI display only — Beads is the persistent and authoritative execution state
+- Non-trivial: prefer `br` issue first → claim/start → work → close
+- `todowrite` = in-session UI display only — `.beads/` is the persistent execution state when task tracking is in use
 - Work in the shared checkout on the repo default branch — no git worktrees or per-task branches unless the user explicitly requests them
 - Check `git status --short --branch` before editing; if overlapping local changes already exist in your scope, stop and coordinate instead of isolating the work
-- Use `beads-village_reserve` to surface conflicts early in the shared workspace
-- Always `reserve` files before editing in multi-agent contexts
-- Call `done` before ending a completed session; for mid-task handoff, leave the issue open and hand off without `done`
+- If optional `beads-village` reservations are available, you may use them to surface conflicts early in the shared workspace
+- Otherwise coordinate through git state, handoffs, and explicit file scope instead of assuming reservations exist
+- Call `br close` before ending a completed tracked session; for mid-task handoff, leave the issue open and hand off without closing it
 
 ### Nested Repository Note
 

package/README.md

@@ -1,6 +1,83 @@
 # CliKit Plugin for OpenCode
 
-Curated agents, commands, skills, and memory system for OpenCode.
+Turn raw OpenCode into a disciplined delivery workflow: **discuss → create → start → verify → ship**.
+
+CliKit is the workflow layer for OpenCode — curated agents, slash commands, runtime hooks, memory artifacts, and quality gates that help you move from vague request to verified change without inventing your process every session.
+
+## Why CliKit exists
+
+OpenCode is powerful, but the hard part is not calling a model — it is keeping planning, execution, verification, and handoff aligned as the task gets bigger.
+
+CliKit adds that missing structure:
+
+- **Workflow orchestration** — opinionated commands for discuss/create/start/verify/ship
+- **Agent library** — specialized roles for build, plan, explore, review, research, oracle, and vision
+- **Memory system** — discussion, plan, research, review, and handoff artifacts that survive across sessions
+- **Safety + quality hooks** — git guard, security checks, truncation, memory digest, and prompt-context helpers
+- **Verification loop** — compressed packet execution plus explicit verification before landing changes
+
+## Start here
+
+### Install in 3 steps
+
+```bash
+# 1) Install Beads Rust for local task tracking
+br --version
+
+# 2) Initialize tracker state in your project
+br init
+
+# 3) Install CliKit for OpenCode
+bun x clikit-plugin install
+```
+
+Need the full install notes, Windows binary path, or MCP details? Jump to [Installation](#installation).
+
+### Pick a workflow
+
+**Quick feature / fix**
+```text
+/discuss → /create → /start → /verify → /ship
+```
+
+**Deeper feature / research-heavy change**
+```text
+/discuss → /create → /design → /start → /verify → /ship
+```
+
+**Audit existing work before landing**
+```text
+/verify → /ship
+```
+
+## What you get
+
+- **7 specialized agents** — build, plan, explore, review, vision, oracle, research
+- **14 slash commands** — including `/discuss`, `/create`, `/start`, `/verify`, `/ship`, `/debug`, `/research`, `/design`, `/status`
+- **26 workflow skills** — planning, debugging, testing, integration, and session-management skills
+- **11 runtime hooks/modules** — git guard, security check, truncator, memory digest, beads context, tilth reading, and more
+- **Structured memory** — templates plus saved discussions, plans, research, reviews, handoffs, and PRDs
+- **Configurable runtime** — per-agent overrides, hook toggles, workflow mode selection, and extended permissions
+
+## Trust & compatibility
+
+- **OpenCode-first** plugin architecture
+- **Compressed workflow** with packetized execution and embedded verification
+- **Beads Rust (`br`)** as the preferred local tracker workflow
+- **Shared-workspace friendly** defaults with optional legacy `beads-village` compatibility
+- **Published package**: [`clikit-plugin` on npm](https://www.npmjs.com/package/clikit-plugin)
+
+## Docs map
+
+- `README.md` — install, workflows, commands, skills, config
+- `AGENTS.md` — repo-wide execution policy and tracker workflow
+- `command/` — slash command definitions and execution rules
+- `src/agents/` — agent prompts and behavior contracts
+- `skill/` — reusable workflow skills
+- `schemas.md` — canonical packet / artifact / tracker schemas
+- `memory/_templates/` — discussion, plan, research, review, PRD, and handoff templates
+
+---
 
 ## Features
 
@@ -15,45 +92,33 @@ Curated agents, commands, skills, and memory system for OpenCode.
 
 ## Installation
 
-### Step 1 — Install Beads (required)
+### Step 1 — Install Beads Rust (`br`)
 
-CliKit uses [Beads](https://github.com/steveyegge/beads) (`bd`) for persistent task tracking. Install it system-wide first.
+CliKit now prefers [beads_rust](https://github.com/Dicklesworthstone/beads_rust) (`br`) for persistent task tracking in `.beads/`. Classic `bd` + Dolt are no longer required for the default workflow.
 
-**Windows (PowerShell):**
-```pwsh
-irm https://raw.githubusercontent.com/steveyegge/beads/main/install.ps1 | iex
-```
+**Windows (native binary):**
+1. Download the latest `br-v*-windows_amd64.zip` asset from the GitHub Releases page.
+2. Extract `br.exe`.
+3. Place it on your `PATH` (for example under `%APPDATA%\npm`).
 
-**macOS / Linux — Homebrew (recommended):**
+**macOS / Linux / Windows via WSL:**
 ```bash
-brew install beads
-```
-
-**npm / bun:**
-```bash
-npm install -g @beads/bd
-# or
-bun install -g --trust @beads/bd
-```
-
-**go install (Go 1.24+ required):**
-```bash
-go install github.com/steveyegge/beads/cmd/bd@latest
+curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/beads_rust/main/install.sh" | bash
 ```
 
 Verify:
 ```bash
-bd version
+br --version
 ```
 
-### Step 2 — Initialize Beads in your project
+### Step 2 — Initialize `.beads/` in your project
 
 ```bash
 cd your-project
-bd init --quiet
+br init
 ```
 
-This creates the `.beads/` database directory. Do this once per project.
+This creates the `.beads/` task-tracking directory. Do this once per project. If `.beads/` already exists, keep it and use `br sync --import-only` after pulling or rebasing older state.
 
 ### Step 3 — Install CliKit
 
@@ -68,11 +133,12 @@ The plugin is registered in `~/.config/opencode/opencode.json`.
 
 CliKit injects default MCP server entries at runtime when missing:
 
-- `beads-village` (`npx beads-village`) — requires `bd init` to have been run in the project
 - `context7` (`https://mcp.context7.com/mcp`)
 - `grep` (`https://mcp.grep.app`)
 - `human-mcp` (`npx @goonnguyen/human-mcp`)
 
+`beads-village` is no longer injected by default. If you still rely on the legacy MCP workflow for reservations or inbox-style coordination, add it manually.
+
 Recommended environment variables:
 
 - `CONTEXT7_API_KEY` for Context7
@@ -101,7 +167,7 @@ Workflow notes:
 - `/ship` finalizes work in the shared checkout — commit, sync, and land on the repo default branch; `/pr` is optional and only for explicit PR-based exceptions
 - `/research` is an optional standalone research command — it reads discussion context first, closes decision gaps with external evidence, and saves a planning-ready report
 - `/design` implements UI/UX with variant exploration and a11y — uses Vision agent
-- Beads is the live execution source of truth
+- `br` + `.beads/` is the preferred persistent task source of truth; `beads-village` is optional legacy compatibility only
 - Plans decompose work into **Task Packets** (1 concern, 1–3 files, one verify bundle)
 
 ## Configuration
@@ -192,8 +258,8 @@ Project config overrides user config.
 | `subagent_question_blocker` | on | Prevents subagents from asking clarifying questions |
 | `truncator` | on | Truncates large outputs to prevent context overflow |
 | `memory_digest` | on | Generates `memory/_digest.md` index + topic files (`decision.md`, `learning.md`, etc.) from SQLite observations |
-| `todo_beads_sync` | off | Legacy todo→Beads mirror; disabled in compressed workflow |
-| `beads_context` | on | Injects active Beads task state into prompts |
+| `todo_beads_sync` | off | Legacy compatibility mirror for syncing todos into `.beads/` exports |
+| `beads_context` | on | Injects active `.beads/` task state into prompts when local Beads data exists |
 | `cass_memory` | on | Loads embedded memory context on session start and runs idle reflection (`cassMemoryContext`, `cassMemoryReflect`) |
 | `tilth_reading` | on | Enhances `read` tool output via tilth when available for smarter file reads |
 
@@ -230,7 +296,7 @@ Run with `/command-name` in OpenCode. **All 14 commands work standalone** — th
 | Command | One-liner |
 |---------|-----------|
 | `/debug` | Reproduce → 5-Whys root cause → fix → regression test |
-| `/status` | Workspace snapshot — Beads tasks, git state, active artifacts |
+| `/status` | Workspace snapshot — task tracker state, git state, active artifacts |
 | `/init` | Bootstrap CliKit — scaffold dirs + write tailored AGENTS.md |
 | `/handoff` | Auto-capture session state for graceful pause |
 | `/resume` | Pick up cold from latest handoff, no warm-up questions |
@@ -278,7 +344,7 @@ Run with `/command-name` in OpenCode. **All 14 commands work standalone** — th
 ### Integration & Collaboration (6)
 | Skill | Use When |
 |-------|----------|
-| `beads` | Multi-agent task coordination via beads-village |
+| `beads` | Multi-agent task coordination with `br` and optional legacy beads-village helpers |
 | `playwright` | Browser automation and E2E testing |
 | `chrome-devtools` | Web debugging and performance analysis |
 | `requesting-code-review` | After completing a task |
@@ -297,9 +363,6 @@ bun run build
 # Type check
 bun run typecheck
 
-# Unit tests
-bun run test
-
 # Full local verification
 bun run verify
 
@@ -328,7 +391,7 @@ bun run dev
 │   ├── research/     # Research artifacts
 │   ├── reviews/      # Code reviews
 │   ├── handoffs/     # Session handoffs
-│   ├── beads/        # Beads task artifacts
+│   ├── beads/        # Optional compatibility bead metadata
 │   └── prds/         # Product requirements
 └── clikit.jsonc
 ```

package/command/create.md

@@ -175,11 +175,14 @@ Before presenting the plan, verify:
 - [ ] All acceptance criteria are agent-executable
 - [ ] Top 2+ risks assessed
 
-### 8. Approval, Create Beads, & Guide
+### 8. Approval, Sync Tracking, & Guide
 
 1. Present plan to user
 2. Wait for explicit approval
-3. Only after approval, call `beads-village_add()` with title, description, and priority
+3. Only after approval, sync task tracking in the active workflow:
+   - Prefer `br` issue creation in DAG order when `.beads/` tracking is active and the runtime can execute `br`
+   - If a legacy `beads-village` MCP setup still exists, it may be used as a compatibility fallback
+   - Do **not** block plan handoff on missing legacy MCP support
 4. Then say: "Plan ready. Use `/start` to begin execution."
 
 ## Rules
@@ -195,7 +198,7 @@ Before presenting the plan, verify:
 - ✅ Include Conventions & Past Decisions section in plan
 - ✅ Every task must include a Task Packet
 - ✅ File Impact is the build contract
-- ✅ Create Beads issues only after explicit approval
+- ✅ Create tracker issues only after explicit approval
 - ❌ NEVER ask generic questions without codebase context
 - ❌ NEVER skip acceptance criteria
 - ❌ NEVER end passively — always question or action

package/command/discuss.md

@@ -1,9 +1,9 @@
 ---
-description: Pre-create discussion phase — clarify intent, lock preferences, confirm assumptions, and write a planning-ready discussion artifact.
+description: Pre-create discussion phase — run an interview-style clarification pass, lock preferences, confirm assumptions, and write a planning-ready discussion artifact.
 agent: plan
 ---
 
-You are the **Plan Agent** operating in discussion mode. Execute the `/discuss` command and write only the discussion artifact.
+You are the **Plan Agent** operating in discussion mode. Execute the `/discuss` command as an **interview-style pre-plan phase** and write only the discussion artifact.
 
 ## Template
 
@@ -13,6 +13,13 @@ Use template at: `@.opencode/memory/_templates/discussion.md`
 
 Run a **pre-create discussion phase adapted for CliKit**.
 
+The command name stays `/discuss`, but the interaction style should feel like a focused **interview**:
+- surface the highest-impact gray areas first
+- ask only the questions that change planning direction
+- prefer structured choices over open-ended brainstorming when possible
+- skip topics that are already settled by prior artifacts or strong codebase evidence
+- end with a concise artifact that captures what the interview resolved
+
 This command exists to capture the decisions that `/create`, `/research`, and `/start` should not have to guess.
 
 Use it to:
@@ -59,13 +66,15 @@ If context is incomplete, capture the uncertainty in the artifact instead of blo
    - 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 few 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 the repository strongly suggests a sensible default, present it as an assumption for confirmation instead of asking a vague question
+   - If multiple gray areas remain, prioritize the ones with the biggest scope or workflow impact first
 
-5. **Lock what is known and defer the rest**
+5. **Lock what the interview resolved and defer the rest**
    - Record confirmed decisions explicitly
    - Separate confirmed assumptions from unresolved questions
    - Push non-critical ideas into a deferred section rather than expanding scope
@@ -85,7 +94,7 @@ Use this request schema:
 
 ```yaml
 type: "discussion"
-mode: "pre-create-phase"
+mode: "interview-style-pre-create-phase"
 topic: "[Feature or topic being clarified]"
 goal: "[What outcome the user wants]"
 ambiguities:
@@ -97,12 +106,15 @@ constraints:
   workflow: "[Any sequencing or approval constraints]"
 format: "discussion-brief"
 depth: "standard"         # quick | standard | deep
+question_style: "adaptive-interview"
 ```
 
 ## Rules
 
 - Start from user intent, not technical implementation detail
 - Clarify only what changes planning, sequencing, or execution direction
+- Treat `/discuss` as an interview, not an unbounded brainstorm
+- Ask the minimum number of questions needed to remove planning-critical ambiguity
 - Prefer concrete decisions over vague summaries
 - Preserve unresolved items instead of guessing them away
 - Write only the final discussion artifact under `.opencode/memory/discussions/`

package/command/init.md

@@ -39,9 +39,10 @@ Ensure these exist:
 - `.opencode/memory/reviews`
 - `.opencode/memory/handoffs`
 - `.opencode/memory/prds`
-- `.opencode/memory/beads`
 - `.opencode/memory/_templates`
 
+Task tracking now lives in the project-root `.beads/` directory created by `br init`, not under `.opencode/memory/beads`.
+
 ### 4) Handle existing AGENTS.md safely
 
 If root `AGENTS.md` exists:

package/command/start.md

@@ -28,20 +28,22 @@ If no plan exists:
 - Read `plan.md` — get objectives, context, task list, file impact, dependencies, and acceptance criteria
 - Read `discussion.md` (if referenced or latest relevant) — preserve locked intent and constraints
 - Read latest handoff in `.opencode/memory/handoffs/` (if exists) — resume from previous session
-- Check bead status via `beads-village_ls()`
+- Check tracker state:
+  - prefer `br ready --json` / `br list --json` when `.beads/` is active
+  - if a legacy `beads-village` MCP is installed, you may also inspect reservations or inbox state
 
 ### 3. Determine Next Packet
 
 Find the first task / packet that is executable:
 - dependencies satisfied
-- within Beads ready state
+- within the active tracker ready state when tracking exists
 - not blocked
 
 If resuming from handoff, pick up `in_progress` tasks first.
 
 ### 4. Execute Packet
 
-- Reserve packet files via `beads-village_reserve()`
+- Reserve packet files when optional legacy reservations are available; otherwise use explicit file scope plus `git status` as the coordination primitive
 - Follow `files_in_scope` strictly
 - Implement only the active packet
 
@@ -58,7 +60,7 @@ If verification fails twice, stop and escalate.
 
 ### 6. Close Packet
 
-- Mark Beads task done
+- Close or update tracker state when a tracked issue exists
 - Report evidence
 - Continue only if another ready packet exists and the user asked to keep going
 

package/command/status.md

@@ -1,23 +1,26 @@
 ---
-description: Instant workspace snapshot — active Beads tasks, ready work, git state, and all memory artifacts in one view.
+description: Instant workspace snapshot — tracker state, ready work, git state, and memory artifacts in one view.
 agent: build
 ---
 
-You are providing a **status overview** of the current workspace and beads.
+You are providing a **status overview** of the current workspace and task tracker.
 
 ## Your Task
 
-Show the current state of work: beads, tasks, files, and git status.
+Show the current state of work: tracker state, tasks, files, and git status.
 
 ## Process
 
-### 1. Check Beads Village
+### 1. Check Task Tracking
 
-```
-beads-village_status()
+Preferred path:
+
+```bash
+br ready --json
+br list --json
 ```
 
-Also inspect ready work, reservations, and inbox state using the matching `beads-village_*` tools.
+If a legacy `beads-village` MCP is installed, you may also inspect reservations, inbox state, or agent presence using the matching MCP tools.
 
 ### 2. Check Git State
 
@@ -48,7 +51,7 @@ Look for:
 
 ---
 
-### 🎯 Beads Village
+### 🎯 Tracker State
 
 | Status | Count |
 |--------|-------|
@@ -62,6 +65,8 @@ Look for:
 1. [ID] [Title] (P[priority])
 2. [ID] [Title] (P[priority])
 
+**Tracker Source:** `br` / `beads-village` / `none`
+
 ---
 
 ### 📁 Active Artifacts
@@ -113,11 +118,9 @@ Look for:
 
 | Area | Tool |
 |------|------|
-| Beads | `beads-village_status()` |
-| Tasks | `beads-village_ls()` |
-| Ready tasks | `beads-village_ls(status="ready")` |
-| Reservations | `beads-village_reservations()` |
-| Messages | `beads-village_inbox()` |
+| Tracker | `br ready --json`, `br list --json` |
+| Legacy reservations | `beads-village_reservations()` when available |
+| Legacy inbox | `beads-village_inbox()` when available |
 | Git | `git status`, `git log` |
 | Artifacts | `glob`, `Read` |