clikit-plugin 0.1.0

package/AGENTS.md

@@ -0,0 +1,46 @@
+# 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 |
+
+## Workflow
+
+```
+/create → /plan → /start → /verify → /ship
+```
+
+## Rules
+
+- 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
+
+## Memory
+
+- Specs: `.opencode/memory/specs/`
+- Plans: `.opencode/memory/plans/`
+- Handoffs: `.opencode/memory/handoffs/`
+
+## Skills
+
+Load relevant skills before tasks:
+- TDD: `test-driven-development`
+- Debugging: `systematic-debugging`
+- Planning: `brainstorming` → `writing-plans`
+- Design: `frontend-aesthetics`

package/README.md

@@ -0,0 +1,282 @@
+# CliKit Plugin for OpenCode
+
+Curated agents, commands, skills, and memory system for OpenCode.
+
+## Features
+
+- **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
+- **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
+
+## Installation
+
+### Option 1: Via npm (Recommended)
+
+```bash
+# In your project
+bun add -d clikit-plugin
+
+# Create .opencode/index.ts
+echo 'import CliKitPlugin from "clikit-plugin";
+export default CliKitPlugin;' > .opencode/index.ts
+```
+
+### Option 2: Direct Copy
+
+```bash
+# Copy the built plugin to OpenCode plugin directory
+cp dist/index.js ~/.config/opencode/plugin/clikit-plugin.js
+```
+
+## Configuration
+
+Create `clikit.config.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`
+
+Project config overrides user config.
+
+### Example Configuration
+
+```json
+{
+  "$schema": "https://unpkg.com/clikit-plugin/schema.json",
+  "disabled_agents": ["scout"],
+  "disabled_commands": ["security"],
+  "agents": {
+    "oracle": {
+      "model": "openai/gpt-4o"
+    },
+    "build": {
+      "model": "anthropic/claude-sonnet-4-5-20250514",
+      "temperature": 0.2,
+      "permission": {
+        "doom_loop": "deny",
+        "external_directory": "ask"
+      }
+    }
+  },
+  "hooks": {
+    "session_logging": true,
+    "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": false }
+  }
+}
+```
+
+### Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `disabled_agents` | `string[]` | `[]` | Agent names to disable |
+| `disabled_commands` | `string[]` | `[]` | Command names to disable |
+| `agents` | `object` | `{}` | Per-agent overrides (model, temperature, etc.) |
+| `commands` | `object` | `{}` | Per-command overrides |
+| `hooks.session_logging` | `boolean` | `true` | Session lifecycle logging |
+| `hooks.tool_logging` | `boolean` | `false` | Tool execution logging |
+
+### Hooks
+
+| Hook | Default | Description |
+|------|---------|-------------|
+| `todo_enforcer` | on | Warns when todos are incomplete at session idle |
+| `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 |
+| `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` | **off** | Enforces task isolation in multi-agent swarms |
+
+## 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 |
+| `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 |
+
+## 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` - Workspace and bead overview
+- `/commit` - Intelligent git commit
+- `/issue` - Quick issue creation
+- `/import-plan` - Import from Jira/Notion/Linear
+
+## Skills
+
+47 workflow skills organized into 8 categories:
+
+### Design & Planning (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 |
+
+### 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)
+| 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 |
+| `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 |
+
+### Testing (4)
+| 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 |
+
+### Debugging (4)
+| 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)
+| Skill | Use When |
+|-------|----------|
+| `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
+
+```bash
+# Install dependencies
+bun install
+
+# Build
+bun run build
+
+# Type check
+bun run typecheck
+
+# Watch mode
+bun run dev
+```
+
+## Structure
+
+```
+.opencode/
+├── src/
+│   ├── index.ts      # Plugin entrypoint
+│   ├── config.ts     # Config loader
+│   ├── types.ts      # Type definitions
+│   ├── agents/       # Agent loaders
+│   ├── skills/       # Skill loaders
+│   └── hooks/        # Runtime hooks (13 modules)
+├── skill/            # Skill definitions (*.md)
+├── command/          # Command definitions (*.md)
+├── memory/           # Memory system
+│   ├── _templates/   # Document templates
+│   ├── specs/        # Specifications
+│   ├── plans/        # Implementation plans
+│   ├── research/     # Research artifacts
+│   ├── reviews/      # Code reviews
+│   ├── handoffs/     # Session handoffs
+│   ├── beads/        # Beads task artifacts
+│   └── prds/         # Product requirements
+└── clikit.config.json
+```
+
+## License
+
+MIT

