clikit-plugin 0.1.0

package/command/issue.md

@@ -0,0 +1,110 @@
+---
+description: Quick issue creation in beads village.
+agent: build
+---
+
+You are creating a **quick issue** in beads village.
+
+## Your Task
+
+Rapidly create an issue/task without full spec process.
+
+## Usage
+
+```
+/issue [title]
+```
+
+Or just `/issue` and I'll ask for details.
+
+## Process
+
+### 1. Gather Minimal Info
+
+- **Title:** What needs to be done? (required)
+- **Type:** task | bug | feature | chore (default: task)
+- **Priority:** P0=critical, P1=high, P2=normal (default: P2)
+- **Description:** Brief context (optional)
+- **Tags:** fe, be, mobile, devops, qa (optional)
+
+### 2. Create in Beads
+
+```
+mcp__beads_village__add(
+  title: "[title]",
+  typ: "[type]",
+  pri: [priority],
+  desc: "[description]",
+  tags: ["tag1", "tag2"]
+)
+```
+
+### 3. Confirm Creation
+
+## Quick Templates
+
+### Bug Report
+```
+/issue Bug: [what's broken]
+```
+→ Creates with `typ: "bug"`, `pri: 1`
+
+### Feature Request
+```
+/issue Feature: [what to add]
+```
+→ Creates with `typ: "feature"`, `pri: 2`
+
+### Quick Task
+```
+/issue [action verb] [thing]
+```
+→ Creates with `typ: "task"`, `pri: 2`
+
+### Chore
+```
+/issue Chore: [maintenance task]
+```
+→ Creates with `typ: "chore"`, `pri: 2`
+
+## Examples
+
+| Input | Result |
+|-------|--------|
+| `/issue Fix login button not working` | Bug, P1 |
+| `/issue Add dark mode support` | Feature, P2 |
+| `/issue Update dependencies` | Chore, P2 |
+| `/issue Refactor auth module` | Task, P2 |
+
+## Output Format
+
+```markdown
+## ✅ Issue Created
+
+**ID:** [bead-id]
+**Title:** [title]
+**Type:** [type]
+**Priority:** P0 | P1 | P2
+**Tags:** [tags]
+
+### Next Steps
+- Claim with `/implement`
+- Add to plan with `/plan`
+- View all with `/status`
+```
+
+## Advanced Options
+
+For complex issues, use full form:
+```
+/issue
+Title: [required]
+Type: bug | task | feature | chore
+Priority: P0 | P1 | P2
+Description: [context]
+Tags: fe, be, mobile, devops, qa
+Parent: [parent-id for subtasks]
+Deps: [blocking-issue-ids]
+```
+
+What issue do you want to create?

package/command/plan.md

