memtrace-skills 0.7.10

package/plugins/memtrace-skills/skills/memtrace-first/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: memtrace-first
+description: "Always use first for indexed source-code repos before searching files, reading code for discovery, debugging, tracing flows, finding implementations, understanding behavior, or answering how code works. Do not use Grep, Glob, rg, find, or manual file browsing for code discovery when Memtrace is indexed. Zero results, missing languages, or partial-looking stats are not permission to grep; diagnose/reindex with Memtrace."
+---
+
+# Memtrace First
+
+## The Iron Law
+
+```
+IF THE REPO IS INDEXED IN MEMTRACE → USE MEMTRACE TOOLS FIRST.
+After a search hit, route to GRAPH tools (get_symbol_context, get_impact,
+analyze_relationships) — that's what Memtrace uniquely provides. Read source
+ONLY when you're about to edit or quote, and read only the bounded span
+returned by Memtrace (start_line .. end_line + small context). Do not
+Grep/Glob/Find to "locate" anything already in the graph, and do not read
+the whole file when Memtrace has given you exact lines.
+```
+
+Memtrace is the **memory layer** of the codebase, not a search engine that returns code. It has the full knowledge graph — every symbol, call, import, community, process, and API — with a time dimension. The point is to navigate that graph: who calls this, what's the blast radius, when did this change, what community is it part of. File tools are blind to all of that.
+
+**97% better accuracy. 83% fewer wasted tokens. No exceptions for what's in the graph.**
+
+## Value Tracking
+
+Do not print usage receipts in normal answers. Memtrace records tool usage, graph facts, file references, and estimated context avoided internally. Users can inspect that in the local UI's Value panel.
+
+## What Memtrace actually indexes
+
+Memtrace's hybrid search = **BM25 over symbol metadata** (name, signature, file_path, kind) **+ semantic vector search over embedded code bodies** (first ~1500 chars of every Function / Method / Class / Struct / Interface body), fused via Reciprocal Rank Fusion.
+
+The semantic side means **string literals, error messages, magic constants, log strings, and any text inside an indexed symbol's body are findable through `find_code`**. The body got embedded; the embedding catches it. You do NOT need `Grep` to hunt for `STRIPE_KEY_FOO_BAR` if it lives inside a function in your indexed codebase.
+
+## Zero results are not a grep license
+
+If Memtrace returns 0 results, or repository stats look incomplete, do **not**
+infer that a source subdirectory is outside the index. Diagnose through
+Memtrace:
+
+1. Call `list_indexed_repositories` and identify the repo root/repo_id.
+2. If the path is under that indexed repo root, keep using Memtrace.
+3. Retry with broader `find_code` terms and, when available, `file_path` filters
+   such as `ui/`, `memtrace-ui/`, `src/`, or the framework directory.
+4. If the language/path still appears missing, run `index_directory` on the repo
+   root with `incremental: true` (or ask before `clear_existing: true`).
+5. Report the indexing coverage problem instead of silently switching to grep.
+
+**Never say "the index only covers X, so grep is right" when the target path is
+inside the indexed repository.** That is an indexing freshness/coverage issue,
+not permission to abandon Memtrace.
+
+## The narrow exceptions where grep/glob are still right
+
+These are the ONLY cases where file tools beat memtrace:
+
+- **Files outside every indexed repo root.** Confirm this with
+  `list_indexed_repositories`; 0 search results or missing language stats do not
+  prove it. Vendored deps, system headers, and excluded dirs
+  (`.git`, `node_modules`, `target`, `dist`) are examples Memtrace cannot see.
+- **Non-source artifacts.** `.env`, `package.json`, build scripts, top-level `README.md`, raw config files. Memtrace indexes parseable code, not configuration text.
+- **Pure file-inventory questions.** "How many `*.test.ts` files exist", "list every Markdown file in `docs/`". You're asking for a file count, not a symbol search.
+- **Reading at a known path outside Memtrace.** For configs, docs, or non-source artifacts that Memtrace cannot index, file `Read` is fine. For source-code spans returned by Memtrace, read the precise line range (your harness's `Read` with offset/limit, or `get_source_window` if your harness lacks bounded reads). Do not whole-file Read when you have a span.
+
+For everything else inside the indexed repo, memtrace is the right tool.
+
+## The decision rule
+
+| Question Claude is asking | Right tool |
+|---|---|
+| "Where is symbol `foo` defined?" | `find_symbol(name="foo")` → then `get_symbol_context` for callers/callees/community, NOT a source read unless you're editing. |
+| "What calls `foo`?" | `get_symbol_context(name="foo")` → callers with file:line each. |
+| "How does authentication work?" | `find_code(query="authentication")` → `get_symbol_context` on the top hit, NOT a source read. |
+| "Find behavior X" with multi-word phrase (3+ words) | `find_code(verbatim)` first; if low confidence, fan out with identifier-shaped reshapes (camelCase / snake_case). |
+| "Find the function that uses `STRIPE_KEY_FOO_BAR`" | `find_code(query="STRIPE_KEY_FOO_BAR")` → semantic finds it inside any embedded body. |
+| "Where's that error message `'connection refused for tenant'`?" | `find_code(query="connection refused for tenant")` → semantic catches it. |
+| "What breaks if I change `foo`?" | `get_impact(name="foo")` → blast radius with file:line. |
+| "What changed in `auth.ts` last week?" | `get_evolution(file_path="auth.ts", from="7d ago")`. |
+| "List all `*.test.ts` files." | `Glob` (file inventory, not symbol search). |
+| "Find this string in my `.env`." | `Grep` (non-source artifact). |
+| "I'm about to edit `foo` — show me its source." | Bounded `Read(file_path, offset=start_line, limit=end_line-start_line+8)`, or `get_source_window` if your harness lacks bounded reads. Never whole-file. |
+| "Read config/doc file I already have the path of." | `Read` (non-source artifact, path is known). |
+
+## Parameter Types — Read This Before Calling Any Tool
+
+All memtrace MCP tools are **strictly typed**. Pass JSON numbers (not strings) for integer parameters.
+
+| Parameter | Correct | WRONG (fails with MCP error -32602) |
+|---|---|---|
+| `limit`, `min_size`, `depth`, `max_depth`, `last_n` | `limit: 20` | `limit: "20"` |
+| `repo_id`, `branch`, `name`, `symbol_name`, `query` | `repo_id: "my-repo"` | `repo_id: my-repo` (unquoted) |
+| `fuzzy`, `include_tests`, `invalidate` | `fuzzy: true` | `fuzzy: "true"` |
+
+If you see `failed to deserialize parameters: invalid type: string "N", expected usize`, remove the quotes from the number and retry.
+
+## Check Indexing First (Once Per Session)
+
+```
+mcp__memtrace__list_indexed_repositories
+```
+
+If the current repo appears → Memtrace is active. Follow this skill for ALL code tasks.
+If not indexed → offer to index with `mcp__memtrace__index_directory`, then follow this skill.
+
+## Task → Tool Map
+
+| What you need | Use instead of Grep/Glob/Read |
+|---|---|
+| Find a function / class / symbol | `find_symbol` or `find_code` |
+| Understand how something works | `get_symbol_context` (the default next step) |
+| Find all callers of a function | `get_symbol_context` (callers field) |
+| Find all callees / dependencies | `get_symbol_context` (callees field) |
+| Trace a request / execution path | `get_process_flow` |
+| Understand module structure | `list_communities` |
+| Find the most important symbols | `find_central_symbols` |
+| Find API endpoints | `find_api_endpoints` |
+| Find where an API is called | `find_api_calls` |
+| Debug a problem | `get_symbol_context` → `get_impact` → `get_evolution` |
+| What changed recently? | `get_changes_since` or `get_evolution` |
+| What breaks if I change X? | `get_impact` |
+| Cross-service / cross-repo calls | `get_service_diagram` or `get_api_topology` |
+| Dependency between two symbols | `find_dependency_path` |
+| What files change together? | `get_cochange_context` |
+| Architecture overview | `list_communities` + `find_central_symbols` |
+| About to edit / quote — need exact lines | Bounded `Read(file, offset=start_line, limit=N)` (preferred), or `get_source_window` for path-resolution parity |
+| About to choose between competing idioms (ternary vs if-else, arrow vs fn-decl, const vs let, await vs `.then`) | `get_style_fingerprint(repo_id, file_path)` — empirical codebase norm; see `memtrace-style-fingerprint` workflow |
+
+## Standard Workflows
+
+### "How does X work?" / "Explain X"
+1. `find_symbol` or `find_code` → locate the symbol
+2. `get_symbol_context` → callers, callees, community, processes (this usually answers "how it works")
+3. `get_process_flow` (if it's a process/request path)
+4. Only if you need to quote source: bounded `Read` at start_line..end_line, or `get_source_window`
+
+### Debugging "X is broken"
+1. `find_symbol` → locate the broken thing
+2. `get_symbol_context` → understand its role
+3. `get_impact` → blast radius (what else breaks)
+4. `get_evolution` → what changed recently (mode: `recent`)
+5. `get_changes_since` → confirm timing vs incident
+
+### "Where is X defined / called?"
+1. `find_symbol` with `fuzzy: true`
+2. `get_symbol_context` for full caller/callee map
+3. Only if you need source text: bounded `Read` at start_line..end_line, or `get_source_window`
+
+### Before any code modification
+1. `find_symbol` → confirm you have the right target
+2. `get_symbol_context` → understand full context
+3. `get_impact` → know blast radius before touching anything
+4. `get_style_fingerprint(repo_id, file_path=<file>)` → match the codebase's empirical idiom (ternary vs if-else, arrow vs fn-decl, etc.) — see `memtrace-style-fingerprint` workflow for the full decision rule
+
+## Red Flags — STOP, Use Memtrace Instead
+
+You are violating this skill if you think:
+
+| Thought | Reality |
+|---|---|
+| "Let me grep for this" | `find_code` or `find_symbol` is faster and structurally aware |
+| "Let me glob for the file" | `find_symbol` returns exact location with context |
+| "Let me read the whole file" | `get_symbol_context` for the WHY (callers/callees/community); a bounded source read at start_line..end_line for the WHAT |
+| "It's just a quick search" | Grep has no understanding of call graphs, communities, or time |
+| "I don't know if it's indexed" | Check with `list_indexed_repositories` first — takes 1 second |
+| "Memtrace returned 0 results" | Broaden the Memtrace query, check repo_id/path coverage, then reindex if needed |
+| "Stats only show Rust, but I need `ui/` or `memtrace-ui/`" | That is a coverage diagnostic. Reindex the repo root; do not grep source code. |
+| "The user didn't say to use Memtrace" | User asked about the code. Repo is indexed. Use Memtrace. |
+| "This is a simple question" | Simple questions benefit most — one `find_symbol` vs 20 file reads |
+
+## When File Tools Are Still Correct
+
+Use Grep/Glob/Read ONLY for:
+- Non-source files or paths outside every indexed source repo
+- Files that are config, data, or docs (not source code symbols)
+- Repos or paths confirmed outside every Memtrace indexed root
+
+For source-code spans already located by Memtrace, use a **bounded** read —
+your harness's `Read(file, offset, limit)` with the returned `start_line` /
+`end_line`, or `get_source_window` if your harness lacks bounded reads. Do
+not read the whole file.
+
+Never use file tools as a **discovery** mechanism when Memtrace is available.
+
+## Skill Priority
+
+This skill is a **process skill** — it runs BEFORE any implementation or search skill.
+
+When this skill applies, it overrides default file-search behavior. Use the specific Memtrace sub-skills for deep detail on each tool:
+
+- Discovery → `memtrace-search`
+- Impact analysis → `memtrace-impact`
+- Temporal / change analysis → `memtrace-evolution`
+- Incident investigation → `memtrace-incident-investigation`
+- Architecture overview → `memtrace-codebase-exploration`
+- Refactoring → `memtrace-refactoring-guide`

package/plugins/memtrace-skills/skills/memtrace-fleet-coordination/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: memtrace-fleet-coordination
+description: "Use when you need to understand or act on fleet conflict resolution: what conflict class A/B/C means, how a Class C destructive overlap gets decided (by an agent judge or a human), how to be the judge (fleet_submit_verdict), how to read your directive after a decision, and how branch-scoping isolates fleets. Triggered by: 'two agents are changing the same thing', 'resolve this conflict', 'who should proceed', 'a decision is waiting', acting as a mediator between agents."
+---
+
+# Fleet Coordination
+
+How the fleet turns overlapping edits into a safe decision. Read
+`memtrace-fleet-first` for the publish→edit→record protocol; this skill is the
+*conflict resolution* half.
+
+## Conflict classes (what `fleet_record_episode` returns)
+
+| Class | Meaning | What to do |
+|---|---|---|
+| **A** | Additive, order-independent | Proceed. |
+| **B** | Non-destructive overlap with another agent's work | Re-read the shared symbols, then proceed. |
+| **C** | A **destructive** change (signature change / move / dead-code removal) overlaps another agent's work | A decision is needed — it does NOT auto-resolve. |
+
+Class is computed **only against agents on your branch** (`(repo, branch)`).
+Agents on other branches are never conflict peers.
+
+## The Class C decision loop
+
+When `fleet_record_episode` returns class C it also returns an `escalation_id` and
+(when mediation is on) a `mediation_request`. The decision is made by an **agent
+judge**, a **human**, or — only when provably safe — the **deterministic referee**.
+
+### Being the judge (the user's own agent does the judging — no API keys)
+
+The `mediation_request` bundles **every agent's `assignment`** plus the contested
+symbols. Read the *other* agent's task and decide on merit (including against your
+own change). Submit:
+
+```jsonc
+fleet_submit_verdict({
+  escalation_id: "01J…",
+  agent_id: "agent-a",
+  verdict: { "kind": "recommend", "winner": "agent-b",
+             "rationale": "the signature change is the wider contract; rebase the fix onto it",
+             "confidence": 0.8 }
+})
+```
+
+Verdict kinds: `reconcile {merge_plan}` · `recommend {winner, rationale, confidence}`
+· `defer_to_human {question}`.
+
+The referee then decides the outcome:
+- **Auto-apply** only when safe: the clear machine case, or ≥2 independent agents
+  agree — and **never** for a destructive *removal* (delete/move), which always
+  needs a human.
+- **Human confirm** — a recommendation is surfaced for one-click confirmation.
+- **Human required** — both sides destructive, agents disagree, or an agent
+  deferred → a person decides.
+
+### Reading your directive
+
+Poll `fleet_get_escalation({escalation_id, agent_id})` until `your_directive` ≠
+`wait`: `proceed` (you continue), `defer` (stand down / rebase onto the winner),
+`review` (read `resolution`).
+
+### Resolving as a human (or on a human's behalf via the dashboard)
+
+`fleet_resolve_escalation({escalation_id, resolution, winner})` records a human
+decision and clears the queue. Prefer the agent-judge path; use this for the
+genuine human-decision cases. `fleet_list_escalations({repo_id})` shows the
+"needs human" queue.
+
+## Why branch-scoping matters here
+
+A "winner / defer" only makes sense on a shared surface. Across branches, the
+loser can't defer (its branch needs the change too), so the fleet never escalates
+cross-branch — that's a merge-time concern git already owns. Keep your fleet to
+one session branch and conflicts stay real and resolvable.
+
+## Inspecting state
+
+`fleet_get_node_state({repo_id, node})` — recent episodes, active intents, dominant
+intent, and conflict density for one symbol. Use it to understand pressure on a
+hot symbol before you pile on.

package/plugins/memtrace-skills/skills/memtrace-fleet-first/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: memtrace-fleet-first
+description: "Always use FIRST when more than one coding agent works the same repo+branch at once (a 'fleet'), before reading code, planning a refactor, or making an edit. Triggered by: 'I'm about to edit X', 'rename Y across the codebase', joining a running fleet/session branch, coordinating with other agents, prose hand-offs. Do not grep for 'who else is touching this' and do not skip fleet_publish_intent because 'it's a small change'. Fleet coordination is branch-scoped: pass your session branch so your fleet coordinates and stays isolated from agents on other branches. Skip ONLY for genuinely solo sessions or pure docs-only edits where coordination has zero value."
+---
+
+# Fleet First
+
+The coordination layer for **fleets of coding agents** working the same repo at the
+same time. It stops agents from silently clobbering each other's edits, and turns
+unsafe overlaps into a clear decision instead of a merge-time surprise.
+
+## The Iron Law
+
+```
+IN A FLEET → FLEET TOOLS BEFORE EDITS. NO EXCEPTIONS.
+  1. fleet_publish_intent   (declare what you'll touch; get blast radius + conflicts)
+  2. edit                   (your normal edit loop)
+  3. fleet_record_episode   (classify A/B/C; if C, the loop resolves it)
+```
+
+A typed intent serializes to ~20 tokens; a prose "I'm going to change X" averages
+200+. A 10-agent fleet × 100 edits = tens of thousands of tokens saved per
+fleet-turn — and zero silent overwrites — when the protocol is followed.
+
+## A fleet = agents on ONE branch (always pass it)
+
+**Coordination is branch-scoped.** Two agents only coordinate when they're on the
+**same `(repo, branch)`**. The branch name is the fleet identifier: a *session
+branch* is how a group of agents opts into one coordinating fleet.
+
+- Working a session branch (`session/auth-revamp`)? Pass `branch` on **every**
+  fleet call. Your fleet coordinates together and stays isolated from agents on
+  other branches.
+- Omit `branch` only for the shared default pool (single, unnamed fleet).
+- Agents on **different** branches never conflict — git already isolates them, and
+  whether branches merge isn't guaranteed, so the fleet never reasons across them.
+
+```jsonc
+{ "repo_id": "myrepo", "branch": "session/auth-revamp",
+  "agent_id": "agent-a", "touched": ["auth::verify_token"],
+  "intent": {"refactor": {"pattern": "change_signature"}},
+  "assignment": "widen verify_token signature for pagination" }
+```
+
+Always include **`assignment`** — your natural-language task. When a conflict
+happens, that's what the judge (another agent) or a human reads to reconcile.
+
+## Check the fleet first (once per session)
+
+```
+fleet_status()        → live_intents, active_agents, pending_escalations, mediator_mode
+```
+
+If it responds, fleet coordination is active — follow this skill for every edit.
+An empty fleet is **not** permission to skip: it just means you're the first agent
+in this window.
+
+## The protocol, step by step
+
+1. **Before editing** — `fleet_preflight({repo_id, branch, agent_id, touched, intent})`
+   (read-only) or go straight to `fleet_publish_intent(...)`. You get the blast
+   radius, any overlapping live intents on your branch, and a `coordination` block
+   that may already suggest who owns a contested symbol.
+2. **Edit** — your normal loop.
+3. **After editing** — `fleet_record_episode({repo_id, branch, agent_id, touched, intent})`.
+   It returns a `conflict_class`:
+   - **A — proceed.** Additive, order-independent. Nothing to do.
+   - **B — re-read, then proceed.** You overlap non-destructively; re-read the
+     shared symbols so you build on current state.
+   - **C — a decision is needed.** A destructive change overlaps another agent's
+     work. This does **not** auto-resolve — see below.
+
+## Class C: the decision loop (read this)
+
+A Class C means two edit paths can't both land safely. `fleet_record_episode`
+returns an `escalation_id` and a `mediation_request` (when mediation is enabled).
+What happens next depends on who judges:
+
+- **You may be asked to judge.** The `mediation_request` carries **every agent's
+  assignment** — including the other side's. Read them and submit a verdict with
+  `fleet_submit_verdict({escalation_id, agent_id, verdict})`, where `verdict` is one
+  of:
+  - `{"kind":"reconcile","merge_plan":"…"}` — the changes combine; here's how.
+  - `{"kind":"recommend","winner":"<agent_id>","rationale":"…","confidence":0.0-1.0}` —
+    one path should continue.
+  - `{"kind":"defer_to_human","question":"…"}` — a real product call; ask a human.
+- **A human may decide** in the Fleet dashboard. Either way the outcome flows back
+  to you.
+- **Close YOUR loop**: poll `fleet_get_escalation({escalation_id, agent_id})` until
+  `your_directive` is no longer `wait`:
+  - `proceed` — you were chosen; continue.
+  - `defer` — another path won; stand down and rebase your work onto it.
+  - `review` — read the free-text `resolution`.
+
+The daemon is a deterministic referee: it never auto-applies a destructive
+*removal* (delete/move) without a human, and only auto-applies when it's safe (a
+clear machine case, or independent agent consensus). So the judge being wrong
+degrades to "a human reviews a suggestion," never a silent bad merge.
+
+## Routing — what do you need?
+
+| You're about to… | Do this |
+|---|---|
+| Start any edit in a fleet | `fleet_publish_intent` (declare it) — never skip |
+| Check before declaring | `fleet_preflight` (read-only "is the coast clear?") |
+| Finish an edit | `fleet_record_episode` (get A/B/C) |
+| Got a Class C as the judge | `fleet_submit_verdict` (reconcile/recommend/defer) |
+| Blocked on a Class C | poll `fleet_get_escalation` until `your_directive ≠ wait` |
+| See who's in the fleet | `fleet_status` (active_agents, pending decisions) |
+| Inspect a symbol's coordination state | `fleet_get_node_state` |
+
+## Parameter notes
+
+- Pass `intent` as JSON (externally-tagged, snake_case):
+  `{"refactor":{"pattern":"rename_symbol"}}`, `{"bug_fix":{"defect":"logic_error"}}`.
+  Destructive kinds: `refactor/change_signature`, `refactor/move_symbol`,
+  `cleanup/dead_code` — these are what trigger Class C over shared symbols.
+- `touched` is a list of qualified symbol identities (e.g. `"module::Symbol"`).
+- Always include `branch` (your session branch) and `assignment` (your task).
+
+## When to skip
+
+Skip the protocol only for a genuinely **solo** session (you're the only agent and
+no one else shares your branch) or **pure docs-only** edits where coordination has
+zero value. Everything else in a fleet goes through the protocol.

