clikit-plugin 0.2.36 → 0.2.38

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 |
 

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...

package/command/verify.md

@@ -1,5 +1,5 @@
 ---
-description: Run full verification suite. Typecheck, tests, lint, build.
+description: Deep verification gate before ship. Run required checks + structured review verdict.
 agent: build
 subtask: true
 ---
@@ -8,72 +8,96 @@ You are the **Build Agent**. Execute the `/verify` command.
 
 ## Your Task
 
-Run the full verification suite and report results.
+Run a strict pre-ship verification gate and produce a ship recommendation.
 
 ## Process
 
-### 1. Detect Project Tools
+### 1) Load Constraints First (Mandatory)
 
-Check which tools are available:
+Before running checks:
+1. Read `AGENTS.md` and any directory-specific AGENTS guidance for changed files.
+2. Read `package.json` scripts.
+3. Inspect changed files (`git diff --name-only`) so the review can focus on actual impact.
 
-```bash
-# Check package manager
-ls package.json && cat package.json | head -5
-ls bun.lockb && echo "bun" || ls pnpm-lock.yaml && echo "pnpm" || ls yarn.lock && echo "yarn" || echo "npm"
-```
+### 2) Detect Runtime + Command Strategy
+
+- Detect package manager from lockfiles (`bun.lock`, `bun.lockb`, `pnpm-lock.yaml`, `yarn.lock`, else npm).
+- Prefer project scripts from `package.json`.
+- If script is missing, use safe fallback command.
+- Do **not** skip a required gate.
 
-Read `package.json` scripts to determine available commands.
+### 3) Run Required Verification Gates (All 4)
 
-### 2. Run Verification Gates
+Run all gates even if earlier gates fail. Record status and key output for each.
 
-Execute in order, collecting results:
+| Gate | Preferred | Fallbacks | Required |
+|------|-----------|-----------|----------|
+| Typecheck | `<pm> run typecheck` | `tsc --noEmit` | Yes |
+| Tests | `<pm> test` or `<pm> run test` | `bun test` | Yes |
+| Lint | `<pm> run lint` | `eslint .` | Yes |
+| Build | `<pm> run build` | `bun run build` | Yes |
 
-| Gate | Commands (try in order) | Required |
-|------|------------------------|----------|
-| **Typecheck** | `pnpm typecheck`, `npm run typecheck`, `tsc --noEmit` | Yes |
-| **Tests** | `pnpm test`, `npm test`, `bun test` | Yes |
-| **Lint** | `pnpm lint`, `npm run lint`, `eslint .` | Yes |
-| **Build** | `pnpm build`, `npm run build`, `bun run build` | Yes |
+### 4) Deep Review Pass (After Commands)
 
-Run each gate. If a gate fails, continue to the next but record the failure.
+Review changed files and report findings by severity:
+- **Critical**: security/data-loss/corruption risk
+- **High**: correctness bug, broken acceptance criteria, major regression risk
+- **Medium**: edge-case gap, weak test coverage, maintainability risk
+- **Low**: clarity/style/doc polish
 
-### 3. Report Results
+Review checklist:
+- Requirements and acceptance criteria alignment
+- Risky logic paths and edge cases
+- Security/privacy concerns
+- Missing or weak tests for changed behavior
+- Debug leftovers / temporary code
 
-Format results clearly:
+### 5) Output Format (Strict)
 
 ```
 ## Verification Report
 
-| Gate       | Status | Details          |
-|------------|--------|------------------|
-| Typecheck  | ✅/❌  | [error count]    |
-| Tests      | ✅/❌  | [pass/fail/skip] |
-| Lint       | ✅/❌  | [warning/error]  |
-| Build      | ✅/❌  | [output]         |
-
-### Overall: PASS / FAIL
-
-### Failures (if any)
-[Detailed error output for each failing gate]
-
-### Recommended Fixes
-1. [Fix suggestion]
+### Context
+- Changed files: [...]
+- Constraints loaded: [AGENTS.md, ...]
+- Package manager: <pm>
+
+| Gate       | Status | Command Used       | Details |
+|------------|--------|--------------------|---------|
+| Typecheck  | ✅/❌  | ...                | ...     |
+| Tests      | ✅/❌  | ...                | ...     |
+| Lint       | ✅/❌  | ...                | ...     |
+| Build      | ✅/❌  | ...                | ...     |
+
+### Review Findings
+#### Critical
+- ...
+#### High
+- ...
+#### Medium
+- ...
+#### Low
+- ...
+
+### Overall Verdict
+- PASS | FAIL
+
+### Ship Recommendation
+- SHIP_READY | CHANGES_REQUIRED | BLOCKED
+
+### Required Fixes (if not SHIP_READY)
+1. ...
+2. ...
 ```
 
-### 4. Fix Mode (Optional)
-
-If the user asks to fix issues:
-- Fix typecheck errors first (most foundational)
-- Then lint errors
-- Then test failures
-- Re-run verification after fixes
-
-## Rules
+## Gate Rules
 
-- ✅ ALWAYS run all 4 gates even if one fails
-- ✅ ALWAYS report detailed error output
-- ✅ ALWAYS suggest fixes for failures
-- ❌ NEVER auto-fix without user confirmation
-- ❌ NEVER report passing if any gate fails
+- ✅ ALWAYS run all 4 required gates
+- ✅ ALWAYS read constraints before checks
+- ✅ ALWAYS include command used + key output per gate
+- ✅ ALWAYS include severity-ranked review findings
+- ❌ NEVER auto-fix unless user explicitly asks
+- ❌ NEVER mark PASS if any required gate fails
+- ❌ NEVER mark SHIP_READY when Critical/High findings exist
 
-Now, running verification...
+Now, running deep verification...