clikit-plugin 0.2.45 → 0.2.46

package/skill/playwright/references/tool-reference.md

@@ -0,0 +1,64 @@
+# Playwright MCP — Tool Reference
+
+## Core Tools
+
+### Navigation
+```
+playwright_navigate(url, waitUntil?)
+  waitUntil: "load" | "domcontentloaded" | "networkidle" (default: "load")
+```
+
+### Interaction
+```
+playwright_click(selector)
+playwright_fill(selector, value)
+playwright_select(selector, value)         # <select> elements
+playwright_evaluate(script)                # run JS in page context
+playwright_wait_for_selector(selector, timeout?)
+```
+
+### Capture
+```
+playwright_screenshot(fullPage?, selector?)
+playwright_get_text(selector?)             # get visible text
+```
+
+### Session
+```
+playwright_close()                         # always call when done
+```
+
+## Common Patterns
+
+### Auth flow
+```
+playwright_navigate("http://localhost:3000/login")
+playwright_fill("#email", "test@example.com")
+playwright_fill("#password", "secret")
+playwright_click("[type=submit]")
+playwright_wait_for_selector(".dashboard")
+playwright_screenshot()
+```
+
+### Responsive test
+```
+playwright_navigate("http://localhost:3000")
+playwright_evaluate("window.innerWidth")   # check viewport
+playwright_screenshot(true)               # full page
+```
+
+### Assert text
+```
+playwright_get_text(".status")
+# compare returned text to expected value
+```
+
+## Viewport Sizes
+
+| Breakpoint | Width |
+|------------|-------|
+| Mobile | 375px |
+| Tablet | 768px |
+| Desktop | 1280px |
+
+Set via `playwright_evaluate("Object.assign(window, {innerWidth: 375})")` or configure in setup.

package/skill/receiving-code-review/SKILL.md

@@ -1,47 +1,36 @@
 ---
 name: receiving-code-review
-description: Use when receiving code review feedback. Technical evaluation, not emotional response.
+description: Use when receiving code review feedback. Verify before accepting, push back with data when appropriate.
 ---
 
-# Receiving Code Review Skill
+# Receiving Code Review
 
-You are running the **receiving-code-review** skill. Respond professionally.
+## Protocol
 
-## Mindset
-
-- Technical evaluation, not emotional
-- Never say "You're absolutely right!" without verification
-- Verify before implementing changes
-- Push back with technical reasoning when appropriate
-
-## Response Protocol
-
-1. **Read carefully** — Understand the actual concern
-2. **Verify locally** — Reproduce or confirm the issue
-3. **Categorize** — Is this a bug, style, optimization, or preference?
-4. **Respond** — Acknowledge, question, or push back with data
+1. **Read** — understand the actual concern, not the surface suggestion
+2. **Verify locally** — reproduce or confirm the issue
+3. **Categorize** — bug / style / optimization / preference
+4. **Respond** — acknowledge, question, or push back with evidence
 
 ## When to Push Back
 
 | Scenario | Response |
 |----------|----------|
-| Suggestion adds complexity without value | "This adds N lines for hypothetical future need. YAGNI applies." |
-| Change breaks existing behavior | "This would break X. Current approach handles Y correctly." |
-| Style preference disguised as bug | "Noted, but current pattern matches codebase conventions." |
-| Requested feature is "professional" polish | "This works correctly. The suggested enhancement is not in scope." |
+| Adds complexity for hypothetical need | "YAGNI — adds N lines for a case we don't have" |
+| Breaks existing behavior | "This breaks X. Current approach handles Y correctly." |
+| Style preference, not a bug | "Current pattern matches codebase conventions." |
+| Out-of-scope polish | "Works correctly. This enhancement is not in scope." |
 
-## YAGNI Check
+## YAGNI Check (before accepting "improvements")
 
-Before implementing "improvements":
-- Does this solve a real problem or hypothetical one?
+- Does this solve a real problem or a hypothetical one?
 - Is the complexity justified by actual usage?
 - Would a simpler solution suffice?
 
-If answer is "hypothetical" or "no" — push back.
+If "hypothetical" → push back.
 
 ## Red Flags
 
