clikit-plugin 0.2.35 → 0.2.37

package/README.md

@@ -4,11 +4,11 @@ Curated agents, commands, skills, and memory system for OpenCode.
 
 ## Features
 
-- **10 Specialized Agents**: build, general, oracle, librarian, explore, looker, plan, review, scout, vision
+- **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
-- **6 Internal Utilities**: memory (read/search/get/timeline/update/admin), observation, swarm, beads-memory-sync, quick-research, context-summary (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, and todo→beads sync
+- **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
 - **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
@@ -24,7 +24,7 @@ bun x clikit-plugin install
 
 That's it! The plugin will be registered in `~/.config/opencode/opencode.json`.
 
-Installer also adds default MCP servers if missing:
+CliKit injects default MCP server entries at runtime when missing:
 
 - `beads-village` (`npx beads-village`)
 - `context7` (`https://mcp.context7.com/mcp`)
@@ -62,7 +62,7 @@ Project config overrides user config.
 ```json
 {
   "$schema": "https://unpkg.com/clikit-plugin@latest/schema.json",
-  "disabled_agents": ["scout"],
+  "disabled_agents": ["review"],
   "disabled_commands": ["security"],
   "disabled_skills": ["playwright"],
   "skills": {
@@ -70,7 +70,7 @@ Project config overrides user config.
     "disable": ["sharing-skills"]
   },
   "agents": {
-    "oracle": {
+    "vision": {
       "model": "openai/gpt-4o"
     },
     "build": {
@@ -93,7 +93,8 @@ Project config overrides user config.
     "truncator": { "enabled": true },
     "swarm_enforcer": { "enabled": true },
     "memory_digest": { "enabled": true },
-    "todo_beads_sync": { "enabled": true }
+    "todo_beads_sync": { "enabled": true },
+    "cass_memory": { "enabled": true }
   }
 }
 ```
@@ -122,21 +123,19 @@ Project config overrides user config.
 | `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` from SQLite observations |
+| `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 |
+| `cass_memory` | on | Loads embedded memory context on session start and runs idle reflection (`cassMemoryContext`, `cassMemoryReflect`) |
 
 ## Agents
 
 | Agent | Mode | Description |
 |-------|------|-------------|
 | `build` | primary | Primary code executor, implements plans |
-| `general` | subagent | General-purpose, multi-step tasks & complex questions |
 | `plan` | primary | Creates implementation plans from specs |
-| `oracle` | subagent | Expert advisor for architecture & debugging |
-| `librarian` | subagent | Multi-repo analysis, doc lookup |
+| `oracle` | subagent | Deep code inspection + architecture trade-off analysis |
+| `research` | subagent | External docs + GitHub evidence research |
 | `explore` | subagent | Fast codebase exploration |
-| `looker` | subagent | Deep code inspection & architecture analysis |
-| `scout` | subagent | External research & web search |
 | `review` | subagent | Code review & quality gate |
 | `vision` | subagent | Design direction + visual implementation |
 
@@ -159,7 +158,7 @@ Run with `/command-name` in OpenCode:
 - `/design` - UI/UX design implementation
 - `/handoff` - Save state for session break
 - `/resume` - Continue from handoff
-- `/status` - Workspace and bead overview
+- `/status-beads` - Workspace and bead overview
 - `/commit` - Intelligent git commit
 - `/issue` - Quick issue creation
 - `/import-plan` - Import from Jira/Notion/Linear

package/command/init.md

@@ -1,189 +1,107 @@
 ---
-description: Initialize CliKit plugin and generate a well-crafted AGENTS.md for the project.
+description: Initialize CliKit and craft a high-quality AGENTS.md for this project.
 agent: build
 ---
 
-You are the **Build Agent**. Execute the `/init` command.
+You are running `/init` for this repository.
 
-## Your Task
+Goal: set up CliKit and produce a **carefully written** `AGENTS.md` (not autogenerated fluff).
 
-Set up CliKit AND generate a high-quality `AGENTS.md` file. The AGENTS.md is the highest-leverage file in the project — it goes into every single session. Craft it carefully.
+## Execution Plan
 
-## Process
+### 1) Detect project context first (parallel)
 
-### 1. Check Prerequisites
+Run focused discovery to identify:
+- runtime/language/framework
+- package manager + canonical install/test/build/lint/typecheck commands
+- monorepo vs single app
+- key top-level directories and entry points
+- existing guidance files (`AGENTS.md`, `CLAUDE.md`, `README*`, `CONTRIBUTING*`)
 
-```bash
-ls -la .opencode/ 2>/dev/null
-ls package.json 2>/dev/null
-ls bun.lockb pnpm-lock.yaml yarn.lock 2>/dev/null
-```
-
-If `.opencode/` already exists with CliKit files, warn user and ask before overwriting.
-
-### 2. Install Plugin
-
-```bash
-bun add -d clikit-plugin 2>/dev/null || \
-pnpm add -D clikit-plugin 2>/dev/null || \
-npm install -D clikit-plugin 2>/dev/null
-```
+### 2) Install plugin + entrypoint
 
-### 3. Create Plugin Entry Point
+Install `clikit-plugin` with the project’s package manager.
 
-Create `.opencode/index.ts`:
+Create/ensure `.opencode/index.ts`:
 
-```typescript
+```ts
 import CliKitPlugin from "clikit-plugin";
+
 export default CliKitPlugin;
 ```
 
-### 4. Create Default Configuration
+### 3) Create `.opencode` structure
 
-Create `.opencode/clikit.config.json` with sensible defaults (see existing template).
+Ensure these exist:
+- `.opencode/memory/specs`
+- `.opencode/memory/plans`
+- `.opencode/memory/research`
+- `.opencode/memory/reviews`
+- `.opencode/memory/handoffs`
+- `.opencode/memory/prds`
+- `.opencode/memory/beads`
+- `.opencode/memory/_templates`
 
-### 5. Create Memory Directory Structure
+### 4) Handle existing AGENTS.md safely
 
-```bash
-mkdir -p .opencode/memory/{specs,plans,research,reviews,handoffs,prds,beads,_templates}
-```
+If root `AGENTS.md` exists:
+1. Read it.
+2. Audit briefly for relevance/conciseness.
+3. Ask before replacing.
 
-### 6. Generate AGENTS.md
+If none exists, create one directly.
 
-**This is the most important step.** The AGENTS.md file goes into EVERY session. Follow these principles:
+### 5) Write AGENTS.md (high-signal only)
 
-#### 6a. Explore the Project First (parallel)
+Use **WHAT / WHY / HOW** and keep it concise.
 
-Fire these immediately to understand the project:
+Required sections:
+1. `# <Project Name>`
+2. 1–2 lines: what this project is and why it exists
+3. `## Stack`
+4. `## Project Structure` (compact map of important dirs)
+5. `## Development` (only core universal commands)
+6. `## Where to Find More` (progressive disclosure pointers)
 
-```
-Explore: "Identify: 1) Language/runtime (check package.json, Cargo.toml, go.mod, pyproject.toml, etc.) 2) Framework (Next.js, Express, FastAPI, etc.) 3) Package manager (bun, pnpm, npm, yarn, cargo, pip) 4) Build command 5) Test command 6) Lint command"
-Explore: "Map top-level structure. What are the main directories? Is this a monorepo? What are the apps vs packages vs shared code?"
-Explore: "Find entry points, main config files, and any existing AGENTS.md/CLAUDE.md/CONTRIBUTING.md/README.md with project conventions."
-```
+Quality constraints:
+- target **< 60 lines**
+- include only universally applicable guidance
+- no task-specific playbooks
+- no style-guide/linter content
+- no stale code snippets when a file reference is better
+- prefer pointers to authoritative files
 
-#### 6b. Write AGENTS.md Following Best Practices
+### 6) Validate result
 
-Write to `AGENTS.md` in the project root. Follow these rules strictly:
+Check:
+- plugin entrypoint exists and imports `clikit-plugin`
+- AGENTS.md exists at project root
+- AGENTS.md length and clarity are within target
 
-**TARGET: Under 60 lines. Every line must be universally applicable to every session.**
+### 7) Final response format
 
-**Structure — WHAT / WHY / HOW:**
+Return:
 
 ```markdown
-# [Project Name]
-
-[1-2 sentences: WHAT this project is and WHY it exists. Be specific — not "a web app" but "a real-time collaboration platform for design teams using WebSocket sync".]
-
-## Stack
-
-[Language, runtime, framework, key libraries. One line each, no fluff.]
-
-## Project Structure
-
-[Map the top-level directories. For monorepos, explain what each app/package does. Use a compact tree — max 10-15 lines. Focus on WHERE things are, not what every file does.]
-
-## Development
-
-[Only the commands an agent needs for ANY task. Build, test, typecheck, lint, dev server. Nothing task-specific.]
-
-```bash
-[package-manager] install
-[package-manager] run build
-[package-manager] run test
-[package-manager] run lint
-```
-
-## Where to Find More
-
-[Progressive disclosure — point to files, don't inline their contents. Only include files that actually exist in the project.]
-
-- Architecture decisions: [path or "ask the team"]
-- API patterns: [path]
-- Testing conventions: [path]
-- Contributing guide: [path]
-```
-
-#### 6c. What NOT to Include
-
-Applying the blog's principles strictly:
-
-- ❌ **No code style rules** — that's what linters and formatters do. Hooks handle auto-format and typecheck.
-- ❌ **No task-specific instructions** — "how to create a database migration" doesn't belong. Put that in a separate doc and point to it.
-- ❌ **No model/agent details** — agents know their own config. Don't list all 10 agents and their models.
-- ❌ **No inline code snippets** — they go stale. Use `file:line` pointers instead.
-- ❌ **No exhaustive command lists** — agent can discover commands. Only include the core workflow.
-- ❌ **No "rules" that are just good engineering** — "write clean code" wastes instruction budget. The agent already knows.
-- ❌ **No skill recommendations** — that's task-specific. Skills are discovered at task time.
-
-#### 6d. What TO Include (universally applicable)
-
-- ✅ **What the project IS** — 1-2 sentences, specific.
-- ✅ **Tech stack** — language, runtime, framework, key deps.
-- ✅ **Project map** — where things live (especially monorepos).
-- ✅ **Essential commands** — build, test, lint, dev server.
-- ✅ **Progressive disclosure pointers** — "Read X for Y" references to existing docs.
-- ✅ **Non-obvious conventions** — only things the agent would get WRONG without being told (e.g., "We use Bun, not Node" or "Database migrations use Drizzle push, not migrate").
-- ✅ **Verification commands** — how to confirm changes work.
-
-### 7. If AGENTS.md Already Exists
-
-If the project already has an `AGENTS.md` or `CLAUDE.md`:
-
-1. Read it first
-2. Audit it against the blog principles (concise? universally applicable? progressive disclosure?)
-3. Propose improvements to the user — don't overwrite without asking
-4. If user approves, rewrite following the principles above
-
-### 8. Verify Setup
-
-- Check that plugin loads correctly
-- Verify agents are available
-- Verify AGENTS.md exists and is under 60 lines
-- Count instructions in AGENTS.md — warn if over 30 (LLMs reliably follow ~150 instructions, Claude Code's system prompt already uses ~50)
-
-### 9. Report
-
-```
 ## CliKit Initialized
 
 ✅ Plugin installed
-✅ Entry point: .opencode/index.ts
-✅ Config: .opencode/clikit.config.json
-✅ Memory directories created
-✅ AGENTS.md generated ([N] lines, [M] instructions)
+✅ Entry point configured
+✅ Memory directories ready
+✅ AGENTS.md created/updated
 
 ### AGENTS.md Quality
-- Lines: [N] (target: <60)
-- Instructions: [M] (target: <30, budget shared with system prompt)
-- Progressive disclosure: [Y/N]
-- Task-specific content: [none found / WARNING: found N task-specific items]
-
-### Next Steps
-1. Review AGENTS.md — every line matters, it affects every session
-2. Run `/create` to start a new feature
-3. Customize `.opencode/clikit.config.json` as needed
+- Lines: <count>
+- Universally applicable: yes/no
+- Progressive disclosure pointers: yes/no
+
+### Next
+1. Restart OpenCode
+2. Run /create to begin work
 ```
 
-## AGENTS.md Quality Principles (from humanlayer.dev)
-
-1. **Less is more** — frontier models follow ~150 instructions reliably. System prompt uses ~50. Your AGENTS.md gets ~100 max. Each unnecessary instruction degrades ALL instructions uniformly.
-2. **Universally applicable only** — if it doesn't matter for EVERY session, it doesn't belong here.
-3. **Progressive disclosure** — point to detailed docs, don't inline them. The agent reads them only when relevant.
-4. **Not a linter** — never put code style in AGENTS.md. Use formatters, hooks, and tooling.
-5. **Pointers over copies** — reference `file:line`, not code snippets. Snippets go stale.
-6. **Carefully crafted** — this is the highest leverage point. Every line either helps or hurts.
-
-## Rules
-
-- ✅ ALWAYS explore the project before generating AGENTS.md
-- ✅ ALWAYS keep AGENTS.md under 60 lines
-- ✅ ALWAYS use WHAT/WHY/HOW structure
-- ✅ ALWAYS use progressive disclosure (pointers, not copies)
-- ✅ ALWAYS verify the final instruction count
-- ✅ ALWAYS check for existing AGENTS.md before overwriting
-- ❌ NEVER put code style rules in AGENTS.md
-- ❌ NEVER put task-specific instructions in AGENTS.md
-- ❌ NEVER inline code snippets (they go stale)
-- ❌ NEVER generate more than 30 instructions
-- ❌ NEVER overwrite existing AGENTS.md without asking
+## Important behavior
+
+- Be deliberate: AGENTS.md is high-leverage context for every session.
+- Prefer concise, accurate, project-specific instructions over long generic rules.
+- Do not overwrite existing AGENTS.md without explicit confirmation.

package/command/issue.md

@@ -90,7 +90,7 @@ mcp__beads_village__add(
 ### Next Steps
 - Claim with `/implement`
 - Add to plan with `/plan`
-- View all with `/status`
+- View all with `/status-beads`
 ```
 
 ## Advanced Options

package/command/plan.md

@@ -32,14 +32,19 @@ Fire these immediately alongside codebase exploration:
 
 **Memory mining** (Plan reads directly — has file read access):
 ```
-Read: ".opencode/memory/_digest.md" — Auto-generated from SQLite (decisions, learnings, blockers, handoffs)
+Read: ".opencode/memory/_digest.md" — Compact index of memory topics and highlights
+Read: ".opencode/memory/decision.md" — Detailed architectural decisions
+Read: ".opencode/memory/learning.md" — Detailed learnings and gotchas
+Read: ".opencode/memory/blocker.md" — Past blockers and mitigations
+Read: ".opencode/memory/progress.md" — Recent progress notes
+Read: ".opencode/memory/handoff.md" — Session handoff observations
 Read: ".opencode/memory/research/" — List files, read any related to the feature
 Read: ".opencode/memory/handoffs/" — Read recent handoffs for prior session context
 Read: ".opencode/memory/reviews/" — Check past review findings on related code
 Read: ".opencode/memory/specs/" — Check for prior/related specs
 ```
 
-> `_digest.md` is generated by the Memory Digest hook on session start. Contains past decisions, learnings, blockers, and handoffs from the SQLite observations DB.
+> `_digest.md` is an index generated by the Memory Digest hook. Use topic files (`decision.md`, `learning.md`, etc.) for full details.
 
 Surface from memory files:
 - Past decisions that constrain this plan
@@ -65,9 +70,9 @@ Explore: "Find existing patterns for similar features — structure, naming, tes
 Explore: "Find test infrastructure and conventions — framework, helpers, fixtures."
 ```
 
-For complex features, also fire:
+For complex features, also delegate in parallel:
 ```
-Scout: "Find docs and production patterns for [relevant libraries/APIs]."
+Research: "Find docs and production patterns for [relevant libraries/APIs]."
 Oracle: "Analyze architecture trade-offs for [key decisions]."
 ```
 

package/command/research.md

@@ -1,10 +1,10 @@
 ---
 description: Deep exploration and research before planning.
-agent: plan
+agent: research
 subtask: true
 ---
 
-You are the **Plan Agent** delegating to **Scout Agent**. Execute the `/research` command.
+You are the **Research Agent**. Execute the `/research` command.
 
 ## Template
 
@@ -18,7 +18,7 @@ Conduct deep research on a topic before planning implementation.
 
 1. **Identify research questions** from spec or user request
 
-2. **Delegate to Scout Agent** with:
+2. **Run focused external research** with:
    - Question to research
    - Constraints (language, framework, versions)
    - Format: summary | comparison | deep-dive
@@ -30,7 +30,7 @@ Conduct deep research on a topic before planning implementation.
 
 ## Research Request Format
 
-When delegating, use:
+Use this request schema:
 ```yaml
 type: "research"
 question: "[Research question]"
@@ -98,6 +98,6 @@ bead_id: [optional]
 - `mcp__context7__*` — Library documentation
 - `mcp__exa__*` — Code examples, recent content
 - `mcp__gh_grep__searchGitHub` — Real-world code patterns
-- `librarian` — Deep repository analysis
+- `web_search` + source links — Cross-check and evidence gathering
 
 Identify the research questions from the user's request or the active spec, then begin research immediately.

package/command/ship.md

@@ -1,5 +1,5 @@
 ---
-description: Ship completed work. Final verification, PR creation, and cleanup.
+description: Ship completed work. Enforce verify gate, create PR, and cleanup.
 agent: build
 ---
 
@@ -7,103 +7,95 @@ You are the **Build Agent**. Execute the `/ship` command.
 
 ## Your Task
 
-Finalize and ship the current work — run all verification gates, create a PR, and clean up.
+Finalize and ship the current work only after `/verify` passes with a ship-ready verdict.
 
 ## Process
 
-### 1. Pre-Ship Verification
+### 1. Enforce Verify Gate (Mandatory)
 
-Run ALL hard gates before shipping:
+Run `/verify` first and require:
+- Overall Verdict: `PASS`
+- Ship Recommendation: `SHIP_READY`
+- No `Critical` or `High` findings
 
-```bash
-# Type checking
-pnpm typecheck || npm run typecheck || yarn typecheck
-
-# Tests
-pnpm test || npm test || yarn test
-
-# Linting
-pnpm lint || npm run lint || yarn lint
-
-# Build
-pnpm build || npm run build || yarn build
-```
-
-If ANY gate fails, stop and fix before continuing.
+If `/verify` returns `FAIL`, `CHANGES_REQUIRED`, or `BLOCKED`:
+- Stop shipping
+- Present required fixes
+- Ask user whether to fix now
 
-### 2. Self-Review
+### 2. Final Self-Review
 
 Before creating PR:
-- Review all changed files (`git diff main`)
-- Check for debug code, console.logs, TODOs
-- Verify acceptance criteria from spec.md
-- Ensure no files outside plan's file impact were changed
+- Review changed files (`git diff --name-only` and `git diff`)
+- Confirm acceptance criteria from spec/plan are satisfied
+- Confirm no debug artifacts (`console.log`, `TODO`, temporary hacks)
+- Confirm changes stay within planned file impact
 
-### 3. Request Review (Optional)
+### 3. Optional Formal Review
 
-Delegate to Review Agent for formal review:
-- Pass changed files list
-- Pass spec.md and plan.md references
-- Wait for verdict
-
-If verdict is `changes_required`, fix issues before continuing.
-If verdict is `blocked`, escalate to user.
+If requested, run `/review` and apply verdict:
+- `approved` → continue
+- `changes_required` → stop and fix first
+- `blocked` → escalate to user
 
 ### 4. Git Preparation
 
 ```bash
-# Ensure clean state
+# Ensure clean understanding of local state
 git status
 
-# Stage changes
-git add -A
+# Stage only files related to this work (never blanket add)
+git add <explicit-file-list>
 
-# Create commit with conventional format
+# Commit using conventional format
 git commit -m "type(scope): description"
 ```
 
 ### 5. Create PR
 
-Delegate to `/pr` command flow:
-- Generate comprehensive PR description
-- Link spec, plan, review artifacts
+Use `/pr` flow:
+- Generate complete PR description
+- Link spec, plan, verify, and review artifacts
 - Create PR via `gh pr create`
 
 ### 6. Post-Ship Cleanup
 
-- Update bead status to `done` or `validating`
-- Create handoff document for tracking
-- Report PR URL to user
+- Update bead/task status
+- Create handoff note if needed
+- Report PR URL + final ship summary to user
 
 ## Ship Checklist
 
 ```
-Pre-Ship:
-- [ ] Typecheck passes
-- [ ] All tests pass
-- [ ] Lint passes
-- [ ] Build succeeds
+Verify Gate:
+- [ ] /verify executed
+- [ ] Overall Verdict = PASS
+- [ ] Ship Recommendation = SHIP_READY
+- [ ] No Critical/High findings
+
+Pre-PR:
 - [ ] Self-review completed
+- [ ] Acceptance criteria verified
 - [ ] No debug/temporary code
 
 Ship:
-- [ ] Changes committed
-- [ ] PR created with full description
-- [ ] Artifacts linked
+- [ ] Relevant files staged explicitly
+- [ ] Commit created
+- [ ] PR created with linked artifacts
 
 Post-Ship:
-- [ ] Bead status updated
+- [ ] Status updated
 - [ ] PR URL reported
 ```
 
 ## Rules
 
-- ✅ ALWAYS run full verification before shipping
-- ✅ ALWAYS self-review changes
-- ✅ ALWAYS create proper commit messages
-- ✅ ALWAYS link artifacts in PR
-- ❌ NEVER ship with failing tests
-- ❌ NEVER ship without verification
-- ❌ NEVER skip self-review
+- ✅ ALWAYS run `/verify` before shipping
+- ✅ ALWAYS block ship when verify is not ship-ready
+- ✅ ALWAYS stage explicit files only
+- ✅ ALWAYS include verification artifacts in PR
+- ❌ NEVER ship with failing gates
+- ❌ NEVER bypass verify verdict
+- ❌ NEVER use `git add -A` or `git add .`
 
-Now, let me verify and ship your work...
+Now, enforcing verify gate before ship...