clikit-plugin 0.1.0

package/command/review-codebase.md

@@ -0,0 +1,228 @@
+---
+description: Full codebase audit with automatic bead creation for findings.
+agent: review
+subtask: true
+---
+
+You are the **Review Agent**. Execute the `/review-codebase` command.
+
+## Your Task
+
+Perform a comprehensive audit of the entire codebase and create beads for all findings.
+
+## Process
+
+### 1. Discover Codebase Structure
+
+```
+1. Read project root (package.json, tsconfig, etc.)
+2. Identify main source directories
+3. Map architecture and key modules
+```
+
+### 2. Audit Categories
+
+Run systematic checks across:
+
+| Category | What to Check |
+|----------|---------------|
+| **Security** | Hardcoded secrets, auth flaws, injection risks, exposed endpoints |
+| **Performance** | N+1 queries, memory leaks, blocking operations, large bundles |
+| **Code Quality** | Dead code, duplication, complexity, naming, patterns |
+| **Architecture** | Circular deps, coupling, layer violations, inconsistencies |
+| **Testing** | Missing tests, low coverage, flaky tests, assertion quality |
+| **Dependencies** | Outdated packages, vulnerabilities, unused deps |
+| **Documentation** | Missing docs, outdated comments, unclear APIs |
+| **Tech Debt** | TODOs, FIXMEs, workarounds, deprecated patterns |
+
+### 3. Severity Classification
+
+| Severity | Priority | Examples |
+|----------|----------|----------|
+| Critical | P0 | Security vulnerabilities, data loss risks |
+| High | P1 | Auth flaws, performance bottlenecks, blocking bugs |
+| Medium | P2 | Code quality issues, missing tests, tech debt |
+| Low | P3 | Style issues, minor improvements, nice-to-haves |
+
+### 4. Create Beads for Findings
+
+For each finding, create a bead:
+
+```
+mcp__beads_village__add(
+  title: "[Category] Brief description",
+  desc: "What: [issue]\nWhere: [location]\nWhy: [impact]\nHow: [suggested fix]",
+  typ: "bug" | "chore" | "task",
+  pri: 0-4,
+  tags: ["security" | "performance" | "quality" | "debt"]
+)
+```
+
+### 5. Generate Summary Report
+
+Save to `.opencode/memory/reviews/YYYY-MM-DD-codebase-audit.md`
+
+## Audit Checklist
+
+### Security
+- [ ] No hardcoded API keys, tokens, passwords
+- [ ] No secrets in git history
+- [ ] Input validation on all endpoints
+- [ ] Auth/authz properly implemented
+- [ ] No SQL injection / XSS vulnerabilities
+- [ ] CORS configured correctly
+- [ ] Rate limiting in place
+
+### Performance
+- [ ] No N+1 database queries
+- [ ] Proper caching strategy
+- [ ] No memory leaks
+- [ ] Async operations non-blocking
+- [ ] Bundle size optimized
+- [ ] Images/assets optimized
+
+### Code Quality
+- [ ] No dead/unreachable code
+- [ ] DRY principles followed
+- [ ] Consistent naming conventions
+- [ ] Reasonable complexity (< 15 cyclomatic)
+- [ ] No deeply nested callbacks
+- [ ] Error handling complete
+
+### Architecture
+- [ ] No circular dependencies
+- [ ] Proper layer separation
+- [ ] Consistent patterns across modules
+- [ ] Clear module boundaries
+- [ ] Single responsibility principle
+
+### Testing
+- [ ] Critical paths have tests
+- [ ] Edge cases covered
+- [ ] No flaky tests
+- [ ] Meaningful assertions
+- [ ] Integration tests exist
+
+### Dependencies
+- [ ] No known vulnerabilities (npm audit)
+- [ ] No unused dependencies
+- [ ] Packages reasonably up-to-date
+- [ ] Lock file committed
+
+### Documentation
+- [ ] README is current
+- [ ] API documentation exists
+- [ ] Complex logic has comments
+- [ ] Setup instructions work
+
+### Tech Debt
+- [ ] TODO/FIXME items catalogued
+- [ ] No deprecated API usage
+- [ ] No temporary workarounds in prod
+- [ ] Console.log/debug removed
+
+## Output Format
+
+```markdown
+# Codebase Audit Report
+
+**Date:** YYYY-MM-DD
+**Auditor:** Review Agent
+**Scope:** Full codebase
+
+---
+
+## Executive Summary
+
+- **Total Issues Found:** X
+- **Critical:** X | **High:** X | **Medium:** X | **Low:** X
+- **Beads Created:** X
+
+### Health Score
+
+| Category | Score | Issues |
+|----------|-------|--------|
+| Security | 🟢 Good / 🟡 Fair / 🔴 Poor | X |
+| Performance | 🟢/🟡/🔴 | X |
+| Code Quality | 🟢/🟡/🔴 | X |
+| Architecture | 🟢/🟡/🔴 | X |
+| Testing | 🟢/🟡/🔴 | X |
+| Dependencies | 🟢/🟡/🔴 | X |
+
+---
+
+## Critical Findings (P0)
+
+| ID | Issue | Location | Bead |
+|----|-------|----------|------|
+| C-01 | [Issue] | [File:Line] | [bead-id] |
+
+## High Priority (P1)
+
+| ID | Issue | Location | Bead |
+|----|-------|----------|------|
+| H-01 | [Issue] | [File:Line] | [bead-id] |
+
+## Medium Priority (P2)
+
+| ID | Issue | Location | Bead |
+|----|-------|----------|------|
+| M-01 | [Issue] | [File:Line] | [bead-id] |
+
+## Low Priority (P3)
+
+| ID | Issue | Location | Bead |
+|----|-------|----------|------|
+| L-01 | [Issue] | [File:Line] | [bead-id] |
+
+---
+
+## Recommendations
+
+### Immediate Actions (This Sprint)
+1. [Action 1]
+
+### Short-term (Next 2-4 weeks)
+1. [Action 2]
+
+### Long-term (Technical Roadmap)
+1. [Action 3]
+
+---
+
+## Beads Created
+
+| Bead ID | Title | Priority | Tags |
+|---------|-------|----------|------|
+| [id] | [title] | P0-P3 | [tags] |
+
+---
+
+## Next Steps
+
+1. Review and prioritize beads
+2. Assign to team members via `/implement`
+3. Schedule critical fixes immediately
+```
+
+## Tools to Use
+
+- `finder` — Semantic code search
+- `Grep` — Pattern matching (TODOs, console.log, etc.)
+- `glob` — File discovery
+- `Read` — File inspection
+- `Bash` — Run npm audit, dependency checks
+- `mcp__beads_village__add` — Create issue beads
+
+## Rules
+
+- ✅ ALWAYS create beads for actionable findings
+- ✅ ALWAYS include file:line locations
+- ✅ ALWAYS prioritize security issues first
+- ✅ ALWAYS provide fix recommendations
+- ✅ ALWAYS save report to `.opencode/memory/reviews/`
+- ❌ NEVER skip security audit
+- ❌ NEVER create beads without clear descriptions
+- ❌ NEVER mark issues without verification
+
+Now, let me begin the codebase audit...