package/plugins/memtrace-skills/skills/memtrace-fleet-publish-intent/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: memtrace-fleet-publish-intent
+description: "Use to declare a structural intent BEFORE editing in a fleet — what symbols you'll touch and why — so other agents on your branch coordinate around you. Triggered by: 'I'm about to edit/rename/refactor X', starting any non-trivial edit while other agents share your repo+branch. Returns the graph blast radius, overlapping live intents on your branch, and a shift-left coordination/partition hint. Do not start editing shared symbols without publishing first."
+---
+
+## Overview
+
+`fleet_publish_intent` is step 1 of the fleet protocol: announce what you're about
+to touch so other agents on the **same `(repo, branch)`** coordinate around you.
+It's a typed, ~20-token declaration — not prose.
+
+## Call it
+
+```jsonc
+fleet_publish_intent({
+  repo_id: "myrepo",
+  branch:  "session/auth-revamp",      // your fleet's session branch
+  agent_id:"agent-a",
+  touched: ["auth::verify_token"],     // qualified symbol identities
+  intent:  {"refactor": {"pattern": "change_signature"}},
+  assignment: "widen verify_token signature for pagination"   // the alignment anchor
+})
+```
+
+You get back:
+- `impact_preview` — the real graph blast radius of the touched symbols.
+- `active_conflicts` — overlapping live intents **on your branch** (none from other
+  branches; coordination is branch-scoped).
+- `coordination` — a shift-left hint: `would_escalate`, a `suggested_partition`
+  (who should own a contested symbol), and advice to realign *before* you edit.
+
+## Intent kinds (JSON, snake_case, externally-tagged)
+
+- `{"refactor":{"pattern":"rename_symbol"|"change_signature"|"move_symbol"|"extract_function"|…}}`
+- `{"feature_add":{"surface":"new_symbol"|"new_endpoint"|…}}`
+- `{"bug_fix":{"defect":"logic_error"|"null_handling"|…}}`
+- `{"cleanup":{"kind":"dead_code"|"unused_import"|…}}`
+- `{"performance":{"axis":"latency"|…}}`, `{"security_fix":{"severity":"high"}}`,
+  `{"test_add":{"covers":[…]}}`, `"docs_only"`, `"exploratory"`
+
+**Destructive** kinds — `change_signature`, `move_symbol`, `cleanup/dead_code` —
+are what raise a Class C decision when they overlap another agent's work.
+
+## Rules
+
+- Always pass `branch` (your session branch) and `assignment` (your task).
+- Read-only check first? Use `fleet_preflight` (same inputs, no registration).
+- An empty `active_conflicts` is good — proceed and `fleet_record_episode` when done.