-- Agreeing immediately without verification
-- Implementing suggestions that increase complexity unnecessarily
+- Agreeing immediately without verifying
+- Implementing suggestions that increase complexity without value
 - Treating style preferences as bugs
-- Adding "professional" features that nobody asked for

package/skill/requesting-code-review/SKILL.md

@@ -1,47 +1,43 @@
 ---
 name: requesting-code-review
-description: Use after completing a task. Dispatch @review subagent for quality gate.
+description: Use after completing a task. Dispatch @review subagent for quality gate before merging.
 ---
 
-# Requesting Code Review Skill
+# Requesting Code Review
 
-You are running the **requesting-code-review** skill. Never skip review.
+## Trigger
 
-## When to Request
+Request review after: major features, significant refactors, before merge, when unsure of approach.
 
-- After major features
-- Before merging
-- After significant refactors
-- When unsure about approach
-
-## Information to Provide
+## What to Provide to @review
 
 | Item | Example |
 |------|---------|
-| Git SHAs | "Changed: a1b2c3d..e4f5g6h" |
-| What was implemented | "Added user authentication with JWT" |
-| Plan/requirements | "Per spec in .opencode/memory/specs/auth.md" |
-| Known issues | "Edge case X not handled yet" |
+| Diff range | `a1b2c3d..e4f5g6h` |
+| What changed | "Added JWT auth with refresh tokens" |
+| Spec/plan ref | `.opencode/memory/specs/auth.md` |
+| Known gaps | "Edge case X not handled yet" |
 
-## Review Workflow
+## Dispatch
 
-1. Dispatch @review subagent
-2. Wait for review results
-3. Fix Critical issues immediately
-4. Address High issues before merge
-5. Medium/Low can be follow-up tickets
+```
+@review: review changes from <sha>..<sha>
+Context: <what was built>
+Spec: <path>
+Known issues: <list or none>
+```
 
-## Issue Severity Response
+## Severity Response
 
 | Severity | Action |
 |----------|--------|
-| Critical | Fix NOW, re-review |
+| Critical | Fix now, re-review |
 | High | Fix before merge |
-| Medium | Create ticket, fix soon |
-| Low | Document, fix later |
+| Medium | Create beads ticket |
+| Low | Document, defer |
 
 ## Red Flags
 
 - Skipping review "because it's small"
-- Merging without addressing Critical issues
-- Not providing context for reviewer
+- Merging with unresolved Critical issues
+- No context given to reviewer

package/skill/ritual-workflow/SKILL.md

@@ -1,101 +1,41 @@
 ---
 name: ritual-workflow
-description: Use when starting any task. Enforces DISCOVER → PLAN → IMPLEMENT → VERIFY → COMPLETE workflow with hard gates.
+description: Use when starting any task. Enforces DISCOVER → PLAN → IMPLEMENT → VERIFY → COMPLETE with hard gates at each phase.
 ---
 
-# Ritual Workflow Skill
+# Ritual Workflow
 
-You are running the **ritual-workflow** skill. Every task follows a strict phase structure.
-
-## Phases (in order)
+## Phases
 
 ```
 DISCOVER → PLAN → IMPLEMENT → VERIFY → COMPLETE
 ```
 
-### Phase 1: DISCOVER
-- Understand the problem
-- Gather requirements
-- Identify stakeholders and constraints
-- Define success criteria
-- **Gate**: Can articulate the problem clearly
-
-### Phase 2: PLAN
-- Design the solution
-- Break into tasks
-- Identify dependencies
-- Estimate effort
-- **Gate**: Plan approved (user confirms)
-
-### Phase 3: IMPLEMENT
-- Write code
-- Follow plan
-- Create tests
-- **Gate**: All planned tasks done
-
-### Phase 4: VERIFY
-- Run tests
-- Type check
-- Lint
-- Build
-- **Gate**: All checks pass
-
-### Phase 5: COMPLETE
-- Document changes
-- Create PR
-- Clean up
-- **Gate**: Merged or deployed
-
-## Hard Gates
-
-| Current Phase | Must Complete Before Advancing |
-|---------------|-------------------------------|
-| DISCOVER | Problem statement written |
-| PLAN | User approves plan |
-| IMPLEMENT | All tasks checked off |
-| VERIFY | Tests pass, build succeeds |
-| COMPLETE | PR merged |
+| Phase | Gate (must pass before advancing) |
+|-------|-----------------------------------|
+| DISCOVER | Problem statement written, success criteria defined |
+| PLAN | User approves spec + plan |
+| IMPLEMENT | All planned tasks checked off |
+| VERIFY | typecheck + tests + lint + build all pass |
+| COMPLETE | PR merged / deployed |
 
