clikit-plugin 0.2.44 → 0.2.46

package/AGENTS.md

@@ -8,18 +8,27 @@ The plugin (`src/index.ts`) loads agents from `src/agents/*.md`, commands from `
 
 ## Workflow
 
+**Quick mode** (simple features):
 ```
-/create → /plan → /start → /verify → /ship
+/create → /start → /ship → /verify
 ```
 
-Always verify before claiming done. Run typecheck + lint + test before commit.
+**Deep mode** (complex features, research, UI):
+```
+/create → /research → /design → /start → /ship → /verify
+```
+
+- `/create` produces both spec and plan — `/start` works directly from this output
+- `/verify` is the pre-ship gate — run before `/ship` finalizes
+- `/research` = external docs, API comparison, library research
+- `/design` = UI/UX design and implementation (uses Vision agent)
 
 ## Where to Find Things
 
 - **Agent behavior**: Read the specific agent's `.md` file in `src/agents/` — each has full instructions in its prompt.
 - **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.
+- **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.
@@ -42,3 +51,60 @@ bun run dev        # watch mode
 - Hooks export from `src/hooks/index.ts`, wired in `src/index.ts` event handlers
 - 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)
+
+**IMPORTANT**: This project uses **bd (beads)** for ALL issue tracking. Do NOT use markdown TODOs, task lists, or other tracking methods.
+
+### Two Interfaces
+
+| 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.**
+
+### Agent Core Cycle
+
+```
+beads-village_init → beads-village_add → beads-village_claim → reserve → work → done
+```
+
+In compressed workflow, the execution unit is a **Task Packet**:
+- one concern
+- one verify bundle
+- 1–3 files
+- strict file scope
+
+### Key Tool Reference (v1.3 API)
+
+| 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)` |
+
+### 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
+- Always `reserve` files before editing in multi-agent contexts
+- Always `done` before ending session (releases file locks)

package/README.md

@@ -5,16 +5,58 @@ Curated agents, commands, skills, and memory system for OpenCode.
 ## Features
 
 - **7 Specialized Agents**: build, plan, explore, review, vision, oracle, research
-- **19 Slash Commands**: /create, /start, /plan, /ship, /verify, /review, /debug, /pr, and more
-- **48 Workflow Skills**: TDD, debugging, design, UI/UX, integrations, ritual-workflow, and more
-- **7 Internal Utilities**: memory (read/search/get/timeline/update/admin), observation, swarm, beads-memory-sync, quick-research, context-summary, cass-memory (used by hooks, not directly registered as agent tools)
-- **10 Runtime Hooks**: todo enforcer, empty output sanitizer, git guard, security check, subagent blocker, truncator, swarm enforcer, memory digest, todo→beads sync, and cass-memory
+- **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
+- **7 Internal Utilities**: memory (read/search/get/timeline/update/admin), observation, context-summary, cass-memory (used by hooks, not directly registered as agent tools)
+- **10 Runtime Hooks**: todo enforcer, empty output sanitizer, git guard, security check, subagent blocker, truncator, memory digest, todo→beads sync, beads-context, and cass-memory
 - **Memory System**: Templates, specs, 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)
+
+CliKit uses [Beads](https://github.com/steveyegge/beads) (`bd`) for persistent task tracking. Install it system-wide first.
+
+**Windows (PowerShell):**
+```pwsh
+irm https://raw.githubusercontent.com/steveyegge/beads/main/install.ps1 | iex
+```
+
+**macOS / Linux — Homebrew (recommended):**
+```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
+```
+
+Verify:
+```bash
+bd version
+```
+
+### Step 2 — Initialize Beads in your project
+
+```bash
+cd your-project
+bd init --quiet
+```
+
+This creates the `.beads/` database directory. Do this once per project.
+
+### Step 3 — Install CliKit
+
 ```bash
 # Install CliKit globally for OpenCode
 bun x clikit-plugin install
@@ -22,11 +64,11 @@ bun x clikit-plugin install
 # Restart OpenCode
 ```
 
-That's it! The plugin will be registered in `~/.config/opencode/opencode.json`.
+The plugin is registered in `~/.config/opencode/opencode.json`.
 
 CliKit injects default MCP server entries at runtime when missing:
 
-- `beads-village` (`npx beads-village`)
+- `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`)
@@ -40,10 +82,27 @@ Recommended environment variables:
 
 After installation, use these commands:
 
