From 26a65bd07879dcef0c1bd938097ea16b5dd9dcbd Mon Sep 17 00:00:00 2001 From: ScriptedAlchemy Date: Fri, 3 Jul 2026 22:14:34 +0000 Subject: [PATCH 1/6] chore(plugin): trim host bundle comments --- src/agents/plugin_bundle.rs | 45 ++++++---------------------- src/automation/skill_frontmatter.rs | 38 +++++------------------- src/hooks/claude.rs | 28 ++---------------- src/hooks/codex.rs | 46 +++++------------------------ src/hooks/mod.rs | 14 ++------- src/hooks/steering.rs | 30 ++++--------------- 6 files changed, 35 insertions(+), 166 deletions(-) diff --git a/src/agents/plugin_bundle.rs b/src/agents/plugin_bundle.rs index d5312ebeb..549ddf058 100644 --- a/src/agents/plugin_bundle.rs +++ b/src/agents/plugin_bundle.rs @@ -1,10 +1,8 @@ -//! Single-source-of-truth plugin bundle registry. +//! Shared plugin bundle registry. //! -//! All three host bundles (Claude, Cursor, Codex) used to live as three -//! byte-duplicated trees (`claude-plugin/`, `cursor-plugin/`, `codex-plugin/`) -//! embedded via three separate `include_str!` tables. They now share **one** -//! on-disk tree under `plugin/`, and this module owns the composed per-host -//! view that each installer deploys. +//! The source tree is unified where host formats match; host-specific overlays +//! remain where each installer needs a different manifest, hook, command, or +//! agent format. //! //! Layout of `plugin/`: //! - `plugin/skills/*/SKILL.md` — the 16 shared model-invocable skills **plus** @@ -27,12 +25,6 @@ //! `plugin/mcp-cursor.json` — Cursor MCP config (deploys to `mcp.json`). //! - `plugin/README-.md` — per-host README (deploys to `README.md`). //! -//! Each [`PluginFile::relative`] is the **deploy-relative** path on disk, kept -//! byte-for-byte identical to the pre-refactor bundles so no host's installed -//! tree changes. The embedded `contents` come from the shared `plugin/` source, -//! whose path may differ from the deploy path (e.g. Cursor's -//! `hooks/hooks.json` is sourced from `plugin/hooks/hooks-cursor.json`). -//! //! Composed per-host view = `GENERATED_SKILL_FILES` (recursively embedded from //! `plugin/skills/`, filtered per host) ∪ `_MANIFEST_FILES` and extras. @@ -56,9 +48,8 @@ pub(crate) fn set_mcp_command(raw: &str, bin: &str) -> Result { Ok(format!("{}\n", serde_json::to_string_pretty(&mcp)?)) } -/// One embedded plugin file: `relative` is its deploy path (unchanged from the -/// legacy per-host bundles), `contents` is embedded from the shared `plugin/` -/// tree at compile time. +/// One embedded plugin file: `relative` is its deploy path; `contents` is +/// embedded from the shared `plugin/` tree at compile time. #[derive(Clone, Copy)] pub struct PluginFile { pub relative: &'static str, @@ -74,37 +65,24 @@ macro_rules! plugin_file { }; } -// `GENERATED_SKILL_FILES`: every file under `plugin/skills/` (all 29 skill -// SKILL.md files **plus** any `references/`/`scripts/`/`assets/` support files), -// embedded recursively at compile time by `build.rs`. This replaced the two -// hand-maintained flat `include_str!` tables so skills can ship support files -// without a matching table edit. +// Every file under `plugin/skills/`, embedded recursively by `build.rs`. include!(concat!(env!("OUT_DIR"), "/plugin_bundle_generated.rs")); /// Prefix of the dispatcher skills that Cursor does **not** deploy (they are /// native commands on Cursor). Claude/Codex deploy every skill. const CURSOR_EXCLUDED_SKILL_PREFIX: &str = "skills/tracedecay-"; -/// Every skill file (all 29 skills' SKILL.md + support files) — the set -/// Claude and Codex deploy unchanged. fn all_skill_files() -> impl Iterator { GENERATED_SKILL_FILES.iter() } -/// The Cursor skill subset: every skill file *except* the `tracedecay-*` -/// dispatcher skills (those slugs are native commands on Cursor). fn cursor_skill_files() -> impl Iterator { GENERATED_SKILL_FILES .iter() .filter(|file| !file.relative.starts_with(CURSOR_EXCLUDED_SKILL_PREFIX)) } -/// Cursor's native slash commands: the same 13 workflow slugs, re-expressed as -/// Cursor 1.6+ `commands/` entries (no `disable-model-invocation` skill — these -/// are commands, not skills). Cursor deploys these to `commands/.md` and -/// ships the shared skill set *without* the canonical `tracedecay-*` dispatcher -/// skills, so Cursor's shared skills are byte-identical to Claude/Codex and its -/// explicit dispatch is native commands. +/// Cursor's native slash commands for the canonical workflow slugs. const CURSOR_COMMAND_FILES: &[PluginFile] = &[ plugin_file!( "commands/tracedecay-audit-safety.md", @@ -243,12 +221,7 @@ pub const CODEX_MANIFEST_FILES: &[PluginFile] = &[ plugin_file!("hooks/hooks.json", "hooks/hooks-codex.json"), ]; -/// Compose a host's full deploy set as `(relative, contents)` tuples: the -/// host's manifest/agent/command/rule sections first, then its skill files -/// (from the recursively-embedded `GENERATED_SKILL_FILES`). -/// -/// Exact ordering does not affect the deployed tree (each file is written by -/// its deploy `relative` path), but a stable order keeps tests deterministic. +/// Compose a host's deploy set as deterministic `(relative, contents)` tuples. fn compose( sections: &[&'static [PluginFile]], skills: impl Iterator, diff --git a/src/automation/skill_frontmatter.rs b/src/automation/skill_frontmatter.rs index 816abcc68..0ab4764c0 100644 --- a/src/automation/skill_frontmatter.rs +++ b/src/automation/skill_frontmatter.rs @@ -1,30 +1,16 @@ -//! Canonical parser for `SKILL.md` YAML frontmatter. -//! -//! Skill frontmatter across the repo (the shared `plugin/skills/` bundle, -//! Hermes hub skills, agent-managed exports) uses a -//! small YAML subset: a `---` fence, `key: value` scalars (optionally single- -//! or double-quoted), and block values made of indented lines (list items or -//! nested maps). This module is the one place that subset is parsed so -//! consumers ([`crate::automation::hermes_skill_inventory`] and the plugin -//! contract tests in `tests/agent_suite/plugin_skill_contract_test.rs`) stop growing -//! bespoke, subtly different parsers. -//! -//! Parsing is line-ending tolerant: CRLF checkouts (e.g. GitHub Windows -//! runners with `core.autocrlf=true`) parse identically to LF checkouts. +//! Parser for the `SKILL.md` frontmatter subset used by plugin and managed +//! skills. use std::collections::BTreeMap; use crate::errors::{Result, TraceDecayError}; -/// One frontmatter value: either an inline scalar (`key: value`) or a block -/// of indented continuation lines (`key:` followed by list items or nested -/// mappings). +/// One frontmatter value. #[derive(Debug, Clone, PartialEq, Eq)] pub enum SkillFrontmatterValue { - /// Inline scalar with quoting already resolved (outer quotes stripped, - /// YAML `''` doubling inside single-quoted scalars unescaped). + /// Inline scalar with outer quotes stripped. Scalar(String), - /// Raw trimmed block lines under a key with no inline value. + /// Trimmed block lines under a key with no inline value. Block(Vec), } @@ -36,9 +22,7 @@ impl SkillFrontmatterValue { } } - /// Returns the unquoted items of a block whose every line is a YAML list - /// item (`- item`), or `None` for scalars and other block shapes (nested - /// maps, empty blocks). + /// Returns unquoted `- item` block entries. pub fn as_list_items(&self) -> Option> { match self { Self::Scalar(_) => None, @@ -58,11 +42,7 @@ impl SkillFrontmatterValue { } } -/// Parses the leading `---`-fenced YAML frontmatter of a `SKILL.md` document. -/// -/// Returns an error when the document does not open with frontmatter, never -/// closes it, repeats a key, or contains a top-level line that is not a -/// `key: value` mapping. Line endings (`\n` vs `\r\n`) are normalized away. +/// Parses the leading `---`-fenced frontmatter of a `SKILL.md` document. pub fn parse_skill_frontmatter(contents: &str) -> Result> { let mut lines = contents.lines(); if lines.next().map(str::trim_end) != Some("---") { @@ -126,9 +106,7 @@ pub fn parse_skill_frontmatter(contents: &str) -> Result String { if let Some(inner) = value.strip_prefix('\'').and_then(|v| v.strip_suffix('\'')) { inner.replace("''", "'") diff --git a/src/hooks/claude.rs b/src/hooks/claude.rs index 30bb1e4d5..03a14ddbf 100644 --- a/src/hooks/claude.rs +++ b/src/hooks/claude.rs @@ -1,7 +1,6 @@ //! Claude Code hook handlers. //! -//! Claude and Codex share the common hook JSON shape, while older Claude -//! handlers keep their legacy input/output contracts. +//! Claude and Codex share the common hook JSON shape. use serde_json::Value; @@ -21,9 +20,6 @@ use super::{ }; /// `PreToolUse` hook handler for Claude Code's Agent tool matcher. -/// -/// Blocks Explore agents and exploration-style prompts, directing Claude to -/// use tracedecay MCP tools instead. pub fn hook_pre_tool_use() { let tool_input = std::env::var("TOOL_INPUT").unwrap_or_default(); record_hook_invoked(None, HintAgent::Claude, "preToolUse", &tool_input); @@ -34,8 +30,6 @@ pub fn hook_pre_tool_use() { } /// Pure decision logic for the `PreToolUse` hook. -/// -/// Returns the JSON decision for Claude to print to stdout. pub fn evaluate_hook_decision(tool_input: &str) -> String { let parsed: serde_json::Value = serde_json::from_str(tool_input).unwrap_or_else(|_| serde_json::json!({})); @@ -100,9 +94,7 @@ pub(super) fn is_code_research_prompt(prompt: &str) -> bool { exploration_patterns.iter().any(|pat| lower.contains(pat)) } -/// Claude Code `SessionStart` hook handler (fail-open). -/// -/// Emits session-specific index freshness and compaction recovery context. +/// Claude Code `SessionStart` hook handler. pub async fn hook_claude_session_start() -> i32 { let event = read_hook_event!(); let root = codex_project_root_from_event(&event); @@ -123,11 +115,6 @@ pub async fn hook_claude_session_start() -> i32 { } /// Builds the Claude `SessionStart` context for code workspaces. -/// -/// On an initialized project this injects the full `using-tracedecay` -/// adoption contract (the `` bootstrap) after the index -/// status line, matching the Cursor and Codex session hooks so Claude's -/// `SessionStart` channel carries the same mandate. pub async fn claude_session_context_for_event(event_json: &str) -> String { let parsed = serde_json::from_str::(event_json).unwrap_or(Value::Null); match codex_project_root_from_parsed_event(&parsed) { @@ -147,11 +134,7 @@ pub async fn claude_session_context_for_event(event_json: &str) -> String { } } -/// Claude Code `PostToolUse` hook handler used to keep the graph fresh after -/// writes. -/// -/// Notifies the daemon, which owns targeted sync, branch tracking, and -/// coalescing. Fail-open and silent. +/// Claude Code `PostToolUse` hook handler used to keep the graph fresh. pub async fn hook_claude_post_tool_use() -> i32 { let event = read_hook_event!(); let root = codex_project_root_from_event(&event); @@ -161,9 +144,6 @@ pub async fn hook_claude_post_tool_use() -> i32 { } /// `UserPromptSubmit` hook handler: resets the per-session local counter. -/// -/// Token savings are now reported inline in each MCP tool response, -/// so this hook only needs to reset the counter for the new turn. pub async fn hook_prompt_submit() { let project_path = crate::config::resolve_path(None); if let Ok(cg) = crate::tracedecay::TraceDecay::open(&project_path).await { @@ -172,8 +152,6 @@ pub async fn hook_prompt_submit() { } /// `Stop` hook handler: ingests new session data and prints a cost receipt. -/// -/// Ingests new Claude Code session lines and prints a one-line cost receipt. pub async fn hook_stop() { let Some(gdb) = crate::global_db::GlobalDb::open().await else { return; diff --git a/src/hooks/codex.rs b/src/hooks/codex.rs index 44491034d..58c89ffeb 100644 --- a/src/hooks/codex.rs +++ b/src/hooks/codex.rs @@ -1,7 +1,6 @@ //! Codex CLI hook handlers. //! -//! Codex emits its documented hook output shape instead of reusing the Claude, -//! Cursor, or Kiro contracts. +//! Codex emits its own hook output shape. use std::collections::BTreeMap; use std::path::{Path, PathBuf}; @@ -39,9 +38,7 @@ may be missing."; const CODEX_POST_COMPACT_BUDGET: Duration = Duration::from_secs(115); -/// Codex `SessionStart` hook handler (fire-and-forget). -/// -/// Emits tracedecay steering and index freshness for the session `cwd`. +/// Codex `SessionStart` hook handler. pub async fn hook_codex_session_start() -> i32 { let event = read_hook_event!(); let root = codex_project_root_from_event(&event); @@ -70,8 +67,7 @@ pub async fn hook_codex_session_start() -> i32 { /// Codex `UserPromptSubmit` hook handler. /// -/// Resets the per-project local counter for the new turn and injects the same -/// tracedecay steering context as `SessionStart`. Never blocks the prompt. +/// Resets the local counter and injects steering context for the new turn. pub async fn hook_codex_user_prompt_submit() -> i32 { let event = read_hook_event!(); let root = codex_project_root_from_event(&event); @@ -111,8 +107,7 @@ async fn codex_prompt_memory_recall(event_json: &str) -> Option { memory_inject::prompt_memory_recall(&root, session_id.as_deref(), &prompt).await } -/// Builds Codex session/prompt context. Unlike Cursor, Codex has no -/// always-applied tracedecay rule, so this carries full steering. +/// Builds Codex session/prompt context. async fn codex_session_context_for_event(event_json: &str) -> (String, HookWorkspaceStatus) { let parsed = serde_json::from_str::(event_json).unwrap_or(Value::Null); let root = codex_project_root_from_parsed_event(&parsed); @@ -134,10 +129,6 @@ async fn codex_session_context_for_event(event_json: &str) -> (String, HookWorks } /// Codex `SubagentStart` hook handler. -/// -/// Steers research/explore subagents toward tracedecay MCP tools. Codex cannot -/// hard-stop a subagent at start (`continue: false` is ignored for this event), -/// so this injects `additionalContext` instead of denying. pub async fn hook_codex_subagent_start() -> i32 { let event = read_hook_event!(); let root = codex_project_root_from_event(&event); @@ -181,10 +172,7 @@ fn merge_codex_subagent_output(output: Option, digest: Option) - Some(parsed.to_string()) } -/// Codex `PostToolUse` hook handler used to keep the graph fresh after writes. -/// -/// Notifies the daemon, which owns targeted sync, branch tracking, and -/// coalescing. Fail-open and silent. +/// Codex `PostToolUse` hook handler used to keep the graph fresh. pub async fn hook_codex_post_tool_use() -> i32 { let event = read_hook_event!(); let root = codex_project_root_from_event(&event); @@ -195,10 +183,7 @@ pub async fn hook_codex_post_tool_use() -> i32 { /// Codex `PostCompact` hook handler. /// -/// Codex stores compacted context bodies encrypted in the transcript. This hook -/// uses the visible source messages already ingested into the LCM store, asks a -/// child Codex app-server turn to summarize them, and replaces the temporary -/// deterministic summary node. Fail-open: compaction must never block Codex. +/// Replaces temporary compaction summaries from visible LCM source messages. pub async fn hook_codex_post_compact() -> i32 { let event = read_hook_event!(); let root = codex_project_root_from_event(&event); @@ -210,9 +195,7 @@ pub async fn hook_codex_post_compact() -> i32 { 0 } -/// Builds a Codex hook stdout payload that injects model-visible context via -/// `hookSpecificOutput.additionalContext`. Used by `SessionStart`, -/// `UserPromptSubmit`, and `SubagentStart`. +/// Builds a Codex hook stdout payload with `additionalContext`. pub fn codex_additional_context_json(event_name: &str, additional_context: &str) -> String { serde_json::json!({ "hookSpecificOutput": { @@ -224,9 +207,6 @@ pub fn codex_additional_context_json(event_name: &str, additional_context: &str) } /// Pure decision logic for Codex `SubagentStart` events. -/// -/// Returns Codex context for research or no-history subagents, or `None` for -/// execution-style subagents that already have history. pub fn evaluate_codex_subagent_start(event_json: &str) -> Option { let parsed: Value = serde_json::from_str(event_json).ok()?; let agent_type = parsed @@ -281,9 +261,7 @@ pub fn evaluate_codex_subagent_start(event_json: &str) -> Option { None } -/// Records a Codex `SubagentStart` in the current project's profile-sharded -/// hook state and returns the session-local count. Fail-open: malformed events, -/// missing roots, and storage errors only disable counting. +/// Records a Codex `SubagentStart` and returns the session-local count. pub fn record_codex_subagent_start(event_json: &str) -> Option { let parsed: Value = serde_json::from_str(event_json).ok()?; let root = codex_project_root_from_parsed_event(&parsed)?; @@ -447,14 +425,6 @@ pub fn codex_workspace_status_from_event(event_json: &str) -> HookWorkspaceStatu } /// Extracts the project-relative paths touched by a Codex `apply_patch` command. -/// -/// Codex sends the patch text as `tool_input.command`. The `apply_patch` envelope -/// names each file with `*** Add File:`, `*** Update File:`, `*** Delete File:`, -/// or `*** Move to:` lines. Patch paths are relative to the session `cwd` -/// (which may be a subdirectory of the discovered project root), so we resolve -/// each against `cwd` and then make it relative to `project_root`. Absolute -/// paths outside the root are skipped. The result feeds the daemon's targeted -/// single-file sync event. pub fn codex_apply_patch_rel_paths(command: &str, cwd: &Path, project_root: &Path) -> Vec { const PREFIXES: [&str; 4] = [ "*** Add File:", diff --git a/src/hooks/mod.rs b/src/hooks/mod.rs index 087a4010e..a2f6d2425 100644 --- a/src/hooks/mod.rs +++ b/src/hooks/mod.rs @@ -1,17 +1,7 @@ //! Hook handlers for Claude Code, Kiro, Cursor, and Codex integrations. //! -//! These functions are invoked by each agent's hook system to intercept tool -//! calls, redirect exploration work to tracedecay MCP tools, keep the index -//! fresh after edits / git state changes, and track per-session token savings. -//! Each agent sends its own event schema on stdin and expects its own output -//! shape, so the handlers are kept agent-specific rather than shared blindly. -//! -//! This module holds the shared plumbing (stdin reader, hook analytics, -//! event-field helpers, and per-session hint dedupe); the per-agent handlers -//! live in the `claude`, `codex`, `cursor`, and `kiro` submodules, with the -//! shared post-tool-use pipeline in `post_tool_use` and the session/steering -//! context builders in `steering`. Every public item is re-exported here so -//! it stays reachable at `crate::hooks::`. +//! Each agent sends its own event schema and expects its own output shape, so +//! handlers stay agent-specific while shared plumbing lives here. use std::collections::HashSet; use std::io::Read; diff --git a/src/hooks/steering.rs b/src/hooks/steering.rs index 639c041b7..1b566d281 100644 --- a/src/hooks/steering.rs +++ b/src/hooks/steering.rs @@ -1,6 +1,4 @@ -//! Session/steering context builders shared by the Cursor, Claude, and Codex -//! session hooks: index-freshness lines, the workflow-skill index, and the -//! post-compaction context-recovery hint. +//! Shared session/steering context builders. use std::path::Path; @@ -8,14 +6,7 @@ use serde_json::Value; use super::now_unix_secs; -/// Model-invocable skills that Cursor ships in its `skills/` directory. The 13 -/// `tracedecay-*` workflow slugs are native Cursor commands (not skills), so -/// they are excluded. This covers the foundational skills plus the memory -/// skills (`project-memory` — the merged recall+curate skill — -/// `managing-session-context`, `retrieving-cached-context`, -/// `retrieving-project-memory`, `storing-project-memory`). Kept as one constant -/// so the session steering context and the bundle coverage test in -/// `agents::cursor` stay in sync. +/// Model-invocable skills that Cursor ships in its `skills/` directory. pub const CURSOR_PLUGIN_SKILLS: &[&str] = &[ "assessing-impact", "code-health", @@ -51,11 +42,6 @@ pub(super) fn append_tracedecay_bootstrap_context(s: &mut String) { pub(super) const COMPACTION_CONTEXT_RECOVERY_HINT: &str = "Context was just compacted. If important prior-session context seems missing, query TraceDecay session context before assuming the compacted summary is complete. Start with `tracedecay_message_search` or `tracedecay_lcm_expand_query`; use `tracedecay_lcm_describe` and `tracedecay_lcm_expand` when you need the summary DAG sources."; /// Builds the Cursor `sessionStart` `additional_context` text. -/// -/// Intentionally lean: the always-applied plugin rule already carries the -/// tool-routing steering, so repeating it here would burn tokens every -/// session. This adds only the session-specific signals — index freshness, -/// the workflow-skill index, and the tokens-saved counter. pub fn build_cursor_session_context( initialized: bool, staleness_hint: Option<&str>, @@ -76,10 +62,7 @@ pub fn build_cursor_session_context( s } -/// One-line index freshness signal shared by the Cursor and Claude session -/// contexts. Both hosts carry the tool-routing steering in an always-applied -/// rule (Cursor plugin rule, CLAUDE.md), so their session hooks report only -/// session-specific signals. +/// One-line index freshness signal. pub(super) fn index_status_line(initialized: bool, staleness_hint: Option<&str>) -> String { if initialized { match staleness_hint { @@ -93,9 +76,7 @@ pub(super) fn index_status_line(initialized: bool, staleness_hint: Option<&str>) } } -/// Builds the Codex session/prompt steering context. Codex has no -/// always-applied tracedecay rule, so the full tool-routing steering lives -/// here. +/// Builds the Codex session/prompt steering context. pub fn build_codex_session_context(initialized: bool, staleness_hint: Option<&str>) -> String { let status = if initialized { HookWorkspaceStatus::Initialized @@ -253,8 +234,7 @@ pub fn cursor_staleness_hint(age_secs: i64) -> String { } } -/// Opens the index once and reads both session-steering signals: the -/// staleness hint and the session tokens-saved counter. +/// Opens the index once and reads both session-steering signals. pub(super) async fn cursor_index_signals_for_root(root: &Path) -> (Option, Option) { let Ok(cg) = crate::tracedecay::TraceDecay::open(root).await else { return (None, None); From 17eba27f2f3f67f6bfa0164275b11e483b437b83 Mon Sep 17 00:00:00 2001 From: ScriptedAlchemy Date: Fri, 3 Jul 2026 22:14:46 +0000 Subject: [PATCH 2/6] docs(plugin): tighten generated plugin prompts --- plugin/README-claude.md | 7 ++- plugin/README-codex.md | 9 ++-- plugin/README-cursor.md | 47 +++++++------------ plugin/agents/code-explorer.md | 6 +-- plugin/agents/code-health-auditor.md | 6 +-- plugin/agents/session-historian.md | 6 +-- .../overlays/cursor/agents/code-explorer.md | 4 +- .../cursor/agents/code-health-auditor.md | 4 +- .../cursor/agents/session-historian.md | 4 +- .../commands/tracedecay-audit-safety.md | 4 +- .../commands/tracedecay-check-health.md | 4 +- .../commands/tracedecay-clean-dead-code.md | 4 +- .../commands/tracedecay-compare-branches.md | 6 +-- .../commands/tracedecay-curate-memory.md | 2 +- .../commands/tracedecay-draft-commit.md | 4 +- .../cursor/commands/tracedecay-find-impact.md | 4 +- .../cursor/commands/tracedecay-fix-build.md | 4 +- .../commands/tracedecay-map-architecture.md | 4 +- .../cursor/commands/tracedecay-port-code.md | 4 +- .../commands/tracedecay-recall-memory.md | 4 +- .../cursor/commands/tracedecay-review-diff.md | 4 +- .../commands/tracedecay-test-changes.md | 4 +- .../skills/tracedecay-audit-safety/SKILL.md | 6 +-- .../skills/tracedecay-check-health/SKILL.md | 6 +-- .../tracedecay-clean-dead-code/SKILL.md | 6 +-- .../tracedecay-compare-branches/SKILL.md | 6 +-- .../skills/tracedecay-curate-memory/SKILL.md | 4 +- .../skills/tracedecay-draft-commit/SKILL.md | 6 +-- plugin/skills/tracedecay-find-impact/SKILL.md | 6 +-- plugin/skills/tracedecay-fix-build/SKILL.md | 6 +-- .../tracedecay-map-architecture/SKILL.md | 6 +-- plugin/skills/tracedecay-port-code/SKILL.md | 6 +-- .../skills/tracedecay-recall-memory/SKILL.md | 4 +- plugin/skills/tracedecay-review-diff/SKILL.md | 6 +-- .../skills/tracedecay-test-changes/SKILL.md | 6 +-- src/agents/claude_agents/code-explorer.md | 6 +-- .../claude_agents/code-health-auditor.md | 6 +-- src/agents/claude_agents/session-historian.md | 6 +-- 38 files changed, 112 insertions(+), 125 deletions(-) diff --git a/plugin/README-claude.md b/plugin/README-claude.md index 6b7334800..51a62d297 100644 --- a/plugin/README-claude.md +++ b/plugin/README-claude.md @@ -33,7 +33,6 @@ path with spaces. ## CLI fallback Every MCP tool is also available from the shell as `tracedecay tool ` -(`tracedecay tool` lists all tools; `tracedecay tool --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. +(`tracedecay tool` lists tools; `tracedecay tool --help` shows +parameters). Bundled skills and steering use that CLI fallback when MCP +transport errors or times out, instead of querying `.tracedecay` databases. diff --git a/plugin/README-codex.md b/plugin/README-codex.md index fa4596f15..f5cf1c728 100644 --- a/plugin/README-codex.md +++ b/plugin/README-codex.md @@ -29,11 +29,10 @@ tool-routing steering Cursor places in a rule is injected through the `SessionStart`/`UserPromptSubmit` hooks instead. Every MCP tool is also available from the shell as `tracedecay tool ` -(`tracedecay tool` lists all tools; `tracedecay tool --help` shows a -tool's parameters). The bundled `using-the-cli` skill and the 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. +(`tracedecay tool` lists tools; `tracedecay tool --help` shows +parameters). The bundled `using-the-cli` skill and injected steering use that +CLI fallback when MCP transport errors or times out, instead of querying +`.tracedecay` databases. The `PostCompact` hook starts `codex app-server` as a short-lived child process and sets `TRACEDECAY_CODEX_SUMMARY_CHILD=1` to prevent recursive summary hooks. diff --git a/plugin/README-cursor.md b/plugin/README-cursor.md index 0dc581de5..40343ba7f 100644 --- a/plugin/README-cursor.md +++ b/plugin/README-cursor.md @@ -17,39 +17,28 @@ The plugin registers the `tracedecay` MCP server as: tracedecay serve --path ${workspaceFolder} ``` -This is intentionally workspace-scoped: each Cursor workspace uses its own -`.tracedecay/` index instead of the legacy global Cursor MCP registration. The -`${workspaceFolder}` variable is resolved by Cursor's MCP runner in normal -editor windows. - -Some Cursor contexts (headless agent-session MCP scopes) spawn the server with -the literal, unexpanded `${workspaceFolder}` string instead, from a working -directory set to the user home rather than the workspace. Cursor never retries -a failed MCP scope, so exiting on that bogus path would permanently break the -connection for the session ("Timed out waiting for connection" on every tool -call). `serve` therefore detects an unexpanded `${...}` template value, warns -on stderr, and falls back to project discovery where possible: cwd walk-up, -MCP initialize roots, then the global project registry. Because the spawn -directory says nothing about the intended workspace in this mode, the registry -step accepts only a unique registered project — with several projects -registered, `serve` still exits with an actionable "multiple projects" error -instead of guessing, and it logs which project it picked and why when -discovery succeeds. This is also why the template keeps -`--path ${workspaceFolder}` rather than dropping it (as was done for VS Code -Copilot in issue #66): normal Cursor windows do expand it, and from a home-dir -cwd no-path discovery cannot scope multi-project setups. If tools still do not -connect, run `tracedecay doctor --agent cursor` to inspect the generated -plugin config. +Each Cursor workspace gets its own `.tracedecay/` index. Cursor's MCP runner +resolves `${workspaceFolder}` in normal editor windows. + +Some Cursor contexts (headless agent-session MCP scopes) pass the literal, +unexpanded `${workspaceFolder}` from the user home directory. Cursor never +retries a failed MCP scope, so `serve` detects unexpanded `${...}` values, +warns on stderr, and falls back to project discovery: cwd walk-up, MCP +initialize roots, then the global project registry. Registry fallback accepts +only a unique registered project; otherwise `serve` exits with an actionable +"multiple projects" error. The template keeps `--path ${workspaceFolder}` +because normal Cursor windows expand it and home-dir discovery cannot scope +multi-project setups. If tools still do not connect, run +`tracedecay doctor --agent cursor`. Hook commands derive the active project from Cursor's event payload / `CURSOR_PROJECT_DIR`, not from the plugin directory. Every MCP tool is also available from the shell as `tracedecay tool ` -(`tracedecay tool` lists all tools; `tracedecay tool --help` shows a -tool's parameters). The bundled `using-the-cli` skill and the always-applied -rule steer agents to that CLI fallback when the MCP transport errors or times -out, instead of querying `.tracedecay` databases directly or giving up on -tracedecay. +(`tracedecay tool` lists tools; `tracedecay tool --help` shows +parameters). The bundled `using-the-cli` skill and always-applied rule use +that CLI fallback when MCP transport errors or times out, instead of querying +`.tracedecay` databases. For sessions resumed from compacted context, the `sessionStart` hook adds a short recovery hint through Cursor's `additional_context` channel so the agent @@ -212,7 +201,7 @@ window. - **Cloud agents:** plugin `sessionStart`, `sessionEnd`, `beforeSubmitPrompt`, `workspaceOpen`, and `stop` hooks never run in Cursor cloud agents, so the - TraceDecay steering context and transcript ingest are desktop-only today. + TraceDecay steering context and transcript ingest are desktop-only. Cloud agents do run repo-level `.cursor/hooks.json` hooks for the supported subset (`afterFileEdit`, `afterShellExecution`, tool hooks, subagent hooks). - The plugin's session-recall tools only see transcripts ingested on this diff --git a/plugin/agents/code-explorer.md b/plugin/agents/code-explorer.md index dd4d33276..2c9ed8c27 100644 --- a/plugin/agents/code-explorer.md +++ b/plugin/agents/code-explorer.md @@ -1,6 +1,6 @@ --- 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. +description: Read-only TraceDecay code exploration agent for how/where/what questions, symbol lookup, callers/callees, call chains, and impact analysis. Use to parallelize codebase research or isolate deep exploration. 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 @@ -8,7 +8,7 @@ disallowedTools: mcp__tracedecay__tracedecay_str_replace, mcp__tracedecay__trace # 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. +Read-only exploration subagent. Investigate the repository and return findings. ## Method @@ -19,7 +19,7 @@ You are a read-only exploration subagent. You investigate the repository and ret ## 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. +- Read-only: never edit files, run test runners or diagnostics, or write memory. Mutating TraceDecay tools are disabled for this agent; do not work around that. - Do not spawn nested subagents unless explicitly asked. ## Return diff --git a/plugin/agents/code-health-auditor.md b/plugin/agents/code-health-auditor.md index c85e5bed9..466f04f28 100644 --- a/plugin/agents/code-health-auditor.md +++ b/plugin/agents/code-health-auditor.md @@ -1,6 +1,6 @@ --- 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. +description: Read-only TraceDecay code-health auditor for health audits, tech-debt reports, scorecards, and worst complexity, duplication, coupling, doc, and test-risk offenders. Use to isolate or parallelize 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 @@ -8,7 +8,7 @@ disallowedTools: mcp__tracedecay__tracedecay_str_replace, mcp__tracedecay__trace # 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. +Read-only audit subagent. Score and rank code health; return findings. ## Method @@ -19,7 +19,7 @@ You are a read-only audit subagent. You score and rank code health and return fi ## 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. +- 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 work around that. - Keep `path`/`max_pairs` tight on `tracedecay_redundancy` (first call can be slow). Do not spawn nested subagents unless asked. ## Return diff --git a/plugin/agents/session-historian.md b/plugin/agents/session-historian.md index 292631d54..b74c2c277 100644 --- a/plugin/agents/session-historian.md +++ b/plugin/agents/session-historian.md @@ -1,6 +1,6 @@ --- 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. +description: Read-only TraceDecay session-recall agent for prior decisions, past work, 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 @@ -8,7 +8,7 @@ disallowedTools: mcp__tracedecay__tracedecay_str_replace, mcp__tracedecay__trace # 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. +Read-only recall subagent. Retrieve what past sessions said, did, and decided for this project. ## Method @@ -20,7 +20,7 @@ You are a read-only recall subagent. You retrieve what past sessions said, did, ## 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. +- 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. Mutating TraceDecay tools are disabled for this agent; do not work around that. - Do not spawn nested subagents unless explicitly asked. ## Return diff --git a/plugin/overlays/cursor/agents/code-explorer.md b/plugin/overlays/cursor/agents/code-explorer.md index 7d0307067..71fc66b3c 100644 --- a/plugin/overlays/cursor/agents/code-explorer.md +++ b/plugin/overlays/cursor/agents/code-explorer.md @@ -7,7 +7,7 @@ readonly: true # 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. +Read-only exploration subagent. Investigate the repository and return findings. ## Method @@ -18,7 +18,7 @@ You are a read-only exploration subagent. You investigate the repository and ret ## Rules -- Read-only: never use editing tools (`tracedecay_str_replace`, `tracedecay_replace_symbol`, `tracedecay_multi_str_replace`, `tracedecay_insert_at`, `tracedecay_insert_at_symbol`), test runners (`tracedecay_run_affected_tests`), `tracedecay_diagnostics`, or memory writes. +- Never use editing tools (`tracedecay_str_replace`, `tracedecay_replace_symbol`, `tracedecay_multi_str_replace`, `tracedecay_insert_at`, `tracedecay_insert_at_symbol`), test runners (`tracedecay_run_affected_tests`), `tracedecay_diagnostics`, or memory writes. - Do not spawn nested subagents unless explicitly asked. ## Return diff --git a/plugin/overlays/cursor/agents/code-health-auditor.md b/plugin/overlays/cursor/agents/code-health-auditor.md index 27a10a253..d641ab66a 100644 --- a/plugin/overlays/cursor/agents/code-health-auditor.md +++ b/plugin/overlays/cursor/agents/code-health-auditor.md @@ -7,7 +7,7 @@ readonly: true # 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. +Read-only audit subagent. Score and rank code health; return findings. ## Method @@ -18,7 +18,7 @@ You are a read-only audit subagent. You score and rank code health and return fi ## Rules -- Read-only: never use editing tools (`tracedecay_str_replace`, `tracedecay_replace_symbol`, `tracedecay_multi_str_replace`, `tracedecay_insert_at`, `tracedecay_insert_at_symbol`), `tracedecay_run_affected_tests`, `tracedecay_diagnostics`, session-baseline writes, or memory writes. +- Never use editing tools (`tracedecay_str_replace`, `tracedecay_replace_symbol`, `tracedecay_multi_str_replace`, `tracedecay_insert_at`, `tracedecay_insert_at_symbol`), `tracedecay_run_affected_tests`, `tracedecay_diagnostics`, session-baseline writes, or memory writes. - Keep `path`/`max_pairs` tight on `tracedecay_redundancy` (first call can be slow). Do not spawn nested subagents unless asked. ## Return diff --git a/plugin/overlays/cursor/agents/session-historian.md b/plugin/overlays/cursor/agents/session-historian.md index 024460874..b193c0fd7 100644 --- a/plugin/overlays/cursor/agents/session-historian.md +++ b/plugin/overlays/cursor/agents/session-historian.md @@ -7,7 +7,7 @@ readonly: true # 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. +Read-only recall subagent. Retrieve what past sessions said, did, and decided for this project. ## Method @@ -19,7 +19,7 @@ You are a read-only recall subagent. You retrieve what past sessions said, did, ## Rules -- Read-only: never use `tracedecay_lcm_compress`, `tracedecay_lcm_preflight`, `tracedecay_lcm_session_boundary`, `tracedecay_lcm_doctor` repair/clean modes, `fact_store` adds, `tracedecay_fact_feedback`, `tracedecay_memory_status`, or any editing tools. +- Never use `tracedecay_lcm_compress`, `tracedecay_lcm_preflight`, `tracedecay_lcm_session_boundary`, `tracedecay_lcm_doctor` repair/clean modes, `fact_store` adds, `tracedecay_fact_feedback`, `tracedecay_memory_status`, or any editing tools. - Do not spawn nested subagents unless explicitly asked. ## Return diff --git a/plugin/overlays/cursor/commands/tracedecay-audit-safety.md b/plugin/overlays/cursor/commands/tracedecay-audit-safety.md index abc6db528..52fddbb69 100644 --- a/plugin/overlays/cursor/commands/tracedecay-audit-safety.md +++ b/plugin/overlays/cursor/commands/tracedecay-audit-safety.md @@ -4,9 +4,9 @@ description: Audit the repo or a directory for ship-blocking risk, panic sites, # /tracedecay-audit-safety -Apply the `tracedecay:reviewing-changes` skill. +Use `tracedecay:reviewing-changes`. - **Scope:** the whole repo, or the directory named in `$ARGUMENTS` if one was given. -- Follow that skill's read-only workflow and guardrails; report findings, don't fix them here. +- Read-only: report findings, don't fix them here. Output: findings grouped Critical / Warning / Note with file + enclosing symbol, and a prioritized follow-up list. diff --git a/plugin/overlays/cursor/commands/tracedecay-check-health.md b/plugin/overlays/cursor/commands/tracedecay-check-health.md index 381211c54..3141adff7 100644 --- a/plugin/overlays/cursor/commands/tracedecay-check-health.md +++ b/plugin/overlays/cursor/commands/tracedecay-check-health.md @@ -4,9 +4,9 @@ description: Check code health for the repo or a directory, including worst offe # /tracedecay-check-health -Apply the `tracedecay:code-health` skill. +Use `tracedecay:code-health`. - **Scope:** the whole repo, or the directory named in `$ARGUMENTS` if one was given. -- Follow that skill's read-only workflow and guardrails; lead with `tracedecay_health` and drill only into weak dimensions. Don't restate the tool ladder here. +- Read-only: lead with `tracedecay_health` and drill only into weak dimensions. Output: the composite health score + weak dimensions, the worst offenders (complexity, duplication, god files, doc gaps, panic sites, test-risk), and a prioritized fix list. diff --git a/plugin/overlays/cursor/commands/tracedecay-clean-dead-code.md b/plugin/overlays/cursor/commands/tracedecay-clean-dead-code.md index fd70722e8..1d09e1a23 100644 --- a/plugin/overlays/cursor/commands/tracedecay-clean-dead-code.md +++ b/plugin/overlays/cursor/commands/tracedecay-clean-dead-code.md @@ -4,9 +4,9 @@ description: Find and safely remove dead code, unused imports, and duplication v # /tracedecay-clean-dead-code -Apply the `tracedecay:reviewing-changes` skill. +Use `tracedecay:reviewing-changes` to identify candidates, then `tracedecay:editing-safely` for removals. - **Scope:** the whole repo, or the directory named in `$ARGUMENTS` if one was given. -- Follow that skill's workflow and guardrails: confirm zero real callers before deleting anything, be conservative with `pub` items, and respect Cursor approval/run-mode for edits and verification runs. +- Confirm zero real callers before deleting anything; be conservative with `pub` items; respect Cursor approval/run-mode for edits and verification runs. Output: removed/consolidated items and the before/after health or test result. diff --git a/plugin/overlays/cursor/commands/tracedecay-compare-branches.md b/plugin/overlays/cursor/commands/tracedecay-compare-branches.md index 3672119ba..7ac0ad5bb 100644 --- a/plugin/overlays/cursor/commands/tracedecay-compare-branches.md +++ b/plugin/overlays/cursor/commands/tracedecay-compare-branches.md @@ -4,9 +4,9 @@ description: Compare or search another git branch's code graph without switching # /tracedecay-compare-branches -Apply the `tracedecay:exploring-code` skill. +Use `tracedecay:exploring-code`. -- **Args:** interpret `$ARGUMENTS` as either a single target branch to compare against the current branch, or " " to diff two branches; if absent, start with `tracedecay_branch_list` and ask what to search/compare. -- Follow that skill's read-only workflow; if a target branch isn't tracked, tell the user to run `tracedecay branch add ` in the terminal first. +- **Args:** interpret `$ARGUMENTS` as a single target branch, or " " to diff two branches; if absent, start with `tracedecay_branch_list` and ask what to search/compare. +- Read-only. If a target branch isn't tracked, tell the user to run `tracedecay branch add ` first. Output: the cross-branch search hits or the added/removed/changed symbol lists, with any branch-fallback warning surfaced. diff --git a/plugin/overlays/cursor/commands/tracedecay-curate-memory.md b/plugin/overlays/cursor/commands/tracedecay-curate-memory.md index fa7b06702..68edc2f5a 100644 --- a/plugin/overlays/cursor/commands/tracedecay-curate-memory.md +++ b/plugin/overlays/cursor/commands/tracedecay-curate-memory.md @@ -4,7 +4,7 @@ description: Curate, update, delete, or inspect TraceDecay memory facts and dash # /tracedecay-curate-memory -Apply the `tracedecay:project-memory` skill. +Use `tracedecay:project-memory`. - **Args:** interpret `$ARGUMENTS` as the fact, entity, query, or curation action to review; if absent, ask what memory scope to curate before mutating anything. - Start read-only with `tracedecay_fact_store` search/list/probe/reason/contradict or `tracedecay_memory_status`; open `tracedecay_dashboard` only when the user wants visual curation. diff --git a/plugin/overlays/cursor/commands/tracedecay-draft-commit.md b/plugin/overlays/cursor/commands/tracedecay-draft-commit.md index 276ac1019..024c92570 100644 --- a/plugin/overlays/cursor/commands/tracedecay-draft-commit.md +++ b/plugin/overlays/cursor/commands/tracedecay-draft-commit.md @@ -4,9 +4,9 @@ description: Draft a commit message, PR description, or changelog from semantic # /tracedecay-draft-commit -Apply the `tracedecay:reviewing-changes` skill. +Use `tracedecay:reviewing-changes`. - **Args:** 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. -- Follow that skill's guardrails: it drafts text only — leave `git commit` / `gh pr create` to the user unless they explicitly ask. +- Draft text only — leave `git commit` / `gh pr create` to the user unless they explicitly ask. Output: the drafted commit / PR / changelog text. diff --git a/plugin/overlays/cursor/commands/tracedecay-find-impact.md b/plugin/overlays/cursor/commands/tracedecay-find-impact.md index 7a46dc035..afa1c616d 100644 --- a/plugin/overlays/cursor/commands/tracedecay-find-impact.md +++ b/plugin/overlays/cursor/commands/tracedecay-find-impact.md @@ -4,9 +4,9 @@ description: Find the blast radius of a change, including impacted symbols, file # /tracedecay-find-impact -Apply the `tracedecay:assessing-impact` skill. +Use `tracedecay:assessing-impact`. - **Args:** interpret `$ARGUMENTS` as the symbol, file, or change to analyze; if absent, use the current working-tree diff. -- Follow that skill's read-only workflow and guardrails (shallow `max_depth` first; it identifies impact, it does not run tests). +- Read-only: shallow `max_depth` first. Identify impact; do not run tests. Output: impacted symbols + files, the test set to run, and any hub/coupling risk. diff --git a/plugin/overlays/cursor/commands/tracedecay-fix-build.md b/plugin/overlays/cursor/commands/tracedecay-fix-build.md index 68ba2bf52..ff8401add 100644 --- a/plugin/overlays/cursor/commands/tracedecay-fix-build.md +++ b/plugin/overlays/cursor/commands/tracedecay-fix-build.md @@ -4,9 +4,9 @@ description: Fix build and type errors by running or parsing diagnostics, mappin # /tracedecay-fix-build -Apply the `tracedecay:fixing-build-and-type-errors` skill. +Use `tracedecay:fixing-build-and-type-errors`. - **Args:** if `$ARGUMENTS` contains pasted `cargo`/`clippy` output, route it to `tracedecay_diagnose`; otherwise run `tracedecay_diagnostics` (scoped to a directory if one was given). -- Follow that skill's guardrails: prefer pasted output when available; `tracedecay_diagnostics` runs the toolchain, so respect Cursor approval/run-mode. +- Prefer pasted output when available. `tracedecay_diagnostics` runs the toolchain, so respect Cursor approval/run-mode. Output: grouped diagnostics with enclosing symbols + callers, the applied fix, and a clean re-check. diff --git a/plugin/overlays/cursor/commands/tracedecay-map-architecture.md b/plugin/overlays/cursor/commands/tracedecay-map-architecture.md index b6a162d6c..b208629af 100644 --- a/plugin/overlays/cursor/commands/tracedecay-map-architecture.md +++ b/plugin/overlays/cursor/commands/tracedecay-map-architecture.md @@ -4,9 +4,9 @@ description: Map repo or directory architecture, including layered modules, depe # /tracedecay-map-architecture -Apply the `tracedecay:code-health` skill. +Use `tracedecay:code-health`. - **Scope:** the whole repo, or the directory named in `$ARGUMENTS` if one was given. -- Follow that skill's read-only workflow and guardrails; don't restate the tool ladder here. +- Read-only. Output: a layered module map, dependency hotspots/violations, and a prioritized risk list. diff --git a/plugin/overlays/cursor/commands/tracedecay-port-code.md b/plugin/overlays/cursor/commands/tracedecay-port-code.md index ece36ae2a..3b58d90c6 100644 --- a/plugin/overlays/cursor/commands/tracedecay-port-code.md +++ b/plugin/overlays/cursor/commands/tracedecay-port-code.md @@ -4,9 +4,9 @@ description: Port or migrate code between directories in dependency-safe order a # /tracedecay-port-code -Apply the `tracedecay:editing-safely` skill. +Use `tracedecay:editing-safely`. - **Args:** interpret `$ARGUMENTS` as " "; if absent, ask for the source and target directories. -- Follow that skill's dependency-safe workflow and guardrails (port leaves first; respect Cursor approval/run-mode for edits and toolchain runs). +- Port leaves first. Respect Cursor approval/run-mode for edits and toolchain runs. Output: updated port status (done / remaining) and the per-batch typecheck result. diff --git a/plugin/overlays/cursor/commands/tracedecay-recall-memory.md b/plugin/overlays/cursor/commands/tracedecay-recall-memory.md index 3365e87ab..31a639f10 100644 --- a/plugin/overlays/cursor/commands/tracedecay-recall-memory.md +++ b/plugin/overlays/cursor/commands/tracedecay-recall-memory.md @@ -4,10 +4,10 @@ description: Recall prior decisions, durable facts, and past session conversatio # /tracedecay-recall-memory -Apply the `tracedecay:project-memory` skill, and for raw conversation recall the `tracedecay:recalling-session-context` skill. +Use `tracedecay:project-memory`; for raw conversation recall, use `tracedecay:recalling-session-context`. - **Args:** interpret `$ARGUMENTS` as the question or topic to recall; if absent, ask what to look up. -- Route durable decisions/facts through `fact_store` search; route "what happened in that session" through `tracedecay_message_search` and the LCM retrieval ladder. Follow both skills' read-only guardrails. +- Route durable decisions/facts through `fact_store` search; route "what happened in that session" through `tracedecay_message_search` and the LCM retrieval ladder. Stay read-only. - If the user asks to update, delete, merge, or prune stored facts, switch to `/tracedecay-curate-memory` / `tracedecay:project-memory`. Output: the recalled decisions/messages with their sources (fact, session id, timestamp). diff --git a/plugin/overlays/cursor/commands/tracedecay-review-diff.md b/plugin/overlays/cursor/commands/tracedecay-review-diff.md index 498ed92f1..583f88164 100644 --- a/plugin/overlays/cursor/commands/tracedecay-review-diff.md +++ b/plugin/overlays/cursor/commands/tracedecay-review-diff.md @@ -4,9 +4,9 @@ description: Review the current PR or diff for impact, risk, and quality via the # /tracedecay-review-diff -Apply the `tracedecay:reviewing-changes` skill. +Use `tracedecay:reviewing-changes`. - **Scope:** the current working-tree diff, or the base ref / PR named in `$ARGUMENTS` if one was given. -- Follow that skill's read-only workflow and guardrails (no edits or test runs; to verify behavior, hand off to `tracedecay:assessing-impact`). +- Read-only: no edits or test runs. To verify behavior, hand off to `tracedecay:assessing-impact`. Output: findings grouped Critical / Warning / Note, the impacted areas, and the test set to run. diff --git a/plugin/overlays/cursor/commands/tracedecay-test-changes.md b/plugin/overlays/cursor/commands/tracedecay-test-changes.md index ac9004028..3775e7f71 100644 --- a/plugin/overlays/cursor/commands/tracedecay-test-changes.md +++ b/plugin/overlays/cursor/commands/tracedecay-test-changes.md @@ -4,9 +4,9 @@ description: Test current changes by running only affected tests and mapping fai # /tracedecay-test-changes -Apply the `tracedecay:assessing-impact` skill. +Use `tracedecay:assessing-impact`. - **Args:** interpret `$ARGUMENTS` as explicit changed paths; if absent, use the current working tree. -- Follow that skill's workflow and guardrails (`tracedecay_run_affected_tests` and `tracedecay_diagnostics` run cargo-backed checks — respect Cursor approval/run-mode; preview scope read-only first). +- Preview scope read-only first. `tracedecay_run_affected_tests` and `tracedecay_diagnostics` run cargo-backed checks; respect Cursor approval/run-mode. Output: pass/fail summary, failing-symbol mapping, and suggested missing tests. diff --git a/plugin/skills/tracedecay-audit-safety/SKILL.md b/plugin/skills/tracedecay-audit-safety/SKILL.md index bfad20c61..4b2d2aac2 100644 --- a/plugin/skills/tracedecay-audit-safety/SKILL.md +++ b/plugin/skills/tracedecay-audit-safety/SKILL.md @@ -5,11 +5,11 @@ description: 'Use to audit the repo or a directory for ship-blocking risk, panic # Audit safety -Use when asked to audit the repo or a directory for ship-blocking risk, panic sites, risk markers, dead code, or untested high-risk symbols. +Use for repo or directory audits covering ship-blocking risk, panic sites, risk markers, dead code, or untested high-risk symbols. -Route this through the `tracedecay:reviewing-changes` skill. +Use `tracedecay:reviewing-changes`. - **Scope:** the whole repo, or a specific directory if one is named. -- Follow that skill's read-only workflow and guardrails: report findings, do not fix them here. +- Read-only: report findings, do not fix them here. Output: findings grouped Critical / Warning / Note with file + enclosing symbol, and a prioritized follow-up list. diff --git a/plugin/skills/tracedecay-check-health/SKILL.md b/plugin/skills/tracedecay-check-health/SKILL.md index 9fc103ee4..7d8c7b3d4 100644 --- a/plugin/skills/tracedecay-check-health/SKILL.md +++ b/plugin/skills/tracedecay-check-health/SKILL.md @@ -5,11 +5,11 @@ description: 'Use to check code health for the repo or a directory, including wo # Check health -Use when asked to check code health for the repo or a directory, including worst offenders and a prioritized fix list. +Use for repo or directory code-health checks, worst offenders, and prioritized fix lists. -Route this through the `tracedecay:code-health` skill. +Use `tracedecay:code-health`. - **Scope:** the whole repo, or a specific directory if one is named. -- Follow that skill's read-only workflow and guardrails: lead with `tracedecay_health` and drill only into weak dimensions. +- Read-only: lead with `tracedecay_health` and drill only into weak dimensions. Output: the composite health score + weak dimensions, the worst offenders (complexity, duplication, god files, doc gaps, panic sites, test-risk), and a prioritized fix list. diff --git a/plugin/skills/tracedecay-clean-dead-code/SKILL.md b/plugin/skills/tracedecay-clean-dead-code/SKILL.md index 19f0ca26b..0aa041815 100644 --- a/plugin/skills/tracedecay-clean-dead-code/SKILL.md +++ b/plugin/skills/tracedecay-clean-dead-code/SKILL.md @@ -5,11 +5,11 @@ description: 'Use to find and safely remove dead code, unused imports, and dupli # Clean dead code -Use when asked to find and safely remove dead code, unused imports, or duplication. +Use to find and safely remove dead code, unused imports, or duplication. -Route this through the `tracedecay:reviewing-changes` skill to identify candidates, then apply `tracedecay:editing-safely` for any removals. +Use `tracedecay:reviewing-changes` to identify candidates, then `tracedecay:editing-safely` for removals. - **Scope:** the whole repo, or a specific directory if one is named. -- Follow those skills' guardrails: confirm zero real callers before deleting anything, be conservative with `pub` items, and verify with a build/test re-check after edits. +- Confirm zero real callers before deleting anything; be conservative with `pub` items; verify with a build/test re-check after edits. Output: removed/consolidated items and the before/after health or test result. diff --git a/plugin/skills/tracedecay-compare-branches/SKILL.md b/plugin/skills/tracedecay-compare-branches/SKILL.md index ab7953637..3f5826bc6 100644 --- a/plugin/skills/tracedecay-compare-branches/SKILL.md +++ b/plugin/skills/tracedecay-compare-branches/SKILL.md @@ -5,11 +5,11 @@ description: 'Use to compare or search another git branch''s code graph without # Compare branches -Use when asked to compare or search another git branch's code graph without switching your checkout. +Use to compare or search another git branch's code graph without switching your checkout. -Route this through the `tracedecay:exploring-code` skill, using the cross-branch tools (`tracedecay_branch_list`, `tracedecay_branch_diff`, `tracedecay_branch_search`). +Use `tracedecay:exploring-code` with `tracedecay_branch_list`, `tracedecay_branch_diff`, and `tracedecay_branch_search`. - **Target:** a single branch to compare against the current branch, or " " to diff two branches. If none is given, start with `tracedecay_branch_list` and ask what to search or compare. -- Follow that skill's read-only workflow. If a target branch isn't tracked, tell the user to run `tracedecay branch add ` in the terminal first, and surface any branch-fallback warning. +- Read-only. If a target branch isn't tracked, tell the user to run `tracedecay branch add ` first, and surface any branch-fallback warning. Output: the cross-branch search hits or the added/removed/changed symbol lists. diff --git a/plugin/skills/tracedecay-curate-memory/SKILL.md b/plugin/skills/tracedecay-curate-memory/SKILL.md index 16adeded9..96bf9f242 100644 --- a/plugin/skills/tracedecay-curate-memory/SKILL.md +++ b/plugin/skills/tracedecay-curate-memory/SKILL.md @@ -5,9 +5,9 @@ description: 'Use to curate, update, delete, or inspect TraceDecay memory facts # Curate memory -Use when asked to curate, update, delete, or inspect TraceDecay memory facts, or to do dashboard curation. +Use to curate, update, delete, or inspect TraceDecay memory facts, or to do dashboard curation. -Route this through the `tracedecay:project-memory` skill. +Use `tracedecay:project-memory`. - **Scope:** the fact, entity, query, or curation action to review. If none is given, ask what memory scope to curate before mutating anything. - Start read-only with `tracedecay_fact_store` search/list/probe/reason/contradict or `tracedecay_memory_status`; open `tracedecay_dashboard` only when the user wants visual curation. diff --git a/plugin/skills/tracedecay-draft-commit/SKILL.md b/plugin/skills/tracedecay-draft-commit/SKILL.md index fec4ef4b4..f25a53a85 100644 --- a/plugin/skills/tracedecay-draft-commit/SKILL.md +++ b/plugin/skills/tracedecay-draft-commit/SKILL.md @@ -5,11 +5,11 @@ description: 'Use to draft a commit message, PR description, or changelog from s # Draft commit -Use when asked to draft a commit message, PR description, or changelog from the current semantic changes. +Use to draft a commit message, PR description, or changelog from current semantic changes. -Route this through the `tracedecay:reviewing-changes` skill to read the diff and its impact. +Use `tracedecay:reviewing-changes` to read the diff and impact. - **Target:** the artifact to draft (e.g. "pr", "changelog", a base ref, or "staged"). If none is given, draft a commit message for the working-tree/staged changes. -- Follow that skill's guardrails: this drafts text only — leave `git commit` / `gh pr create` to the user unless they explicitly ask. +- Draft text only — leave `git commit` / `gh pr create` to the user unless they explicitly ask. Output: the drafted commit / PR / changelog text. diff --git a/plugin/skills/tracedecay-find-impact/SKILL.md b/plugin/skills/tracedecay-find-impact/SKILL.md index 7d87163dd..68300a339 100644 --- a/plugin/skills/tracedecay-find-impact/SKILL.md +++ b/plugin/skills/tracedecay-find-impact/SKILL.md @@ -5,11 +5,11 @@ description: 'Use to find the blast radius of a change, including impacted symbo # Find impact -Use when asked to find the blast radius of a change, including impacted symbols, files, and the tests to run. +Use to find a change's blast radius: impacted symbols, files, and tests to run. -Route this through the `tracedecay:assessing-impact` skill. +Use `tracedecay:assessing-impact`. - **Target:** the symbol, file, or change to analyze. If none is given, use the current working-tree diff. -- Follow that skill's read-only workflow and guardrails: shallow `max_depth` first; it identifies impact, it does not run tests. +- Read-only: shallow `max_depth` first. Identify impact; do not run tests. Output: impacted symbols + files, the test set to run, and any hub/coupling risk. diff --git a/plugin/skills/tracedecay-fix-build/SKILL.md b/plugin/skills/tracedecay-fix-build/SKILL.md index f0be4d26f..688e42279 100644 --- a/plugin/skills/tracedecay-fix-build/SKILL.md +++ b/plugin/skills/tracedecay-fix-build/SKILL.md @@ -5,11 +5,11 @@ description: 'Use to fix build and type errors by running or parsing diagnostics # Fix build -Use when asked to fix build and type errors by running or parsing diagnostics, mapping them to symbols with callers, then fixing. +Use to fix build and type errors by running or parsing diagnostics, mapping them to symbols with callers, then fixing. -Route this through the `tracedecay:fixing-build-and-type-errors` skill. +Use `tracedecay:fixing-build-and-type-errors`. - **Input:** if the user pasted `cargo`/`clippy` output, route it to `tracedecay_diagnose`; otherwise run `tracedecay_diagnostics` (scoped to a directory if one is named). -- Follow that skill's guardrails: prefer pasted output when available; `tracedecay_diagnostics` runs the toolchain, so confirm before running long checks. +- Prefer pasted output when available. `tracedecay_diagnostics` runs the toolchain, so confirm before long checks. Output: grouped diagnostics with enclosing symbols + callers, the applied fix, and a clean re-check. diff --git a/plugin/skills/tracedecay-map-architecture/SKILL.md b/plugin/skills/tracedecay-map-architecture/SKILL.md index 7b659dd4a..0a5a49a87 100644 --- a/plugin/skills/tracedecay-map-architecture/SKILL.md +++ b/plugin/skills/tracedecay-map-architecture/SKILL.md @@ -5,11 +5,11 @@ description: 'Use to map repo or directory architecture, including layered modul # Map architecture -Use when asked to map the repo or a directory's architecture, including layered modules, dependency hotspots, and structural risks. +Use to map repo or directory architecture: layered modules, dependency hotspots, and structural risks. -Route this through the `tracedecay:exploring-code` skill for structure, and `tracedecay:code-health` for dependency hotspots and structural risk. +Use `tracedecay:exploring-code` for structure and `tracedecay:code-health` for dependency hotspots and structural risk. - **Scope:** the whole repo, or a specific directory if one is named. -- Follow those skills' read-only workflow and guardrails. +- Read-only. Output: a layered module map, dependency hotspots/violations, and a prioritized risk list. diff --git a/plugin/skills/tracedecay-port-code/SKILL.md b/plugin/skills/tracedecay-port-code/SKILL.md index 1769f1c22..c95923fdc 100644 --- a/plugin/skills/tracedecay-port-code/SKILL.md +++ b/plugin/skills/tracedecay-port-code/SKILL.md @@ -5,11 +5,11 @@ description: 'Use to port or migrate code between directories in dependency-safe # Port code -Use when asked to port or migrate code between directories in dependency-safe order and track progress. +Use to port or migrate code between directories in dependency-safe order and track progress. -Route this through the `tracedecay:editing-safely` skill, using the port tools (`tracedecay_port_order`, `tracedecay_port_status`). +Use `tracedecay:editing-safely` with `tracedecay_port_order` and `tracedecay_port_status`. - **Args:** " ". If absent, ask for the source and target directories. -- Follow that skill's dependency-safe workflow and guardrails: port leaves first, and confirm before edits and toolchain runs. +- Port leaves first. Confirm before edits and toolchain runs. Output: updated port status (done / remaining) and the per-batch typecheck result. diff --git a/plugin/skills/tracedecay-recall-memory/SKILL.md b/plugin/skills/tracedecay-recall-memory/SKILL.md index 8712126e7..075c4a6fa 100644 --- a/plugin/skills/tracedecay-recall-memory/SKILL.md +++ b/plugin/skills/tracedecay-recall-memory/SKILL.md @@ -5,12 +5,12 @@ description: 'Use to recall prior decisions, durable facts, and past session con # Recall memory -Use when asked to recall prior decisions, durable facts, or past session conversations for this project. +Use to recall prior decisions, durable facts, or past session conversations for this project. Route durable decisions/facts through the `tracedecay:project-memory` skill, and raw conversation recall through the `tracedecay:recalling-session-context` skill. - **Target:** the question or topic to recall. If none is given, ask what to look up. -- Route durable decisions/facts through `fact_store` search; route "what happened in that session" through `tracedecay_message_search` and the LCM retrieval ladder. Follow both skills' read-only guardrails. +- Route durable decisions/facts through `fact_store` search; route "what happened in that session" through `tracedecay_message_search` and the LCM retrieval ladder. Stay read-only. - If the user asks to update, delete, merge, or prune stored facts, switch to `tracedecay:project-memory`. Output: the recalled decisions/messages with their sources (fact, session id, timestamp). diff --git a/plugin/skills/tracedecay-review-diff/SKILL.md b/plugin/skills/tracedecay-review-diff/SKILL.md index dc5be51f1..fa6aab9ee 100644 --- a/plugin/skills/tracedecay-review-diff/SKILL.md +++ b/plugin/skills/tracedecay-review-diff/SKILL.md @@ -5,11 +5,11 @@ description: 'Use to review the current PR or diff for impact, risk, and quality # Review diff -Use when asked to review the current PR or diff for impact, risk, and quality. +Use to review the current PR or diff for impact, risk, and quality. -Route this through the `tracedecay:reviewing-changes` skill. +Use `tracedecay:reviewing-changes`. - **Scope:** the current working-tree diff, or the base ref / PR named if one is given. -- Follow that skill's read-only workflow and guardrails: no edits or test runs; to verify behavior, hand off to `tracedecay:assessing-impact`. +- Read-only: no edits or test runs. To verify behavior, hand off to `tracedecay:assessing-impact`. Output: findings grouped Critical / Warning / Note, the impacted areas, and the test set to run. diff --git a/plugin/skills/tracedecay-test-changes/SKILL.md b/plugin/skills/tracedecay-test-changes/SKILL.md index 0431351f0..3b52922d3 100644 --- a/plugin/skills/tracedecay-test-changes/SKILL.md +++ b/plugin/skills/tracedecay-test-changes/SKILL.md @@ -5,11 +5,11 @@ description: 'Use to test current changes by running only affected tests and map # Test changes -Use when asked to test current changes by running only the affected tests and mapping failures back to source. +Use to test current changes by running only affected tests and mapping failures back to source. -Route this through the `tracedecay:assessing-impact` skill, using the affected-tests tools (`tracedecay_run_affected_tests`, `tracedecay_diagnostics`). +Use `tracedecay:assessing-impact` with `tracedecay_run_affected_tests` and `tracedecay_diagnostics`. - **Input:** explicit changed paths if given; otherwise use the current working tree. -- Follow that skill's workflow and guardrails: `tracedecay_run_affected_tests` and `tracedecay_diagnostics` run cargo-backed checks, so confirm before running; preview scope read-only first. +- Preview scope read-only first. `tracedecay_run_affected_tests` and `tracedecay_diagnostics` run cargo-backed checks, so confirm before running. Output: pass/fail summary, failing-symbol mapping, and suggested missing tests. diff --git a/src/agents/claude_agents/code-explorer.md b/src/agents/claude_agents/code-explorer.md index dd4d33276..2c9ed8c27 100644 --- a/src/agents/claude_agents/code-explorer.md +++ b/src/agents/claude_agents/code-explorer.md @@ -1,6 +1,6 @@ --- 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. +description: Read-only TraceDecay code exploration agent for how/where/what questions, symbol lookup, callers/callees, call chains, and impact analysis. Use to parallelize codebase research or isolate deep exploration. 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 @@ -8,7 +8,7 @@ disallowedTools: mcp__tracedecay__tracedecay_str_replace, mcp__tracedecay__trace # 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. +Read-only exploration subagent. Investigate the repository and return findings. ## Method @@ -19,7 +19,7 @@ You are a read-only exploration subagent. You investigate the repository and ret ## 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. +- Read-only: never edit files, run test runners or diagnostics, or write memory. Mutating TraceDecay tools are disabled for this agent; do not work around that. - Do not spawn nested subagents unless explicitly asked. ## Return diff --git a/src/agents/claude_agents/code-health-auditor.md b/src/agents/claude_agents/code-health-auditor.md index c85e5bed9..466f04f28 100644 --- a/src/agents/claude_agents/code-health-auditor.md +++ b/src/agents/claude_agents/code-health-auditor.md @@ -1,6 +1,6 @@ --- 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. +description: Read-only TraceDecay code-health auditor for health audits, tech-debt reports, scorecards, and worst complexity, duplication, coupling, doc, and test-risk offenders. Use to isolate or parallelize 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 @@ -8,7 +8,7 @@ disallowedTools: mcp__tracedecay__tracedecay_str_replace, mcp__tracedecay__trace # 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. +Read-only audit subagent. Score and rank code health; return findings. ## Method @@ -19,7 +19,7 @@ You are a read-only audit subagent. You score and rank code health and return fi ## 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. +- 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 work around that. - Keep `path`/`max_pairs` tight on `tracedecay_redundancy` (first call can be slow). Do not spawn nested subagents unless asked. ## Return diff --git a/src/agents/claude_agents/session-historian.md b/src/agents/claude_agents/session-historian.md index 292631d54..b74c2c277 100644 --- a/src/agents/claude_agents/session-historian.md +++ b/src/agents/claude_agents/session-historian.md @@ -1,6 +1,6 @@ --- 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. +description: Read-only TraceDecay session-recall agent for prior decisions, past work, 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 @@ -8,7 +8,7 @@ disallowedTools: mcp__tracedecay__tracedecay_str_replace, mcp__tracedecay__trace # 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. +Read-only recall subagent. Retrieve what past sessions said, did, and decided for this project. ## Method @@ -20,7 +20,7 @@ You are a read-only recall subagent. You retrieve what past sessions said, did, ## 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. +- 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. Mutating TraceDecay tools are disabled for this agent; do not work around that. - Do not spawn nested subagents unless explicitly asked. ## Return From 435e08b28c57e1ce2596a58471a22141fb9f66d8 Mon Sep 17 00:00:00 2001 From: ScriptedAlchemy Date: Fri, 3 Jul 2026 22:14:50 +0000 Subject: [PATCH 3/6] test(plugin): remove stale contract commentary --- .../agent_suite/claude_plugin_bundle_test.rs | 4 -- .../agent_suite/plugin_skill_contract_test.rs | 28 +------- .../agent_suite/shared_skill_contract_test.rs | 66 +------------------ tests/agent_suite/update_plugin_test.rs | 22 ------- 4 files changed, 5 insertions(+), 115 deletions(-) diff --git a/tests/agent_suite/claude_plugin_bundle_test.rs b/tests/agent_suite/claude_plugin_bundle_test.rs index 0539ee1d7..2b06992a3 100644 --- a/tests/agent_suite/claude_plugin_bundle_test.rs +++ b/tests/agent_suite/claude_plugin_bundle_test.rs @@ -450,7 +450,3 @@ fn claude_bundle_agents_are_byte_identical_to_the_source_of_truth() { required_scalar(&raw, "description", &bundle_path); } } - -// (Removed `claude_bundle_skills_stay_byte_identical_to_the_codex_source`: -// Claude and Codex now read the identical skills from the single shared -// `plugin/skills/` tree, so there is no second copy to keep in sync.) diff --git a/tests/agent_suite/plugin_skill_contract_test.rs b/tests/agent_suite/plugin_skill_contract_test.rs index ff9a77063..33ae4de20 100644 --- a/tests/agent_suite/plugin_skill_contract_test.rs +++ b/tests/agent_suite/plugin_skill_contract_test.rs @@ -1,13 +1,5 @@ -//! Contract tests for the shared plugin skills: frontmatter schema per host, -//! plus the shared skill-creator design-advice checks. -//! -//! The three host bundles now share one `plugin/` tree. Codex deploys all 29 -//! skills from `plugin/skills/` (canonical, model-invocable form). Cursor -//! deploys only the 16 shared model-invocable skills from `plugin/skills/` -//! (the `tracedecay-*` workflow slugs are native commands on Cursor, not -//! skills). Each host's deployed skill *source* set is staged into a temp dir -//! below so the contract and byte-copy checks run over exactly what that host -//! installs. +//! Host-specific contract tests for skills installed from the shared +//! `plugin/skills/` tree. #![allow(clippy::unwrap_used, clippy::expect_used)] @@ -22,12 +14,7 @@ use tempfile::TempDir; use tracedecay::agents::{expected_tool_perms, get_integration, InstallContext}; use tracedecay::config::USER_DATA_DIR_ENV; -/// Codex deploys every skill under `plugin/skills/` (all 29, canonical form). const CODEX_SKILL_ROOT: &str = "plugin/skills"; -// Metadata budget: a bundle's preloaded name+description metadata stays under -// 6,000 chars (~1.5k tokens) so skill discovery never crowds an agent host's -// context window. The per-skill size budgets (500-line body, 320-char / -// 45-word description) now live in shared_skill_contract_test.rs. const MAX_BUNDLED_SKILL_METADATA_CHARS: usize = 6_000; const CODEX_QUICK_VALIDATE_ALLOWED_FRONTMATTER: &[&str] = &[ "allowed-tools", @@ -114,12 +101,6 @@ fn generated_cursor_plugin_skills_are_byte_copies_of_the_source_bundle() { assert_skill_trees_byte_identical(source_root, &installed_root); } -/// The per-file design rules (trigger-first / length / word / 500-line / -/// no-`## When to Use` / supported-file layout) now live once in -/// `shared_skill_contract_test.rs` over the single `plugin/skills/` tree, which -/// is the same set Codex ships and a superset of Cursor's. This test keeps only -/// what is NOT in that intersection contract: the aggregate metadata budget and -/// the optional `agents/openai.yaml` marketplace contract. #[test] fn produced_plugin_skills_meet_the_metadata_budget_and_openai_contract() { let codex_skills = load_skill_docs(CODEX_SKILL_ROOT); @@ -137,7 +118,6 @@ fn produced_plugin_skills_meet_the_metadata_budget_and_openai_contract() { } } -/// Serializes the generated-bundle tests, which mutate process-wide env vars. fn install_env_lock() -> tokio::sync::MutexGuard<'static, ()> { PROCESS_ENV_LOCK.blocking_lock() } @@ -160,10 +140,6 @@ fn install_ctx(home: &Path) -> InstallContext { } } -/// Stages the Cursor skill *source* tree into a temp dir: the 17 shared -/// model-invocable skills from `plugin/skills/` (all non-`tracedecay-*` slugs). -/// This mirrors exactly what Cursor deploys — the `tracedecay-*` workflow slugs -/// are native commands on Cursor, not skills. fn staged_cursor_skill_source() -> TempDir { let staged = TempDir::new().expect("temp cursor skill source"); let shared = repo_path("plugin/skills"); diff --git a/tests/agent_suite/shared_skill_contract_test.rs b/tests/agent_suite/shared_skill_contract_test.rs index 9fab66c36..8888bfcde 100644 --- a/tests/agent_suite/shared_skill_contract_test.rs +++ b/tests/agent_suite/shared_skill_contract_test.rs @@ -1,38 +1,7 @@ -//! Unified contract for the single shared `plugin/skills/` tree. +//! Intersection contract for the single shared `plugin/skills/` tree. //! -//! Since the three host bundles collapsed into one `plugin/` tree, there is one -//! model-invocable skill set that every host (Claude, Codex, Cursor) ships -//! byte-identically. This test validates that one set against the **intersection -//! contract** — the rules a SKILL.md must satisfy to install cleanly on *all* -//! three hosts — plus each host's extra allowances. It supersedes the shared -//! frontmatter/description/heading/hygiene checks that previously lived split -//! across `plugin_skill_contract_test.rs` and `skill_lint_cursor_test.rs`. -//! -//! Covered here (the intersection contract, over `plugin/skills/`): -//! - Frontmatter keys ⊆ {name, description, allowed-tools, license, metadata}; -//! `name` matches the directory and is kebab-case; `name`/`description` -//! required and non-empty. -//! - `description`: 50–320 chars, ≤45 words, trigger-first ("Use …"), ends with -//! a period, no angle brackets, unique across the set. -//! - Body: exactly one plain-title H1 (never the slash form), no skipped -//! heading levels, no `## When to Use` section, ≤500 lines. -//! - Hygiene: no BOM, LF-only, exactly one trailing newline, no trailing -//! whitespace/tabs, balanced code fences, non-empty body. -//! - Support-file layout: only SKILL.md + scripts/references/assets/agents. -//! -//! Also validated **separately** (host-extra surfaces): -//! - Cursor native commands (`plugin/overlays/cursor/commands/*.md`): a -//! `# /` H1 matching the file name, and hygiene. -//! - Cursor agent overlay (`plugin/overlays/cursor/agents/*.md`): present and -//! hygienic. -//! - Host-extra frontmatter: Codex is spec-strict (intersection only); Cursor -//! additionally tolerates `disable-model-invocation` / `paths` (none are used -//! in the shared set today, but the allowance is asserted so a future -//! Cursor-only key does not silently pass the strict intersection). -//! -//! Install-time byte-parity (`generated_*_plugin_skills_are_byte_copies_*`) and -//! the metadata/openai.yaml budgets stay in `plugin_skill_contract_test.rs`; -//! this file owns the pure per-file contract over the single source tree. +//! Host-specific install parity stays in `plugin_skill_contract_test.rs`; this +//! file owns per-skill frontmatter, body, hygiene, and support-file rules. #![allow(clippy::unwrap_used, clippy::expect_used)] @@ -44,15 +13,10 @@ use crate::plugin_validation_support::{ is_kebab_case_skill_name, load_skill_docs, relative_files_under, repo_path, SkillDoc, }; -/// The one shared model-invocable skill tree every host ships. const SHARED_SKILL_ROOT: &str = "plugin/skills"; -/// Cursor native slash commands (the 13 `tracedecay-*` workflow slugs). const CURSOR_COMMAND_ROOT: &str = "plugin/overlays/cursor/commands"; -/// Cursor agent overlay. const CURSOR_AGENT_OVERLAY_ROOT: &str = "plugin/overlays/cursor/agents"; -/// The intersection frontmatter whitelist: the keys accepted by *every* host's -/// validator (Codex `quick_validate.py` ∩ Cursor ∩ Claude Agent Skills spec). const INTERSECTION_FRONTMATTER: &[&str] = &[ "allowed-tools", "description", @@ -61,10 +25,6 @@ const INTERSECTION_FRONTMATTER: &[&str] = &[ "name", ]; -/// Cursor tolerates two extra keys on top of the intersection. None are used in -/// the shared set today (workflow dispatch is native commands), but the -/// allowance is documented so the strict intersection check below can point at -/// it if a Cursor-only key ever appears. const CURSOR_EXTRA_FRONTMATTER: &[&str] = &["disable-model-invocation", "paths"]; const MIN_DESCRIPTION_CHARS: usize = 50; @@ -94,7 +54,6 @@ fn scalar<'a>(skill: &'a SkillDoc, field: &str) -> Option<&'a str> { .and_then(SkillFrontmatterValue::as_scalar) } -/// ATX headings outside code fences, as (level, text-after-hashes). fn unfenced_headings(body: &str) -> Vec<(usize, String)> { let mut in_fence = false; let mut headings = Vec::new(); @@ -124,9 +83,6 @@ fn shared_skills_pass_the_intersection_frontmatter_contract() { for skill in &skills { let at = skill.path.display(); - // Frontmatter keys ⊆ the intersection whitelist. A Cursor-only key - // (disable-model-invocation / paths) would break Codex/Claude, so the - // shared set must not carry it. for key in skill.frontmatter.keys() { if !INTERSECTION_FRONTMATTER.contains(&key.as_str()) { let hint = if CURSOR_EXTRA_FRONTMATTER.contains(&key.as_str()) { @@ -141,7 +97,6 @@ fn shared_skills_pass_the_intersection_frontmatter_contract() { } } - // name required, matches dir, kebab-case, ≤64 chars. match scalar(skill, "name") { None => violations.push(format!("{at}: missing name")), Some(name) => { @@ -198,8 +153,6 @@ fn shared_skill_descriptions_meet_the_intersection_budget() { "{at}: description over {MAX_DESCRIPTION_WORDS} words" )); } - // Trigger-first: agents route on metadata alone, so a "Use …" trigger - // must lead or follow a short capability summary. if !(description.starts_with("Use ") || description.contains(". Use ")) { violations.push(format!( "{at}: description must be trigger-first (\"Use …\")" @@ -227,7 +180,6 @@ fn shared_skill_bodies_follow_the_intersection_body_rules() { let at = skill.path.display(); let headings = unfenced_headings(&skill.body); - // Exactly one H1, plain-title form (never `# /slug`). let h1s: Vec<&String> = headings .iter() .filter(|(level, _)| *level == 1) @@ -247,9 +199,6 @@ fn shared_skill_bodies_follow_the_intersection_body_rules() { } } - // The first content line after the frontmatter must be that H1: a - // single plain-title H1 opens the body (restores the retired - // `cursor_skill_bodies_follow_heading_conventions` check). match skill.body.lines().find(|line| !line.trim().is_empty()) { Some(first) if first.starts_with("# ") => {} Some(first) => violations.push(format!( @@ -258,7 +207,6 @@ fn shared_skill_bodies_follow_the_intersection_body_rules() { None => {} // empty-body already flagged by the hygiene test } - // No skipped heading levels. let mut prev = 0usize; for (level, text) in &headings { if prev > 0 && *level > prev + 1 { @@ -267,14 +215,12 @@ fn shared_skill_bodies_follow_the_intersection_body_rules() { prev = *level; } - // Trigger lives in the description, never a body `## When to Use`. if skill.raw.to_ascii_lowercase().contains("\n## when to use") { violations.push(format!( "{at}: body must not carry a `## When to Use` section" )); } - // ≤500 lines. let lines = skill.raw.lines().count(); if lines > MAX_SKILL_MD_LINES { violations.push(format!("{at}: {lines} lines exceeds {MAX_SKILL_MD_LINES}")); @@ -326,8 +272,6 @@ fn shared_skill_files_are_hygienic_and_use_supported_layout() { } } - // Support-file layout: only SKILL.md + the allowed resource dirs, and - // no auxiliary documentation files (keep skill folders lean). let forbidden_doc_files = [ "README.md", "CHANGELOG.md", @@ -365,8 +309,6 @@ fn shared_skill_files_are_hygienic_and_use_supported_layout() { assert_no_violations("hygiene + layout", &violations); } -/// Cursor native commands are a separate surface from the shared skills: they -/// carry the slash-form H1 the model-invocable skills must NOT use. #[test] fn cursor_native_commands_are_hygienic_slash_commands() { let command_dir = repo_path(CURSOR_COMMAND_ROOT); @@ -405,8 +347,6 @@ fn cursor_native_commands_are_hygienic_slash_commands() { assert_no_violations("cursor commands", &violations); } -/// The Cursor agent overlay is a small separate surface; assert it ships and is -/// LF-clean so a byte-copy install of it stays stable. #[test] fn cursor_agent_overlay_is_present_and_clean() { let overlay = repo_path(CURSOR_AGENT_OVERLAY_ROOT); diff --git a/tests/agent_suite/update_plugin_test.rs b/tests/agent_suite/update_plugin_test.rs index 023435dc9..455a02792 100644 --- a/tests/agent_suite/update_plugin_test.rs +++ b/tests/agent_suite/update_plugin_test.rs @@ -717,31 +717,10 @@ fn config_only_integrations_report_config_only_and_write_nothing() { } } -// --------------------------------------------------------------------------- -// Rendered-output structural validation -// -// The install/update-plugin renderers rewrite bundle commands to the absolute -// tracedecay binary path and stamp the package version. The tests above prove -// user config survives a refresh; this section proves the RENDERED artifacts -// themselves are structurally sound: manifests stay schema-shaped, hook -// commands are absolute and shell-quoted, no template placeholder survives -// rendering except the one intentional `${workspaceFolder}` in Cursor's -// mcp.json args, and no source-bundle file is silently dropped. -// --------------------------------------------------------------------------- - -/// Stages a host's deploy-relative source tree from the shared `plugin/` tree -/// into a temp dir. The shared tree stores host files under host-specific names -/// (e.g. `mcp-cursor.json`, `README-cursor.md`, `hooks/hooks-cursor.json`); -/// staging maps them to their deploy paths so `assert_source_bundle_fully_rendered` -/// compares the correct expected file set. Returns the temp dir (kept alive by -/// the caller). fn staged_host_source(host: &str) -> TempDir { let src = Path::new(env!("CARGO_MANIFEST_DIR")).join("plugin"); let staged = TempDir::new().expect("temp host source"); let mut copies: Vec<(String, String)> = Vec::new(); - // Shared canonical skills — same deploy path for all hosts. Codex ships all - // 30; Cursor ships only the 17 model-invocable ones (the `tracedecay-*` - // workflow slugs are native commands on Cursor, not skills). for name in subdir_names(&src.join("skills")) { if host == "cursor" && name.starts_with("tracedecay-") { continue; @@ -751,7 +730,6 @@ fn staged_host_source(host: &str) -> TempDir { } match host { "cursor" => { - // Cursor ships the 13 workflow slugs as native slash commands. for entry in std::fs::read_dir(src.join("overlays/cursor/commands")).unwrap() { let file = entry.unwrap().file_name().to_string_lossy().into_owned(); copies.push(( From 4a1297e4cac5f0b93ce3d0672923df07efcda652 Mon Sep 17 00:00:00 2001 From: ScriptedAlchemy Date: Fri, 3 Jul 2026 22:14:53 +0000 Subject: [PATCH 4/6] docs(plugin): condense validation guidance --- .github/workflows/plugin-validation.yml | 24 +---- docs/AGENT-MEMORY-INTERCEPTION.md | 84 ++++++--------- docs/PLUGIN-VALIDATION.md | 138 +++++++++--------------- 3 files changed, 90 insertions(+), 156 deletions(-) diff --git a/.github/workflows/plugin-validation.yml b/.github/workflows/plugin-validation.yml index b85bc8ee7..888ceccdb 100644 --- a/.github/workflows/plugin-validation.yml +++ b/.github/workflows/plugin-validation.yml @@ -1,12 +1,8 @@ -# Schema/lint layer for the shipped agent plugin bundles. Mirrors the official -# Cursor marketplace validation workflow: +# Schema/lint layer for the shipped agent plugin bundles. Mirrors: # https://github.com/cursor/plugins/blob/main/.github/workflows/validate-plugins.yml -# (ajv + ajv-formats against the plugin/marketplace JSON schemas; the schemas -# are vendored in tests/fixtures/cursor-schemas/). # -# The Rust contract tests for the bundles already run in ci.yml — do not add -# plain cargo test jobs here. The MCP conformance smoke below is the one -# exception: it needs a built binary plus npx, which cargo test can't provide. +# Rust contract tests already run in ci.yml. Keep this workflow to schema checks +# and the SDK-backed MCP smoke, which needs a built binary plus npx. name: Plugin Validation on: @@ -14,13 +10,9 @@ on: paths: - "plugin/**" - "tests/fixtures/cursor-schemas/**" - # Plugin/skill test modules (e.g. plugin_manifest_schema_test.rs, - # plugin_skill_contract_test.rs, the skill lint tests). - "tests/agent_suite/*plugin*" - "tests/agent_suite/*skill*" - "scripts/mcp-conformance-smoke.sh" - # The Inspector smoke is the workflow's SDK-backed coverage for - # `tracedecay serve` protocol and tool-schema compatibility. - "src/serve.rs" - "src/main.rs" - "src/lib.rs" @@ -48,7 +40,6 @@ jobs: with: node-version: 22 - # Pinned, unlike upstream's floating `npm install ajv ajv-formats`. - name: Install ajv-cli run: npm install --no-save ajv-cli@5.0.0 ajv-formats@2.1.1 @@ -66,9 +57,6 @@ jobs: -s tests/fixtures/cursor-schemas/plugin.schema.json \ -d plugin/.cursor-plugin/plugin.json - # The Codex manifest follows Codex's own layout (e.g. its `interface` - # block), so the Cursor schema does not apply; keep it to a strict JSON - # well-formedness check alongside the other bundle JSON files. - name: Check bundle JSON files parse run: | set -euo pipefail @@ -79,10 +67,8 @@ jobs: echo "ok: $f" done - # Drives a real `tracedecay serve` stdio server through the MCP Inspector - # CLI (pinned version), which embeds the official TypeScript MCP SDK client - # — covering protocol-version negotiation and SDK-side schema validation - # that the in-repo Rust MCP tests cannot. See scripts/mcp-conformance-smoke.sh. + # Uses MCP Inspector's TypeScript SDK client to cover stdio handshake and + # schema compatibility beyond the in-repo Rust MCP tests. mcp-conformance-smoke: name: MCP conformance smoke runs-on: ubuntu-latest diff --git a/docs/AGENT-MEMORY-INTERCEPTION.md b/docs/AGENT-MEMORY-INTERCEPTION.md index d4bbfbe0d..bda82943d 100644 --- a/docs/AGENT-MEMORY-INTERCEPTION.md +++ b/docs/AGENT-MEMORY-INTERCEPTION.md @@ -1,24 +1,16 @@ # Agent Memory Interception: Codex CLI & Cursor × TraceDecay Fact Store -**Status:** research + design proposal (2026-07-02). +**Status:** research + design proposal (2026-07-02; plugin paths refreshed +2026-07-03). **Goal:** make Codex CLI and Cursor use the TraceDecay holographic fact store (`tracedecay_fact_store` add/search/probe/reason, `memory_facts` table, HRR vectors + trust scores) as their agent memory for both **recall** (facts reach the model at the right moment) and **storage** (new durable facts get written), instead of — or layered on top of — each agent's native memory mechanism. -All file paths below were verified on this machine (Codex CLI 0.142.4, Cursor -with hooks + plugins, tracedecay plugin v0.0.23 installed for both agents). - -> **Note (as of 2026-07-03):** the per-host `cursor-plugin/` / `codex-plugin/` -> source trees have since collapsed into a single shared `plugin/` tree, so -> skill/command/agent sources now live under `plugin/skills/…`, -> `plugin/commands/…`, and `plugin/agents/…` (Cursor-only surfaces under -> `plugin/overlays/cursor/…`). The `recalling-project-memory` and -> `curating-project-memory` skills were also merged into a single -> `project-memory` skill. References below to the old paths/slugs are retained -> as historical design context; the current locations are the shared-tree -> equivalents. +Current plugin source lives under the shared `plugin/` tree: shared skills in +`plugin/skills/`, Claude commands in `plugin/commands/`, shared agents in +`plugin/agents/`, and Cursor-only surfaces in `plugin/overlays/cursor/`. --- @@ -169,8 +161,9 @@ tool calls (reliable but discretionary). **Storage** interception rides on ### 3.1 `tracedecay install --agent cursor` (`src/agents/cursor.rs`) -Writes an embedded plugin (`EMBEDDED_PLUGIN_FILES`, `src/agents/cursor.rs:175`) -to `~/.cursor/plugins/local/tracedecay/`: +Writes the Cursor projection of the shared plugin bundle +(`src/agents/plugin_bundle.rs::cursor_files`) to +`~/.cursor/plugins/local/tracedecay/`: - **`mcp.json`** — stdio server `tracedecay serve --path ${workspaceFolder}` (all fact-store/memory/graph tools available to the model). @@ -182,11 +175,12 @@ to `~/.cursor/plugins/local/tracedecay/`: - **`rules/tracedecay.mdc`** — always-applied rule; its **Recall** bullet steers models to `tracedecay_message_search` / `tracedecay_fact_store` search and the `project-memory` skill. -- **`skills/`** — 25+ workflow skills incl. `project-memory` (the merged - recall+curate memory skill) and `recalling-session-context`; plus an - agent-managed skill overlay (`install_cursor_managed_skill_overlay`). -- **`agents/`** — `code-explorer`, `code-health-auditor`, `session-historian` - subagent definitions. +- **`skills/`** — shared model-invocable skills, excluding the + `tracedecay-*` dispatcher skills that Cursor exposes as native commands. +- **`commands/`** — Cursor-native workflow commands from + `plugin/overlays/cursor/commands/`. +- **`agents/`** — Cursor agent definitions from + `plugin/overlays/cursor/agents/`. What the hooks currently do (all fail-open): @@ -205,8 +199,8 @@ What the hooks currently do (all fail-open): ### 3.2 `tracedecay install --agent codex` (`src/agents/codex.rs`) -Installs a **plugin bundle** (`CODEX_EMBEDDED_PLUGIN_FILES`, -`src/agents/codex.rs:209`) to +Installs the Codex projection of the shared plugin bundle +(`src/agents/plugin_bundle.rs::codex_files`) to `~/.codex/plugins/cache/personal/tracedecay//` plus a personal marketplace entry (`install_codex_marketplace_entry`) and `[plugins."tracedecay@personal"] enabled = true` in `config.toml`: @@ -218,7 +212,8 @@ marketplace entry (`install_codex_marketplace_entry`) and `PostToolUse` (matcher `Bash|apply_patch`), `PostCompact` (matcher `auto|manual`). Hooks require one-time `/hooks` trust (`print_hook_trust_guidance`); trusted hashes live in `[hooks.state]`. -- **`skills/`** — same 25 workflow skills + `agent-managed/` overlay. +- **`skills/`** — shared skills from `plugin/skills/` plus the + `agent-managed/` overlay. - **No rule surface exists in Codex**, so the steering text Cursor gets via `tracedecay.mdc` is injected through `SessionStart`/`UserPromptSubmit` `additionalContext` instead (`build_codex_session_context`, @@ -300,13 +295,9 @@ model electing to call an MCP tool; storage depends on the user saying --- -## 5. Ranked integration designs - -Ranked by effect ÷ effort. A + B are the core; C–F layer on. +## 5. Integration designs -### A. Codex per-prompt & session-start fact injection via existing hooks — **do first** - -*Effort: S–M. Effect: high. Risk: low (fail-open, additive).* +### A. Codex per-prompt & session-start fact injection via existing hooks Codex is the lowest-effort path because `UserPromptSubmit` carries the prompt text and honors `hookSpecificOutput.additionalContext`, and the hook binary is @@ -335,9 +326,7 @@ Implementation pointers: `src/hooks/codex.rs`, `src/hooks/cursor.rs`, change; hook hashes change → users re-trust via `/hooks` (already documented in the Codex plugin README). -### B. Cursor session-start injection + a materialized memory rule — **do with A** - -*Effort: M. Effect: high (rule) / medium (hook, due to Cursor bugs). Risk: low.* +### B. Cursor session-start injection + a materialized memory rule Per-prompt injection is impossible in Cursor (§2.3), so combine the two channels that exist: @@ -358,16 +347,13 @@ channels that exist: and/or a scheduler task. Keep it small (facts are one-liners; cap ~1–2 KB) and deterministic (sorted) so diffs are reviewable. -Implementation pointers: rule generation next to -`cursor_plugin_manifest`/`write_embedded_plugin` (`src/agents/cursor.rs:404`), -refresh in `hook_cursor_workspace_open` (`src/hooks/cursor.rs`); mark the file -managed the same way the skill overlay marks generated skills -(`managed_skill_format.rs`) so uninstall (`remove_cursor_plugin_install`) and -doctor checks cover it. +Implementation pointers: add the managed rule to the Cursor projection in +`src/agents/plugin_bundle.rs` / `src/agents/cursor.rs`, refresh it from +`hook_cursor_workspace_open` (`src/hooks/cursor.rs`), and mark it managed the +same way generated skills are marked (`managed_skill_format.rs`) so uninstall +and doctor checks cover it. -### C. Rule/skill text: make storage proactive — **small, ship with A/B** - -*Effort: XS. Effect: medium. Risk: memory spam (mitigated by write-time dedupe).* +### C. Rule/skill text: make storage proactive Today `project-memory`'s guardrail says add facts "**only when the user asks**" — the opposite of agent-memory behavior. Change the instruction @@ -384,9 +370,7 @@ user asks**" — the opposite of agent-memory behavior. Change the instruction This mirrors Cursor's hybrid design (sidecar + tool calls), with the tool-call half pointed at TraceDecay. -### D. Enable the reflection loop (sidecar-equivalent storage) — **medium** - -*Effort: S (config/UX) — the code exists. Effect: high over time.* +### D. Enable the reflection loop (sidecar-equivalent storage) session_reflector is the background sidecar analog: transcripts (both agents, already ingested by the hooks) → evidence-cited fact proposals → dashboard @@ -404,9 +388,7 @@ Pointers: `src/automation/config.rs` (defaults/validation), dashboard curation UI (concurrent work in `dashboard/` — coordinate, don't touch). -### E. Codex-native-memory coexistence policy — **decide, small change** - -*Effort: XS–S. Effect: avoids divergence/duplication.* +### E. Codex-native-memory coexistence policy With `features.memories = true`, Codex builds a parallel memory in `~/.codex/memories/` from the same sessions. Options: @@ -430,9 +412,7 @@ is the Settings toggle. Once B+C are live, recommend users disable "Generate Memories" to keep one memory system (document in `KIRO-INTEGRATION.md`-style agent doc; can't be automated). -### F. Materialized `AGENTS.md` / memory-file generation — **fallback, partial overlap with B2** - -*Effort: M. Effect: medium. Risk: touches user-owned files.* +### F. Materialized `AGENTS.md` / memory-file generation Scheduled materialization of facts into files agents read natively without any tool call: a `## Memory (generated by tracedecay)` fenced section in repo @@ -466,8 +446,8 @@ alongside D and reusing the managed-file conventions from the skill overlay. + `src/memory/retrieval.rs` helpers; measurable via existing hook analytics. 2. **B2 + C** (materialized Cursor memory rule + proactive storage wording) — - one PR in `src/agents/cursor.rs` embedded files + plugin rule/skill text - (shared skill text under `plugin/skills/`). + one PR in `src/agents/plugin_bundle.rs`, `src/agents/cursor.rs`, and plugin + rule/skill text (shared skill text under `plugin/skills/`). 3. **D** (reflector enablement UX) — config/doctor/dashboard nudge. 4. **E** (coexistence policy + optional Codex-memories harvest importer). 5. **F** (generalized AGENTS.md materialization across all 15 agent diff --git a/docs/PLUGIN-VALIDATION.md b/docs/PLUGIN-VALIDATION.md index 8df742f4f..7c93d6a7a 100644 --- a/docs/PLUGIN-VALIDATION.md +++ b/docs/PLUGIN-VALIDATION.md @@ -1,29 +1,21 @@ # Plugin and Skill Validation -> **Layout note (single-bundle rearchitecture):** the three duplicated bundles -> `cursor-plugin/`, `codex-plugin/`, and `claude-plugin/` have been collapsed -> into one shared `plugin/` tree. Shared skills live in `plugin/skills/`; -> per-host manifests live in `plugin/.cursor-plugin/`, `plugin/.codex-plugin/`, -> `plugin/.claude-plugin/`; per-host hooks are `plugin/hooks/hooks-.json`; -> MCP configs are `plugin/.mcp.json` (Claude/Codex) and `plugin/mcp-cursor.json` -> (Cursor, deployed as `mcp.json`); READMEs are `plugin/README-.md`; and -> Cursor's 13 workflow slugs ship as native Cursor 1.6+ slash commands -> (`plugin/overlays/cursor/commands/*.md`, deployed to `commands/` and declared -> by the manifest's `commands` key), *not* as `disable-model-invocation` -> dispatcher skills. Cursor's shared skill set is therefore the 17 canonical -> model-invocable skills, byte-identical to Claude/Codex. The composed per-host -> deploy set is owned by `src/agents/plugin_bundle.rs`. Sections below that -> describe cross-bundle *parity/mirroring* are historical — with one shared tree -> there is nothing to keep in sync. +> **Current layout:** all agent bundles are composed from the shared +> `plugin/` tree. Skills live in `plugin/skills/`; per-host manifests in +> `plugin/.{cursor,codex,claude}-plugin/`; hooks in +> `plugin/hooks/hooks-.json`; host READMEs in `plugin/README-.md`. +> Cursor's workflow dispatchers deploy as native Cursor 1.6+ commands from +> `plugin/overlays/cursor/commands/*.md`; Claude uses `plugin/commands/*.md`. +> `src/agents/plugin_bundle.rs` owns each host's deployed file set. How the bundled agent plugins (shared `plugin/` tree) and their skills are validated, where each check runs, and how to extend the system without breaking the contracts. -This document covers the validation of the *agent integration bundles* — the -Cursor plugin, the Codex plugin, and their skills, hooks, rules, and MCP -registrations. It is unrelated to the language-extractor plugin runtime -described in [`PLUGINS-DESIGN.md`](PLUGINS-DESIGN.md). +This document covers the bundled Cursor, Codex, and Claude integrations: +skills, commands, hooks, rules, manifests, and MCP registrations. It is +unrelated to the language-extractor plugin runtime described in +[`PLUGINS-DESIGN.md`](PLUGINS-DESIGN.md). --- @@ -64,7 +56,7 @@ never validates schemas at runtime). Beyond schema shape, `tests/agent_suite/plugin_manifest_schema_test.rs` also asserts that every component path a manifest declares (`skills/`, `hooks/hooks.json`, `rules/*.mdc`, …) resolves to a real file or directory in the bundle, and -that both bundles share the same plugin `name`. The config-schema tests +that host manifests share the same plugin `name`. The config-schema tests include negative cases proving the mcp/hooks schemas actually reject malformed configs (missing `command`, unknown fields, typo'd event names). @@ -101,8 +93,7 @@ matching its file name) and the Cursor agent overlay. `tests/agent_suite/plugin_skill_contract_test.rs` now owns only what is *not* in the intersection: the aggregate 6,000-char metadata budget, the optional -`agents/openai.yaml` marketplace contract, the per-host frontmatter allowances -(Codex `quick_validate.py`; Cursor's `disable-model-invocation`/`paths`), and +`agents/openai.yaml` marketplace contract, Codex `quick_validate.py`, and **byte-copy install parity** (installing the Cursor or Codex integration into a temp home must produce a byte-identical copy of the source skill tree — catches install-time mutation and missing embeds; see @@ -130,34 +121,24 @@ skilldoctor, skillkit) and Cursor's skills docs: checked against the live `tracedecay::mcp::get_tool_definitions()` list); `paths` globs must be relative, forward-slash, without `..`. -### 3. Cross-bundle sync (cargo test) - -`cursor-plugin/` is the **source of truth**. The Codex bundle is a mirror of -the Cursor skills, embedded via `include_str!` in `src/agents/codex.rs` and -checked by the unit test `codex_skills_match_the_cursor_source_for_parity`: -every model-invocable Cursor skill (the `hooks::CURSOR_PLUGIN_SKILLS` list in -`src/hooks.rs`) must exist in the Codex bundle, and content divergence is -only allowed through explicit per-skill allowlists in that test. Cursor-only -skills — the `tracedecay-*` slash dispatchers — are exempt from mirroring. - -Practical consequence: **never edit a `codex-plugin/skills/*/SKILL.md` by -hand.** Edit the Cursor source and propagate, or the parity test fails. - -On top of the skill-level parity, `tests/agent_suite/plugin_bundle_sync_test.rs` enforces -disk-level cross-bundle sync through three declarative tables: the bundle -list, a top-level manifest assigning every bundle entry a policy -(`SyncedSkills`, `HostSpecific { reason }`, or `OnlyIn { bundles, reason }`), -and a skill exception table (`OnlyIn`, `DivergentBody`, -`DivergentFrontmatter`). The default is strict — every skill ships in every -bundle with a byte-identical tree — and any deviation needs a documented -exception. The tables are self-cleaning: an undeclared divergence fails, and -so does a *stale* exception (an `OnlyIn` that no longer matches, or a -declared divergence that no longer diverges). The exception table mirrors the -codex.rs allowlists — if the two drift apart, one of the tests fails and -names the other — and the set of skills shared by every bundle must equal -`hooks::CURSOR_PLUGIN_SKILLS`. The assertions are bundle-count agnostic: a -future ecosystem bundle joins the check by adding one `Bundle` row plus its -manifest and exception entries. +### 3. Shared source and host projections (cargo test) + +There is one source tree: `plugin/`. Host bundles are filtered projections of +that tree, composed by `src/agents/plugin_bundle.rs`: + +- Claude deploys manifest, MCP config, hooks, agents, commands, README, and + every file under `plugin/skills/`. +- Codex deploys manifest, MCP config, hooks, README, and every file under + `plugin/skills/`. +- Cursor deploys its manifest, MCP config, hooks, rules, README, native + commands, Cursor agents, and the shared skill files **except** the + `tracedecay-*` dispatcher skills. Those slugs are native Cursor commands. + +`src/agents/plugin_bundle.rs` unit tests check that recursive skill embedding +matches every file under `plugin/skills/`, that Cursor filtering stays +intentional, and that the host file lists remain deterministic. Contract tests +then validate each projected surface: shared skills once, Cursor commands and +agents separately, and Claude/Codex host metadata separately. ### 4. Rendered-output and manifest-path validation (cargo test) @@ -167,7 +148,7 @@ Beyond validating the *source* bundles, install-time output is validated. `.cursor-plugin/plugin.json` inside the plugin root (per [cursor.com/docs/plugins](https://cursor.com/docs/plugins) and the official [cursor/plugins](https://github.com/cursor/plugins) marketplace repo). This -repo already conforms — `cursor-plugin/.cursor-plugin/plugin.json` in source, +repo already conforms — `plugin/.cursor-plugin/plugin.json` in source, and `src/agents/cursor.rs` renders it to `~/.cursor/plugins/local/tracedecay/.cursor-plugin/plugin.json`. The layout is pinned by existing assertions in `tests/agent_suite/agent_test.rs` and @@ -190,22 +171,17 @@ parity in layer 2. ### 5. Claude Code portability (cargo test) -`tests/agent_suite/skill_lint_claude_test.rs` lints every skill in both bundles against -Claude Code / Agent Skills portability rules, so a future `claude-plugin/` -bundle would be a re-packaging exercise rather than a rewrite. The rules -(sources cited in the test's module docs) include: frontmatter keys limited -to Claude-Code-documented fields, kebab-case `name` matching the directory +`tests/agent_suite/skill_lint_claude_test.rs` lints the shared skills against +Claude Code / Agent Skills portability rules. The rules (sources cited in the +test's module docs) include: frontmatter keys limited to Claude-Code-documented +fields, kebab-case `name` matching the directory (≤ 64 chars, no XML tags, no reserved words `anthropic`/`claude`), `description` non-empty with no angle brackets (≤ 1,024 chars, and `description` + `when_to_use` ≤ 1,536 chars — Claude Code truncates listings beyond that), and the shared 6,000-char per-bundle metadata budget. -One Cursor-required field conflicts with the strict Agent Skills open spec — -`disable-model-invocation`. Claude Code itself supports it, so it is a -*documented skip* (`CROSS_ECOSYSTEM_CONFLICT_FIELDS` in the test), with a -stale-allowlist guard that fails if a documented conflict field stops being -used. Any *new* nonconformant field fails the strict-spec test, and the Codex -bundle must stay 100% spec-clean. +Cursor workflow dispatchers are native commands now, so shared skills do not +need Cursor-only `disable-model-invocation` frontmatter. ### 6. Checks outside the Rust test harness @@ -219,7 +195,7 @@ can't do: the official `cursor/plugins` marketplace validation: `ajv` compiles all four vendored schemas (so a broken schema edit fails even when no manifest changed), validates the Cursor manifest against `plugin.schema.json`, and - parse-checks every `*.json` in both bundles. The Codex manifest is only + parse-checks every `*.json` in `plugin/`. The Codex manifest is only parse-checked here (its layout differs from Cursor's); its semantics are covered by the Rust tests. The workflow is path-filtered to bundle, schema, and plugin-test paths, so it shows as *skipped* on unrelated PRs — account @@ -311,33 +287,25 @@ not hand-register `include_str!` entries. ## Adding a new ecosystem bundle -To ship a bundle for another agent host (the way `codex-plugin/` mirrors -`cursor-plugin/`): - -1. **Create the bundle directory** at the repo root (`-plugin/`) with - the host's manifest layout and a `README.md` explaining install and any - host-specific caveats. -2. **Add the integration** in `src/agents/.rs`, embedding bundle files - with `include_str!` so the installed output is generated from the checked-in - source, and register it in `src/agents/mod.rs`. -3. **Treat `cursor-plugin/` as the skill source of truth.** Mirror skills - rather than forking them, and add a parity test in the new integration - module modeled on `codex_skills_match_the_cursor_source_for_parity`, - including a divergence allowlist for justified host-specific edits. -4. **Extend the contract tests:** add the host's frontmatter allowlist and a - contract assertion in - `tests/agent_suite/plugin_skill_contract_test.rs`, plus a byte-copy - install-parity test for the generated bundle. Note that - `tests/agent_suite/` is a single test binary: new modules must be +To ship a bundle for another agent host: + +1. **Add host-specific source files** under `plugin/` or + `plugin/overlays//`, keeping shared skills in `plugin/skills/`. +2. **Add the integration** in `src/agents/.rs`, compose its deployed + file set from `src/agents/plugin_bundle.rs`, and register it in + `src/agents/mod.rs`. +3. **Extend the contract tests:** add any host frontmatter allowlist, + host-specific manifest/config assertions, and install-output validation. + `tests/agent_suite/` is a single test binary, so new modules must be registered in `tests/agent_suite/main.rs`. +4. **Keep skills shared.** Host-specific dispatch belongs in commands, rules, + hooks, or overlays, not forked copies of `plugin/skills/*/SKILL.md`. 5. **Vendor the host's schemas** (if it publishes any) under `tests/fixtures/-schemas/` and validate the bundle's JSON artifacts against them, following the same offline-vendoring rules as the Cursor schemas. -6. **Wire it into the sync/CI layers:** add a `Bundle` row (plus any - divergence exceptions) in `tests/agent_suite/plugin_bundle_sync_test.rs`, and extend - the CI schema-validation workflow's path filters if the new bundle lives - outside the existing globs. +6. **Wire it into CI:** extend `.github/workflows/plugin-validation.yml` path + filters if the new host adds files outside the existing globs. --- From 42d8bf5805b2bc12c20c5fec5e77540422514629 Mon Sep 17 00:00:00 2001 From: ScriptedAlchemy Date: Fri, 3 Jul 2026 22:19:39 +0000 Subject: [PATCH 5/6] docs(plugin): clarify shared bundle contracts --- src/agents/plugin_bundle.rs | 6 +++--- src/automation/skill_frontmatter.rs | 12 ++++++------ 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/src/agents/plugin_bundle.rs b/src/agents/plugin_bundle.rs index 549ddf058..b475e8e73 100644 --- a/src/agents/plugin_bundle.rs +++ b/src/agents/plugin_bundle.rs @@ -48,8 +48,8 @@ pub(crate) fn set_mcp_command(raw: &str, bin: &str) -> Result { Ok(format!("{}\n", serde_json::to_string_pretty(&mcp)?)) } -/// One embedded plugin file: `relative` is its deploy path; `contents` is -/// embedded from the shared `plugin/` tree at compile time. +/// One embedded plugin file: `relative` is its deploy path; `contents` may come +/// from a different source path in the shared `plugin/` tree. #[derive(Clone, Copy)] pub struct PluginFile { pub relative: &'static str, @@ -65,7 +65,7 @@ macro_rules! plugin_file { }; } -// Every file under `plugin/skills/`, embedded recursively by `build.rs`. +// Every file under `plugin/skills/`, including support files, embedded by build.rs. include!(concat!(env!("OUT_DIR"), "/plugin_bundle_generated.rs")); /// Prefix of the dispatcher skills that Cursor does **not** deploy (they are diff --git a/src/automation/skill_frontmatter.rs b/src/automation/skill_frontmatter.rs index 0ab4764c0..8295b1a83 100644 --- a/src/automation/skill_frontmatter.rs +++ b/src/automation/skill_frontmatter.rs @@ -1,14 +1,14 @@ //! Parser for the `SKILL.md` frontmatter subset used by plugin and managed -//! skills. +//! skills: fenced `key: value` scalars plus indented block values. use std::collections::BTreeMap; use crate::errors::{Result, TraceDecayError}; -/// One frontmatter value. +/// One parsed frontmatter value. #[derive(Debug, Clone, PartialEq, Eq)] pub enum SkillFrontmatterValue { - /// Inline scalar with outer quotes stripped. + /// Inline scalar with one level of YAML quotes stripped. Scalar(String), /// Trimmed block lines under a key with no inline value. Block(Vec), @@ -22,7 +22,7 @@ impl SkillFrontmatterValue { } } - /// Returns unquoted `- item` block entries. + /// Returns unquoted `- item` entries when every block line is a list item. pub fn as_list_items(&self) -> Option> { match self { Self::Scalar(_) => None, @@ -42,7 +42,7 @@ impl SkillFrontmatterValue { } } -/// Parses the leading `---`-fenced frontmatter of a `SKILL.md` document. +/// Parses leading `---`-fenced frontmatter, normalizing LF and CRLF input. pub fn parse_skill_frontmatter(contents: &str) -> Result> { let mut lines = contents.lines(); if lines.next().map(str::trim_end) != Some("---") { @@ -106,7 +106,7 @@ pub fn parse_skill_frontmatter(contents: &str) -> Result String { if let Some(inner) = value.strip_prefix('\'').and_then(|v| v.strip_suffix('\'')) { inner.replace("''", "'") From e0e849f68c8de3db9160632ebf9e7bf0f38f2014 Mon Sep 17 00:00:00 2001 From: ScriptedAlchemy Date: Fri, 3 Jul 2026 22:28:50 +0000 Subject: [PATCH 6/6] docs(plugin): refresh Cursor README workflow notes --- plugin/README-cursor.md | 23 ++++++++--------------- 1 file changed, 8 insertions(+), 15 deletions(-) diff --git a/plugin/README-cursor.md b/plugin/README-cursor.md index 40343ba7f..52d63c851 100644 --- a/plugin/README-cursor.md +++ b/plugin/README-cursor.md @@ -45,13 +45,10 @@ short recovery hint through Cursor's `additional_context` channel so the agent knows to query TraceDecay LCM/session recall before assuming the compacted summary is complete. -Slash workflows ship as skills with `disable-model-invocation: true` +Slash workflows ship as Cursor-native commands (`/tracedecay-map-architecture`, `/tracedecay-check-health`, -`/tracedecay-curate-memory`, `/tracedecay-review-diff`, …) — Cursor's Commands surface was absorbed into -Skills, so this bundle no longer ships a `commands/` directory. Their slugs -keep the `tracedecay-` prefix so typing `/tracedecay` lists every command, and -the suffix is a verb phrase so the human-facing title (Cursor displays the -humanized slug) reads as the action it performs. +`/tracedecay-curate-memory`, `/tracedecay-review-diff`, ...). Their slugs keep +the `tracedecay-` prefix so typing `/tracedecay` lists every command. ## Auto-review and `permissions.json` @@ -209,16 +206,12 @@ window. ## Local development -For checkout dogfooding, Cursor's docs bless symlinking the bundle into the -local plugin directory so edits are picked up without reinstalling: +For checkout dogfooding, install the generated Cursor projection after edits: ```bash -mkdir -p ~/.cursor/plugins/local -rm -rf ~/.cursor/plugins/local/tracedecay -ln -s /path/to/tracedecay/cursor-plugin ~/.cursor/plugins/local/tracedecay +tracedecay install --agent cursor ``` -Caveat: a symlinked bundle keeps the literal `tracedecay ...` hook/MCP commands, -so GUI-launched Cursor must be able to resolve `tracedecay` on `PATH` (the real -install rewrites them to an absolute binary path). Copying the directory -(`cp -R` instead of `ln -s`) also works. Reload Cursor after either change. +The install path rewrites hook/MCP commands to the absolute binary path and +maps Cursor-specific overlays into their deployed locations. Reload Cursor +after reinstalling.