clikit-plugin 0.1.0

package/command/debug.md

@@ -0,0 +1,185 @@
+---
+description: Debug issues, find root cause, implement fix.
+agent: build
+---
+
+You are the **Build Agent**. Execute the `/debug` command.
+
+## Your Task
+
+Systematically debug an issue: find root cause, implement fix, verify, and prevent regression.
+
+## Process
+
+### 1. Reproduce the Issue
+
+```bash
+# Run the failing test/command
+[command that shows the error]
+```
+
+Document:
+- Error message / stack trace
+- Steps to reproduce
+- Expected vs actual behavior
+
+### 2. Gather Evidence
+
+```bash
+# Recent changes
+git log --oneline -10
+git diff HEAD~5
+
+# Search for related code
+Grep: [error pattern]
+```
+
+### 3. Investigate
+
+```
+Hypothesis → Evidence → Verify → Repeat
+```
+
+1. Form hypothesis about cause
+2. Predict what evidence would confirm/deny
+3. Gather evidence (grep, read, run, LSP)
+4. If wrong, form new hypothesis
+
+### 4. Root Cause Analysis (5 Whys)
+
+| Why | Question | Answer |
+|-----|----------|--------|
+| 1 | Why did this fail? | |
+| 2 | Why did that happen? | |
+| 3 | Why? | |
+| 4 | Why? | |
+| 5 | Root cause? | |
+
+### 5. Implement Fix
+
+Once root cause identified:
+1. Create minimal fix
+2. Add regression test
+3. Verify fix works
+4. Check for side effects
+
+### 6. Verify
+
+```bash
+# Run original failing test
+[original command] → Should pass
+
+# Run full test suite
+pnpm test
+
+# Type check
+pnpm typecheck
+```
+
+## Debugging Tools
+
+| Tool | Use For |
+|------|---------|
+| `Grep` | Find error patterns, related code |
+| `Read` | Examine suspicious files |
+| `Bash` | Run tests, check logs, git bisect |
+| `LSP` | Trace definitions, find references |
+| `ast_grep_search` | Find structural code patterns |
+| Oracle | Complex multi-layer analysis (escalation) |
+
+## Common Patterns
+
+### Find When Bug Was Introduced
+```bash
+git log --oneline -20
+git bisect start
+git bisect bad HEAD
+git bisect good [known-good-commit]
+```
+
+### Trace Error Source
+```bash
+# Find all occurrences of error message
+Grep: "error message"
+
+# Find callers of problematic function
+Grep: "functionName("
+```
+
+## Debug Report
+
+```markdown
+## Debug Report: [Issue Title]
+
+**Date:** YYYY-MM-DD
+**Error:** [Error message]
+
+### Reproduction
+1. [Step 1]
+2. [Step 2]
+3. Error occurs
+
+### Investigation
+
+#### Hypotheses Tested
+| # | Hypothesis | Evidence | Result |
+|---|------------|----------|--------|
+| 1 | [Theory] | [What I found] | ❌ |
+| 2 | [Theory] | [What I found] | ✅ |
+
+### Root Cause
+[Clear explanation]
+
+**5 Whys:**
+1. → [Answer]
+2. → [Answer]
+3. → [Answer]
+4. → [Answer]
+5. → **[Root cause]**
+
+### Fix Applied
+
+**Files Changed:**
+- `path/to/file.ts` — [What changed]
+
+**Code Change:**
+```diff
+- old code
++ new code
+```
+
+**Regression Test Added:**
+- `path/to/test.ts` — [Test description]
+
+### Verification
+| Check | Result |
+|-------|--------|
+| Original issue | ✅ Fixed |
+| Regression test | ✅ Pass |
+| Full test suite | ✅ Pass |
+| Type check | ✅ Pass |
+
+### Prevention
+- [ ] Added test to prevent regression
+- [ ] Updated error handling
+- [ ] Documented the issue
+```
+
+## Rules
+
+- ✅ ALWAYS reproduce before fixing
+- ✅ ALWAYS add regression test
+- ✅ ALWAYS verify fix doesn't break other things
+- ✅ ALWAYS document root cause
+- ❌ NEVER apply fix without understanding cause
+- ❌ NEVER skip verification
+- ❌ NEVER suppress errors without fixing
+
+## Escalation
+
+If after 3 attempts:
+- Still can't reproduce → Ask for more info
+- Can't find root cause → Delegate to Oracle for deeper analysis
+- Fix causes other failures → Escalate to Plan Agent
+
+Describe the issue to debug and fix...