+**Quick mode** (simple features):
 ```
-/create → /plan → /start → /verify → /ship
+/create → /start → /ship → /verify
 ```
 
+**Deep mode** (complex features, research, UI):
+```
+/create → /research → /design → /start → /ship → /verify
+```
+
+Workflow notes:
+- All 15 commands work **standalone** — the pipeline is recommended, not required
+- `/create` explores codebase first, then produces both spec and 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` finalized work and creates PR — runs self-review standalone, recommended to run `/verify` first
+- `/research` conducts external research — use standalone before any complex implementation
+- `/design` implements UI/UX with variant exploration and a11y — uses Vision agent
+- Beads is the live execution source of truth
+- Plans decompose work into **Task Packets** (1 concern, 1–3 files, one verify bundle)
+
 ## Configuration
 
 Create `clikit.jsonc` (preferred) or `clikit.json` in one of these locations:
@@ -85,16 +144,24 @@ Project config overrides user config.
   "hooks": {
     "session_logging": false,
     "tool_logging": false,
-    "todo_enforcer": { "enabled": true },
+    "todo_enforcer": { "enabled": true, "beads_authoritative": true, "warn_on_incomplete": false },
     "empty_message_sanitizer": { "enabled": true },
     "git_guard": { "enabled": true },
     "security_check": { "enabled": true },
     "subagent_question_blocker": { "enabled": true },
-    "truncator": { "enabled": true },
-    "swarm_enforcer": { "enabled": true },
-    "memory_digest": { "enabled": true },
-    "todo_beads_sync": { "enabled": true },
-    "cass_memory": { "enabled": true }
+    "truncator": { "enabled": true, "packet_friendly": true },
+    "memory_digest": { "enabled": true, "compact_mode": true },
+    "todo_beads_sync": { "enabled": false, "mode": "disabled" },
+    "cass_memory": { "enabled": true },
+    "beads_context": { "enabled": true, "active_only": true, "ready_limit": 3 }
+  },
+  "workflow": {
+    "mode": "compressed",
+    "active_roles": ["build", "plan", "review", "coordinator"],
+    "use_packets": true,
+    "embed_verify_in_start": true,
+    "verify_is_audit": true,
+    "subagent_call_budget": 2
   }
 }
 ```
@@ -111,20 +178,21 @@ Project config overrides user config.
 | `skills` | `object \| string[]` | `{}` | Skill enable/disable and per-skill overrides |
 | `hooks.session_logging` | `boolean` | `false` | Session lifecycle logging |
 | `hooks.tool_logging` | `boolean` | `false` | Tool execution logging |
+| `workflow.mode` | `classic \| compressed` | `compressed` | Select compressed packet workflow |
 
 ### Hooks
 
 | Hook | Default | Description |
 |------|---------|-------------|