-## Ritual State
+## Command Map
 
-State is tracked in `.opencode/memory/ritual-state.json`:
-
-```json
-{
-  "taskId": "bead-123",
-  "phases": [
-    { "name": "discover", "status": "done" },
-    { "name": "plan", "status": "in_progress" },
-    ...
-  ],
-  "currentPhase": 1
-}
-```
-
-## Commands
-
-| Command | Phase | Action |
-|---------|-------|--------|
-| `/create` | DISCOVER | Initialize ritual, gather requirements |
-| `/plan` | PLAN | Create implementation plan |
-| `/start` | IMPLEMENT | Begin implementation |
-| `/verify` | VERIFY | Run checks |
-| `/ship` | COMPLETE | Finalize and deploy |
+| Mode | Commands |
+|------|----------|
+| Quick | `/create` → `/start` → `/verify` → `/ship` |
+| Deep (research/UI) | `/create` → `/research` → `/design` → `/start` → `/verify` → `/ship` |
 
 ## Enforcement
 
 - Cannot skip phases
-- Cannot implement without approved plan
-- Cannot complete without passing verify
-- Each phase requires explicit completion
-
-## Status Check
-
-Run `checkRitualProgress()` to see current phase and blockers.
+- Cannot IMPLEMENT without an approved plan — run `/create` first
+- Cannot COMPLETE without `/verify` returning SHIP_READY
+- Each phase requires explicit completion signal
 
 ## Red Flags
 
-- Skipping to IMPLEMENT without PLAN
-- Marking COMPLETE with failing tests
-- Moving forward without user approval
-- Ignoring phase gates
+- Implementing without a plan
+- Marking COMPLETE with failing `/verify` gates
+- Moving forward without user approval on spec/plan
+- Running `/ship` before SHIP_READY

package/skill/root-cause-tracing/SKILL.md

@@ -1,73 +1,49 @@
 ---
 name: root-cause-tracing
-description: Trace bugs backward through call chain to original trigger. Never fix where error appears.
+description: Trace bugs backward through call chain to original trigger. Never fix where error appears — fix where bad data originated.
 ---
 
-# Root Cause Tracing Skill
+# Root Cause Tracing
 
-You are running the **root-cause-tracing** skill. Fix the origin, not the symptom.
+## Principle
 
-## Core Principle
+Error appears at **A**. Cause is at **B**. Trace backward to **B** and fix there.
 
-The error appears at point A. The cause is at point B. Always trace backward to B.
+## Process
 
-## Tracing Process
-
-### Step 1: Locate the Error
-- Find where the error manifests
-- DO NOT fix here yet
-- This is the symptom location
-
-### Step 2: Trace the Call Chain
-- Who called this function?
-- Who called that function?
-- Keep going until you find the trigger
+```
+1. LOCATE  — find where error manifests (do NOT fix here)
+2. TRACE   — walk the call chain backward (who called this? who called that?)
+3. FIND    — first place wrong data/state originated
+4. FIX     — apply fix at origin
+5. VERIFY  — confirm symptom disappears
+```
 
-### Step 3: Find the Root Cause
-- The first place where incorrect data/state originated
-- The decision point that led to wrong path
-- The missing validation that allowed bad input
+## Example
 
-### Step 4: Fix at Origin
-- Apply fix at the root cause location
-- NOT where the error appeared
-- Verify symptom disappears
+```
+Error: Cannot read property 'length' of undefined
+  at processItems (line 42)    ← symptom — DO NOT FIX HERE
+  at handleRequest (line 28)
+  at parseInput (line 15)      ← origin — FIX HERE (return [] not null)
+```
 
 ## Instrumentation
 