package/command/design.md

@@ -0,0 +1,82 @@
+---
+description: Frontend UI/UX design with a designer's eye.
+agent: build
+---
+
+You are the **Build Agent** with design expertise. Execute the `/design` command.
+
+## Your Task
+
+Create visually stunning, emotionally engaging frontend interfaces with a designer's eye.
+
+## What I Can Build
+
+| Type | Example |
+|------|---------|
+| **Component** | "Create a premium login form" |
+| **Page** | "Design a dashboard for traders" |
+| **Layout** | "Build a magazine-style blog layout" |
+| **Animation** | "Add micro-interactions to this button" |
+
+## Design Thinking (Before Coding)
+
+1. **Purpose**: What problem? Who uses it?
+2. **Tone**: Pick an extreme aesthetic direction
+3. **Differentiation**: What makes this UNFORGETTABLE?
+
+## Aesthetic Directions
+
+| Style | Character |
+|-------|-----------|
+| Brutally minimal | Stark, powerful emptiness |
+| Maximalist | Rich, layered, overwhelming |
+| Retro-futuristic | Nostalgic tech, neon, CRT |
+| Luxury/refined | Premium, elegant, exclusive |
+| Brutalist/raw | Exposed, honest, anti-design |
+| Playful/toy-like | Fun, bouncy, colorful |
+
+## Anti-Patterns (NEVER USE)
+
+❌ Generic fonts: Inter, Roboto, Arial, Space Grotesk
+❌ Clichéd colors: Purple gradients on white
+❌ Cookie-cutter layouts
+❌ Same choices across designs
+
+## Focus Areas
+
+| Element | Approach |
+|---------|----------|
+| **Typography** | Distinctive, characterful fonts |
+| **Color** | Dominant + sharp accents, CSS variables |
+| **Motion** | High-impact moments, staggered reveals |
+| **Layout** | Asymmetry, overlap, grid-breaking |
+| **Details** | Textures, gradients, shadows, grain |
+
+## Output
+
+```markdown
+## Design: [Component]
+
+### Aesthetic Direction
+**Chosen**: [Style]
+**Why**: [Rationale]
+
+### Key Choices
+| Element | Decision | Why |
+|---------|----------|-----|
+| Typography | ... | ... |
+| Colors | ... | ... |
+
+### Files Created
+- [path/to/file.tsx](file://...)
+```
+
+## Rules
+
+- Study existing design patterns first
+- Commit to BOLD aesthetic direction
+- Match project code conventions
+- Verify visual output
+- Document design decisions
+
+What do you want me to design?

package/command/handoff.md

@@ -0,0 +1,95 @@
+---
+description: Save state for session break.
+agent: plan
+---
+
+You are the **Plan Agent** (or **Build Agent**). Execute the `/handoff` command.
+
+## Template
+
+Use template at: `@.opencode/memory/_templates/handoff.md`
+
+## Your Task
+
+Save the current work state for a session break, enabling seamless resumption later.
+
+## Process
+
+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. **Create handoff document** at `.opencode/memory/handoffs/YYYY-MM-DD-<phase>.md`
+
+3. **Update bead metadata** with handoff reference
+
+## Handoff Template
+
+```markdown
+---
+date: YYYY-MM-DD
+phase: spec'd | researched | planned | implementing | validating
+branch: [git branch name]
+bead_id: [optional]
+---
+
+# 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 |
+
+## Task Status
+
+### ✅ Completed
+- [x] T-001: [Task title]
+- [x] T-002: [Task title]
+
+### 🔄 In Progress
+- [ ] T-003: [Task title]
+  - **Current state:** [What's been done]
+  - **Next step:** [What to do next]
+
+### ⏸️ Blocked
+- [ ] T-004: [Task title]
+  - **Blocked by:** [Reason/dependency]
+
+### 📋 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]
+
+## Next Steps
+1. [Next action 1]
+2. [Next action 2]
+
+## Context for Resumption
+[Any important context the next session needs to know]
+```
+
+## 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
+
+Now, let me gather the current state and create the handoff document.