package/plugins/memtrace-skills/skills/memtrace-fleet-record-episode/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: memtrace-fleet-record-episode
+description: "Use AFTER an edit in a fleet to record it and get its conflict class (A/B/C) against agents on your branch. Triggered by: finishing an edit, 'I just changed X', completing a refactor step while other agents share your repo+branch. Returns conflict_class + replan_hint; a Class C returns an escalation_id and mediation_request that starts the decision loop. Do not finish a coordinated edit without recording it."
+---
+
+## Overview
+
+`fleet_record_episode` is step 3 of the fleet protocol: record the edit you just
+made and learn whether it collided with another agent on your branch.
+
+## Call it
+
+```jsonc
+fleet_record_episode({
+  repo_id: "myrepo",
+  branch:  "session/auth-revamp",
+  agent_id:"agent-a",
+  touched: ["auth::verify_token"],
+  intent:  {"refactor": {"pattern": "change_signature"}}
+})
+```
+
+## The result: conflict_class
+
+- **A → proceed.** Additive, order-independent.
+- **B → re-read, then proceed.** Non-destructive overlap; re-read the shared
+  symbols so you build on current state.
+- **C → a decision is needed.** A destructive change overlaps another agent's
+  work. The response includes:
+  - `escalation_id` — the decision's id.
+  - `mediation_request` — the judging task (every agent's `assignment` + the
+    contested symbols). If you're asked to judge, call `fleet_submit_verdict`.
+  - `next_action` — poll `fleet_get_escalation({escalation_id, agent_id})` until
+    `your_directive` ≠ `wait`, then `proceed` / `defer` / `review`.
+
+Class is computed **only against agents on your branch**. Agents on other branches
+never make your edit a Class C.
+
+## After recording
+
+- Class A/B → continue.
+- Class C → enter the decision loop (see `memtrace-fleet-coordination`). Don't keep
+  editing the contested symbols until your directive is `proceed`.
+- Review history with `fleet_query_episodes({repo_id, node?, conflict_class?})`.