package/command/review.md

@@ -0,0 +1,135 @@
+---
+description: Full code review for quality and correctness.
+agent: review
+subtask: true
+---
+
+You are the **Review Agent**. Execute the `/review` command.
+
+## Template
+
+Use template at: `@.opencode/memory/_templates/review.md`
+
+## Your Task
+
+Perform a comprehensive code review of recent changes.
+
+## Process
+
+### 1. Gather Context
+- Load spec.md, plan.md
+- Identify changed files via `git diff` or provided list
+- Read each changed file
+
+### 2. Review Checklist
+
+**Correctness**
+- [ ] Logic is correct
+- [ ] Edge cases handled
+- [ ] Null/undefined handling
+- [ ] Error handling complete
+
+**Security**
+- [ ] No hardcoded secrets
+- [ ] Input validation present
+- [ ] Auth/authz logic correct
+- [ ] No SQL injection/XSS risks
+
+**Performance**
+- [ ] No N+1 queries
+- [ ] No memory leaks
+- [ ] Efficient algorithms
+
+**Maintainability**
+- [ ] Code is readable
+- [ ] DRY principles followed
+- [ ] Complexity is reasonable
+- [ ] Naming is clear
+
+**Testing**
+- [ ] Tests exist for changes
+- [ ] Assertions are meaningful
+- [ ] Coverage is adequate
+
+### 3. Issue Severity
+
+| Severity | Examples |
+|----------|----------|
+| Critical | Security vuln, data loss risk, logic error causing crashes |
+| High | Auth flaw, unhandled errors, performance bottleneck |
+| Medium | Missing edge case, poor error messages, minor perf issue |
+| Low | Style issues, minor clarity improvements |
+
+### 4. Generate Report
+
+Save to `.opencode/memory/reviews/YYYY-MM-DD-<feature>-review.md`
+
+## Review Report Template
+
+```markdown
+---
+type: Code | PRD | Spec | Plan | Security
+date: YYYY-MM-DD
+reviewer: Review Agent
+artifact: [Path to reviewed artifact]
+verdict: approved | changes_required | blocked
+bead_id: [optional]
+task_ids: []
+---
+
+# Review: [Feature/PR Name]
+
+## Summary
+[2-3 sentence overview]
+
+## Findings
+
+### Critical (Must Fix Before Approval)
+| ID | Issue | Location | Recommendation |
+|----|-------|----------|----------------|
+| C-01 | [Issue] | [Where] | [Fix] |
+
+### High (Should Fix)
+| ID | Issue | Location | Recommendation |
+|----|-------|----------|----------------|
+| H-01 | [Issue] | [Where] | [Fix] |
+
+### Medium (Consider Fixing)
+| ID | Issue | Location | Recommendation |
+|----|-------|----------|----------------|
+| M-01 | [Issue] | [Where] | [Fix] |
+
+### Low (Optional)
+| ID | Issue | Location | Recommendation |
+|----|-------|----------|----------------|
+| L-01 | [Issue] | [Where] | [Fix] |
+
+## Required Changes
+1. [Change 1]
+2. [Change 2]
+
+## Suggestions (Optional)
+- [Improvement idea]
+
+## Security Checklist
+- [x] No hardcoded secrets
+- [x] Input validation present
+- [x] Auth logic reviewed
+
+## Acceptance Criteria Verification
+- [x] AC-01: [Verified]
+- [x] AC-02: [Verified]
+
+## Verdict Details
+[Why this verdict was chosen]
+```
+
+## Verdict Rules
+
+| Verdict | Criteria |
+|---------|----------|
+| `approved` | 0 critical, 0 high, ACs verified |
+| `changes_required` | 0 critical, has high/medium fixable issues |
+| `blocked` | Has critical issues, security vulnerabilities |
+
+Now, gathering files to review...