package/command/import-plan.md

@@ -0,0 +1,175 @@
+---
+description: Import external planning data (Jira, Notion, Linear, etc.)
+agent: plan
+---
+
+You are the **Plan Agent**. Execute the `/import-plan` command.
+
+## Your Task
+
+Import planning data from external tools (Jira, Notion, Linear, etc.) and convert to internal format.
+
+## Process
+
+### 1. Gather Source Data
+
+Ask user for:
+- Source type (Jira, Notion, Linear, Markdown, JSON)
+- Data to import (URL, file path, or pasted content)
+
+### 2. Parse External Format
+
+**Jira:**
+```
+- Epic → Bead
+- Story/Task → Task (T-XXX)
+- Subtask → Acceptance Criteria
+- Priority → P0/P1/P2 mapping
+- Story Points → Effort (S/M/L/XL)
+```
+
+**Notion:**
+```
+- Page → Bead or Spec
+- Database items → Tasks
+- Properties → Task fields
+```
+
+**Linear:**
+```
+- Project → Bead
+- Issue → Task
+- Labels → Tags
+- Priority → P0/P1/P2 mapping
+```
+
+**Markdown/JSON:**
+```
+- Parse structure
+- Map to Task Schema
+```
+
+### 3. Normalize to Internal Format
+
+Convert each item to Task Schema (`.opencode/schemas.md` §1):
+
+```yaml
+task_id: "T-001"
+title: "[Imported title]"
+type: task | bug | feature | chore
+status: not_started
+assignee: build | fe | be | mobile | devops
+priority: P0 | P1 | P2
+effort: S | M | L | XL
+dependencies: []
+description: "[Imported description]"
+input: []
+output: []
+boundaries: []
+acceptance_criteria: []
+```
+
+### 4. Validate Against Spec
+
+- Check if `spec.md` exists
+- If yes: validate imported tasks align with spec
+- If no: suggest creating spec first or generate from import
+
+### 5. Identify Gaps
+
+| Gap Type | Action |
+|----------|--------|
+| Missing acceptance criteria | Flag for user input |
+| Missing dependencies | Ask user to define |
+| Unclear scope | Mark as "Needs Clarification" |
+| Missing effort estimates | Suggest based on description |
+
+### 6. Generate plan.md
+
+Create plan at `.opencode/memory/plans/YYYY-MM-DD-<feature>.md` using template `@.opencode/memory/_templates/plan.md`
+
+### 7. Create Beads
+
+For each task:
+```
+mcp__beads_village__add(
+  title: "[Task title]",
+  desc: "[Description]",
+  typ: "[type]",
+  pri: [0-4],
+  deps: ["task:T-XXX"]
+)
+```
+
+## Output Format
+
+```markdown
+## Import Summary
+
+### Source
+- **Type:** [Jira/Notion/Linear/etc.]
+- **Items Found:** [count]
+
+### Imported Tasks
+
+| ID | Title | Type | Effort | Priority | Status |
+|----|-------|------|--------|----------|--------|
+| T-001 | [Title] | feature | M | P1 | Imported ✅ |
+| T-002 | [Title] | task | S | P2 | Needs AC ⚠️ |
+
+### Gaps Identified
+
+- [ ] T-002: Missing acceptance criteria
+- [ ] T-003: Dependencies unclear
+
+### Artifacts Created
+
+- Plan: `.opencode/memory/plans/YYYY-MM-DD-feature.md`
+- Beads: [count] tasks added to beads village
+
+### Next Steps
+
+1. Review and fill gaps
+2. Get user approval on plan
+3. `/implement` to start execution
+```
+
+## Field Mapping Reference
+
+### Priority Mapping
+
+| External | Internal |
+|----------|----------|
+| Highest, Critical, P0 | P0 |
+| High, P1 | P1 |
+| Medium, Normal, P2 | P2 |
+| Low, P3, P4 | P2 |
+
+### Effort Mapping
+
+| External | Internal |
+|----------|----------|
+| 1-2 points, XS | S |
+| 3-5 points, S, M | M |
+| 8-13 points, L | L |
+| 21+ points, XL | XL |
+
+### Type Mapping
+
+| External | Internal |
+|----------|----------|
+| Story, Feature, Enhancement | feature |
+| Bug, Defect | bug |
+| Task, Subtask | task |
+| Chore, Maintenance, Tech Debt | chore |
+
+## Rules
+
+- ✅ ALWAYS validate against Task Schema
+- ✅ ALWAYS preserve original IDs as reference
+- ✅ ALWAYS flag gaps rather than guess
+- ✅ ALWAYS get user approval before proceeding
+- ❌ NEVER auto-fill critical fields (AC, dependencies)
+- ❌ NEVER import without creating beads
+
+Now, what would you like to import? Please provide the source type and data.