package/plugins/memtrace-skills/skills/memtrace-fleet-resolve/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: memtrace-fleet-resolve
+description: "Use to act on a Class C decision: submit your verdict as an agent judge (fleet_submit_verdict), poll your own directive (fleet_get_escalation), see the needs-human queue (fleet_list_escalations), or record a human decision (fleet_resolve_escalation). Triggered by: 'a decision is waiting', 'who should proceed', being handed a mediation_request, acting as a mediator between two agents, or a human choosing a winner in the dashboard."
+---
+
+## Overview
+
+The tools that resolve a Class C conflict. The judging is done by the user's own
+agents (no API keys): an agent reads the bundle and submits a verdict; the daemon
+is the deterministic referee that decides the outcome and routes it back.
+
+## Submit a verdict (you are the judge)
+
+You were handed a `mediation_request` (from `fleet_record_episode`). Read **every
+agent's `assignment`** in it and decide on merit — including against your own
+change:
+
+```jsonc
+fleet_submit_verdict({
+  escalation_id: "01J…",
+  agent_id: "agent-a",
+  verdict: { "kind": "recommend", "winner": "agent-b",
+             "rationale": "wider contract; rebase the fix onto it", "confidence": 0.8 }
+})
+// kinds: reconcile {merge_plan} | recommend {winner, rationale, confidence} | defer_to_human {question}
+```
+
+The response tells you the `outcome` (`auto_apply` | `human_confirm` |
+`human_required` | `pending`) and `your_directive`.
+
+## Read your own directive (you are blocked)
+
+```jsonc
+fleet_get_escalation({ escalation_id: "01J…", agent_id: "agent-a" })
+// → your_directive: wait | proceed | defer | review
+```
+
+Poll until it's not `wait`. `proceed` = continue; `defer` = stand down and rebase
+onto the winner; `review` = read `resolution`.
+
+## Human paths
+
+- `fleet_list_escalations({repo_id})` — the per-repo "needs human" queue.
+- `fleet_resolve_escalation({escalation_id, resolution, winner})` — record a human
+  decision (pick which agent proceeds) and clear it. Prefer the agent-judge path;
+  use this for genuine human/product calls.
+
+## Safety the referee guarantees
+
+- A destructive **removal** (delete/move) is **never** auto-applied — always a human.
+- Auto-apply happens only for the clear-safe machine case or ≥2 agents agreeing on
+  a non-destructive resolution.
+- So a wrong verdict degrades to "a human reviews a suggestion," never a silent
+  bad merge.

