keepmind 1.0.0

package/plugin/skills/smart-explore/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: smart-explore
+description: Token-optimized structural code search using tree-sitter AST parsing. Use instead of reading full files when you need to understand code structure, find functions, or explore a codebase efficiently.
+---
+
+# Smart Explore
+
+Structural code exploration using AST parsing. **This skill overrides your default exploration behavior.** While this skill is active, use smart_search/smart_outline/smart_unfold as your primary tools instead of Read, Grep, and Glob.
+
+**Core principle:** Index first, fetch on demand. Give yourself a map of the code before loading implementation details. The question before every file read should be: "do I need to see all of this, or can I get a structural overview first?" The answer is almost always: get the map.
+
+## Your Next Tool Call
+
+This skill only loads instructions. You must call the MCP tools yourself. Your next action should be one of:
+
+```
+smart_search(query="<topic>", path="./src")    -- discover files + symbols across a directory
+smart_outline(file_path="<file>")              -- structural skeleton of one file
+smart_unfold(file_path="<file>", symbol_name="<name>")  -- full source of one symbol
+```
+
+Do NOT run Grep, Glob, Read, or find to discover files first. `smart_search` walks directories, parses all code files, and returns ranked symbols in one call. It replaces the Glob → Grep → Read discovery cycle.
+
+## 3-Layer Workflow
+
+### Step 1: Search -- Discover Files and Symbols
+
+```
+smart_search(query="shutdown", path="./src", max_results=15)
+```
+
+**Returns:** Ranked symbols with signatures, line numbers, match reasons, plus folded file views (~2-6k tokens)
+
+```
+-- Matching Symbols --
+  function performGracefulShutdown (services/infrastructure/GracefulShutdown.ts:56)
+  function httpShutdown (services/infrastructure/HealthMonitor.ts:92)
+  method WorkerService.shutdown (services/worker-service.ts:846)
+
+-- Folded File Views --
+  services/infrastructure/GracefulShutdown.ts (7 symbols)
+  services/worker-service.ts (12 symbols)
+```
+
+This is your discovery tool. It finds relevant files AND shows their structure. No Glob/find pre-scan needed.
+
+**Parameters:**
+
+- `query` (string, required) -- What to search for (function name, concept, class name)
+- `path` (string) -- Root directory to search (defaults to cwd)
+- `max_results` (number) -- Max matching symbols, default 20, max 50
+- `file_pattern` (string, optional) -- Filter to specific files/paths
+
+### Step 2: Outline -- Get File Structure
+
+```
+smart_outline(file_path="services/worker-service.ts")
+```
+
+**Returns:** Complete structural skeleton -- all functions, classes, methods, properties, imports (~1-2k tokens per file)
+
+**Skip this step** when Step 1's folded file views already provide enough structure. Most useful for files not covered by the search results.
+
+**Parameters:**
+
+- `file_path` (string, required) -- Path to the file
+
+### Step 3: Unfold -- See Implementation
+
+Review symbols from Steps 1-2. Pick the ones you need. Unfold only those:
+
+```
+smart_unfold(file_path="services/worker-service.ts", symbol_name="shutdown")
+```
+
+**Returns:** Full source code of the specified symbol including JSDoc, decorators, and complete implementation (~400-2,100 tokens depending on symbol size). AST node boundaries guarantee completeness regardless of symbol size — unlike Read + agent summarization, which may truncate long methods.
+
+**Parameters:**
+
+- `file_path` (string, required) -- Path to the file (as returned by search/outline)
+- `symbol_name` (string, required) -- Name of the function/class/method to expand
+
+## When to Use Standard Tools Instead
+
+Use these only when smart_* tools are the wrong fit:
+
+- **Grep:** Exact string/regex search ("find all TODO comments", "where is `ensureWorkerStarted` defined?")
+- **Read:** Small files under ~100 lines, non-code files (JSON, markdown, config)
+- **Glob:** File path patterns ("find all test files")
+- **Explore agent:** When you need synthesized understanding across 6+ files, architecture narratives, or answers to open-ended questions like "how does this entire system work end-to-end?" Smart-explore is a scalpel — it answers "where is this?" and "show me that." It doesn't synthesize cross-file data flows, design decisions, or edge cases across an entire feature.
+
+For code files over ~100 lines, prefer smart_outline + smart_unfold over Read.
+
+## Workflow Examples
+
+**Discover how a feature works (cross-cutting):**
+
+```
+1. smart_search(query="shutdown", path="./src")
+   -> 14 symbols across 7 files, full picture in one call
+2. smart_unfold(file_path="services/infrastructure/GracefulShutdown.ts", symbol_name="performGracefulShutdown")
+   -> See the core implementation
+```
+
+**Navigate a large file:**
+
+```
+1. smart_outline(file_path="services/worker-service.ts")
+   -> 1,466 tokens: 12 functions, WorkerService class with 24 members
+2. smart_unfold(file_path="services/worker-service.ts", symbol_name="startSessionProcessor")
+   -> 1,610 tokens: the specific method you need
+Total: ~3,076 tokens vs ~12,000 to Read the full file
+```
+
+**Write documentation about code (hybrid workflow):**
+
+```
+1. smart_search(query="feature name", path="./src")    -- discover all relevant files and symbols
+2. smart_outline on key files                           -- understand structure
+3. smart_unfold on important functions                  -- get implementation details
+4. Read on small config/markdown/plan files             -- get non-code context
+```
+
+Use smart_* tools for code exploration, Read for non-code files. Mix freely.
+
+**Exploration then precision:**
+
+```
+1. smart_search(query="session", path="./src", max_results=10)
+   -> 10 ranked symbols: SessionMetadata, SessionQueueProcessor, SessionSummary...
+2. Pick the relevant one, unfold it
+```
+
+## Token Economics
+
+| Approach | Tokens | Use Case |
+|----------|--------|----------|
+| smart_outline | ~1,000-2,000 | "What's in this file?" |
+| smart_unfold | ~400-2,100 | "Show me this function" |
+| smart_search | ~2,000-6,000 | "Find all X across the codebase" |
+| search + unfold | ~3,000-8,000 | End-to-end: find and read (the primary workflow) |
+| Read (full file) | ~12,000+ | When you truly need everything |
+| Explore agent | ~39,000-59,000 | Cross-file synthesis with narrative |
+
+**4-8x savings** on file understanding (outline + unfold vs Read). **11-18x savings** on codebase exploration vs Explore agent. The narrower the query, the wider the gap — a 27-line function costs 55x less to read via unfold than via an Explore agent, because the agent still reads the entire file.
+
+## Language Support
+
+Smart-explore uses **tree-sitter AST parsing** for structural analysis. Unsupported file types fall back to text-based search.
+
+### Bundled Languages
+
+| Language | Extensions |
+|----------|-----------|
+| JavaScript | `.js`, `.mjs`, `.cjs` |
+| TypeScript | `.ts` |
+| TSX / JSX | `.tsx`, `.jsx` |
+| Python | `.py`, `.pyw` |
+| Go | `.go` |
+| Rust | `.rs` |
+| Ruby | `.rb` |
+| Java | `.java` |
+| C | `.c`, `.h` |
+| C++ | `.cpp`, `.cc`, `.cxx`, `.hpp`, `.hh` |
+
+Files with unrecognized extensions are parsed as plain text — `smart_search` still works (grep-style), but `smart_outline` and `smart_unfold` will not extract structured symbols.
+
+### Custom Grammars (`.claude-mem.json`)
+
+You can register additional tree-sitter grammars for file types not in the bundled list. Create or update `.claude-mem.json` in your project root:
+
+```json
+{
+  "grammars": {
+    "solidity": {
+      "package": "tree-sitter-solidity",
+      "extensions": [".sol"],
+      "query": "solidity-query.scm"
+    }
+  }
+}
+```
+
+Each key is a language name. `package` is the npm package of the tree-sitter grammar and `extensions` lists the file extensions it covers; the package must be installed in the project's `node_modules` (`npm install tree-sitter-solidity`). `query` (optional) is a path, relative to the config file, to a tree-sitter query whose captures (`@func`, `@cls`, `@method`, `@iface`, `@enm`, `@struct_def`, `@imp`) extract symbols. Without `query`, a minimal generic pattern is used — it only matches grammars that define `function_declaration`/`class_declaration` node types, and query compilation fails silently (0 symbols) for grammars that lack them, so a custom query is effectively required for most languages. Once registered, `smart_outline` and `smart_unfold` parse those extensions structurally instead of falling back to plain text.
+
+### Markdown Special Support
+
+Markdown files (`.md`, `.mdx`) receive special handling beyond the generic plain-text fallback:
+
+- **`smart_outline`** — extracts headings (`#`, `##`, `###`) as the symbol tree. Use it to navigate long documents without reading the full file.
+- **`smart_search`** — searches within code fences as well as prose, so queries for function names inside ` ```ts ``` ` blocks work as expected.
+- **`smart_unfold`** — expands heading sections rather than function bodies; each section up to the next same-level heading is returned as a chunk.
+- **Frontmatter** — YAML frontmatter (lines between leading `---` delimiters) is included in `smart_outline` output under a synthetic `frontmatter` symbol so metadata like `title:` and `description:` is visible without reading the whole file.

