clikit-plugin 0.2.28 → 0.2.30

package/AGENTS.md

@@ -1,21 +1,10 @@
 # CliKit
 
-OpenCode plugin with 10 agents, 19 commands, 48 skills, 14 hooks.
-
-## Agents
-
-| Agent | Role |
-|-------|------|
-| @build | Primary executor |
-| @plan | Strategic planning |
-| @general | Multi-step tasks |
-| @oracle | Architecture advisor |
-| @librarian | Multi-repo analysis |
-| @explore | Fast navigation |
-| @looker | Deep inspection |
-| @scout | External research |
-| @review | Code review |
-| @vision | Design + visuals |
+An OpenCode plugin that provides agents, commands, skills, hooks, and a memory system for AI-assisted development. Built with TypeScript and Bun.
+
+## 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`.
 
 ## Workflow
 
@@ -23,24 +12,33 @@ OpenCode plugin with 10 agents, 19 commands, 48 skills, 14 hooks.
 /create → /plan → /start → /verify → /ship
 ```
 
-## Rules
+Always verify before claiming done. Run typecheck + lint + test before commit.
 
-- Always verify before claiming done
-- Use TDD for new features
-- Check todos before session end
-- Run typecheck + lint + test before commit
-- Never force push without --force-with-lease
+## Where to Find Things
 
-## Memory
+- **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.
+- **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.
+- **Full docs**: `@.opencode/README.md` — complete reference for all agents, commands, skills, hooks, and config options.
 
-- Specs: `.opencode/memory/specs/`
-- Plans: `.opencode/memory/plans/`
-- Handoffs: `.opencode/memory/handoffs/`
+## Development
+
+```bash
+bun install        # dependencies
+bun run build      # compile plugin
+bun run typecheck  # type check
+bun run dev        # watch mode
+```
 
-## Skills
+## Key Conventions
 
-Load relevant skills before tasks:
-- TDD: `test-driven-development`
-- Debugging: `systematic-debugging`
-- Planning: `brainstorming` → `writing-plans`
-- Design: `frontend-aesthetics`
+- Plugin entrypoint: `src/index.ts`
+- Agents are parsed from markdown frontmatter (gray-matter): `src/agents/index.ts`
+- Commands are parsed the same way: `src/commands/index.ts`
+- 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`

package/README.md

@@ -7,10 +7,9 @@ Curated agents, commands, skills, and memory system for OpenCode.
 - **10 Specialized Agents**: build, general, oracle, librarian, explore, looker, plan, review, scout, vision
 - **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 Custom Tools**: memory (6), observation, swarm, beads-memory-sync, quick-research, context-summary
-- **14 Runtime Hooks**: git guard, security check, auto-format, typecheck gate, truncator, compaction, ritual enforcer, session notifications, 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
 - **Memory System**: Templates, specs, plans, research artifacts with FTS5 search
-- **Ritual Workflow**: Enforces DISCOVER → PLAN → IMPLEMENT → VERIFY → COMPLETE phases
 - **Extended Permissions**: doom_loop, external_directory controls
 - **Configurable**: Enable/disable agents, override models, customize behavior
 
@@ -25,6 +24,18 @@ 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:
+
+- `beads-village` (`npx beads-village`)
+- `context7` (`https://mcp.context7.com/mcp`)
+- `grep` (`https://mcp.grep.app`)
+- `human-mcp` (`npx @goonnguyen/human-mcp`)
+
+Recommended environment variables:
+
+- `CONTEXT7_API_KEY` for Context7
+- `GOOGLE_GEMINI_API_KEY` for Human MCP
+
 ## Quick Start
 
 After installation, use these commands:
@@ -35,12 +46,14 @@ After installation, use these commands:
 
 ## Configuration
 
-Create `clikit.config.json` in one of these locations:
+Create `clikit.jsonc` (preferred) or `clikit.json` in one of these locations:
 
 - **User (global)**:
-  - Linux/macOS: `~/.config/opencode/clikit.config.json`
-  - Windows: `%APPDATA%\opencode\clikit.config.json`
-- **Project**: `.opencode/clikit.config.json`
+  - Linux/macOS: `~/.config/opencode/clikit.jsonc` (or `clikit.json`)
+  - Windows: `%APPDATA%\opencode\clikit.jsonc` (or `clikit.json`)
+- **Project**: `.opencode/clikit.jsonc` (or `clikit.json`)
+
+Legacy `clikit.config.json` is still supported for backward compatibility.
 
 Project config overrides user config.
 
