Merge pull request #248 from ScriptedAlchemy/feat/claude-plugin-bundle

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

Author: ScriptedAlchemy

.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.