clikit-plugin 0.3.10 → 0.3.12

package/AGENTS.md

@@ -4,24 +4,27 @@ An OpenCode plugin that provides agents, commands, skills, hooks, and a memory s
 
 ## How It Works
 
-The plugin (`src/index.ts`) loads agents from `src/agents/*.md`, commands from `command/*.md`, and skills from `skill/*/SKILL.md`. Runtime hooks in `src/hooks/` intercept tool execution for safety (git guard, security scan) and quality (typecheck, formatting). Configuration lives in `clikit.config.json`.
+The plugin (`src/index.ts`) loads agents from `src/agents/*.md`, commands from `command/*.md`, and skills from `skill/*/SKILL.md`. Runtime hooks in `src/hooks/` intercept tool execution for safety (git guard, security scan) and quality (typecheck, formatting). Configuration prefers `clikit.jsonc` or `clikit.json`; legacy `clikit.config.json` remains supported for backward compatibility.
 
 ## Workflow
 
 **Quick mode** (simple features):
 ```
-/create → /start → /verify → /ship
+/discuss → /create → /start → /verify → /ship
 ```
 
 **Deep mode** (complex features, research, UI):
 ```
-/create → /research → /design → /start → /verify → /ship
+/discuss → /create → /design → /start → /verify → /ship
 ```
 
-- `/create` produces both spec and plan — `/start` works directly from this output
-- `/verify` is the pre-ship gate — run before `/ship` finalizes and lands shared-checkout changes
-- `/research` = external docs, API comparison, library research
+- `/discuss` captures user intent and writes a planning-ready discussion artifact
+- `/create` reads discussion context, runs a mandatory pre-plan research pass, then produces a single XML-structured plan — `/start` works directly from this output
+- `/start` executes packet-by-packet and embeds the execute + verify loop in compressed mode
+- `/verify` is the deeper optional audit / pre-ship gate — run before `/ship` finalizes and lands shared-checkout changes
+- `/research` = optional standalone research command — read discussion context, close decision gaps with external evidence, and write a planning-ready report
 - `/design` = UI/UX design and implementation (uses Vision agent)
+- Execution happens one **Task Packet** at a time (1 concern, 1–3 files, one verify bundle)
 
 ## Where to Find Things
 