-```javascript
-// At each layer, add:
-console.error('[TRACE] Function:', functionName);
-console.error('[TRACE] Args:', JSON.stringify(args, null, 2));
-console.error('[TRACE] Stack:', new Error().stack);
+```js
+console.error('[TRACE]', functionName, JSON.stringify(args, null, 2));
+console.error('[STACK]', new Error().stack);
 ```
 
-## Bisection for Test Polluters
-
-When tests fail in batch but pass individually:
+## Test Polluter Bisection
 
-1. Run first half of tests → passing?
-2. If yes: bug in second half
-3. If no: bug in first half
-4. Repeat until isolated to single test
-5. That test is polluting shared state
+Tests fail in batch but pass alone → shared state pollution:
+1. Run first half → passes? bug in second half
+2. Run first half → fails? bug in first half
+3. Repeat until single test isolated
 
 ## Red Flags
 
-- Fixing where error is thrown (not where caused)
-- "Let me add a null check here" (defensive, not corrective)
-- Not tracing the full call chain
-- Assuming you know the cause without evidence
-
-## Example
-
-```
-Error: Cannot read property 'length' of undefined
-  at processItems (line 42)      ← DO NOT FIX HERE
-  at handleRequest (line 28)
-  at parseInput (line 15)        ← FIX HERE: null should be []
-```
-
-## Rule
-
-**Never fix at the symptom. Always trace to the root.**
+- Adding a null check at the symptom location (defensive, not corrective)
+- Assuming cause without tracing the full chain
+- No evidence before applying fix

package/skill/session-management/SKILL.md

@@ -3,51 +3,32 @@ name: session-management
 description: Use for managing context growth, task switching, and session continuity in long-running work.
 ---
 
-# Session Management Skill
-
-You are running the **session-management** skill. Context and continuity management.
+# Session Management
 
 ## Context Thresholds
 
 | State | Context % | Action |
 |-------|-----------|--------|
-| Green | < 50% | Normal operation |
-| Yellow | 50-75% | Start summarizing, offload to memory |
-| Orange | 75-90% | Aggressive context pruning, handoff prep |
-| Red | > 90% | Initiate session handoff |
-
-## Session Tools
-
-| Tool | Purpose |
-|------|---------|
-| Memory artifacts | Save state to `.opencode/memory/` |
-| Handoff docs | Session state for next agent |
-| Beads sync | Persist tasks to `.beads/` |
-| Git commits | Checkpoint progress |
-
-## Workflow Patterns
-
-### Starting a Session
-1. Check Beads for in-progress tasks
-2. Read handoff if continuing previous session
-3. Claim ready tasks
-4. Begin work
-
-### During Session
-1. Monitor context usage
-2. Write specs/plans to memory as created
-3. Commit incremental progress
-4. Sync Beads regularly
-
-### Ending a Session
+| Green | < 50% | Normal |
+| Yellow | 50–75% | Offload findings to `memory/` |
+| Orange | 75–90% | Prep handoff doc |
+| Red | > 90% | Run `/handoff`, end session |
+
+## Session Start
+
+1. `beads-village_init` → join workspace
+2. `beads-village_inbox(unread=true)` → check blockers
+3. Read `memory/_digest.md` + latest handoff if continuing
+
+## Session End
+
 1. Complete or checkpoint current task
-2. Write handoff document
-3. Sync all state to git/Beads
-4. Release file reservations
+2. Run `/handoff` → write handoff doc
+3. `beads-village_sync` → push state
+4. Release all file reservations via `beads-village_done`
 
-## Best Practices
+## Red Flags
 
-- Check context percentage periodically
-- Write to memory before hitting thresholds
-- Use handoff documents for continuity
-- Keep session state in version control
+- Crossing 90% without writing a handoff
+- Not reading the handoff when resuming
+- Losing task state between sessions

package/skill/source-code-research/SKILL.md

@@ -1,98 +1,42 @@
 ---
 name: source-code-research
-description: Use when API documentation is insufficient. Research library implementation details by fetching package source.
+description: Use when API docs are insufficient. Go directly to package source to understand edge cases, error behavior, and internal patterns.
 ---
 
-# Source Code Research Skill
-
-You are running the **source-code-research** skill. Go beyond API docs to understand internals.
+# Source Code Research
 
 ## When to Use
 
-- API docs don't explain behavior
-- Need to understand edge cases
+- API docs don't explain the behavior you're seeing
+- Need to understand edge cases or error handling
 - Debugging library interactions
-- Learning implementation patterns
-- Verifying documented behavior
+- Verifying that documented behavior is actually implemented
 
-## Research Protocol
+## Protocol
 
-### 1. Identify Package
 ```bash
