feat(claude): proper Claude Code plugin bundle + 30-skill cross-surface sync

.gitattributes

@@ -6,6 +6,11 @@ tests/fixtures/** text eol=lf
 # them before the lint runs.
 codex-plugin/skills/** text eol=lf
 cursor-plugin/skills/** text eol=lf
+claude-plugin/** text eol=lf
+# Force LF for the retained agent source of truth; the bundle byte-identity
+# test compares claude-plugin agents against these files and Windows checkout
+# otherwise rewrites them to CRLF.
+src/agents/claude_agents/** text eol=lf
 # Force LF for embedded Hermes plugin template assets — they are pulled into
 # the binary via include_str! and the generated-plugin snapshot test asserts
 # their exact bytes.

.gitignore

@@ -4,6 +4,7 @@
 .tracedecay
 .mcp.json
 !codex-plugin/.mcp.json
+!claude-plugin/.mcp.json
 .claude/
 .cursor/
 docs/superpowers

claude-plugin/.claude-plugin/marketplace.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "tracedecay",
+  "owner": {
+    "name": "ScriptedAlchemy"
+  },
+  "plugins": [
+    {
+      "name": "tracedecay",
+      "source": "./",
+      "description": "Semantic code intelligence, code graph, and project memory for Claude Code.",
+      "category": "productivity",
+      "homepage": "https://github.com/ScriptedAlchemy/tracedecay"
+    }
+  ]
+}

claude-plugin/.claude-plugin/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "tracedecay",
+  "version": "0.0.0",
+  "description": "Claude Code integration for TraceDecay semantic code intelligence: MCP server plus a `tracedecay tool` CLI fallback exposing the same tools when MCP is unavailable.",
+  "author": {
+    "name": "ScriptedAlchemy"
+  },
+  "homepage": "https://github.com/ScriptedAlchemy/tracedecay",
+  "repository": "https://github.com/ScriptedAlchemy/tracedecay",
+  "license": "MIT",
+  "keywords": [
+    "code-graph",
+    "mcp",
+    "code-search",
+    "token-savings",
+    "call-graph",
+    "code-health"
+  ]
+}

claude-plugin/.mcp.json

@@ -0,0 +1,14 @@
+{
+  "mcpServers": {
+    "tracedecay": {
+      "type": "stdio",
+      "command": "tracedecay",
+      "args": [
+        "serve"
+      ],
+      "env": {
+        "TRACEDECAY_ENABLE_GLOBAL_DB": "1"
+      }
+    }
+  }
+}

claude-plugin/README.md

@@ -0,0 +1,39 @@
+# TraceDecay for Claude Code
+
+This plugin bundles the TraceDecay MCP server, a suite of workflow skills, and
+lifecycle hooks for code-graph, impact, recall, and context-saving workflows in
+Claude Code.
+
+## What it ships
+
+- **MCP server** (`.mcp.json`): the `tracedecay` stdio server exposing the code
+  graph, search, call-graph, impact, memory, and session-recall tools.
+- **Skills** (`skills/`): one skill per common workflow — searching for code,
+  reading code cheaply, mapping architecture, impact analysis, reviewing diffs,
+  recalling project memory and session context, and more. Claude Code
+  auto-discovers each `SKILL.md` by its `name`/`description` frontmatter and
+  loads the body only when the workflow matches.
+- **Lifecycle hooks** (`hooks/hooks.json`): `SessionStart`,
+  `UserPromptSubmit`, `Stop`, `PreToolUse`, and `PostToolUse` handlers that
+  inject index status and tool-routing steering, keep the graph/session store
+  warm, and redirect explore-agent calls toward the tracedecay tools.
+
+## Install
+
+Install the plugin (and register its hooks and MCP server) with:
+
+```
+tracedecay install --agent claude
+```
+
+The installer resolves the absolute path of the `tracedecay` binary and writes
+it into the managed hooks, so the plugin works even when tracedecay lives on a
+path with spaces.
+
+## CLI fallback
+
+Every MCP tool is also available from the shell as `tracedecay tool <name>`
+(`tracedecay tool` lists all tools; `tracedecay tool <name> --help` shows a
+tool's parameters). The bundled skills and injected steering point agents at
+that CLI fallback when the MCP transport errors or times out, instead of
+querying `.tracedecay` databases directly or giving up on tracedecay.

claude-plugin/agents/code-explorer.md

@@ -0,0 +1,28 @@
+---
+name: code-explorer
+description: Read-only code exploration agent powered by the TraceDecay code graph. Use PROACTIVELY for codebase research — how/where/what questions, symbol lookup, callers/callees tracing, call chains, and impact analysis — whenever TraceDecay MCP tools are available. Also use to parallelize codebase research or isolate a deep exploration from the main thread. Never edits files.
+model: inherit
+tools: Read, Grep, Glob, mcp__tracedecay
+disallowedTools: mcp__tracedecay__tracedecay_str_replace, mcp__tracedecay__tracedecay_multi_str_replace, mcp__tracedecay__tracedecay_insert_at, mcp__tracedecay__tracedecay_insert_at_symbol, mcp__tracedecay__tracedecay_replace_symbol, mcp__tracedecay__tracedecay_ast_grep_rewrite, mcp__tracedecay__tracedecay_run_affected_tests, mcp__tracedecay__tracedecay_diagnostics, mcp__tracedecay__tracedecay_session_start, mcp__tracedecay__tracedecay_session_end, mcp__tracedecay__tracedecay_fact_store, mcp__tracedecay__tracedecay_fact_feedback, mcp__tracedecay__tracedecay_memory_status, mcp__tracedecay__tracedecay_lcm_compress, mcp__tracedecay__tracedecay_lcm_preflight, mcp__tracedecay__tracedecay_lcm_session_boundary, mcp__tracedecay__tracedecay_lcm_doctor
+---
+
+# Code explorer (read-only)
+
+You are a read-only exploration subagent. You investigate the repository and return findings; you never edit files or run mutating tools.
+
+## Method
+
+1. Start with `tracedecay_context` (add `keywords` for concepts). **Respect the per-project call budget shown in the tool description.** Pass `seen_node_ids` from each response to the next call's `exclude_node_ids`.
+2. Narrow with `tracedecay_search` / `tracedecay_find_exact_symbol` / `tracedecay_body` / `tracedecay_outline`.
+3. Trace with `tracedecay_callers` / `tracedecay_callees` / `tracedecay_call_chain`; assess reach with `tracedecay_impact`.
+4. Fall back to Grep/Read only for non-indexed content or after TraceDecay pinpoints files.
+
+## Rules
+
+- Read-only: never edit files, run test runners or diagnostics, or write memory. Mutating TraceDecay tools are disabled for this agent; do not attempt to work around that.
+- Do not spawn nested subagents unless explicitly asked.
+
+## Return
+
+- A concise answer plus the concrete files + qualified symbol names and key relationships found.
+- If any result includes a `tracedecay_metrics:` line, report the savings to the user.

claude-plugin/agents/code-health-auditor.md

@@ -0,0 +1,28 @@
+---
+name: code-health-auditor
+description: Read-only code-health audit agent powered by the TraceDecay code graph. Use PROACTIVELY when asked for a health audit, tech-debt report, code-quality scorecard, or the worst complexity, duplication, coupling, doc, and test-risk offenders. Also use to run a health audit in isolation or parallelize a large-repo review. Never edits files.
+model: inherit
+tools: Read, Grep, Glob, Skill, mcp__tracedecay
+disallowedTools: mcp__tracedecay__tracedecay_str_replace, mcp__tracedecay__tracedecay_multi_str_replace, mcp__tracedecay__tracedecay_insert_at, mcp__tracedecay__tracedecay_insert_at_symbol, mcp__tracedecay__tracedecay_replace_symbol, mcp__tracedecay__tracedecay_ast_grep_rewrite, mcp__tracedecay__tracedecay_run_affected_tests, mcp__tracedecay__tracedecay_diagnostics, mcp__tracedecay__tracedecay_session_start, mcp__tracedecay__tracedecay_session_end, mcp__tracedecay__tracedecay_fact_store, mcp__tracedecay__tracedecay_fact_feedback, mcp__tracedecay__tracedecay_memory_status, mcp__tracedecay__tracedecay_lcm_compress, mcp__tracedecay__tracedecay_lcm_preflight, mcp__tracedecay__tracedecay_lcm_session_boundary, mcp__tracedecay__tracedecay_lcm_doctor
+---
+
+# Code-health auditor (read-only)
+
+You are a read-only audit subagent. You score and rank code health and return findings; you never edit files, run the toolchain, or write memory.
+
+## Method
+
+1. Start with `tracedecay_health` (`details: true`) and let the weak dimensions drive the drill-down.
+2. Drill only into weak dimensions or explicit asks: complexity/size -> `tracedecay_complexity`, `tracedecay_gini`, `tracedecay_god_class`, `tracedecay_largest`, `tracedecay_hotspots`; structure -> `tracedecay_coupling`, `tracedecay_dependency_depth`, `tracedecay_dsm`, `tracedecay_circular`, `tracedecay_recursion`; quality -> `tracedecay_redundancy`, `tracedecay_doc_coverage`, `tracedecay_unsafe_patterns`, `tracedecay_test_risk`.
+3. Keep expensive scans scoped (`path`, `limit`, `max_pairs`) and stop once the ranked findings are actionable.
+4. If the `tracedecay:code-health` skill is available, follow its full workflow.
+
+## Rules
+
+- Read-only: never edit files, run test runners or diagnostics, write session baselines, or write memory. Mutating TraceDecay tools are disabled for this agent; do not attempt to work around that.
+- Keep `path`/`max_pairs` tight on `tracedecay_redundancy` (first call can be slow). Do not spawn nested subagents unless asked.
+
+## Return
+
+- The composite score, weak dimensions, ranked offenders, and a prioritized fix list with concrete files + qualified symbol names.
+- If any result includes a `tracedecay_metrics:` line, report the savings to the user.

claude-plugin/agents/session-historian.md

@@ -0,0 +1,29 @@
+---
+name: session-historian
+description: Read-only session-recall agent powered by TraceDecay's transcript index and LCM store. Use PROACTIVELY for "what did we decide/do/discuss previously" questions — message search, lossless session replay, summary-DAG drill-down, and durable fact search. Use to recover prior context without polluting the main thread. Never edits files or mutates memory.
+model: inherit
+tools: Read, Grep, Glob, Skill, mcp__tracedecay
+disallowedTools: mcp__tracedecay__tracedecay_str_replace, mcp__tracedecay__tracedecay_multi_str_replace, mcp__tracedecay__tracedecay_insert_at, mcp__tracedecay__tracedecay_insert_at_symbol, mcp__tracedecay__tracedecay_replace_symbol, mcp__tracedecay__tracedecay_ast_grep_rewrite, mcp__tracedecay__tracedecay_run_affected_tests, mcp__tracedecay__tracedecay_diagnostics, mcp__tracedecay__tracedecay_session_start, mcp__tracedecay__tracedecay_session_end, mcp__tracedecay__tracedecay_fact_feedback, mcp__tracedecay__tracedecay_memory_status, mcp__tracedecay__tracedecay_lcm_compress, mcp__tracedecay__tracedecay_lcm_preflight, mcp__tracedecay__tracedecay_lcm_session_boundary
+---
+
+# Session historian (read-only)
+
+You are a read-only recall subagent. You retrieve what past sessions said, did, and decided for this project; you never edit files, mutate memory, or run lifecycle tools.
+
+## Method
+
+1. Start with `tracedecay_message_search` (fast FTS over ingested transcripts; note the session ids on hits).
+2. Narrow with `tracedecay_lcm_grep` (scope/role/time filters), then replay with `tracedecay_lcm_load_session` (paginate via `after_store_id`, never dump whole sessions).
+3. Drill into summaries with `tracedecay_lcm_describe` / `tracedecay_lcm_expand` / `tracedecay_lcm_expand_query`; inspect the store with `tracedecay_lcm_status`.
+4. For durable decisions/facts, search `tracedecay_fact_store` (`action: "search"`, plus `"probe"`/`"reason"` when useful).
+5. If the `tracedecay:recalling-session-context` skill is available, follow its full ladder.
+
+## Rules
+
+- Read-only: use `tracedecay_fact_store` only with read actions (`search`, `probe`, `reason`, `related`, `get`, `list`) — never `add`, `update`, or `remove`. Use `tracedecay_lcm_doctor` only in check mode — never repair/clean modes. Other mutating TraceDecay tools are disabled for this agent; do not attempt to work around that.
+- Do not spawn nested subagents unless explicitly asked.
+
+## Return
+
+- A concise answer with the supporting quotes/decisions, each cited by session id + timestamp (and fact id where applicable).
+- If any result includes a `tracedecay_metrics:` line, report the savings to the user.

claude-plugin/commands/audit-safety.md

@@ -0,0 +1,18 @@
+---
+description: Audit the repo or a directory for ship-blocking risk, panic sites, risk markers, dead code, and untested high-risk symbols.
+argument-hint: "[path]"
+---
+
+# Audit safety
+
+Run a read-only ship-readiness sweep over the whole repo, or `$ARGUMENTS` if a directory was given. Report findings; do not fix them here.
+
+1. Panic & unsafe sites → `tracedecay_unsafe_patterns` (use `kinds` to narrow to `unwrap`/`unsafe`, `exclude_tests: true` for production-only, `path` to scope). Each hit carries file, line, kind, enclosing symbol, `in_test`.
+2. Unfinished work → `tracedecay_todos` (`kinds: ["FIXME","HACK","XXX","UNIMPLEMENTED"]`).
+3. Unreachable code → `tracedecay_dead_code` (`include_public: true` for workspace-internal audits) and `tracedecay_unused_imports`.
+4. Risky and untested → `tracedecay_test_risk`: high-complexity, high-fan-in symbols with weak coverage.
+5. Rank: production panic/unsafe in hot paths first (cross-check fan-in with `tracedecay_callers`), then UNIMPLEMENTED/HACK markers, then untested high-risk symbols, then dead code and imports.
+
+`unwrap`/`panic!` inside tests is normal — respect `exclude_tests`/`in_test` before flagging. An `unsafe { }` block is a review-attention site, not automatically a finding.
+
+Output: findings grouped Critical / Warning / Note with file + enclosing symbol, and a prioritized follow-up list. If any result includes a `tracedecay_metrics:` line, report the savings.

claude-plugin/commands/check-health.md

@@ -0,0 +1,18 @@
+---
+description: Check code health for the repo or a directory, including worst offenders and a prioritized fix list.
+argument-hint: "[path]"
+---
+
+# Check health
+
+Produce a read-only code-health scorecard for the whole repo, or `$ARGUMENTS` if a directory was given. Lead with the one composite signal, then drill only into the weak dimensions — don't run every tool by reflex.
+
+1. Composite signal → `tracedecay_health` (`details: true`, optional `path`): the 0–10000 score plus the 5-dimension breakdown (acyclicity, depth, equality, redundancy, modularity) and the `coverage_discipline` penalty. The weak dimensions choose the drill-downs.
+2. Inequality / god files → `tracedecay_gini` (`metric`, `scope`, optional `path`).
+3. Complexity & size offenders: `tracedecay_complexity`, `tracedecay_largest`, `tracedecay_god_class`, `tracedecay_hotspots`.
+4. Structure drill-downs matched to the weak dimension: acyclicity → `tracedecay_circular` + `tracedecay_recursion`; modularity → `tracedecay_dsm` + `tracedecay_coupling`; depth → `tracedecay_dependency_depth` + `tracedecay_inheritance_depth`.
+5. Duplication → `tracedecay_redundancy`; doc gaps → `tracedecay_doc_coverage`; panic sites → `tracedecay_unsafe_patterns`; test gaps → `tracedecay_test_risk`.
+
+This reports and prioritizes; it does not edit.
+
+Output: the composite score + weak dimensions, the worst offenders (complexity, duplication, god files, doc gaps, panic sites, test-risk), and a prioritized fix list. If any result includes a `tracedecay_metrics:` line, report the savings.

claude-plugin/commands/clean-dead-code.md

@@ -0,0 +1,14 @@
+---
+description: Find and safely remove dead code, unused imports, and duplication via the TraceDecay code graph.
+argument-hint: "[path]"
+---
+
+# Clean dead code
+
+Find and safely remove dead code across the whole repo, or `$ARGUMENTS` if a directory was given.
+
+1. Discover with `tracedecay_dead_code` / `tracedecay_unused_imports` / `tracedecay_redundancy`; focused pass → `tracedecay_simplify_scan` (`files`).
+2. Before deleting anything, confirm zero real callers with `tracedecay_callers` / `tracedecay_rename_preview`. Be conservative with `pub` items (they may be used outside the indexed scope). Never delete a symbol whose callers/references are non-empty.
+3. Apply edits via the anchored primitives (`tracedecay_str_replace`, `tracedecay_multi_str_replace`, `tracedecay_replace_symbol`); verify with `tracedecay_diagnostics` and the affected tests (`tracedecay_run_affected_tests` / `tracedecay_affected`). Optionally bracket the cleanup with a `tracedecay_session_start` / `tracedecay_session_end` health delta.
+
+Output: removed/consolidated items and the before/after health or test result. If any result includes a `tracedecay_metrics:` line, report the savings.

claude-plugin/commands/compare-branches.md

@@ -0,0 +1,16 @@
+---
+description: Compare or search another git branch's code graph without switching your checkout.
+argument-hint: "[branch | base head]"
+---
+
+# Compare branches
+
+Interpret `$ARGUMENTS` as either a single target branch to compare against the current branch, or "<base> <head>" to diff two branches. If absent, start with `tracedecay_branch_list` and ask what to search or compare.
+
+1. What's tracked → `tracedecay_branch_list`.
+2. Search another branch → `tracedecay_branch_search` (`branch`, `query`).
+3. Compare branches → `tracedecay_branch_diff` (`base`, `head`, optional `file`, `kind`) — added / removed / changed symbols, read-only and never touching your checkout.
+
+Branch tracking is opt-in per branch. If a target branch isn't tracked, tell the user to run `tracedecay branch add <branch>` in the terminal first. A branch-fallback `WARNING` prefix means results came from the nearest tracked ancestor — surface that to the user.
+
+Output: the cross-branch search hits or the added/removed/changed symbol lists, with any branch-fallback warning surfaced. If any result includes a `tracedecay_metrics:` line, report the savings.

claude-plugin/commands/curate-memory.md

@@ -0,0 +1,17 @@
+---
+description: Curate, update, delete, or inspect TraceDecay memory facts and dashboard curation from an explicit slash workflow.
+argument-hint: "[subject]"
+---
+
+# Curate memory
+
+Interpret `$ARGUMENTS` as the fact, entity, query, or curation action to review. If absent, ask what memory scope to curate before mutating anything.
+
+1. Resolve scope: confirm the active project root/store with `tracedecay_active_project` before touching memory.
+2. Start read-only with `tracedecay_fact_store` (`action`: `search` / `list` / `get` / `probe` / `related` / `reason` / `contradict`) or `tracedecay_memory_status` (only when the user asks for counts/health, since it may repair vectors/banks). Open `tracedecay_dashboard` (`action: "start"`) only when the user wants visual curation.
+3. Inventory candidates into add, update, merge/dedupe, stale, contradiction, secret-like, and possible-delete buckets, keeping fact ids, source, trust, tags, and evidence with each.
+4. Apply narrowly with `tracedecay_fact_store` `action: "add"` / `"update"`. Prefer update/merge over removal when useful provenance should survive.
+5. Hard-delete guardrail: require explicit approval immediately before every `action: "remove"` or dashboard hard delete, showing fact id, content/source summary, reason, and a permanent-delete warning — unless the user already gave an exact deletion instruction. Deletion is permanent; there is no undo. Never store secrets, credentials, or PII.
+6. Verify read-only: re-run search/list/probe/get and report final facts changed, skipped, or still needing judgment.
+
+Output: memory facts inspected or changed, confirmations requested, and the final verification search/list result. If any result includes a `tracedecay_metrics:` line, report the savings.

claude-plugin/commands/draft-commit.md

@@ -0,0 +1,15 @@
+---
+description: Draft a commit message, PR description, or changelog from semantic changes; drafts text only and never commits or pushes.
+---
+
+# Draft commit
+
+Interpret `$ARGUMENTS` as the target (e.g. "pr", "changelog", a base ref, or "staged"). If absent, draft a commit message for the working-tree/staged changes.
+
+1. Commit message → `tracedecay_commit_context` (`staged_only`): changed symbols + file roles + recent commit style.
+2. PR description → `tracedecay_pr_context` (`base_ref`, `head_ref`): Summary / Impact / Tests.
+3. Release notes → `tracedecay_changelog` (`from_ref`, `to_ref`); sanity-check with `tracedecay_branch_diff`.
+
+This drafts text only — leave `git commit` / `gh pr create` to the user unless they explicitly ask.
+
+Output: the drafted commit / PR / changelog text. If any result includes a `tracedecay_metrics:` line, report the savings.