clikit-plugin 0.2.44 → 0.2.46

package/skill/source-code-research/mcp.json

@@ -0,0 +1,13 @@
+{
+  "mcpServers": {
+    "context7": {
+      "type": "remote",
+      "url": "https://mcp.context7.com/mcp",
+      "description": "Fetch library docs and source when npm package internals are unclear",
+      "tools": [
+        "resolve-library-id",
+        "get-library-docs"
+      ]
+    }
+  }
+}

package/skill/source-code-research/references/quick-ref.md

@@ -0,0 +1,65 @@
+# Source Code Research — Quick Reference
+
+## Locate Package Source
+
+```bash
+# Entry point
+node -e "console.log(require.resolve('<pkg>'))"
+
+# package.json fields
+node -e "const p=require('<pkg>/package.json'); console.log(p.main, p.types, p.source, p.exports)"
+
+# Source directory
+ls node_modules/<pkg>/src/ 2>/dev/null || ls node_modules/<pkg>/lib/
+
+# Has TypeScript source?
+ls node_modules/<pkg>/src/*.ts 2>/dev/null | head -5
+```
+
+## Read Tests (Best Behavior Docs)
+
+```bash
+ls node_modules/<pkg>/test/
+ls node_modules/<pkg>/__tests__/
+ls node_modules/<pkg>/spec/
+
+# Read one
+cat node_modules/<pkg>/test/core.test.js | head -100
+```
+
+## Trace a Specific Behavior
+
+```bash
+# Find where a method/function is defined
+grep -r "functionName" node_modules/<pkg>/src/ -l
+grep -n "functionName" node_modules/<pkg>/src/core.ts
+
+# Find error messages (understand throw conditions)
+grep -n "throw\|Error(" node_modules/<pkg>/src/core.ts
+
+# Find defaults
+grep -n "default\|DEFAULT\|\|\s*{}" node_modules/<pkg>/src/options.ts
+```
+
+## Context7 MCP Alternative
+
+When local source is unclear, use Context7 MCP:
+
+```
+resolve-library-id(libraryName="<pkg>", query="<what you need to understand>")
+→ get library ID
+get-library-docs(libraryId="<id>", query="<specific question>")
+```
+
+## Output Template
+
+```markdown
+## [pkg] — [function/behavior]
+
+- **Location**: src/core.ts:142
+- **Behavior**: [what it actually does]
+- **Defaults**: [default values if any]
+- **Throws when**: [conditions]
+- **Returns**: [shape of return value]
+- **Gotcha**: [surprising behavior]
+```

package/skill/systematic-debugging/SKILL.md

@@ -1,58 +1,45 @@
 ---
 name: systematic-debugging
-description: Use when encountering a bug. Enforces evidence-based 4-phase debugging process.
+description: Use when encountering a bug. Enforces evidence-based 4-phase process: Reproduce → Isolate → Identify → Verify. No guessing.
 ---
 
-# Systematic Debugging Skill
+# Systematic Debugging
 
-You are running the **systematic-debugging** skill. No guessing. No random changes.
+## 4 Phases
 
-## 4-Phase Process
-
-### Phase 1: Reproduce
-- Create a minimal reproduction case
-- Document exact steps to trigger
-- Verify it's reproducible (not intermittent)
-
-### Phase 2: Isolate
-- Binary search: Comment out half the code
-- Which half contains the bug?
-- Repeat until isolated to smallest possible unit
+```
+REPRODUCE → ISOLATE → IDENTIFY → VERIFY
+```
 
-### Phase 3: Identify
-- Read the isolated code carefully
-- Trace variable values
-- Add instrumentation (console.log, debugger)
-- Understand WHY it fails, not just WHERE
+**Reproduce** — Minimal repro case. Document exact trigger. Confirm it's not intermittent.
 
-### Phase 4: Verify
-- Fix the root cause
-- Run tests to confirm fix
-- Check for similar issues elsewhere
-- Add regression test
+**Isolate** — Binary search: comment out half the code. Which half has the bug? Repeat until smallest unit.
 
-## Rules
+**Identify** — Read isolated code. Trace variable values. Understand *why* it fails, not just *where*.
 