@@ -29,9 +32,9 @@ The plugin (`src/index.ts`) loads agents from `src/agents/*.md`, commands from `
 - **Commands**: `command/*.md` — each slash command's template and instructions.
 - **Skills**: `skill/*/SKILL.md` — load relevant skills before tasks. List available skills with `ls skill/`.
 - **Schemas**: `@.opencode/schemas.md` — canonical schemas for tasks, beads, delegation, artifacts, and Task Packets.
-- **Templates**: `memory/_templates/*.md` — templates for specs, plans, research, reviews, handoffs, PRDs.
-- **Memory**: `memory/_digest.md` (auto-generated from SQLite observations on session start), plus `memory/specs/`, `memory/plans/`, `memory/research/`, `memory/handoffs/`.
-- **Config**: `clikit.config.json` — enable/disable agents, hooks, override models.
+- **Templates**: `memory/_templates/*.md` — templates for discussions, plans, research, reviews, handoffs, PRDs.
+- **Memory**: `memory/_digest.md` (auto-generated from SQLite observations on session start), plus `memory/discussions/`, `memory/plans/`, `memory/research/`, `memory/handoffs/`, `memory/reviews/`, `memory/prds/`.
+- **Config**: `.opencode/clikit.jsonc` or `.opencode/clikit.json` (preferred); `clikit.config.json` remains a legacy fallback.
 - **Full docs**: `@.opencode/README.md` — complete reference for all agents, commands, skills, hooks, and config options.
 
 ## Context Management (DCP Beta)
@@ -74,6 +77,7 @@ 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 verify     # full local verification
 bun run dev        # watch mode
 ```
 
@@ -86,23 +90,38 @@ bun run dev        # watch mode
 - Memory tools in `src/tools/` are library code used by hooks, not registered as agent tools
 - Never force push without `--force-with-lease`
 
-## Issue Tracking with bd (beads)
+## Tilth Navigation Policy
 
-**IMPORTANT**: This project uses **bd (beads)** for ALL issue tracking. Do NOT use markdown TODOs, task lists, or other tracking methods.
+When agents navigate files or search the codebase, use **tilth CLI first**.
 
-### Two Interfaces
+Fallback order:
+
+```text
+tilth CLI → read → grep → glob
+```
+
+- Use `read` once the target file is narrowed and you need raw content
+- Use `grep` for text-pattern fallback when tilth did not answer the question
+- Use `glob` only for explicit path enumeration
+- Use LSP after navigation when semantic confirmation is required
+
+This is a documented agent rule, not a hard runtime block.
+
+## Issue Tracking with Beads Rust (`br`)
+
+**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.
+
+### 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 → inspect shared git state → beads-village_add → beads-village_claim → reserve → work → done
+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**:
@@ -115,33 +134,35 @@ 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
+
+- In this workspace, `.opencode/` is treated as its own nested git repository
+- The outer repo often only shows `.opencode` as modified, while detailed diffs live inside the nested `.opencode` repo
+- It is not currently configured as a normal `.gitmodules` submodule, so inspect both git layers when auditing docs or code changes

package/README.md

@@ -1,59 +1,124 @@
 # 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
 
 - **7 Specialized Agents**: build, plan, explore, review, vision, oracle, research
-- **15 Slash Commands**: /create, /start, /ship, /verify, /debug, /design, /research, /commit, /pr, and more
-- **22 Workflow Skills**: TDD, debugging, research, integrations, ritual-workflow, and more
+- **14 Slash Commands**: /discuss, /create, /start, /ship, /verify, /debug, /design, /research, /commit, /pr, and more
+- **26 Workflow Skills**: TDD, debugging, research, integrations, ritual-workflow, and more
 - **7 Internal Utilities**: memory (read/search/get/timeline/update/admin), observation, context-summary, cass-memory (used by hooks, not directly registered as agent tools)
-- **12 Runtime Hooks/Modules**: todo enforcer, empty output sanitizer, git guard, security check, subagent blocker, tilth-first guard, truncator, memory digest, todo→beads sync, beads-context, cass-memory, and tilth-reading
-- **Memory System**: Templates, specs, plans, research artifacts with FTS5 search
+- **11 Runtime Hooks/Modules**: todo enforcer, empty output sanitizer, git guard, security check, subagent blocker, truncator, memory digest, todo→beads sync, beads-context, cass-memory, and tilth-reading
+- **Memory System**: Templates, discussions, plans, research artifacts with FTS5 search
 - **Extended Permissions**: doom_loop, external_directory controls
 - **Configurable**: Enable/disable agents, override models, customize behavior
 
 ## 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
@@ -84,23 +150,24 @@ After installation, use these commands:
 
 **Quick mode** (simple features):
 ```
-/create → /start → /verify → /ship
+/discuss → /create → /start → /verify → /ship
 ```
 
 **Deep mode** (complex features, research, UI):
 ```
-/create → /research → /design → /start → /verify → /ship
+/discuss → /create → /design → /start → /verify → /ship
 ```
 
 Workflow notes:
-- All 15 commands work **standalone** — the pipeline is recommended, not required
-- `/create` explores codebase first, then produces both spec and plan
+- All 14 commands work **standalone** — the pipeline is recommended, not required
+- `/discuss` runs a pre-create discussion phase — clarify intent, confirm assumptions, and save a planning-ready discussion artifact
+- `/create` explores codebase first, consumes discussion context, runs a mandatory pre-plan research pass, then produces a single XML-structured plan
 - `/start` executes the plan, one Task Packet at a time — creates a minimal inline plan if none exists
 - `/verify` runs all 4 gates (typecheck, tests, lint, build) + deep review — use anytime, not just pre-ship
 - `/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` conducts external research — use standalone before any complex implementation
+- `/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
@@ -149,7 +216,6 @@ Project config overrides user config.
     "git_guard": { "enabled": true },
     "security_check": { "enabled": true },
     "subagent_question_blocker": { "enabled": true },
-    "tilth_first_guard": { "enabled": true, "log": false },
     "truncator": { "enabled": true, "packet_friendly": true },
     "memory_digest": { "enabled": true, "compact_mode": true },
     "todo_beads_sync": { "enabled": false, "mode": "disabled" },
@@ -190,11 +256,10 @@ Project config overrides user config.
 | `git_guard` | on | Blocks dangerous git commands (force push, hard reset, rm -rf) |
 | `security_check` | on | Scans for secrets/credentials before git commits |
 | `subagent_question_blocker` | on | Prevents subagents from asking clarifying questions |
-| `tilth_first_guard` | on | Requires `@explore` to make an explicit `tilth` CLI attempt before `read` / `grep` / `glob` fallback |
 | `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 |
 
@@ -203,9 +268,9 @@ Project config overrides user config.
 | Agent | Mode | Description |
 |-------|------|-------------|
 | `build` | primary | Primary code executor, implements plans |
-| `plan` | primary | Creates implementation plans from specs |
+| `plan` | primary | Handles `/discuss` intent locking and `/create` planning, producing discussion artifacts and XML-structured plans |
 | `oracle` | subagent | Deep code inspection + architecture trade-off analysis |
-| `research` | subagent | External docs + GitHub evidence research |
+| `research` | subagent | External evidence specialist; writes research artifacts for `/research` and Plan's pre-plan pass |
 | `explore` | subagent | Fast codebase exploration |
 | `review` | subagent | Code review & quality gate |
 | `vision` | subagent | Design direction + visual implementation |
@@ -214,13 +279,14 @@ Default active roles in compressed workflow: `build`, `plan`, `review`, plus coo
 
 ## Commands
 
-Run with `/command-name` in OpenCode. **All 15 commands work standalone** — the pipeline is a recommended flow, not a requirement.
+Run with `/command-name` in OpenCode. **All 14 commands work standalone** — the pipeline is a recommended flow, not a requirement.
 
 ### Workflow pipeline
 | Command | Standalone? | One-liner |
 |---------|-------------|-----------|
-| `/create` | ✅ | Explore codebase → interview requirements → produce spec + plan |
-| `/research` | ✅ | Deep-dive any library, API, or pattern with saved report |
+| `/discuss` | ✅ | Pre-create discussion phase — lock intent, confirm assumptions, save planning-ready artifact |
+| `/create` | ✅ | Explore codebase → load discussion context → run mandatory pre-plan research → produce a single XML-structured plan |
+| `/research` | ✅ | Optional standalone research pass — read discussion context, gather evidence, save planning-ready report |
 | `/design` | ✅ | UI/UX design + implementation — variant exploration, a11y, responsive (Vision agent) |
 | `/start` | ✅ | Execute plan packets — creates minimal inline plan if none exists |
 | `/ship` | ✅ | Commit + land shared-checkout changes on the default branch — self-review built in, `/verify` recommended |
@@ -230,14 +296,12 @@ Run with `/command-name` in OpenCode. **All 15 commands work standalone** — th
 | Command | One-liner |
 |---------|-----------|
 | `/debug` | Reproduce → 5-Whys root cause → fix → regression test |
-| `/issue` | Instantly capture a task, bug, or idea as a Beads issue |
-| `/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 |
 | `/commit` | Auto-detect type/scope → perfect Conventional Commit message |
 | `/pr` | Optional PR flow for explicit branch-based review exceptions |
-| `/import-plan` | Import Jira/Notion/Linear tasks → Beads issues + plan |
 
 ## Skills
 
@@ -280,7 +344,7 @@ Run with `/command-name` in OpenCode. **All 15 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 |
@@ -299,9 +363,6 @@ bun run build
 # Type check
 bun run typecheck
 
-# Unit tests
-bun run test
-
 # Full local verification
 bun run verify
 
@@ -318,19 +379,19 @@ bun run dev
 │   ├── config.ts     # Config loader
 │   ├── types.ts      # Type definitions
 │   ├── agents/       # Agent loaders
-│   ├── skills/       # Skill loaders
+│   ├── skill/        # Skill loaders
 │   ├── tools/        # Internal utilities (memory, context-summary, cass-memory)
-│   └── hooks/        # Runtime hooks (10 modules)
+│   └── hooks/        # Runtime hooks (11 modules + index)
 ├── skill/            # Skill definitions (*.md)
 ├── command/          # Command definitions (*.md)
 ├── memory/           # Memory system
-│   ├── _templates/   # Document templates
-│   ├── specs/        # Specifications
+│   ├── _templates/   # Document templates (discussion, plan, research, handoff, review, PRD)
+│   ├── discussions/  # Discussion artifacts
 │   ├── plans/        # Implementation plans
 │   ├── research/     # Research artifacts
 │   ├── reviews/      # Code reviews
 │   ├── handoffs/     # Session handoffs
-│   ├── beads/        # Beads task artifacts
+│   ├── beads/        # Optional compatibility bead metadata
 │   └── prds/         # Product requirements
 └── clikit.jsonc
 ```