package/command/ship.md

@@ -0,0 +1,109 @@
+---
+description: Ship completed work. Final verification, PR creation, and cleanup.
+agent: build
+---
+
+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.
+
+## Process
+
+### 1. Pre-Ship Verification
+
+Run ALL hard gates before shipping:
+
+```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.
+
+### 2. 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
+
+### 3. Request Review (Optional)
+
+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.
+
+### 4. Git Preparation
+
+```bash
+# Ensure clean state
+git status
+
+# Stage changes
+git add -A
+
+# Create commit with 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
+- 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
+
+## Ship Checklist
+
+```
+Pre-Ship:
+- [ ] Typecheck passes
+- [ ] All tests pass
+- [ ] Lint passes
+- [ ] Build succeeds
+- [ ] Self-review completed
+- [ ] No debug/temporary code
+
+Ship:
+- [ ] Changes committed
+- [ ] PR created with full description
+- [ ] Artifacts linked
+
+Post-Ship:
+- [ ] Bead 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
+
+Now, let me verify and ship your work...

package/command/start.md

@@ -0,0 +1,77 @@
+---
+description: Begin implementing from an existing plan. Pick up next task and start coding.
+agent: build
+---
+
+You are the **Build Agent**. Execute the `/start` command.
+
+## Your Task
+
+Begin implementation from an existing plan. Pick up the next available task and start coding.
+
+## Process
+
+### 1. Find Active Plan
+
+Look for plans in `.opencode/memory/plans/`. If multiple exist, ask the user which one.
+
+If no plan exists:
+- Suggest running `/plan` first
+- Check for specs in `.opencode/memory/specs/`
+
+### 2. Load Context
+
+- Read `plan.md` — get task list, file impact, dependencies
+- Read `spec.md` — understand requirements and acceptance criteria
+- Read latest `handoff.md` (if exists) — resume from previous session
+- Check bead status via `mcp__beads_village__ls()`
+
+### 3. Determine Next Task
+
+Find the first task that is:
+- Status: `not_started`
+- All dependencies are `done`
+- Not blocked
+
+If resuming from handoff, pick up `in_progress` tasks first.
+
+### 4. Create Todos
+
+Break the task into detailed, trackable todos using the TodoWrite tool.
+
+### 5. Begin Implementation
+
+- Reserve files via `mcp__beads_village__reserve()`
+- Follow the plan's file impact strictly
+- Implement incrementally — edit, verify, mark complete, repeat
+
+### 6. Verify Each Task
+
+After completing each task:
+- Run targeted checks (typecheck, tests, lint)
+- Verify acceptance criteria
+- Mark task as `done` in plan
+- Move to next task
+
+## Quick Start Checklist
+
+```
+1. ✅ Plan exists and is approved
+2. ✅ Context loaded (spec, plan, handoff)
+3. ✅ Next task identified
+4. ✅ Todos created
+5. ✅ Files reserved
+6. 🔄 Implementation in progress
+```
+
+## Rules
+
+- ✅ ALWAYS load plan and spec before starting
+- ✅ ALWAYS check for existing handoff to resume
+- ✅ ALWAYS create todos before coding
+- ✅ ALWAYS verify each task before moving on
+- ✅ ALWAYS respect file impact boundaries
+- ❌ NEVER skip verification gates
+- ❌ NEVER implement without an approved plan
+
+Now, let me find your plan and start implementing...

package/command/status.md

@@ -0,0 +1,123 @@
+---
+description: Current state overview of workspace and beads.
+agent: build
+---
+
+You are providing a **status overview** of the current workspace and beads.
+
+## Your Task
+
+Show the current state of work: beads, tasks, files, and git status.
+
+## Process
+
+### 1. Check Beads Village
+
+```
+mcp__beads_village__status()
+```
+
+### 2. Check Git State
+
+```bash
+git status
+git branch --show-current
+git log --oneline -5
+```
+
+### 3. Check Artifacts
+
+Look for:
+- `.opencode/memory/specs/` — Active specifications
+- `.opencode/memory/plans/` — Implementation plans
+- `.opencode/memory/handoffs/` — Pending handoffs
+- `.opencode/memory/research/` — Research docs
+
+### 4. Generate Overview
+
+## Status Report Template
+
+```markdown
+## 📊 Status Overview
+
+**Date:** YYYY-MM-DD HH:MM
+**Branch:** [current branch]
+**Workspace:** [path]
+
+---
+
+### 🎯 Beads Village
+
+| Status | Count |
+|--------|-------|
+| Open | X |
+| In Progress | X |
+| Closed | X |
+
+**Current Task:** [ID] [Title] (if any)
+
+**Ready to Claim:**
+1. [ID] [Title] (P[priority])
+2. [ID] [Title] (P[priority])
+
+---
+
+### 📁 Active Artifacts
+
+| Type | File | Status |
+|------|------|--------|
+| Spec | YYYY-MM-DD-feature.md | ✅ Active |
+| Plan | YYYY-MM-DD-feature.md | ✅ Active |
+| Research | YYYY-MM-DD-topic.md | 📚 Reference |
+| Handoff | YYYY-MM-DD-phase.md | ⏸️ Paused |
+
+---
+
+### 🔧 Git Status
+
+**Branch:** `feature/xyz`
+**Ahead/Behind:** +2 / -0
+
+**Uncommitted Changes:**
+- M path/to/modified.ts
+- A path/to/new.ts
+
+**Recent Commits:**
+1. abc1234 - feat: added X
+2. def5678 - fix: resolved Y
+
+---
+
+### 📋 Quick Actions
+
+| Need | Command |
+|------|---------|
+| Start new feature | `/create` |
+| Begin implementing | `/start` |
+| Resume paused work | `/resume` |
+| Review changes | `/review` |
+| Ship & merge | `/ship` |
+| Commit changes | `/commit` |
+
+---
+
+### ⚠️ Alerts
+
+- [Any blockers or issues]
+- [Any drift detected]
+- [Any stale handoffs]
+```
+
+## What I Check
+
+| Area | Tool |
+|------|------|
+| Beads | `mcp__beads_village__status()` |
+| Tasks | `mcp__beads_village__ls()` |
+| Ready tasks | `mcp__beads_village__ready()` |
+| Reservations | `mcp__beads_village__reservations()` |
+| Messages | `mcp__beads_village__inbox()` |
+| Git | `git status`, `git log` |
+| Artifacts | `glob`, `Read` |
+
+Now generating status overview...