-| Rule | Why |
-|------|-----|
-| No random changes | Masks symptoms, doesn't fix cause |
-| After 3+ failed fixes | Question architectural assumptions |
-| Always reproduce first | Can't fix what you can't trigger |
-| Add regression test | Prevent recurrence |
+**Verify** — Fix root cause. Run tests. Check for similar issues. Add regression test.
 
 ## Instrumentation
 
-```javascript
-// Stack trace
-console.error('Debug:', new Error().stack);
-
-// Variable dump
-console.error('Context:', JSON.stringify({ var1, var2 }, null, 2));
+```js
+console.error('[DBG]', JSON.stringify({ var1, var2 }, null, 2));
+console.error('[STACK]', new Error().stack);
 ```
 
+## Rules
+
+| Situation | Action |
+|-----------|--------|
+| 3+ failed fixes | Question architectural assumptions |
+| Error appears at A | Trace backward — cause is at B, fix B |
+| No repro steps | Don't touch code yet |
+
 ## Red Flags
 
-- Changing code without understanding why
-- "Let me try this" without hypothesis
-- Fixing symptoms instead of root cause
-- No reproduction steps
+- Changing code without a hypothesis
+- Fixing where error appears, not where it originates
+- No regression test after fix
+
+## References
+
+- [Debugging patterns](references/patterns.md) — binary search template, instrumentation helpers, async bug patterns, hypothesis template

package/skill/systematic-debugging/references/patterns.md

@@ -0,0 +1,71 @@
+# Debugging Patterns
+
+## Binary Search (Isolate Phase)
+
+```js
+// 1. Comment out second half of suspect function
+// 2. Does bug disappear? → bug was in that half
+// 3. Restore, comment out first half
+// 4. Repeat until isolated to single expression
+
+function process(input) {
+  const a = step1(input);    // ← comment from here down
+  const b = step2(a);
+  const c = step3(b);        // ← to here
+  return c;
+}
+```
+
+## Instrumentation Templates
+
+```js
+// Entry/exit trace
+function traced(name, fn) {
+  return function(...args) {
+    console.error(`[ENTER] ${name}`, JSON.stringify(args));
+    const result = fn.apply(this, args);
+    console.error(`[EXIT]  ${name}`, JSON.stringify(result));
+    return result;
+  };
+}
+
+// State snapshot at a point
+function snapshot(label, state) {
+  console.error(`[SNAP] ${label}`, JSON.stringify(state, null, 2));
+  console.error(`[STACK]`, new Error().stack.split('\n').slice(1,5).join('\n'));
+}
+```
+
+## Test Polluter Isolation
+
+```bash
+# Run individual test — passes?
+npx jest path/to/test.spec.ts
+
+# Run full suite — fails?
+npx jest
+
+# Binary search: run subsets
+npx jest --testPathPattern="a|b|c"     # first half
+npx jest --testPathPattern="d|e|f"     # second half
+# isolate to single file, then single test
+```
+
+## Async Bug Patterns
+
+| Symptom | Likely Cause |
+|---------|-------------|
+| Passes locally, fails CI | Race condition — missing await or setTimeout |
+| Intermittent failure | Shared mutable state between tests |
+| Works in isolation, fails in batch | Test polluter — global state mutation |
+| Wrong value but no error | Stale closure or captured reference |
+
+## Hypothesis Template
+
+Before changing anything, write:
+```
+Hypothesis: [specific cause]
+Evidence:   [what I observed]
+Test:       [how I will verify or falsify]
+Expected:   [what should happen if hypothesis is correct]
+```

package/skill/test-driven-development/SKILL.md

@@ -1,53 +1,29 @@
 ---
 name: test-driven-development
-description: Use when implementing any feature. Enforces strict RED-GREEN-REFACTOR cycle.
+description: Use when implementing any feature. Enforces strict RED-GREEN-REFACTOR cycle. No code before a failing test exists.
 ---
 
-# Test-Driven Development Skill
+# Test-Driven Development
 
-You are running the **test-driven-development** skill. No code without tests. No exceptions.
-
-## RED-GREEN-REFACTOR
-
-### Phase 1: RED
-1. Write a failing test
-2. Run the test — it MUST fail
-3. If it passes, the test is wrong — delete and rewrite
-
-### Phase 2: GREEN
-1. Write the MINIMUM code to make the test pass
-2. Run the test — it MUST pass
-3. If it fails, fix the code (not the test)
-
-### Phase 3: REFACTOR
-1. Clean up code while keeping tests green
-2. Run tests after each change
-3. Commit when satisfied
-
-## Rules
-
-| Rule | Enforcement |
-|------|-------------|
-| Write code before test? | DELETE the code. Don't keep as reference. |
-| Test passes unexpectedly? | DELETE the test. It's testing nothing. |
-| Skip RED phase? | Not allowed. Always start with failing test. |
-| "Just this once"? | No. No exceptions. |
-
-## Workflow
+## Cycle
 
 ```