package/command/init.md

@@ -0,0 +1,112 @@
+---
+description: Initialize CliKit plugin in the current project.
+agent: build
+---
+
+You are the **Build Agent**. Execute the `/init` command.
+
+## Your Task
+
+Set up the CliKit plugin in the current project.
+
+## Process
+
+### 1. Check Prerequisites
+
+```bash
+# Check if .opencode/ already exists
+ls -la .opencode/ 2>/dev/null
+
+# Check if package.json exists
+ls package.json 2>/dev/null
+
+# Check package manager
+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
+# Detect package manager and install
+bun add -d clikit-plugin 2>/dev/null || \
+pnpm add -D clikit-plugin 2>/dev/null || \
+npm install -D clikit-plugin 2>/dev/null
+```
+
+### 3. Create Plugin Entry Point
+
+Create `.opencode/index.ts`:
+
+```typescript
+import CliKitPlugin from "clikit-plugin";
+export default CliKitPlugin;
+```
+
+### 4. Create Default Configuration
+
+Create `.opencode/clikit.config.json`:
+
+```json
+{
+  "$schema": "https://unpkg.com/clikit-plugin/schema.json",
+  "disabled_agents": [],
+  "disabled_commands": [],
+  "hooks": {
+    "session_logging": true,
+    "todo_enforcer": {
+      "enabled": true,
+      "warn_on_incomplete": true
+    },
+    "empty_message_sanitizer": {
+      "enabled": true
+    }
+  }
+}
+```
+
+### 5. Create Memory Directory Structure
+
+```bash
+mkdir -p .opencode/memory/{specs,plans,research,reviews,handoffs,prds,beads}
+```
+
+### 6. Verify Setup
+
+- Check that plugin loads correctly
+- Verify agents are available
+- Verify commands are registered
+
+### 7. Report
+
+```
+## CliKit Initialized
+
+✅ Plugin installed: clikit-plugin
+✅ Entry point: .opencode/index.ts
+✅ Config: .opencode/clikit.config.json
+✅ Memory directories created
+
+### Available Agents
+[list agents]
+
+### Available Commands
+[list commands]
+
+### Next Steps
+1. Run `/create` to start a new feature
+2. Customize `.opencode/clikit.config.json` as needed
+3. See README for full configuration options
+```
+
+## Rules
+
+- ✅ ALWAYS check for existing setup before overwriting
+- ✅ ALWAYS detect the correct package manager
+- ✅ ALWAYS create memory directory structure
+- ✅ ALWAYS verify the setup works
+- ❌ NEVER overwrite existing config without asking
+- ❌ NEVER skip verification step
+
+Now, initializing CliKit...