-# Find package location
-which <package>
-npm list <package>
+# 1. Locate source
+cat node_modules/<pkg>/package.json | grep -E '"main"|"types"|"source"'
+ls node_modules/<pkg>/src/
 
-# Find source location
-ls -la node_modules/<package>/
-```
+# 2. Read entry point
+cat node_modules/<pkg>/src/index.ts   # or index.js
 
-### 2. Locate Source
-```
-Check for:
-- src/ directory
-- lib/ directory
-- dist/ with sourcemaps
-- TypeScript .ts files
-- Index entry point
+# 3. Read tests (best doc of real behavior)
+ls node_modules/<pkg>/test/  ||  ls node_modules/<pkg>/__tests__/
 ```
 
-### 3. Read Key Files
-Focus on:
-- Entry point (index.js/ts)
-- Main export file
-- Types/interfaces
-- Core implementation
-- Tests (for behavior)
-
-### 4. Trace Execution
-- Follow function calls
-- Map data flow
-- Identify decision points
-- Note error handling
-
-## Key Questions to Answer
-
-| Question | Why |
-|----------|-----|
-| How is this implemented? | Understand behavior |
-| What edge cases exist? | Avoid surprises |
-| How are errors handled? | Proper error handling |
-| What are the types? | TypeScript integration |
-| What are the defaults? | Implicit behavior |
-
-## Finding Patterns
-
-### Constructor Pattern
-```javascript
-// Look for initialization logic
-class Example {
-  constructor(options) {
-    this.options = { ...defaults, ...options };
-  }
-}
-```
+## What to Look For
 
-### Error Handling Pattern
-```javascript
-// Identify what throws vs returns
-if (!valid) {
-  throw new Error('...');
-  // or
-  return { error: '...' };
-}
-```
-
-### Async Pattern
-```javascript
-// Understand async behavior
-async function process() {
-  // Is this parallel or sequential?
-  await Promise.all([...]);
-}
-```
+| Question | Where |
+|----------|-------|
+| What are the defaults? | Constructor / options merge |
+| What throws vs returns error? | Error handling paths |
+| What's async vs sync? | Promise.all vs sequential awaits |
+| What are the types? | Type definitions, interfaces |
+| What edge cases exist? | Conditional branches, null checks |
 
-## Output Format
+## Output
 
 Save to `.opencode/memory/research/[package]-internals.md`:
 
@@ -104,35 +48,22 @@ Save to `.opencode/memory/research/[package]-internals.md`:
 - Types: [file]
 
 ## Key Findings
-
-### [Feature Name]
-- **Location**: file:line
-- **Behavior**: [description]
-- **Edge Cases**: [list]
-
-## Implementation Notes
-[Key patterns discovered]
+### [Feature]
+- Location: file:line
+- Behavior: …
+- Edge Cases: …
 
 ## Gotchas
-[Surprising behaviors]
 ```
 
-## Anti-Patterns
+## Red Flags
 
-- Relying only on TypeScript definitions
-- Not reading tests
-- Assuming behavior from name
+- Relying only on TypeScript type definitions (not the same as behavior)
+- Not reading the tests
+- Assuming behavior from the function name
 - Ignoring error paths
 
-## Quick Reference
-
-```bash
-# Find main entry
-cat node_modules/pkg/package.json | grep main
-
-# Find types
-cat node_modules/pkg/package.json | grep types
+## References
 
-# Check for source
-ls node_modules/pkg/src/
-```
+- [Quick reference](references/quick-ref.md) — locate source commands, grep patterns, Context7 MCP alternative
+- MCP: `context7` — see [mcp.json](mcp.json)