-1. Think → What should this do?
-2. RED → Write failing test
-3. Run → Watch it fail
-4. GREEN → Write minimal code
-5. Run → Watch it pass
-6. REFACTOR → Clean up
-7. Commit
+RED   → write failing test → run → must fail
+GREEN → write minimum code → run → must pass
+REFACTOR → clean up, keep green → commit
 ```
 
+## Hard Rules
+
+| Situation | Action |
+|-----------|--------|
+| Code written before test | DELETE the code. Start over. |
+| Test passes on first run | DELETE the test. It's testing nothing. |
+| Tempted to skip RED | Not allowed. Always see it fail first. |
+
 ## Red Flags
 
-- Writing implementation before test
+- Implementation exists before test
 - Keeping "reference code" while writing test
 - Skipping "watch it fail" step
-- Test that can never fail
+- Test body mirrors the implementation

package/skill/testing-anti-patterns/SKILL.md

@@ -1,100 +1,72 @@
 ---
 name: testing-anti-patterns
-description: Prevents testing mock behavior instead of real code, test-only methods in production classes, mocking without understanding dependencies.
+description: Prevents testing mock behavior instead of real code, test-only production methods, and mocking without understanding boundaries.
 ---
 
-# Testing Anti-Patterns Skill
+# Testing Anti-Patterns
 
-You are running the **testing-anti-patterns** skill. Tests should verify real behavior, not mock theater.
+## Anti-Pattern 1 — Testing the Mock
 
-## Anti-Pattern #1: Testing Mocks
-
-```javascript
-// BAD: Test verifies mock was called
-const mock = jest.fn();
-service.doThing(mock);
+```js
+// BAD: proves nothing about service.doThing
 expect(mock).toHaveBeenCalled();
 
-// This tests nothing about service.doThing
-// It only proves you called the mock
-```
-
-```javascript
-// GOOD: Test verifies actual behavior
-const result = service.doThing(realDependency);
+// GOOD: verify actual behavior
 expect(result.status).toBe('success');
 expect(sideEffectHappened).toBe(true);
 ```
 
-## Anti-Pattern #2: Test-Only Methods
+## Anti-Pattern 2 — Test-Only Production Methods
 
-```javascript
-// BAD: Method exists only for testing
+```js
+// BAD
 class UserService {
-  private validateEmail(email) { ... }  // private
-  _validateEmailForTesting(email) { ... }  // NEVER DO THIS
+  _validateEmailForTesting(email) { ... }  // NEVER
 }
 
-// This couples tests to implementation
-// Refactoring becomes impossible
-```
-
-```javascript
-// GOOD: Test through public API
-// If you need to test validation, test it through the method that uses it
+// GOOD: test through the public API
 const result = userService.register(email);
 expect(result.isValid).toBe(true);
 ```
 
-## Anti-Pattern #3: Mocking Without Understanding
+## Anti-Pattern 3 — Over-Mocking
 
-```javascript
-// BAD: Over-mocking without knowing why
+```js
+// BAD: mocking everything means testing nothing
 jest.mock('./database');
 jest.mock('./logger');
 jest.mock('./config');
-jest.mock('./everything');
 
-// Test now verifies nothing about integration
-// Any refactoring breaks tests
+// GOOD: mock only external boundaries
+// Mock: network calls, filesystem, external services, time/date
+// Keep real: domain logic, internal utilities, business rules
 ```
 
