@bjlee2024/claude-mem 13.4.0

package/plugin/skills/make-plan/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: make-plan
+description: Create a detailed, phased implementation plan with documentation discovery. Use when asked to plan a feature, task, or multi-step implementation — especially before executing with do.
+---
+
+# Make Plan
+
+You are an ORCHESTRATOR. Create an LLM-friendly plan in phases that can be executed consecutively in new chat contexts.
+
+## Delegation Model
+
+Use subagents for *fact gathering and extraction* (docs, examples, signatures, grep results). Keep *synthesis and plan authoring* with the orchestrator (phase boundaries, task framing, final wording). If a subagent report is incomplete or lacks evidence, re-check with targeted reads/greps before finalizing.
+
+### Subagent Reporting Contract (MANDATORY)
+
+Each subagent response must include:
+1. Sources consulted (files/URLs) and what was read
+2. Concrete findings (exact API names/signatures; exact file paths/locations)
+3. Copy-ready snippet locations (example files/sections to copy)
+4. "Confidence" note + known gaps (what might still be missing)
+
+Reject and redeploy the subagent if it reports conclusions without sources.
+
+## Plan Structure
+
+### Phase 0: Documentation Discovery (ALWAYS FIRST)
+
+Before planning implementation, deploy "Documentation Discovery" subagents to:
+1. Search for and read relevant documentation, examples, and existing patterns
+2. Identify the actual APIs, methods, and signatures available (not assumed)
+3. Create a brief "Allowed APIs" list citing specific documentation sources
+4. Note any anti-patterns to avoid (methods that DON'T exist, deprecated parameters)
+
+The orchestrator consolidates findings into a single Phase 0 output.
+
+### Each Implementation Phase Must Include
+
+1. **What to implement** — Frame tasks to COPY from docs, not transform existing code
+   - Good: "Copy the V2 session pattern from docs/examples.ts:45-60"
+   - Bad: "Migrate the existing code to V2"
+2. **Documentation references** — Cite specific files/lines for patterns to follow
+3. **Verification checklist** — How to prove this phase worked (tests, grep checks)
+4. **Anti-pattern guards** — What NOT to do (invented APIs, undocumented params)
+
+### Final Phase: Verification
+
+1. Verify all implementations match documentation
+2. Check for anti-patterns (grep for known bad patterns)
+3. Run tests to confirm functionality
+
+## Key Principles
+
+- Documentation Availability ≠ Usage: Explicitly require reading docs
+- Task Framing Matters: Direct agents to docs, not just outcomes
+- Verify > Assume: Require proof, not assumptions about APIs
+- Session Boundaries: Each phase should be self-contained with its own doc references
+
+## Anti-Patterns to Prevent
+
+- Inventing API methods that "should" exist
+- Adding parameters not in documentation
+- Skipping verification steps
+- Assuming structure without checking examples
+
+## See Also
+
+- `oh-my-issues` — the issue-side sibling. When the plan you're being asked to make is rooted in a bug or feature backlog rather than a fresh idea, route through `oh-my-issues` first to cluster issues by root cause into plan masters and `plans/0X-*.md` design docs. `make-plan` then operates on the design doc for one plan slice.

package/plugin/skills/mem-search/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: mem-search
+description: Search claude-mem's persistent cross-session memory database. Use when user asks "did we already solve this?", "how did we do X last time?", or needs work from previous sessions.
+---
+
+# Memory Search
+
+Search past work across all sessions. Simple workflow: search -> filter -> fetch.
+
+## When to Use
+
+Use when users ask about PREVIOUS sessions (not current conversation):
+
+- "Did we already fix this?"
+- "How did we solve X last time?"
+- "What happened last week?"
+
+## 3-Layer Workflow (ALWAYS Follow)
+
+**NEVER fetch full details without filtering first. 10x token savings.**
+
+### Step 1: Search - Get Index with IDs
+
+Use the `search` MCP tool:
+
+```
+search(query="authentication", limit=20, project="my-project")
+```
+
+**Returns:** Table with IDs, timestamps, types, titles (~50-100 tokens/result)
+
+```
+| ID | Time | T | Title | Read |
+|----|------|---|-------|------|
+| #11131 | 3:48 PM | 🟣 | Added JWT authentication | ~75 |
+| #10942 | 2:15 PM | 🔴 | Fixed auth token expiration | ~50 |
+```
+
+**Parameters:**
+
+- `query` (string) - Search term
+- `limit` (number) - Max results, default 20, max 100
+- `project` (string) - Project name filter
+- `type` (string, optional) - "observations", "sessions", or "prompts"
+- `obs_type` (string, optional) - Comma-separated: bugfix, feature, decision, discovery, change
+- `dateStart` (string, optional) - YYYY-MM-DD or epoch ms
+- `dateEnd` (string, optional) - YYYY-MM-DD or epoch ms
+- `offset` (number, optional) - Skip N results
+- `orderBy` (string, optional) - "date_desc" (default), "date_asc", "relevance"
+
+### Step 2: Timeline - Get Context Around Interesting Results
+
+Use the `timeline` MCP tool:
+
+```
+timeline(anchor=11131, depth_before=3, depth_after=3, project="my-project")
+```
+
+Or find anchor automatically from query:
+
+```
+timeline(query="authentication", depth_before=3, depth_after=3, project="my-project")
+```
+
+**Returns:** `depth_before + 1 + depth_after` items in chronological order with observations, sessions, and prompts interleaved around the anchor.
+
+**Parameters:**
+
+- `anchor` (number, optional) - Observation ID to center around
+- `query` (string, optional) - Find anchor automatically if anchor not provided
+- `depth_before` (number, optional) - Items before anchor, default 5, max 20
+- `depth_after` (number, optional) - Items after anchor, default 5, max 20
+- `project` (string) - Project name filter
+
+### Step 3: Fetch - Get Full Details ONLY for Filtered IDs
+
+Review titles from Step 1 and context from Step 2. Pick relevant IDs. Discard the rest.
+
+Use the `get_observations` MCP tool:
+
+```
+get_observations(ids=[11131, 10942])
+```
+
+**ALWAYS use `get_observations` for 2+ observations - single request vs N requests.**
+
+**Parameters:**
+
+- `ids` (array of numbers, required) - Observation IDs to fetch
+- `orderBy` (string, optional) - "date_desc" (default), "date_asc"
+- `limit` (number, optional) - Max observations to return
+- `project` (string, optional) - Project name filter
+
+**Returns:** Complete observation objects with title, subtitle, narrative, facts, concepts, files (~500-1000 tokens each)
+
+## Examples
+
+**Find recent bug fixes:**
+
+```
+search(query="bug", type="observations", obs_type="bugfix", limit=20, project="my-project")
+```
+
+**Find what happened last week:**
+
+```
+search(type="observations", dateStart="2025-11-11", limit=20, project="my-project")
+```
+
+**Understand context around a discovery:**
+
+```
+timeline(anchor=11131, depth_before=5, depth_after=5, project="my-project")
+```
+
+**Batch fetch details:**
+
+```
+get_observations(ids=[11131, 10942, 10855], orderBy="date_desc")
+```
+
+## Why This Workflow?
+
+- **Search index:** ~50-100 tokens per result
+- **Full observation:** ~500-1000 tokens each
+- **Batch fetch:** 1 HTTP request vs N individual requests
+- **10x token savings** by filtering before fetching
+
+## Knowledge Agents
+
+Want synthesized answers instead of raw records? Use `/knowledge-agent` to build a queryable corpus from your observation history. The knowledge agent reads all matching observations and answers questions conversationally.

package/plugin/skills/oh-my-issues/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: oh-my-issues
+description: Cluster a GitHub issue backlog by root cause into a small set of plan-master issues, redirect children with a standardized comment, and bundle architectural-fix PRs that close clusters atomically. Use when an issue tracker has accumulated dozens of reports that share underlying defects, when asked to triage / consolidate / cluster / dedupe issues, when asked to build a plan series or roadmap from open issues, or when routing a new incoming bug into an existing plan.
+---
+
+# oh-my-issues
+
+Turn an issue backlog into a roadmap. Issues are symptom data, not units of work — the unit of work is the architectural defect that produces them. The end state is `open issues == open plans`, 1:1.
+
+## Core principle
+
+Stop closing issues one at a time. Group symptoms that share a single architectural fix into a cluster, give the cluster one canonical home (a plan-master issue + a `plans/0X-*.md` design doc), close every child with a standardized redirect, and ship one PR per cluster that closes all children atomically. New incoming bugs get appended to the matching master as a "Round N" comment, not opened as new tracked issues.
+
+This compounds three ways: architectural fixes retire whole symptom families, the plan's test matrix institutionalizes prevention in CI, and standardized triage makes residual inflow cheap.
+
+## When to use
+
+- The repo has 20+ open issues and many feel like duplicates or platform-specific symptoms of the same defect.
+- The user asks to "triage", "consolidate", "cluster", "dedupe", "group", or "make a plan from" the issue list.
+- A new bug is filed and the user wants to know whether it belongs to existing work.
+- The user wants to ship a focused PR that resolves a cluster of related issues.
+
+## When NOT to use
+
+- Fewer than ~15 open issues: just close them.
+- Issues are genuinely independent (no shared root causes): one fix per issue is correct.
+- The repo lacks `plans/` discipline and the user does not want to introduce one — propose first, do not impose.
+
+## Three modes
+
+### Mode 1: Cluster pass (initial reduction)
+
+Use when the backlog has never been consolidated. Goal: go from N issues to N_plans masters in one operation.
+
+1. **Read everything in full.** Fetch every open issue's body *and* its comment thread — not just titles. Surface-level grouping fails without full text, and reproduction steps, linked duplicates, and diagnostic output often live in comments rather than the original body. See "GitHub CLI primitives" below for the correct paginated listing + per-issue comment fetch (a single `gh issue list` call does **not** return comment bodies).
+2. **Cluster by root cause, not by surface.** The clustering question is *would one architectural change retire all of these?* — not *do these mention the same word?*. "Windows" is a surface; "spawn contract violated by host shells" is a root cause. Two issues with different surfaces can share a cluster (e.g. an env-var leak in two different code paths sharing one missing env-isolation boundary).
+3. **Name each cluster as an architectural problem.** Title format: `[plan-XX] <Architectural Defect> — <one-line scope>`. Example: `[plan-02] Spawn-Contract Templating — canonical ${CLAUDE_PLUGIN_ROOT} resolution across all hosts`. The title must imply a fix, not a topic.
+4. **Open one master issue per cluster** with a body that lists: the architectural defect, the children (by issue number), the fix sequence, and a required test matrix (host × IDE × shell, etc.) that prevents regression.
+5. **Mirror each master as `plans/0X-<slug>.md`** in the repo. The issue is the public tracker; the doc is the design. They reference each other.
+6. **Close every child** with the standardized redirect comment (see below) and state `not planned`.
+7. **Verify end state:** `gh issue list --state open` returns exactly the masters and nothing else.
+
+Target shape for ~100 issues: 4–8 masters. More than 10 means you're clustering by surface; fewer than 3 means clusters are too broad to ship as one PR each.
+
+### Mode 2: Triage (new incoming bug, steady state)
+
+Use when a new issue is filed after consolidation is in place. Goal: never let the issue list re-accumulate.
+
+1. **Read the new issue's body in full.**
+2. **Pattern-match the symptom against existing plan masters.** For each open master, ask: *would the fix described here also fix this new bug?* If yes → it belongs to that plan.
+3. **If a match exists**, post a "Round N" comment on the master that:
+   - Names the new child by number
+   - Describes the symptom in one line
+   - Sketches the concrete fix (1–3 lines, e.g. "guard with `case "$_SH" in /*.exe|"") _SH=bash ;; esac`")
+   - Adds any new test-matrix cell the bug exposes
+4. **Close the child** with the standardized redirect comment, `not planned`.
+5. **If no match exists** and the bug is genuinely novel: open a new plan master + `plans/0X-*.md`. Resist this. Most bugs are children of existing plans.
+
+### Mode 3: Bundle (ship the cluster)
+
+Use when a plan slice is ready to ship. Goal: one PR closes N children atomically.
+
+1. **List the master's children.** From the master body and consolidation comments, collect every child issue number routed to this plan.
+2. **Verify each child's symptom is covered** by the architectural fix in the PR. If a child is not covered, the PR is not ready or that child belongs in a different plan.
+3. **Generate the PR description**: title is the plan slice (e.g. "fix(spawn): canonical ${CLAUDE_PLUGIN_ROOT} resolution"); body lists every child with `Closes #N` so GitHub auto-closes them on merge.
+4. **Add the test matrix from the plan** to CI in the same PR. Without the matrix, the cluster will re-emerge.
+5. **After merge**, the master issue can be closed only if every child was covered. If the plan has remaining scope, leave the master open and link the PR as a partial-shipping checkpoint.
+
+## Naming a plan master
+
+A plan-master title must imply its fix.
+
+| Bad (surface) | Good (architectural) |
+|---|---|
+| Windows bugs | Spawn-Contract Templating across hosts |
+| Worker crashes | Worker / Daemon Lifecycle Hardening — supervision, health, retry |
+| Auth issues | Worker Env Isolation — strip host CLI env from the SDK subprocess |
+| Install failures | Installer Failure Transparency — cross-IDE error taxonomy + 12×4 test matrix |
+
+If you cannot write a one-line architectural scope, the cluster is wrong.
+
+## The standardized redirect comment
+
+Use this exact phrasing on every child closure. Consistency lets contributors recognize the pattern at a glance and keeps the audit trail searchable.
+
+```text
+Consolidating into #<MASTER> (plan-XX). The root cause and fix sequencing are tracked there alongside the rest of the cluster — please follow that issue for progress.
+```
+
+Close as `not planned` (not `completed`) — the child was a symptom, not a unit of work.
+
+## GitHub CLI primitives
+
+Resolve repo:
+
+```bash
+repo_json=$(gh repo view --json owner,name)
+owner=$(jq -r '.owner.login // .owner.name' <<<"$repo_json")
+repo=$(jq -r '.name' <<<"$repo_json")
+```
+
+List all open issues (the read-everything pass). Two gotchas:
+- `gh issue list --json comments` returns only a count placeholder, not the comment bodies. You must fetch comments per issue with `gh issue view <N> --json comments`.
+- Any explicit `--limit` silently truncates if the backlog is larger. Always check the total open count first.
+
+```bash
+# 1. Confirm total — never trust an arbitrary --limit.
+# Note: GitHub's REST API treats PRs as issues, so .open_issues_count
+# from /repos/{owner}/{repo} is actually issues + PRs. Use the search
+# API to get the issue-only count.
+total=$(gh api "search/issues?q=repo:$owner/$repo+is:issue+is:open" --jq '.total_count')
+echo "Open issues: $total"
+
+# 2. List bodies (set --limit at or above the true total)
+gh issue list --state open --limit "$total" \
+  --json number,title,body,labels,author,createdAt
+
+# 3. For each issue, fetch its full comment thread
+for n in $(gh issue list --state open --limit "$total" --json number --jq '.[].number'); do
+  echo "=== Issue #$n ==="
+  gh issue view "$n" --json comments \
+    --jq '.comments[] | "\(.author.login) (\(.createdAt)): \(.body)"'
+done
+```
+
+If `total > 1000`, paginate via the REST API: `gh api "repos/$owner/$repo/issues?state=open&per_page=100&page=N"` looped until the result array is empty (note this includes PRs, so filter `select(.pull_request|not)`).
+
+Open a plan master:
+
+```bash
+gh issue create \
+  --title "[plan-02] Spawn-Contract Templating — canonical \${CLAUDE_PLUGIN_ROOT} resolution across all hosts" \
+  --body-file plans/02-spawn-contract-templating.md \
+  --label plan,plan-02
+```
+
+Post the consolidation comment + close the child:
+
+```bash
+gh issue comment <CHILD> --body "Consolidating into #<MASTER> (plan-XX). The root cause and fix sequencing are tracked there alongside the rest of the cluster — please follow that issue for progress."
+gh issue close <CHILD> --reason "not planned"
+```
+
+Append a "Round N" triage comment to a master:
+
+```bash
+gh issue comment <MASTER> --body "$(cat <<'EOF'
+**Round N consolidation**
+
+- #<CHILD> (<one-line symptom>) folded into this plan as <classification>.
+
+Proposed fix: <1–3 line sketch>.
+
+Adds matrix cell: <host/IDE/shell combination>.
+EOF
+)"
+```
+
+Verify final state:
+
+```bash
+gh issue list --state open --json number,title \
+  | jq -r '.[] | "\(.number)\t\(.title)"'
+```
+
+Output should be exactly the plan masters.
+
+## Plan master body template
+
+Save as `plans/0X-<slug>.md` and use as `--body-file` for the master issue.
+
+```markdown
+# [plan-XX] <Architectural Defect> — <one-line scope>
+
+## Defect
+
+<One paragraph: what is structurally broken, why it produces the observed family of symptoms.>
+
+## Children
+
+- #N — <symptom one-liner>
+- #N — <symptom one-liner>
+- ...
+
+## Fix sequence
+
+1. <First architectural change — bounded, reviewable>
+2. <Second>
+3. ...
+
+## Test matrix
+
+| Axis A | Axis B | Required behavior |
+|---|---|---|
+| ... | ... | ... |
+
+The matrix lives in CI. A future regression must fail CI before a user can file.
+
+## Out of scope
+
+<What this plan deliberately does not cover, with pointers to other plan masters.>
+```
+
+## Health checks
+
+Run periodically against the plan masters to catch the failure modes.
+
+- **Graveyard master:** master issue has accumulated 5+ "Round N" comments without a shipping PR. The plan needs a forcing PR or it must be split.
+- **Over-broad master:** the children's fixes cannot fit one PR. Split into two plans with narrower scope.
+- **Surface-clustered master:** the children share a topic but not a fix. Re-cluster by root cause; some children belong to different plans.
+- **Drift between issue and doc:** the plan master body and `plans/0X-*.md` disagree. Pick one as canonical (the doc) and regenerate the issue body from it.
+
+## Stop conditions
+
+For a cluster pass: stop when `gh issue list --state open` returns exactly the masters.
+
+For a triage: stop when the new child is closed and the master has a Round-N entry.
+
+For a bundle: stop when the PR is merged and every listed child is auto-closed by `Closes #N`.
+
+## Failure modes worth refusing
+
+- **Premature clustering** before reading every issue body in full. Don't.
+- **Closing children before the master is open.** Children must always have a redirect target.
+- **Using the redirect comment for issues that aren't symptoms** (e.g. genuine feature requests with no shared root cause). Those stay open or get their own track.
+- **Closing a master before every listed child is shipped.** The master is the contract; closing it early breaks the audit trail.

package/plugin/skills/pathfinder/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: pathfinder
+description: Map a codebase into feature-grouped flowcharts, identify duplicated concerns across features, and propose a unified architecture. Use when asked to "find the ideal path," unify duplicated systems, or audit architecture before a refactor. Emits a proposed unified flowchart plus per-system /make-plan prompts.
+---
+
+# Pathfinder
+
+You are an ORCHESTRATOR. Map the codebase into feature-grouped flowcharts, identify duplicated concerns, propose the simplest unified architecture, and hand off per-system plans to `/make-plan`.
+
+You do not write implementation code. You produce diagrams, a duplication report, a proposed unified flowchart, and handoff prompts.
+
+## Delegation Model
+
+Use subagents for *discovery and extraction* (file reading, flow tracing, grep, diagramming). Keep *synthesis* (deciding feature boundaries, picking unification strategies, final flowchart) with the orchestrator. Reject subagent reports that lack source citations and redeploy.
+
+### Subagent Reporting Contract (MANDATORY)
+
+Each subagent response must include:
+1. Sources consulted — exact file paths and line ranges read
+2. Concrete findings — exact function names, call sites, data flow
+3. Mermaid diagram(s) with nodes labeled by `file:line`
+4. Confidence note + known gaps
+
+## Output Artifacts
+
+All artifacts go in `PATHFINDER-<YYYY-MM-DD>/` at repo root:
+- `00-features.md` — feature inventory with boundaries
+- `01-flowcharts/<feature>.md` — one Mermaid flowchart per feature
+- `02-duplication-report.md` — cross-cutting duplicated concerns with evidence
+- `03-unified-proposal.md` — proposed unified architecture + Mermaid
+- `04-handoff-prompts.md` — copy-pasteable `/make-plan` prompts per unified system
+
+## Phases
+
+### Phase 0: Feature Discovery (ALWAYS FIRST)
+
+Deploy ONE "Feature Discovery" subagent to:
+1. Walk the source tree (not built artifacts) and read top-level README / CLAUDE.md
+2. Propose feature boundaries based on directory structure, import graph, and naming
+3. Return a flat list of features with: name, entry points (file:line), core files, brief purpose
+
+Orchestrator reviews the proposal, adjusts boundaries if needed, writes `00-features.md`. Do NOT fan out until feature boundaries are approved.
+
+### Phase 1: Per-Feature Flowcharts (FAN OUT)
+
+Deploy ONE "Flowchart" subagent per feature in parallel. Each receives only its feature's scope. Each must:
+1. Trace the feature's primary happy path from entry point to terminal state
+2. Identify side effects (DB writes, HTTP calls, file I/O, process spawns)
+3. Note error and fallback branches but do not let them dominate the diagram
+4. Produce a Mermaid `flowchart TD` with every node labeled `Name<br/>file:line`
+5. List external dependencies (other features it calls into) at the bottom
+
+Orchestrator writes each flowchart to `01-flowcharts/<feature>.md`. Reject any diagram missing `file:line` labels.
+
+### Phase 2: Duplication Hunt
+
+Deploy TWO subagents in parallel:
+
+**"Within-Feature Duplication"** subagent:
+- For each feature, find repeated code/logic patterns inside the feature only
+- Report only duplications worth consolidating (ignore trivial repetition)
+
+**"Cross-Feature Duplication"** subagent:
+- Compare flowcharts across features for concerns that appear in multiple places
+- Examples of what to look for: multiple capture paths, parallel queue implementations, duplicated storage/migration code, repeated agent scaffolding, parallel parsing layers
+- For each duplication, report: (a) the concern, (b) every location with `file:line`, (c) why they diverged, (d) whether the divergence is legitimate specialization or accidental
+
+Orchestrator synthesizes both into `02-duplication-report.md`. Every duplication claim must cite ≥2 `file:line` locations.
+
+### Phase 3: Unified Proposal (ORCHESTRATOR)
+
+The orchestrator writes `03-unified-proposal.md` itself — do not delegate synthesis.
+
+For each duplicated concern from Phase 2 that is NOT legitimate specialization:
+1. Propose the simplest unified design (one path, one store, one handler — whatever applies)
+2. Name the consolidated component and its single entry point
+3. Show what each old call site becomes
+4. Call out any loss of capability and whether it's acceptable
+
+End the document with ONE combined Mermaid flowchart showing the proposed unified system. Nodes still labeled with target `file:line` (new or existing) where knowable.
+
+**Anti-patterns to reject in your own proposal:**
+- Adding a new abstraction layer "for flexibility"
+- Keeping both old paths behind a feature flag
+- Introducing a registry/factory when a switch statement suffices
+- Preserving divergent behavior "just in case"
+
+### Phase 4: Per-System Handoff Prompts
+
+For each unified system in the proposal, write a ready-to-run `/make-plan` prompt to `04-handoff-prompts.md`. Each prompt must:
+1. State the target unified component and its single entry point
+2. List the exact call sites to rewrite (from Phase 2 evidence)
+3. Cite the relevant flowchart file from `01-flowcharts/`
+4. Include anti-pattern guards specific to this system
+
+Format each as a fenced code block the user can copy directly into `/make-plan`.
+
+## Key Principles
+
+- **Evidence over intuition** — every diagram node and duplication claim cites `file:line`
+- **Current state before ideal state** — Phases 0–2 describe what IS; Phase 3 describes what SHOULD BE
+- **Simplest unification wins** — prefer deletion over abstraction; prefer one path over configurable paths
+- **Specialization is not duplication** — two components serving different trust models or data sources are legitimate even if their code looks similar
+- **Handoff, don't implement** — Pathfinder ends at plan prompts; `/make-plan` and `/do` take it from there
+
+## Failure Modes to Prevent
+
+- Drawing flowcharts from memory instead of source — redeploy subagent with grep evidence requirement
+- Proposing unification of legitimately specialized components — re-examine trust/data-source divergence
+- Handoff prompts that lack concrete call sites — rewrite with Phase 2 evidence
+- Skipping Phase 0 boundary review — fanning out on bad feature boundaries wastes all of Phase 1