package/plugin/skills/standup/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: standup
+version: 1.0.0
+description: Facilitate a read-only standup across git worktrees, branches, or PRs to compare changes and produce one consolidation plan.
+allowed-tools:
+  - Bash
+  - Read
+  - Edit
+  - Task
+  - AskUserQuestion
+---
+
+# standup — facilitate a group chat between branch-agents
+
+You're the **facilitator**. Each of the user's git worktrees (and any PRs they
+pick) joins a shared markdown chat as its own agent, and the agents reconcile
+their scattered work into ONE consolidated worktree. You convene the room, run
+the conversation in rounds, and carry the outcome back — the reconciling happens
+in the chat, between the agents.
+
+The room is one shared file (default `~/.claude-mem/STANDUP.md`): YAML front
+matter holds the `goal` + `prompt`; the body is the transcript. Writes are
+atomically locked, so agents speak at once. It is **read-only** — agents decide
+how the merge *should* go; nobody commits or merges inside the room. Real git
+work happens afterward via `/do`.
+
+## 1. Fill the room
+
+Two ways, mixable:
+
+- **By recency** (common) — worktrees active in a window:
+  ```bash
+  node "${CLAUDE_SKILL_DIR}/standup.mjs" worktrees --since <1h|4h|24h|7d|all> --json
+  ```
+  Active = a commit *or* an uncommitted/staged/untracked edit in the window. If
+  the user didn't name a window, offer 1h / 4h / 24h / 7d / all.
+
+- **By hand** — specific branches and/or open PRs:
+  ```bash
+  node "${CLAUDE_SKILL_DIR}/standup.mjs" worktrees --json   # local branches
+  node "${CLAUDE_SKILL_DIR}/standup.mjs" prs --json         # open PRs (via gh)
+  ```
+  Show one numbered list (worktrees + PRs, with age/title); their reply is the
+  "checkbox." If `prs` errors (no `gh` / not GitHub), carry on worktrees-only.
+
+Zero or one candidate isn't a standup — say so, offer to widen, stop. Otherwise
+echo the roster to confirm before you start.
+
+## 2. Open the room
+
+Set a goal + prompt that invite a conversation, not one-shot status reports:
+
+```bash
+node "${CLAUDE_SKILL_DIR}/standup.mjs" open --force --agent facilitator \
+  --goal "Collapse these branches/PRs into ONE consolidated worktree: what each changed, where they overlap, which becomes the target, and the merge order." \
+  --prompt "Facilitated rounds. Round 1: introduce your branch and its state. Then resolve the conflicts the facilitator surfaces, round by round, until the room lands on one concrete plan (target worktree + merge order + conflict resolutions). Read-only: decide, don't merge. Register AGREE when you back the plan."
+```
+
+## 3. Run it as rounds
+
+You drive the turns — if agents watch-loop on their own the room can stall with
+nothing decided. Each agent speaks once per round (read → post → return); you
+read between rounds and bring back whoever's still needed.
+
+Spawned agents don't inherit `CLAUDE_SKILL_DIR`, so resolve it once and paste the
+real path into each brief:
+```bash
+echo "${CLAUDE_SKILL_DIR}"
+```
+
+**Round 1 — intros (everyone, one Task message so they run together).** Brief
+each:
+
+> You're **`<branch>`** (a PR is **`pr-<number>`**) in a standup group chat. Read
+> `<skill-dir>/agent-brief.md` and play your part by it. The room is
+> `~/.claude-mem/STANDUP.md`; speak with `node "<skill-dir>/standup.mjs" post …`,
+> catch up with `… read`. Get your bearings (`cd "<path>"`,
+> `git log --oneline origin/main..HEAD`, `git status --short`,
+> `git diff --stat origin/main...HEAD`; a PR uses `gh pr view/diff <number>`),
+> then post ONE turn: your branch, its real state, and how it should fold in.
+> Read-only. Then return.
+
+**Reconcile.** Once they've returned, `read` the room and list the **open
+items** — overlaps, conflicts, competing implementations, undecided
+target/order. None? Skip to the close.
+
+**Resolution rounds (cap ~4).** Per open item, re-spawn only the agents it
+implicates, with the specific question. Tell them to `read --since <their-name>`
+first, then post their position and `--agree` if convinced. `read` again, update
+the list. Repeat.
+
+**Close — you always write it.** Stop when the list is empty, you hit the cap, or
+an agent errors (note "didn't report," don't block). Then write the SUMMATION
+yourself — don't wait for an agent to volunteer. Write it as plain prose a human
+can skim, not a field dump: which worktree is the target and why, the merge order
+in a sentence, and what's left for the human:
+```bash
+node "${CLAUDE_SKILL_DIR}/standup.mjs" summation --agent facilitator \
+  --text "Build on <worktree> — it's the only one with real code. Layer <branch>'s changes on top, then drop in the doc-only branches; skip <empty branch>. Your call before it's safe: <the one or two real decisions>. Done when it all sits in <target> and builds clean."
+```
+
+## 4. Brief the human in plain language
+
+This is the payoff — don't hand them the raw SUMMATION, **translate it.** A human
+who didn't watch the room should understand the outcome without decoding paths,
+line counts, or commit hashes. Lead with the answer, then the few choices only
+they can make:
+
+- **What you found** — one plain line per branch: who has real code, who's just
+  docs, who's empty.
+- **The plan** — target + merge order in a sentence or two.
+- **Their call** — only the decisions a human must make (which implementation
+  wins, what to drop, anything risky), as concrete questions. Use
+  `AskUserQuestion` for the clear-cut ones.
+
+Keep git internals out unless they ask. Once they've settled the open calls, hand
+the plan to **`/do`** to perform the merges — don't merge anything yourself
+outside `/do`.
+
+## CLI
+
+```bash
+node "${CLAUDE_SKILL_DIR}/standup.mjs" <command> [--flags]
+```
+Defaults: agent = git branch, file = `~/.claude-mem/STANDUP.md`. Every write is
+atomically locked.
+
+| command | what it does |
+|---|---|
+| `worktrees [--since 4h] [--json]` | worktrees newest-first; `--since N{m,h,d,w}` keeps those active in the window |
+| `prs [--since 4h] [--json]` | open GitHub PRs (via `gh`) newest-first |
+| `open --goal "…" --prompt "…" [--force]` | create the room (`--force` rotates an old one aside) |
+| `join [--message "…"]` | add yourself + say Hello |
+| `post --message "…" [--agree "…"]` | append a turn |
+| `agree --deliverable "…"` | append an AGREE turn |
+| `watch [--timeout SEC] [--interval SEC]` | block until someone else posts, print it (exit 2 on timeout) |
+| `read [--tail N] [--since AGENT]` | print the chat (or only turns after AGENT's last) |
+| `status` | participants + AGREEs + consensus check |
+| `summation --text "…"` | write the SUMMATION, flip `status: agreed` |
+
+Each spawned agent plays its turns by **`agent-brief.md`** (bundled here) — the
+playbook for being one voice in the room.

package/plugin/skills/standup/agent-brief.md

@@ -0,0 +1,47 @@
+# You're in a standup — a group chat with the other branches
+
+You're one voice in a room of coding agents, each embodying a git branch or PR,
+all sharing **one markdown file** as the chat. This is a conversation, not a form
+to fill in: state your case, react, push back, change your mind — together the
+room lands on one plan.
+
+The point is in the file's front matter — a `goal` and a `prompt`. Read them
+first; trust them over this page. Usually: collapse everyone's work into one
+consolidated worktree.
+
+A **facilitator** runs the rounds and decides when it's done. So **you don't loop
+or wait** — you're brought in, you take your turn, you return (you'll likely be
+called back). Scheduling the next speaker and closing the room are the
+facilitator's job, not yours.
+
+## Your turn
+
+A tiny CLI to speak and listen (the facilitator gives you the path to
+`standup.mjs`):
+
+- `read` — the whole room; `read --since <you>` — just what's new. Always catch
+  up before you speak.
+- `post --message "…"` — say something; add `--agree "<deliverable>"` to back a
+  decision.
+- `status` — who's agreed so far.
+
+Each time you're brought in:
+
+1. **Catch up** — `read --since <you>` (or `read` on your first turn).
+2. **Say one substantive thing** — `post` one turn. First turn: introduce your
+   branch and its honest state (changed what, committed or not, merged or not,
+   where it overlaps). Later: engage the facilitator's question, address people
+   by `@branch`, agree or disagree *with reasons*, propose or concede. Move the
+   room toward one plan — don't restate status.
+3. **Take a position** — back the plan with `AGREE: <deliverable>`, quoting it
+   precisely (consensus = the *same* words). Not convinced? Say what would
+   convince you — that's the next round's open item.
+4. **Return** — then stop. Don't watch, loop, or write the summation; the
+   facilitator does that.
+
+## Stay in your lane
+
+Only ever speak as yourself — never post as another branch. **Read-only**:
+introspect, discuss, decide — do not commit, merge, push, or deploy. Execution
+happens later via `/do`, under the human's eye. A sharp, honest turn beats a long
+one.