-| `todo_enforcer` | on | Warns when todos are incomplete at session idle |
+| `todo_enforcer` | on | Optional UI warning; Beads can remain authoritative |
 | `empty_message_sanitizer` | on | Replaces empty tool outputs with placeholder |
 | `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 |
 | `truncator` | on | Truncates large outputs to prevent context overflow |
-| `swarm_enforcer` | on | Enforces task isolation in multi-agent swarms |
 | `memory_digest` | on | Generates `memory/_digest.md` index + topic files (`decision.md`, `learning.md`, etc.) from SQLite observations |
-| `todo_beads_sync` | on | Mirrors OpenCode todos into Beads issues |
+| `todo_beads_sync` | off | Legacy todo→Beads mirror; disabled in compressed workflow |
+| `beads_context` | on | Injects active Beads task state into prompts |
 | `cass_memory` | on | Loads embedded memory context on session start and runs idle reflection (`cassMemoryContext`, `cassMemoryReflect`) |
 
 ## Agents
@@ -139,111 +207,79 @@ Project config overrides user config.
 | `review` | subagent | Code review & quality gate |
 | `vision` | subagent | Design direction + visual implementation |
 
+Default active roles in compressed workflow: `build`, `plan`, `review`, plus coordinator logic in runtime. `explore`, `research`, `oracle`, and `vision` are on-demand specialists.
+
 ## Commands
 
-Run with `/command-name` in OpenCode:
-
-- `/create` - Start new bead, create specification
-- `/start` - Begin implementing from a plan
-- `/plan` - Create implementation plan
-- `/debug` - Debug issues, find root cause, implement fix
-- `/verify` - Run full verification suite
-- `/ship` - Final verification + PR + cleanup
-- `/review` - Request code review
-- `/review-codebase` - Full codebase audit
-- `/vision` - Review UI for design, a11y, responsiveness
-- `/pr` - Create pull request
-- `/init` - Initialize CliKit in a project
-- `/research` - External research
-- `/design` - UI/UX design implementation
-- `/handoff` - Save state for session break
-- `/resume` - Continue from handoff
-- `/status-beads` - Workspace and bead overview
-- `/commit` - Intelligent git commit
-- `/issue` - Quick issue creation
-- `/import-plan` - Import from Jira/Notion/Linear
+Run with `/command-name` in OpenCode. **All 15 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 |
+| `/design` | ✅ | UI/UX design + implementation — variant exploration, a11y, responsive (Vision agent) |
+| `/start` | ✅ | Execute plan packets — creates minimal inline plan if none exists |
+| `/ship` | ✅ | Commit + create PR — self-review built in, `/verify` recommended |
+| `/verify` | ✅ | Full 4-gate check (typecheck, tests, lint, build) + deep code review |
+
+### Utilities (all standalone)
+| 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 |
+| `/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` | Full PR description from git diff, linked to spec/plan/bead |
+| `/import-plan` | Import Jira/Notion/Linear tasks → Beads issues + plan |
 
 ## Skills
 
-48 workflow skills organized into 8 categories:
+22 workflow skills organized into 5 categories:
 
-### Design & Planning (4)
+### Planning & Workflow (4)
 | Skill | Use When |
 |-------|----------|
-| `brainstorming` | Starting without clear requirements |
 | `writing-plans` | Requirements clear, need implementation plan |
 | `executing-plans` | Plan exists, need to execute tasks |
-| `development-lifecycle` | Building complete feature from scratch |
+| `ritual-workflow` | Starting any task — DISCOVER→PLAN→IMPLEMENT→VERIFY |
+| `session-management` | Managing context growth or switching tasks |
 
-### UI/UX & Frontend (7)
-| Skill | Use When |
-|-------|----------|
-| `frontend-aesthetics` | Building UI, avoid "AI slop" |
-| `gemini-large-context` | Analyzing 100KB+ files |
-| `ui-ux-research` | Multimodal UI/UX analysis |
-| `mockup-to-code` | Converting mockups to code |
-| `visual-analysis` | Analyzing images/screenshots |
-| `accessibility-audit` | WCAG compliance check |
-| `design-system-audit` | Design system consistency |
-
-### Development (8)
+### Development (4)
 | Skill | Use When |
 |-------|----------|
-| `subagent-driven-development` | Fast iteration with quality gates |
-| `dispatching-parallel-agents` | 3+ independent failures |
-| `deep-research` | LSP exploration with confidence scores |
-| `source-code-research` | Library internals research |
+| `deep-research` | Exploring unfamiliar code or complex features |
+| `source-code-research` | API docs insufficient, need library internals |
 | `using-git-worktrees` | Isolated workspace on new branch |
-| `finishing-a-development-branch` | Complete branch workflow |
-| `vercel-react-best-practices` | React/Next.js optimization |
-| `supabase-postgres-best-practices` | Postgres optimization |
+| `finishing-a-development-branch` | Completing work on a branch |
 
-### Testing (4)
+### Testing & Quality (5)
 | Skill | Use When |
 |-------|----------|
 | `test-driven-development` | Implementing any feature |
 | `condition-based-waiting` | Flaky tests from race conditions |
 | `testing-anti-patterns` | Avoiding testing mistakes |
-| `testing-skills-with-subagents` | TDD for process docs |
+| `verification-before-completion` | Marking any task complete |
+| `vercel-react-best-practices` | React/Next.js code review or refactor |
 
-### Debugging (4)
+### Debugging (3)
 | Skill | Use When |
 |-------|----------|
 | `systematic-debugging` | Encountering a bug |
 | `root-cause-tracing` | Finding original trigger |
 | `defense-in-depth` | Multi-layer validation |
-| `verification-before-completion` | Marking task complete |
 
-### Integration (16)
-| Skill | Use When |
-|-------|----------|
-| `figma` | Access Figma design data |
-| `playwright` | Browser automation |
-| `chrome-devtools` | Browser debugging |
-| `polar` | Payment integration |
-| `beads` | Multi-agent task coordination |
-| `beads-bridge` | Bridge Beads with todo system |
-| `swarm-coordination` | Parallel task execution |
-| `session-management` | Context growth management |
-| `playwriter` | Chrome extension browser automation |
-| `mqdh` | Meta Quest VR/AR development |
-| `v0` | AI-powered UI generation |
-| `resend` | Transactional emails |
-| `notebooklm` | Query NotebookLM |
-| `supabase` | Supabase platform |
-| `cloudflare` | Cloudflare Workers/Pages |
-| `v1-run` | npm package intelligence |
-
-### Collaboration (3)
+### Integration & Collaboration (6)
 | Skill | Use When |
 |-------|----------|
+| `beads` | Multi-agent task coordination via beads-village |
+| `playwright` | Browser automation and E2E testing |
+| `chrome-devtools` | Web debugging and performance analysis |
 | `requesting-code-review` | After completing a task |
 | `receiving-code-review` | Handling review feedback |
-| `sharing-skills` | Contributing skills via PR |
-
-### Meta (1)
-| Skill | Use When |
-|-------|----------|
 | `writing-skills` | Creating new skills |
 
 ## Development
@@ -278,8 +314,8 @@ bun run dev
 │   ├── types.ts      # Type definitions
 │   ├── agents/       # Agent loaders
 │   ├── skills/       # Skill loaders
-│   ├── tools/        # Internal utilities (memory, swarm, etc.)
-│   └── hooks/        # Runtime hooks (10 modules)
+│   ├── tools/        # Internal utilities (memory, context-summary, cass-memory)
+│   └── hooks/        # Runtime hooks (9 modules)
 ├── skill/            # Skill definitions (*.md)
 ├── command/          # Command definitions (*.md)
 ├── memory/           # Memory system

package/command/commit.md

@@ -1,5 +1,5 @@
 ---
-description: Intelligent git commit with Conventional Commits format.
+description: Analyze staged changes and generate a perfect Conventional Commit message — type, scope, body, and bead link auto-detected.
 agent: build
 ---
 

package/command/create.md

@@ -1,19 +1,20 @@
 ---
-description: Start a new bead. Explore codebase, gather requirements, create specification.
+description: Kick off any feature — explore codebase, interview requirements, produce spec + implementation plan. Use standalone or as the first step of the workflow.
 agent: plan
 ---
 
 You are the **Plan Agent**. Execute the `/create` command.
 
-## Template
+## Templates
 
-Use template at: `@.opencode/memory/_templates/spec.md`
+- Spec: `@.opencode/memory/_templates/spec.md`
+- Plan: `@.opencode/memory/_templates/plan.md`
 
 ## Execution Rules
 
 - **DO NOT** start with generic questions — explore the codebase FIRST
 - **DO NOT** end turns passively — always end with a specific question or action
-- Auto-transition to spec generation when self-clearance passes
+- Auto-transition to spec + plan generation when self-clearance passes
 
 ## Process
 
@@ -37,7 +38,7 @@ Max 3 questions per turn. Update draft after each exchange.
 
 ### 3. Self-Clearance Check
 
-When ALL of these are true, auto-transition to spec generation:
+When ALL of these are true, auto-transition to spec + plan generation:
 - Core problem understood and confirmed
 - Scope boundaries defined
 - Enough info for acceptance criteria
@@ -46,13 +47,59 @@ When ALL of these are true, auto-transition to spec generation:
 
 ### 4. Generate Spec
 
-Write to `.opencode/memory/specs/YYYY-MM-DD-<descriptor>.md` using full template structure.
+Write to `.opencode/memory/specs/YYYY-MM-DD-<descriptor>.md` using the spec template.
 
 **Acceptance criteria MUST be agent-executable** — commands with expected outputs, not "user manually verifies."
 
-### 5. Create Bead
+### 5. Memory & History Mining (parallel with plan generation)
 
-Call `mcp__beads_village__add()` with title, description, and priority.
+**Memory mining** (Plan reads directly — has file read access):
+```
+Read: ".opencode/memory/_digest.md" — Compact index of memory topics and highlights
+Read: ".opencode/memory/decision.md" — Architectural decisions
+Read: ".opencode/memory/learning.md" — Learnings and gotchas
+Read: ".opencode/memory/blocker.md" — Past blockers and mitigations
+Read: ".opencode/memory/handoffs/" — Recent handoffs for prior session context
+Read: ".opencode/memory/research/" — Any related research
+```
+
+**Git history mining** (delegate to Explore):
+```
+Explore: "Mine git log for conventions. Return:
+  1. Commit message format (git log --oneline -n 20)
+  2. Branch naming (git branch -a | head -20)
+  3. Recent commits on related files
+  4. Gotcha markers (git log --grep='HACK\|TODO\|FIXME\|workaround' --oneline -n 10)"
+```
+
+### 6. Generate Plan
+
+Write to `.opencode/memory/plans/YYYY-MM-DD-<feature>.md` using the plan template.
+
+**Task decomposition rules:**
+- Each task must contain a **Task Packet**
+- 1 packet = 1 concern = 1-3 files
+- Group tasks into parallel waves where possible
+- Every packet must define `files_in_scope`, `verification_commands`, and `escalate_if`
+
+**File Impact = BUILD BOUNDARY:**
+Build Agent may ONLY touch files listed here. Missing a file = Build can't modify it.
+
+### 7. Quality Self-Review
+
+Before presenting spec + plan, verify:
+- [ ] Every task has task_id, acceptance criteria, effort, priority
+- [ ] File Impact covers ALL files across ALL tasks
+- [ ] No dependency cycles
+- [ ] No task touches > 3 files
+- [ ] All acceptance criteria are agent-executable
+- [ ] Top 2+ risks assessed
+
+### 8. Create Bead & Guide
+
+1. Call `mcp__beads_village__add()` with title, description, and priority
+2. Present spec + plan to user
+3. After approval: "Spec and plan ready. Use `/start` to begin execution."
 
 ## Rules
 
@@ -60,6 +107,16 @@ Call `mcp__beads_village__add()` with title, description, and priority.
 - ✅ Write agent-executable acceptance criteria
 - ✅ Tag assumptions as Confirmed/Unconfirmed
 - ✅ Auto-transition when clearance check passes
+- ✅ Always produce BOTH spec and plan before guiding to `/start`
+- ✅ Mine memory for past decisions, learnings, blockers
+- ✅ Delegate git history mining to Explore (Plan has bash: false)
+- ✅ Include Conventions & Past Decisions section in plan
+- ✅ Every task must include a Task Packet
+- ✅ File Impact is the build contract
 - ❌ NEVER ask generic questions without codebase context
 - ❌ NEVER skip acceptance criteria
 - ❌ NEVER end passively — always question or action
+- ❌ NEVER create tasks touching > 3 files
+- ❌ NEVER write "user manually tests..." criteria
+- ❌ NEVER omit File Impact section
+- ❌ NEVER skip gap analysis

package/command/debug.md

@@ -1,5 +1,5 @@
 ---
-description: Debug issues, find root cause, implement fix.
+description: Reproduce a bug, trace root cause with 5-Whys, fix it, and add a regression test — all in one command.
 agent: build
 ---