@@ -48,9 +61,14 @@ Project config overrides user config.
 
 ```json
 {
-  "$schema": "https://unpkg.com/clikit-plugin/schema.json",
+  "$schema": "https://unpkg.com/clikit-plugin@latest/schema.json",
   "disabled_agents": ["scout"],
   "disabled_commands": ["security"],
+  "disabled_skills": ["playwright"],
+  "skills": {
+    "enable": ["test-driven-development", "systematic-debugging"],
+    "disable": ["sharing-skills"]
+  },
   "agents": {
     "oracle": {
       "model": "openai/gpt-4o"
@@ -65,21 +83,17 @@ Project config overrides user config.
     }
   },
   "hooks": {
-    "session_logging": true,
+    "session_logging": false,
     "tool_logging": false,
     "todo_enforcer": { "enabled": true },
     "empty_message_sanitizer": { "enabled": true },
     "git_guard": { "enabled": true },
     "security_check": { "enabled": true },
     "subagent_question_blocker": { "enabled": true },
-    "comment_checker": { "enabled": true, "threshold": 0.3 },
-    "env_context": { "enabled": true },
-    "auto_format": { "enabled": false },
-    "typecheck_gate": { "enabled": false },
-    "session_notification": { "enabled": true },
     "truncator": { "enabled": true },
-    "compaction": { "enabled": true },
-    "swarm_enforcer": { "enabled": true }
+    "swarm_enforcer": { "enabled": true },
+    "memory_digest": { "enabled": true },
+    "todo_beads_sync": { "enabled": true }
   }
 }
 ```
@@ -90,9 +104,11 @@ Project config overrides user config.
 |--------|------|---------|-------------|
 | `disabled_agents` | `string[]` | `[]` | Agent names to disable |
 | `disabled_commands` | `string[]` | `[]` | Command names to disable |
+| `disabled_skills` | `string[]` | `[]` | Skill names to disable |
 | `agents` | `object` | `{}` | Per-agent overrides (model, temperature, etc.) |
 | `commands` | `object` | `{}` | Per-command overrides |
-| `hooks.session_logging` | `boolean` | `true` | Session lifecycle logging |
+| `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 |
 
 ### Hooks
@@ -104,14 +120,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 |
-| `comment_checker` | on | Detects excessive AI-generated comments in code |
-| `env_context` | on | Injects git branch, package info, project structure |
-| `auto_format` | **off** | Runs prettier/biome/dprint after file edits |
-| `typecheck_gate` | **off** | Runs tsc after TypeScript file edits |
-| `session_notification` | on | Desktop notifications on idle/error (Linux/macOS/Windows) |
 | `truncator` | on | Truncates large outputs to prevent context overflow |
-| `compaction` | on | Preserves beads state + memory during context compaction |
 | `swarm_enforcer` | on | Enforces task isolation in multi-agent swarms |
+| `memory_digest` | on | Generates `memory/_digest.md` from SQLite observations |
+| `todo_beads_sync` | on | Mirrors OpenCode todos into Beads issues |
 
 ## Agents
 
@@ -154,7 +166,7 @@ Run with `/command-name` in OpenCode:
 
 ## Skills
 
-47 workflow skills organized into 8 categories:
+48 workflow skills organized into 8 categories:
 
 ### Design & Planning (4)
 | Skill | Use When |
@@ -247,6 +259,12 @@ bun run build
 # Type check
 bun run typecheck
 
+# Unit tests
+bun run test
+
+# Full local verification
+bun run verify
+
 # Watch mode
 bun run dev
 ```
@@ -261,7 +279,8 @@ bun run dev
 │   ├── types.ts      # Type definitions
 │   ├── agents/       # Agent loaders
 │   ├── skills/       # Skill loaders
-│   └── hooks/        # Runtime hooks (13 modules)
+│   ├── tools/        # Internal utilities (memory, swarm, etc.)
+│   └── hooks/        # Runtime hooks (10 modules)
 ├── skill/            # Skill definitions (*.md)
 ├── command/          # Command definitions (*.md)
 ├── memory/           # Memory system
@@ -273,7 +292,7 @@ bun run dev
 │   ├── handoffs/     # Session handoffs
 │   ├── beads/        # Beads task artifacts
 │   └── prds/         # Product requirements