@@ -0,0 +1,205 @@
+---
+description: Convert specs and research into execution plan.
+agent: plan
+---
+
+You are the **Plan Agent**. Execute the `/plan` command.
+
+## Template
+
+Use template at: `@.opencode/memory/_templates/plan.md`
+
+## Prerequisites
+- `spec.md` MUST exist
+- `research.md` recommended if external knowledge needed
+
+## Your Task
+
+Create a detailed implementation plan from the specification.
+
+## Process
+
+1. **Load artifacts**: spec.md, research.md (if exists)
+
+2. **Understand codebase** using:
+   - `finder` for semantic search
+   - Delegate to Explore Agent for file discovery
+
+3. **Consult Oracle** for non-trivial architecture decisions
+
+4. **Decompose into tasks** following Task Schema (see `.opencode/schemas.md` §1)
+
+5. **Generate File Impact section** (REQUIRED)
+
+6. **Create `plan.md`** at `.opencode/memory/plans/YYYY-MM-DD-<feature>.md`
+
+7. **Update bead** with plan reference
+
+8. **Get user approval**
+
+## Plan Structure (follows `_templates/plan.md`)
+
+The plan MUST include:
+
+```markdown
+# Implementation Plan: [Feature]
+
+**Date:** YYYY-MM-DD
+**Author:** [Name]
+**Status:** Draft | Approved
+**bead_id:** [ID]
+
+---
+
+## Overview
+
+[Brief description of what will be built]
+
+## References
+
+- **Spec:** `.opencode/memory/specs/YYYY-MM-DD-descriptor.md`
+- **PRD:** `.opencode/memory/prds/YYYY-MM-DD-feature.md` (if applicable)
+- **Research:** `.opencode/memory/research/YYYY-MM-DD-topic.md` (if applicable)
+
+---
+
+## Tasks
+
+### Task 1: [Title]
+
+| Field | Value |
+|-------|-------|
+| **task_id** | T-001 |
+| **type** | task \| bug \| feature \| chore |
+| **assignee** | build \| fe \| be \| mobile \| devops |
+| **effort** | S \| M \| L \| XL |
+| **priority** | P0 \| P1 \| P2 |
+| **status** | not_started \| in_progress \| blocked \| done |
+| **dependencies** | [T-xxx] or none |
+
+**Description:**
+[What needs to be done]
+
+**Input:**
+- [Required artifacts/context]
+
+**Output:**
+- [Expected deliverables]
+- [Files to create/modify]
+
+**Acceptance Criteria:**
+- [ ] AC-01: [Criteria]
+- [ ] AC-02: [Criteria]
+
+**Boundaries:**
+- [What NOT to do]
+
+---
+
+### Task 2: [Title]
+
+[Repeat structure]
+
+---
+
+## File Impact
+
+**Files to CREATE:**
+- `path/to/new-file.ts` — [Purpose]
+
+**Files to MODIFY:**
+- `path/to/existing.ts` — [Reason]
+
+**Files to DELETE:**
+- (none)
+
+---
+
+## Dependencies
+
+```mermaid
+graph TD
+    T001[T-001: Title] --> T002[T-002: Title]
+    T002 --> T003[T-003: Title]
+    T001 --> T003
+```
+
+---
+
+## Effort Summary
+
+| Task | Effort | Priority |
+|------|--------|----------|
+| T-001 | S | P0 |
+| T-002 | M | P0 |
+| T-003 | S | P1 |
+
+**Total Estimated Effort:** [X days/weeks]
+
+---
+
+## Risk Assessment
+
+| Risk | Probability | Impact | Mitigation |
+|------|-------------|--------|------------|
+| [Risk 1] | L/M/H | L/M/H | [Mitigation] |
+
+---
+
+## Quick Mode Eligibility
+
+Tasks eligible for Quick Mode (no full plan needed):
+- [ ] T-001 (S, ≤3 files, no security/db/api)
+
+---
+
+## Rollout Plan
+
+| Phase | Tasks | Milestone |
+|-------|-------|-----------|
+| Phase 1 | T-001, T-002 | [Milestone] |
+| Phase 2 | T-003 | [Milestone] |
+
+---
+
+## Approval
+
+- [ ] Plan reviewed
+- [ ] User approved
+- [ ] Ready for implementation
+```
+
+## Task Schema Requirements
+
+Every task MUST include these fields (per `.opencode/schemas.md` §1):
+- `task_id` (T-XXX format)
+- `title`
+- `type` (task | bug | feature | chore)
+- `status` (not_started | in_progress | blocked | done)
+- `assignee` (build | fe | be | mobile | devops)
+- `priority` (P0 | P1 | P2)
+- `effort` (S | M | L | XL)
+- `dependencies` (list or none)
+- `description`, `input`, `output`, `boundaries`
+- `acceptance_criteria` (list)
+
+## Quick Mode Eligibility
+
+Task qualifies for Quick Mode (Build Agent) if:
+- `effort: "S"`
+- 3 files or fewer affected
+- No security/auth/db in boundaries
+- No new API endpoints
+
+## Rules
+
+- ✅ ALWAYS use the full template structure from `_templates/plan.md`
+- ✅ ALWAYS include frontmatter (Date, Author, Status, bead_id)
+- ✅ ALWAYS use `task_id` field (not `ID`)
+- ✅ ALWAYS include all Task Schema fields
+- ✅ File Impact is the BUILD BOUNDARY — only listed files allowed
+- ✅ Stable IDs: Deprecate tasks, don't delete
+- ✅ Confirm with user before proceeding to build
+- ❌ NEVER omit required Task Schema fields
+
+Now, load the spec and create the implementation plan.

package/command/pr.md