package/plugins/memtrace-skills/skills/memtrace-graph/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: memtrace-graph
+description: "Always use for source-code architecture, important symbols, centrality, PageRank, bridge functions, communities, logical modules, chokepoints, service boundaries, or dependency path questions. Do not use Glob, find, tree, or directory browsing to infer architecture; Memtrace runs graph algorithms over the AST graph."
+---
+
+## Overview
+
+Graph algorithms that reveal the structural architecture of a codebase — community detection (Louvain), centrality ranking (PageRank), bridge symbol identification (Tarjan articulation points), shortest-path discovery, and execution flow tracing.
+
+All four algorithm tools (`find_central_symbols`, `find_bridge_symbols`, `find_dependency_path`, `list_communities`) run natively against the MemDB-backed knowledge graph — no Cypher required.
+
+## Quick Reference
+
+| Tool | Purpose |
+|------|---------|
+| `find_bridge_symbols` | Architectural chokepoints — symbols whose removal disconnects the graph (Tarjan articulation points) |
+| `find_central_symbols` | Most important symbols by **PageRank** (default) or degree centrality |
+| `find_dependency_path` | Shortest call/import path between two symbols (BFS over typed edges) |
+| `list_communities` | Louvain-detected logical modules/services |
+| `list_processes` | Execution flows: HTTP handlers, background jobs, CLI commands, event handlers |
+| `get_process_flow` | Trace a single process step-by-step |
+
+## Steps
+
+### 1. Understand the architecture
+
+Start with `list_communities` to see how the codebase is naturally partitioned into logical modules. Each community has a name, member count, and representative symbols.
+
+### 2. Find critical infrastructure
+
+Use `find_central_symbols` to identify the most important symbols:
+- `method: "pagerank"` — importance by link structure (default; same algorithm Google uses)
+- `method: "degree"` — importance by direct connection count
+- `limit` — how many to return
+
+The PageRank pass walks every CALLS / REFERENCES edge in the repo, distributes rank with the standard 0.85 damping factor, and converges on a stable ordering. The output is sorted by score descending, with each entry carrying `name`, `kind`, `file_path`, `score`, and the `in_degree`/`out_degree` it accumulated during the walk.
+
+### 3. Find architectural chokepoints
+
+Use `find_bridge_symbols` to find symbols that, if removed, would disconnect parts of the graph (Tarjan articulation points). These are:
+- **Single points of failure** — if they break, cascading failures occur
+- **Integration points** — good places for interfaces/contracts
+- **Refactoring targets** — often too much responsibility concentrated in one place
+
+### 4. Discover the path between two symbols
+
+Use `find_dependency_path` to answer "how does symbol A reach symbol B?" — returns the shortest call/import chain via BFS over typed edges. Useful for:
+- "Why does the auth handler depend on the database client?"
+- "How does this CLI command reach the logging subsystem?"
+- "Confirm symbol X actually transitively depends on Y."
+
+### 5. Trace execution flows
+
+Use `list_processes` to see all entry points (HTTP handlers, background jobs, CLI commands, event handlers).
+
+Use `get_process_flow` with a process name to trace a specific flow step-by-step — shows the full call chain from entry point through business logic to data access, ordered by the indexed `step` property on each STEP_IN_PROCESS edge.
+
+## Decision Points
+
+| Question | Tool |
+|----------|------|
+| "What are the main modules?" | `list_communities` |
+| "What are the most important functions?" | `find_central_symbols` with method=pagerank |
+| "Where are the bottlenecks?" | `find_bridge_symbols` |
+| "How does symbol A reach symbol B?" | `find_dependency_path` |
+| "How does a request flow through the system?" | `list_processes` → `get_process_flow` |
+| "What's the entry point for feature X?" | `list_processes`, then filter by name |