-└── clikit.config.json
+└── clikit.jsonc
 ```
 
 ## License

package/command/create.md

@@ -1,5 +1,5 @@
 ---
-description: Start a new bead. Gather requirements and create specification.
+description: Start a new bead. Explore codebase, gather requirements, create specification.
 agent: plan
 ---
 
@@ -9,142 +9,57 @@ You are the **Plan Agent**. Execute the `/create` command.
 
 Use template at: `@.opencode/memory/_templates/spec.md`
 
-## Your Task
+## Execution Rules
 
-Create a new specification and bead for the user's goal/idea.
+- **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
 
 ## Process
 
-1. **Interview** the user using 5 core dimensions:
-   - **Problem & Context** — Why is this needed? Who is affected?
-   - **Outcomes** — What changes if successful?
-   - **Scope** — What's in/out of boundaries?
-   - **Users** — Primary and secondary users?
-   - **Constraints** — Performance, security, timeline?
+### 1. Proactive Exploration (BEFORE asking questions)
 
-2. **Paraphrase and confirm**: "Is anything missing or wrong?"
+Fire Explore agents in parallel immediately:
+- Find similar implementations, patterns, and conventions in the codebase
+- Find test infrastructure (framework, coverage, examples)
+- Find related code that this feature will integrate with
 
-3. **Generate `spec.md`** at `.opencode/memory/specs/YYYY-MM-DD-<descriptor>.md` using the canonical template
+### 2. Informed Interview
 
-4. **Create bead** via `mcp__beads_village__add()` with title, description, and priority
+Use exploration results to ask SPECIFIC questions across 5 dimensions:
+- **Problem & Context** — Why is this needed? (reference what you found in codebase)
+- **Outcomes** — What measurable changes?
+- **Scope** — In/out boundaries? (suggest based on codebase patterns)
+- **Users** — Primary/secondary users?
+- **Constraints** — Technical, business, timeline?
 
-## Spec Structure (follows `_templates/spec.md`)
+Max 3 questions per turn. Update draft after each exchange.
 
-The spec MUST include:
+### 3. Self-Clearance Check
 
-```markdown
-# Specification: [Title]
+When ALL of these are true, auto-transition to spec generation:
+- Core problem understood and confirmed
+- Scope boundaries defined
+- Enough info for acceptance criteria
+- Codebase patterns identified
+- No critical open questions
 
-**Date:** YYYY-MM-DD
-**Author:** [Name]
-**Status:** Draft | Confirmed
-**bead_id:** [ID]
+### 4. Generate Spec
 
----
-
-## Problem & Context
-
-### Problem Statement
-[Why is this needed?]
+Write to `.opencode/memory/specs/YYYY-MM-DD-<descriptor>.md` using full template structure.
 
-### Background
-[Context and history]
-
-### Who is Affected
-[Stakeholders and users impacted]
-
----
-
-## Outcomes
-
-### Success Criteria
-1. [Measurable outcome 1]
-2. [Measurable outcome 2]
-
-### Key Results
-| Outcome | Metric | Target |
-|---------|--------|--------|
-| [Outcome] | [How to measure] | [Target value] |
-
----
+**Acceptance criteria MUST be agent-executable** — commands with expected outputs, not "user manually verifies."
 
-## Scope
-
-### In Scope
-- [Feature/capability 1]
-
-### Out of Scope
-- [Excluded item 1]
-
-### Boundaries
-[Clear boundaries of what this spec covers]
-
----
-
-## Users
-
-### Primary Users
-| User Type | Description | Needs |
-|-----------|-------------|-------|
-| [Type] | [Who they are] | [What they need] |
-
-### Secondary Users
-| User Type | Description | Needs |
-|-----------|-------------|-------|
-
----
+### 5. Create Bead
 