@@ -0,0 +1,174 @@
+---
+description: Create pull request with comprehensive description.
+agent: build
+---
+
+You are creating a **pull request** with comprehensive description.
+
+## Your Task
+
+Generate a well-structured PR with context, changes, and testing info.
+
+## Process
+
+### 1. Gather Context
+
+```bash
+# Current branch
+git branch --show-current
+
+# Commits to include
+git log main..HEAD --oneline
+
+# Files changed
+git diff main --stat
+
+# Target branch
+git remote show origin | grep "HEAD branch"
+```
+
+### 2. Load Artifacts
+
+- `spec.md` — Link requirements
+- `plan.md` — Link implementation plan
+- `review.md` — Link review results (if exists)
+- Bead info — Get from beads village
+
+### 3. Generate PR Description
+
+### 4. Create PR
+
+```bash
+gh pr create \
+  --title "[type]: [description]" \
+  --body "[generated body]" \
+  --base main \
+  --head [current-branch]
+```
+
+## PR Template
+
+```markdown
+## 🚀 Pull Request
+
+### Title
+`[type](scope): [description]`
+
+### Description
+[2-3 sentences explaining WHAT and WHY]
+
+### Related
+- **Bead:** [ID]
+- **Spec:** `.opencode/memory/specs/YYYY-MM-DD-feature.md`
+- **Plan:** `.opencode/memory/plans/YYYY-MM-DD-feature.md`
+
+---
+
+## Changes
+
+### Summary
+[Brief overview of changes]
+
+### Files Changed
+| File | Change |
+|------|--------|
+| `path/to/file.ts` | [What changed] |
+
+### Key Changes
+- ✨ [New feature/change 1]
+- 🐛 [Bug fix]
+- ♻️ [Refactor]
+
+---
+
+## Testing
+
+### Automated
+- [x] Unit tests pass
+- [x] Integration tests pass
+- [x] Type check passes
+- [x] Lint passes
+
+### Manual Testing
+- [ ] [Test scenario 1]
+- [ ] [Test scenario 2]
+
+### Test Commands
+```bash
+pnpm test
+pnpm typecheck
+pnpm lint
+```
+
+---
+
+## Checklist
+
+- [x] Code follows project conventions
+- [x] Tests added/updated
+- [x] Documentation updated (if needed)
+- [x] No console.log or debug code
+- [x] Self-review completed
+- [ ] Ready for review
+
+---
+
+## Screenshots (if UI changes)
+[Add screenshots here]
+
+---
+
+## Reviewer Notes
+[Any specific areas to focus on]
+```
+
+## PR Types
+
+| Type | Prefix | Example |
+|------|--------|---------|
+| Feature | `feat:` | `feat(auth): add SSO login` |
+| Bug Fix | `fix:` | `fix(api): handle null response` |
+| Refactor | `refactor:` | `refactor(core): simplify logic` |
+| Docs | `docs:` | `docs: update API guide` |
+| Chore | `chore:` | `chore(deps): update packages` |
+
+## Options
+
+```
+/pr                  # Auto-generate full PR
+/pr --draft          # Create as draft
+/pr --title "..."    # Custom title
+/pr --reviewer @user # Request reviewer
+/pr --label bug      # Add labels
+```
+
+## After Creation
+
+```markdown
+## ✅ PR Created
+
+**URL:** https://github.com/[repo]/pull/[number]
+**Title:** [title]
+**Branch:** [head] → [base]
+
+### Next Steps
+1. Request review from team
+2. Address feedback
+3. Merge when approved
+
+### Commands
+- View: `gh pr view`
+- Check status: `gh pr checks`
+- Merge: `gh pr merge`
+```
+
+## Rules
+
+- ✅ ALWAYS link to spec/plan/bead
+- ✅ ALWAYS include testing info
+- ✅ ALWAYS run checks before PR
+- ✅ ALWAYS self-review first
+- ❌ NEVER create PR with failing tests
+- ❌ NEVER skip description
+
+Now gathering info for PR...

package/command/research.md