-```javascript
-// GOOD: Mock only external boundaries
-// Keep real implementations for:
-// - Domain logic
-// - Internal utilities
-// - Business rules
-
-// Mock only:
-// - Network calls
-// - File system
-// - External services
-// - Time/date
-```
-
-## Decision Matrix
+## Mock Decision
 
-| Mock It? | Yes If... | No If... |
-|----------|-----------|----------|
-| Database | Unit test | Integration test |
-| Logger | Never | Always use real |
-| Config | External file | In-memory defaults |
-| HTTP client | External API | Your own server |
-| Time | Tests time-sensitive logic | Tests pure functions |
+| Dependency | Mock? |
+|------------|-------|
+| Network / external API | Yes |
+| File system | Yes |
+| Time / date | Yes |
+| Logger | No — use real |
+| Domain logic | No |
+| Your own services | No |
 
 ## Rules
 
-1. **Test behavior, not implementation** - What does it do, not how
-2. **No test-only code in production** - If it's not used, delete it
-3. **Mock at boundaries** - External dependencies only
-4. **One assertion per test** - Or at least one concept
-5. **Test names describe behavior** - `shouldRejectInvalidEmail` not `testEmail`
+- Test behavior, not implementation
+- No test-only code in production classes
+- Mock at external boundaries only
+- Test names describe behavior: `rejectsInvalidEmail` not `testEmail`
 
 ## Red Flags
 
-- Test file has more mock setup than assertions
+- More mock setup than assertions in test file
 - Private methods exposed for testing
 - Tests break on harmless refactors
-- `toHaveBeenCalled` without verifying the result
-- Mocking modules you own
+- `toHaveBeenCalled` without asserting the result
+
+## References
+
+- [Decision matrix](references/decision-matrix.md) — full mock decision table, naming conventions, AAA structure, smell → fix guide

package/skill/testing-anti-patterns/references/decision-matrix.md

@@ -0,0 +1,55 @@
+# Testing Anti-Patterns — Decision Reference
+
+## Mock Decision Matrix (expanded)
+
+| Dependency | Mock in unit? | Mock in integration? | Reason |
+|------------|:---:|:---:|--------|
+| External HTTP API | ✅ | ❌ | External boundary |
+| Database (real) | ✅ | ❌ | External boundary |
+| File system | ✅ | context | Depends on test scope |
+| Time / Date | ✅ | ✅ | Non-deterministic |
+| Logger | ❌ | ❌ | No behavior, use real |
+| Your own service class | ❌ | ❌ | You own it — test it |
+| Domain logic | ❌ | ❌ | Core behavior |
+| Config (env vars) | ❌ | ❌ | Use test env values |
+| In-memory store | ❌ | ❌ | Fast, no reason to mock |
+
+## Naming Convention
+
+```js
+// Bad — describes mechanics
+test('testEmail')
+test('checkValidation')
+
+// Good — describes behavior
+test('rejects email missing @ symbol')
+test('returns 400 when name exceeds 255 chars')
+test('does not create user when email already exists')
+```
+
+## Test Structure (Arrange-Act-Assert)
+
+```js
+test('returns error when stock is zero', () => {
+  // Arrange
+  const product = { id: 1, stock: 0 };
+
+  // Act
+  const result = checkout(product, quantity=1);
+
+  // Assert
+  expect(result.error).toBe('OUT_OF_STOCK');
+  expect(result.charged).toBe(false);
+});
+```
+
+## Smell → Fix Reference
+
+| Smell | Fix |
+|-------|-----|
+| 10+ lines of mock setup | Extract to fixture or factory |
+| `beforeEach` with global mocks | Move to test-local setup |
+| Testing private via `_method` | Test via public API |
+| `toHaveBeenCalledWith` only | Add assertion on the real result |
+| Mock chain 3 levels deep | Mock the boundary, not each call |
+| Same test body repeated 5× | Parameterize with `test.each` |

package/skill/using-git-worktrees/SKILL.md

@@ -1,129 +1,53 @@
 ---
 name: using-git-worktrees
-description: Use when starting isolated development work. Creates isolated workspace on new branch with smart directory selection.
+description: Use when starting isolated development work. Creates isolated workspace on new branch via bd worktree, prevents dirty-state conflicts.
 ---
 