-## Constraints
-
-### Technical Constraints
-- [Constraint 1]
-
-### Business Constraints
-- [Timeline, budget, etc.]
-
-### Dependencies
-| Dependency | Type | Status |
-|------------|------|--------|
-| [Dependency] | Blocking/Soft | Ready/Pending |
-
----
-
-## Acceptance Criteria
-
-| ID | Criteria | Verification |
-|----|----------|--------------|
-| AC-01 | [Criteria] | [How to verify] |
-| AC-02 | [Criteria] | [How to verify] |
-
----
-
-## Assumptions
-
-| ID | Assumption | Status | Notes |
-|----|------------|--------|-------|
-| A-01 | [Assumption] | Confirmed/Unconfirmed | [Notes] |
-
----
-
-## Open Questions
-
-- [ ] [Question 1]
-- [ ] [Question 2]
-
----
-
-## References
-
-- [Link to related docs]
-```
+Call `mcp__beads_village__add()` with title, description, and priority.
 
 ## Rules
 
-- ✅ ALWAYS use the full template structure from `_templates/spec.md`
-- ✅ ALWAYS include frontmatter (Date, Author, Status, bead_id)
-- ✅ ALWAYS ask clarifying questions if goal is vague
-- ✅ ALWAYS tag assumptions clearly as "Confirmed" vs "Unconfirmed"
-- ✅ ALWAYS get user confirmation before finalizing
-- ❌ NEVER skip the Acceptance Criteria section
-
-Now, ask the user about their goal/idea to begin the interview process.
+- ✅ Explore codebase BEFORE asking user questions
+- ✅ Write agent-executable acceptance criteria
+- ✅ Tag assumptions as Confirmed/Unconfirmed
+- ✅ Auto-transition when clearance check passes
+- ❌ NEVER ask generic questions without codebase context
+- ❌ NEVER skip acceptance criteria
+- ❌ NEVER end passively — always question or action

package/command/handoff.md

@@ -1,95 +1,71 @@
 ---
-description: Save state for session break.
-agent: plan
+description: Save state for session break. Auto-gathers context and writes handoff immediately.
+agent: build
 ---
 
-You are the **Plan Agent** (or **Build Agent**). Execute the `/handoff` command.
+You are the **Build Agent**. Execute the `/handoff` command **immediately without asking for confirmation**.
 
-## Template
+## Execution Rules
 
-Use template at: `@.opencode/memory/_templates/handoff.md`
+- **DO NOT** ask the user any questions
+- **DO NOT** wait for confirmation
+- **DO NOT** present a plan before acting
+- Gather all state automatically and write the handoff document in one shot
 
-## Your Task
+## Process (execute all steps silently)
 
-Save the current work state for a session break, enabling seamless resumption later.
+### 1. Auto-Gather State
 
-## Process
+Run these in parallel:
+- `git branch --show-current` — current branch
+- `git log --oneline -5` — recent commits
+- `git status --short` — uncommitted changes
+- `git diff --stat` — what changed
+- Check `.opencode/memory/plans/` for active plan
+- Check `.opencode/memory/specs/` for active spec
+- Check ritual state if exists
 
-1. **Gather current state**:
-   - Which phase are we in? (spec'd, researched, planned, implementing, validating)
-   - What tasks are completed/in-progress/blocked?
-   - What files have been modified?
+### 2. Write Handoff
 
-2. **Create handoff document** at `.opencode/memory/handoffs/YYYY-MM-DD-<phase>.md`
-
-3. **Update bead metadata** with handoff reference
-
-## Handoff Template
+Create `.opencode/memory/handoffs/YYYY-MM-DD-handoff.md` with this structure:
 
 ```markdown
 ---
 date: YYYY-MM-DD
-phase: spec'd | researched | planned | implementing | validating
-branch: [git branch name]
-bead_id: [optional]
+phase: discover | plan | implement | verify | complete
+branch: <branch>
 ---
 
-# Handoff: [Feature/Task Name]
-
-## Status Summary
-[2-5 sentences describing current state]
-
-## Artifacts
-
-| Type | Path | Status |
-|------|------|--------|
-| Spec | `.opencode/memory/specs/YYYY-MM-DD-descriptor.md` | ✅ Complete |
-| Plan | `.opencode/memory/plans/YYYY-MM-DD-feature.md` | ✅ Complete |
-| Research | `.opencode/memory/research/YYYY-MM-DD-topic.md` | 📚 Reference |
+# Handoff: <what we were working on>
 
-## Task Status
+## What Was Done
+<2-3 bullet points of concrete accomplishments>
 
-### ✅ Completed
-- [x] T-001: [Task title]
-- [x] T-002: [Task title]
+## Current State
+- Branch: `<branch>`
+- Last commit: `<hash>` — <message>
+- Uncommitted: <yes/no, list if yes>
 
-### 🔄 In Progress
-- [ ] T-003: [Task title]
-  - **Current state:** [What's been done]
-  - **Next step:** [What to do next]
+## Active Artifacts
+- Spec: `<path>` (if exists)
+- Plan: `<path>` (if exists)
 
-### ⏸️ Blocked
-- [ ] T-004: [Task title]
-  - **Blocked by:** [Reason/dependency]
+## What To Do Next
+1. <immediate next action — be specific>
+2. <following action>
+3. <after that>
 
-### 📋 Not Started
-- [ ] T-005: [Task title]
-
-## Files Modified
-| File | Status | Notes |
-|------|--------|-------|
-| path/to/file.ts | Modified | [Brief note] |
-
-## Git State
-- **Branch:** [branch name]
-- **Last commit:** [hash] - [message]
-- **Uncommitted changes:** Yes/No
-
-## Known Issues
-- [Issue 1]
+## Key Context
+<1-3 sentences of critical context the next session must know — decisions made, gotchas, things that didn't work>
+```
 
-## Next Steps
-1. [Next action 1]
-2. [Next action 2]
+### 3. Confirm Completion
 
-## Context for Resumption
-[Any important context the next session needs to know]
+After writing, output a single line:
+```
+✅ Handoff saved to .opencode/memory/handoffs/<filename>. Resume with /resume.
 ```
 
-## Rules
-- Include all relevant artifact paths
-- Be specific about what's done vs what's remaining
-- Note any blockers or issues
-- Provide clear next steps
+## Philosophy
 
-Now, let me gather the current state and create the handoff document.
+Inspired by Amp's handoff: focus on **what needs to be done next**, not exhaustive history. Keep it short — a future agent should understand the situation in 30 seconds. The handoff is a launchpad, not a journal.