package/command/commit.md

@@ -0,0 +1,137 @@
+---
+description: Intelligent git commit with Conventional Commits format.
+agent: build
+---
+
+You are creating an **intelligent git commit** with proper message formatting.
+
+## Your Task
+
+Analyze changes and create a well-formatted commit following Conventional Commits.
+
+## Process
+
+### 1. Analyze Changes
+
+```bash
+git status
+git diff --staged
+git diff  # if nothing staged
+```
+
+### 2. Determine Commit Type
+
+| Type | When |
+|------|------|
+| `feat` | New feature |
+| `fix` | Bug fix |
+| `docs` | Documentation only |
+| `style` | Formatting, no code change |
+| `refactor` | Code change, no feature/fix |
+| `perf` | Performance improvement |
+| `test` | Adding/updating tests |
+| `chore` | Build, deps, tooling |
+| `ci` | CI/CD changes |
+
+### 3. Identify Scope
+
+Based on changed files:
+- `auth` — Authentication related
+- `api` — API changes
+- `ui` — Frontend/UI
+- `db` — Database
+- `core` — Core logic
+- Or specific module name
+
+### 4. Generate Message
+
+Format:
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer]
+bead_id: [id if applicable]
+```
+
+### 5. Stage & Commit
+
+```bash
+# Stage if needed
+git add [files]
+
+# Commit
+git commit -m "[message]"
+```
+
+## Commit Template
+
+```markdown
+## 📝 Commit Preview
+
+### Changes Detected
+| File | Status | Lines |
+|------|--------|-------|
+| path/to/file.ts | Modified | +10 / -5 |
+
+### Suggested Commit
+
+```
+feat(auth): add JWT refresh token support
+
+- Implement token refresh endpoint
+- Add automatic refresh on 401
+- Update auth middleware
+
+bead_id: T-xxx
+```
+
+### Actions
+- [x] Stage all changes
+- [ ] Stage specific files
+- [ ] Edit message
+- [ ] Commit
+
+Proceed with commit? [Y/n/edit]
+```
+
+## Smart Detection
+
+| Changes In | Suggested Type |
+|------------|----------------|
+| `*.test.ts` | `test` |
+| `*.md`, `docs/` | `docs` |
+| `package.json` (deps) | `chore(deps)` |
+| `.github/`, CI files | `ci` |
+| Bug fix patterns | `fix` |
+| New files + exports | `feat` |
+
+## Options
+
+```
+/commit              # Auto-detect and suggest
+/commit -a           # Stage all + commit
+/commit --amend      # Amend last commit
+/commit -m "msg"     # Use specific message
+/commit --dry-run    # Preview only
+```
+
+## Breaking Changes
+
+If breaking change detected:
+```
+feat(api)!: change response format
+
+BREAKING CHANGE: Response now returns {data, meta} wrapper
+```
+
+## Rules
+
+- ✅ ALWAYS use Conventional Commits format
+- ✅ ALWAYS include bead_id if working on a bead
+- ✅ ALWAYS verify staged changes before commit
+- ❌ NEVER commit with generic messages like "fix" or "update"
+- ❌ NEVER commit sensitive data (secrets, keys)
+
+Now analyzing changes for commit...

package/command/create.md

@@ -0,0 +1,150 @@
+---
+description: Start a new bead. Gather requirements and create specification.
+agent: plan
+---
+
+You are the **Plan Agent**. Execute the `/create` command.
+
+## Template
+
+Use template at: `@.opencode/memory/_templates/spec.md`
+
+## Your Task
+
+Create a new specification and bead for the user's goal/idea.
+
+## 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?
+
+2. **Paraphrase and confirm**: "Is anything missing or wrong?"
+
+3. **Generate `spec.md`** at `.opencode/memory/specs/YYYY-MM-DD-<descriptor>.md` using the canonical template
+
+4. **Create bead** via `mcp__beads_village__add()` with title, description, and priority
+
+## Spec Structure (follows `_templates/spec.md`)
+
+The spec MUST include:
+
+```markdown
+# Specification: [Title]
+
+**Date:** YYYY-MM-DD
+**Author:** [Name]
+**Status:** Draft | Confirmed
+**bead_id:** [ID]
+
+---
+
+## Problem & Context
+
+### Problem Statement
+[Why is this needed?]
+
+### 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] |
+
+---
+
+## 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 |
+|-----------|-------------|-------|
+
+---
+
+## 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]
+```
+
+## 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.