@@ -0,0 +1,103 @@
+---
+description: Deep exploration and research before planning.
+agent: plan
+subtask: true
+---
+
+You are the **Plan Agent** delegating to **Scout Agent**. Execute the `/research` command.
+
+## Template
+
+Use template at: `@.opencode/memory/_templates/research.md`
+
+## Your Task
+
+Conduct deep research on a topic before planning implementation.
+
+## Process
+
+1. **Identify research questions** from spec or user request
+
+2. **Delegate to Scout Agent** with:
+   - Question to research
+   - Constraints (language, framework, versions)
+   - Format: summary | comparison | deep-dive
+   - Depth: quick | standard | deep
+
+3. **Document findings** at `.opencode/memory/research/YYYY-MM-DD-<topic>.md`
+
+4. **Summarize key insights** for planning
+
+## Research Request Format
+
+When delegating, use:
+```yaml
+type: "research"
+question: "[Research question]"
+constraints:
+  language: "[Language]"
+  framework: "[Framework]"
+format: "comparison"  # summary | comparison | deep-dive
+depth: "standard"     # quick | standard | deep
+```
+
+## Research Report Template
+
+```markdown
+---
+topic: [Topic]
+date: YYYY-MM-DD
+confidence: high | medium | low
+depth: quick | standard | deep
+versions:
+  - library: "[name]"
+    version: "[version]"
+bead_id: [optional]
+---
+
+# Research: [Topic]
+
+**Question:** [Original research question]
+
+## Summary
+[2-3 sentence answer]
+
+## Key Findings
+1. [Finding 1]
+2. [Finding 2]
+
+## Comparison (if applicable)
+| Option | Pros | Cons | Best For |
+|--------|------|------|----------|
+| A | | | |
+| B | | | |
+
+## Code Examples (if applicable)
+```[language]
+// Code example
+```
+
+## Recommendation
+[Recommended approach]
+
+## Verification Steps
+- [ ] [Item to verify in implementation]
+
+## Open Questions
+- [Question needing verification]
+
+## Sources
+| Source | Type | Reliability |
+|--------|------|-------------|
+| [URL/Title] | Official Docs | High |
+```
+
+## Tools to Use
+- `web_search` — General web search
+- `read_web_page` — Read specific URLs
+- `mcp__context7__*` — Library documentation
+- `mcp__exa__*` — Code examples, recent content
+- `mcp__gh_grep__searchGitHub` — Real-world code patterns
+- `librarian` — Deep repository analysis
+
+Now, what topic do you need to research?

package/command/resume.md

@@ -0,0 +1,80 @@
+---
+description: Continue from handoff. Restore state and resume work.
+agent: plan
+---
+
+You are the **Plan Agent** (or **Build Agent**). Execute the `/resume` command.
+
+## Your Task
+
+Resume work from a previous session using the handoff document.
+
+## Process
+
+1. **Load latest handoff** from `.opencode/memory/handoffs/`
+
+2. **Load related artifacts**:
+   - spec.md
+   - plan.md
+   - research.md (if exists)
+
+3. **Detect drift** — Check if code changed outside the session:
+   - Run `git status` and `git diff`
+   - Compare with handoff's file list
+
+4. **Summarize current state**: "We are here; these are next steps"
+
+5. **Propose next action**
+
+## Resume Workflow
+
+```
+1. Find latest handoff.md
+2. Load spec.md, plan.md
+3. Check git status for drift
+4. If drift detected:
+   - Summarize changes
+   - Mark affected tasks for re-evaluation
+   - Ask user to reconcile
+5. If no drift:
+   - Present status summary
+   - Propose next task
+```
+
+## Output Format
+
+```markdown
+## Session Resumed
+
+**Previous Session:** YYYY-MM-DD
+**Phase:** [current phase]
+**Branch:** [branch name]
+
+### Where We Left Off
+[Summary from handoff]
+
+### Drift Detection
+- [ ] No changes detected outside session
+- [ ] Changes detected: [list files]
+
+### Current Status
+- **Completed:** X tasks
+- **In Progress:** Y tasks
+- **Remaining:** Z tasks
+
+### Proposed Next Action
+[Specific next step to take]
+
+---
+Ready to continue? [Y/n]
+```
+
+## Drift Handling
+
+If drift is detected:
+1. List changed files
+2. Identify which tasks are affected
+3. Mark those tasks for re-evaluation
+4. Ask user: "Code changed outside session. Should I re-evaluate affected tasks?"
+
+Now, let me find and load the latest handoff to resume your work.