-# Using Git Worktrees Skill
+# Using Git Worktrees
 
-You are running the **using-git-worktrees** skill. Isolated workspaces for parallel development.
+## Pre-conditions (verify before creating)
 
-## When to Use
-
-- Starting new feature branch
-- Parallel development work
-- Isolated experimentation
-- Hotfix development
-
-## Directory Selection Priority
-
-```
-1. .worktrees/          (preferred hidden directory)
-2. worktrees/           (visible alternative)
-3. Check CLAUDE.md      (project preference)
-4. Ask user             (if unclear)
-```
-
-## Workflow
-
-### 1. Verify Pre-conditions
 ```bash
-# Check we're in a git repo
-git rev-parse --is-inside-work-tree
-
-# Check for uncommitted changes
-git status --porcelain
-
-# Check .gitignore exists
-test -f .gitignore && echo "exists"
+git rev-parse --is-inside-work-tree  # must be inside a repo
+git status --porcelain               # must be clean — no uncommitted changes
 ```
 
-### 2. Create Worktree
-```bash
-# Choose directory
-WORKTREE_DIR=".worktrees"
+## Create Worktree
 
-# Create branch and worktree
-git worktree add -b <branch-name> ${WORKTREE_DIR}/<branch-name>
-```
-
-### 3. Verify Setup
 ```bash
-# Check worktree list
-git worktree list
+# Preferred: use bd (shares .beads/ database automatically)
+bd worktree create <issue-id>-<desc> --branch <type>/<issue-id>-<desc>
 
-# Verify .gitignore in worktree
-test -f ${WORKTREE_DIR}/<branch-name>/.gitignore
+# Fallback: raw git
+git worktree add -b <branch> .worktrees/<branch>
 ```
 
-### 4. Run Setup
-```bash
-# Enter worktree
-cd ${WORKTREE_DIR}/<branch-name>
-
-# Install dependencies
-npm install  # or appropriate package manager
+## Branch Naming
 
-# Run baseline tests
-npm test
 ```
-
-## Directory Structure
-
-```
-project-root/
-├── .git/
-├── .worktrees/
-│   ├── feature-a/
-│   ├── feature-b/
-│   └── hotfix-123/
-├── src/
-└── ...
+feature/<id>-<desc>   fix/<id>-<desc>   hotfix/<id>-<desc>
+refactor/<id>-<desc>  experiment/<id>-<desc>
 ```
 
-## Branch Naming Convention
+## After Creating
 
+```bash
+cd .worktrees/<branch>
+npm install        # install deps
+npm test           # run baseline — must pass before any changes
 ```
-feature/[description]    # New features
-fix/[description]        # Bug fixes
-hotfix/[description]     # Urgent fixes
-refactor/[description]   # Code improvements
-experiment/[description] # Exploration
-```
-
-## Commands Reference
-
-| Command | Purpose |
-|---------|---------|
-| `git worktree add -b branch path` | Create new worktree with branch |
-| `git worktree list` | List all worktrees |
-| `git worktree remove path` | Remove worktree |
-| `git worktree prune` | Clean up stale entries |
-
-## Safety Checks
-
-- [ ] Git repository confirmed
-- [ ] No uncommitted changes
-- [ ] .gitignore present
-- [ ] Baseline tests pass
-- [ ] Branch name follows convention
-
-## Anti-Patterns
-
-- Creating worktree with dirty state
-- Not verifying .gitignore
-- Skipping baseline tests
-- Using unclear branch names
 
 ## Cleanup
 
-When done with worktree:
 ```bash
-# Remove worktree
-git worktree remove ${WORKTREE_DIR}/<branch-name>
+bd worktree remove <name>    # preferred (cleans .beads redirect)
+git worktree prune           # clean stale refs
+git branch -d <branch>       # only after confirmed merge
+```
 
-# Delete branch (if merged)
-git branch -d <branch-name>
+## Red Flags
 
-# Prune stale references
-git worktree prune
-```
+- Creating worktree with uncommitted changes
+- Skipping baseline test run
+- Using raw `git worktree add` without `bd` (loses beads database link)
+- Unclear branch names