From d15630aaf0cbdefdcd99bccc5959f7655636db2a Mon Sep 17 00:00:00 2001 From: Robert Gering Date: Fri, 12 Jun 2026 13:13:37 +0200 Subject: [PATCH 1/2] Consolidate knowledge-system rules into one per-project surface - Merge auto-query + auto-curate behavior into the /init-written knowledge-system-usage.md; drop both plugin rules - Resolve inline-vs-/query contradiction: read inline for a known path, /query for open questions - /reindex flags a stale usage rule via a version marker and nudges /init (read-only; agent stays fenced to knowledge/ + logs/) - ~56% less always-loaded context (~1010 tokens/session) Existing projects: re-run /init to pick up the new template. Co-Authored-By: Claude Opus 4.8 (1M context) --- .claude-plugin/marketplace.json | 2 +- .../.claude-plugin/plugin.json | 2 +- plugins/knowledge-system/README.md | 7 ++- plugins/knowledge-system/rules/auto-curate.md | 54 ----------------- plugins/knowledge-system/rules/auto-query.md | 36 ----------- plugins/knowledge-system/skills/init/SKILL.md | 60 +++++++++++-------- .../knowledge-system/skills/reindex/SKILL.md | 7 ++- 7 files changed, 48 insertions(+), 120 deletions(-) delete mode 100644 plugins/knowledge-system/rules/auto-curate.md delete mode 100644 plugins/knowledge-system/rules/auto-query.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index b4565de..749cb49 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -12,7 +12,7 @@ "name": "knowledge-system", "source": "./plugins/knowledge-system", "description": "Lightweight, native knowledge management for Claude Code projects. Three layers of persistent knowledge: Rules (always active), Knowledge (on demand), and Memory (automatic).", - "version": "1.6.0" + "version": "1.7.0" }, { "name": "work-system", diff --git a/plugins/knowledge-system/.claude-plugin/plugin.json b/plugins/knowledge-system/.claude-plugin/plugin.json index 29efcea..9cea223 100644 --- a/plugins/knowledge-system/.claude-plugin/plugin.json +++ b/plugins/knowledge-system/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "knowledge-system", "description": "Lightweight, native knowledge management for Claude Code projects. Three layers of persistent knowledge: Rules (always active), Knowledge (on demand), and Memory (automatic).", - "version": "1.6.0", + "version": "1.7.0", "author": { "name": "gering" }, diff --git a/plugins/knowledge-system/README.md b/plugins/knowledge-system/README.md index 9ba0cc2..c7df844 100644 --- a/plugins/knowledge-system/README.md +++ b/plugins/knowledge-system/README.md @@ -47,6 +47,7 @@ Lightweight, native knowledge management for Claude Code projects. Build up a pe - **proactively proposes new cross-links** between files that discuss the same concepts but don't link each other - backfills missing `createdAt` / `updatedAt` from git history - updates `reindexedAt` and `pluginVersion` +- flags the managed `knowledge-system-usage.md` when a newer plugin template has shipped (nudges you to re-run `/init`; read-only — never edits `.claude/rules/`) - appends a short bullet-point summary to `.claude/logs/reindex.md` **Why a background agent.** A thorough QA pass reads many files and reasons over the whole graph — that's slow. Running it in the foreground would block your session for minutes. As a background agent, you type `/reindex` and keep working; the summary comes back when it's done. @@ -112,7 +113,7 @@ Lightweight, native knowledge management for Claude Code projects. Build up a pe | Command | Description | |---------|-------------| -| `/init` | Scaffold knowledge system: directories, starter files, auto-prime rule, CLAUDE.md entry | +| `/init` | Scaffold knowledge system: directories, starter files, usage rule, CLAUDE.md entry | | `/query` | Retrieve relevant knowledge on demand — Haiku subagent, sub-second | | `/prime` | Load the foundational docs (architecture + overviews) into context on demand; `` to scope, `--full` for everything | | `/curate` | Store a new learning in the right layer; merges with existing entries | @@ -136,7 +137,7 @@ Lightweight, native knowledge management for Claude Code projects. Build up a pe `/init` does two things to ensure Claude actually uses the system: - Injects `@.claude/knowledge/_index.md` into `CLAUDE.md`, wrapped in `` / `` markers. Claude Code auto-loads `CLAUDE.md` every session and expands `@file` references inline — so your knowledge index lives in Claude's context from the start. -- Writes `.claude/rules/knowledge-system-usage.md`, an always-active rule with usage directives (when to `/query`, when to `/curate`, when to suggest `/reindex`) and a **fallback**: if for any reason the index isn't in context, Claude reads it once via the Read tool. Belt-and-suspenders. +- Writes `.claude/rules/knowledge-system-usage.md`, a per-project rule that carries the index-load **fallback** (if the index isn't in context, Claude reads it once via the Read tool — belt-and-suspenders), the *when* (when to `/query` vs read inline, when to `/curate`), and a command catalog. It lives in the repo, so the guidance travels with the project — team-shared and plugin-independent. ## Usage examples @@ -335,7 +336,7 @@ Part of the [gering-plugins](https://github.com/gering/claude-plugins) marketpla ### Plugin-managed files (safe to remove) -- `.claude/rules/knowledge-system-usage.md` — the always-active directives rule +- `.claude/rules/knowledge-system-usage.md` — the per-project usage rule (fallback + when-to-query/curate + command catalog) - The block inside `CLAUDE.md` wrapped in `` and `` markers ### User data (remove only if you really want to lose it) diff --git a/plugins/knowledge-system/rules/auto-curate.md b/plugins/knowledge-system/rules/auto-curate.md deleted file mode 100644 index e822f88..0000000 --- a/plugins/knowledge-system/rules/auto-curate.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -description: Automatically curate knowledge and rules at key moments -globs: ---- - -# Auto-Curate - -## When to curate - -You MUST check for curate-worthy learnings at these moments: - -1. **Before a push** — Review what changed in the commits being pushed. Ask yourself: "Would future-me benefit from knowing why this was done this way?" If yes, curate before pushing. - -2. **Before creating a PR** — Review the full diff. Curate any non-obvious patterns, architectural decisions, or gotchas that emerged during the work. - -3. **After a non-trivial bug fix** — If the root cause was surprising or the fix required understanding a non-obvious interaction, curate it. - -4. **When the user corrects your approach** — If the user says "don't do X" or "always do Y", check if it should become a rule. - -5. **When you notice outdated knowledge** — If a knowledge file contains wrong details (renamed files, changed behavior), update it immediately. - -## How to curate (inline — do NOT use /curate) - -Decide where it belongs (see `rules/knowledge-boundaries.md`): -- Short code directive (do/don't) → `.claude/rules/.md` -- Workflow checklist (PR, deploy) → `CLAUDE.md` -- Detailed feature/architecture → `.claude/knowledge//.md` -- User preference/feedback → Memory - -Then: -1. Check if an existing file already covers the topic (read `.claude/rules/` or `.claude/knowledge/_index.md`) -2. Update the existing file, or create a new one — on a new knowledge file, set `prime: true` (foundational/overview) or `prime: false` (narrow detail) so `/prime` knows whether to load it -3. If a new knowledge file was created, update `.claude/knowledge/_index.md` -4. Briefly tell the user what you curated and where - -## What to curate - -- Architectural decisions and their rationale -- Non-obvious patterns or conventions that emerged -- Gotchas, edge cases, and workarounds with context -- Integration details between components - -## What NOT to curate - -- Trivial changes (rename, typo fix, formatting) -- Volatile values (version numbers, counts, thresholds) -- Security-sensitive details (API keys, secrets, auth internals) -- Things already obvious from the code itself - -## Content guidelines - -- Describe **how things work**, not current exact values -- Include **why**, not just what — the reasoning is what helps future-you -- Keep it concise — if it's more than a paragraph, it's probably knowledge, not a rule diff --git a/plugins/knowledge-system/rules/auto-query.md b/plugins/knowledge-system/rules/auto-query.md deleted file mode 100644 index 0247d6d..0000000 --- a/plugins/knowledge-system/rules/auto-query.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -description: Automatically check project knowledge before diving into unfamiliar code -globs: ---- - -# Auto-Query - -## When to check knowledge - -Before diving into code, check if `.claude/knowledge/_index.md` exists. If it does, read it and look for entries relevant to your current task. Read matching knowledge files before exploring the codebase. - -You MUST check knowledge at these moments: - -1. **Starting work in an unfamiliar area** — Before reading source code in a part of the codebase you haven't touched in this conversation, check if there's documented knowledge about it. This saves time and avoids rediscovering what's already known. - -2. **User asks "how does X work"** — Check knowledge FIRST, before grepping through code. If knowledge exists, answer from it. Only explore code if knowledge is missing or incomplete. - -3. **Before making architectural decisions** — If your change affects how components interact, check if there's documented architecture knowledge that should inform your approach. - -4. **When you encounter unexpected behavior** — Before debugging from scratch, check if there's a known gotcha or edge case documented in knowledge. - -## How to query (inline — do NOT use /query) - -1. Read `.claude/knowledge/_index.md` -2. Identify 1-3 relevant entries based on the topic -3. Read those files -4. Use the knowledge to inform your work - -Do NOT read the entire knowledge base — be selective. The index tells you what exists. - -## When NOT to query - -- Trivial changes (typo, formatting, rename) -- You already have full context from earlier in the conversation -- The change is isolated and self-contained (e.g., fixing a single function you already understand) -- No `.claude/knowledge/` directory exists diff --git a/plugins/knowledge-system/skills/init/SKILL.md b/plugins/knowledge-system/skills/init/SKILL.md index 46bec2f..ef81003 100644 --- a/plugins/knowledge-system/skills/init/SKILL.md +++ b/plugins/knowledge-system/skills/init/SKILL.md @@ -1,7 +1,7 @@ --- name: init description: | - Scaffolds `.claude/knowledge/` + `.claude/rules/`, writes the auto-prime + Scaffolds `.claude/knowledge/` + `.claude/rules/`, writes the usage rule, injects the index into `CLAUDE.md`. Idempotent. Trigger: "init knowledge", "set up knowledge system", "bootstrap .claude/". user_invocable: true @@ -9,7 +9,7 @@ user_invocable: true # Initialize Knowledge System -Scaffold the knowledge system directory structure, the auto-prime rule, and the CLAUDE.md entry. +Scaffold the knowledge system directory structure, the usage rule, and the CLAUDE.md entry. ## Usage `/init` @@ -18,7 +18,7 @@ Scaffold the knowledge system directory structure, the auto-prime rule, and the ## What this skill creates Plugin-managed (regenerated on re-run, safe to delete): -- `.claude/rules/knowledge-system-usage.md` — always-active directives + index-load fallback +- `.claude/rules/knowledge-system-usage.md` — index-load fallback + command pointers - A wrapped block inside `CLAUDE.md` (markers: `` / ``) that `@`-imports the knowledge index User content (created empty once, never overwritten afterwards): @@ -62,43 +62,55 @@ Look for `.claude/knowledge/_index.md`. If it exists, inform the user that the k Skip this step if `_index.md` already exists. -### 3. Write the auto-prime rule +### 3. Write the usage rule -Write `.claude/rules/knowledge-system-usage.md` with this exact content (overwrite any existing plugin-managed version): +Read the plugin version from `${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json` (`version` field) and substitute it for `{{VERSION}}` in the marker below. Then write `.claude/rules/knowledge-system-usage.md` with this content (overwrite any existing plugin-managed version): ```markdown --- -description: Knowledge-system usage — always-active directives and index-load fallback +description: Knowledge system — when to consult/curate, index-load fallback, commands --- - - + + # Project Knowledge System ## Auto-load fallback -Your context should already contain the knowledge index, injected via -`@.claude/knowledge/_index.md` from `CLAUDE.md` on session start. +The knowledge index is injected via `@.claude/knowledge/_index.md` from +`CLAUDE.md` on session start. **If you do not see a "Knowledge Index" section +in your initial context, read `.claude/knowledge/_index.md` once with the Read +tool** before any `/query`. Once per session is enough — do not re-read. -**If you do not see a "Knowledge Index" section in your initial context, -read `.claude/knowledge/_index.md` with the Read tool once at the start of -the session before any `/query`.** Do not re-read on subsequent turns — -once per session is enough. +## Consult before diving in -## When to use which command +Check the index for relevant entries before exploring code when: starting in an +area untouched this conversation; the user asks "how does X work" (check +knowledge before grepping); a change affects how components interact; or you hit +unexpected behavior (look for a documented gotcha first). -- At the start of a working session that will touch real architecture: `/prime` — loads the foundational docs (architecture + overviews) into context, beyond the always-loaded index. -- Before non-trivial changes to unfamiliar modules: `/query ""` — retrieves relevant entries without dragging full files into context. -- After discovering a pattern, fix, or decision worth preserving: `/curate "" [file...]` — stores it in the right layer (rule vs knowledge). -- When the knowledge base feels stale, indexes drift, or cross-references look wrong: `/reindex` — runs a thorough QA pass (infrequent, Sonnet-1M-backed). -- When adopting the knowledge system on an existing project (or after a long curation gap): `/backfill-knowledge` — mines merged PR history for significant learnings (features, architecture, major insights) that are missing from the knowledge base. Run `/reindex` first so the idempotency check has up-to-date origin metadata. +- **Index already names the file** → read it inline; no subagent for a known path. +- **Open-ended question** → `/query ""` — a cheap Haiku subagent + answers without pulling full files into context. -## Layers +Skip for trivial or self-contained changes, or when you already have the context. -- `.claude/rules/` — always-loaded directives (this file lives here) -- `.claude/knowledge/` — on-demand detailed knowledge, accessed via `/query` -- `CLAUDE.md` — project-level guidance, loaded every session +## Curate at key moments + +Store a learning with `/curate "" [file...]` (it picks the right layer +and maintains frontmatter) when: about to push or open a PR (non-obvious +patterns, decisions, gotchas in the diff); after a surprising bug fix; the user +corrects your approach ("always do Y"); or you notice stale knowledge. Capture +the *why*, not volatile values; skip trivia, secrets, and the obvious. + +## Other commands + +- `/prime [topic|--full]` — load foundational docs (architecture + overviews) + into context for real architectural work; beyond the always-loaded index. +- `/reindex` — thorough QA pass when indexes drift or cross-refs look stale. +- `/backfill-knowledge` — mine merged PR history for missing learnings (run + `/reindex` first so the idempotency check has up-to-date origin metadata). ``` ### 4. Update CLAUDE.md with the auto-prime block diff --git a/plugins/knowledge-system/skills/reindex/SKILL.md b/plugins/knowledge-system/skills/reindex/SKILL.md index 721e118..c0ff3fe 100644 --- a/plugins/knowledge-system/skills/reindex/SKILL.md +++ b/plugins/knowledge-system/skills/reindex/SKILL.md @@ -22,6 +22,7 @@ Run a thorough, cross-cutting QA pass over `.claude/knowledge/` as a background - Check that `.claude/knowledge/_index.md` exists. If it does not: inform the user that the knowledge system is not initialized and suggest `/init`. Stop. - Check that `.claude/logs/` exists — create it if missing. - Read the plugin version from `${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json` (`version` field). You will pass this to the agent so it can stamp `pluginVersion`. +- **Usage-rule staleness check** (foreground, read-only — `/reindex` never writes to `.claude/rules/`): read `.claude/rules/knowledge-system-usage.md` and look for a `knowledge-system-usage vX.Y.Z` marker comment near the top. If that version is older than the plugin version read above, remember a stale-rule nudge for step 3. If the marker is absent (the user removed it to opt out) or the file does not exist, skip silently. - Capture today's date as `YYYY-MM-DD` (UTC) — pass this to the agent so the run is tagged with a consistent date. - Parse `$ARGUMENTS`: if it contains `--dry-run`, set `{{DRY_RUN}}` to `true`; otherwise `false`. This must be resolved before substitution so the placeholder never lands literally in the agent prompt. @@ -40,6 +41,10 @@ Immediately report to the user (in the channel, not as a separate tool call): > Reindex started as a background agent. It will walk the knowledge base, rebuild indexes, validate and propose cross-references, backfill frontmatter, and append a summary to `.claude/logs/reindex.md`. You'll be notified when the report is ready — typical run: 1–3 minutes. +If the step-1 staleness check flagged the usage rule, append one line (substitute the actual versions): + +> ⚠ Your `.claude/rules/knowledge-system-usage.md` is v\ but the plugin is v\. Re-run `/init` to refresh the managed template — your knowledge files are untouched. + Return control. Do not block. ### 4. When the agent reports back @@ -60,7 +65,7 @@ You are running a thorough QA pass over a Claude Code knowledge base located at ## Scope -Operate over every `.md` file under `.claude/knowledge/**`. Do NOT touch files under `.claude/rules/`, `.claude/logs/`, or anywhere else. +Operate over every `.md` file under `.claude/knowledge/**`. Write only inside `.claude/knowledge/` and to `.claude/logs/reindex.md` (the run log) — do NOT touch `.claude/rules/` or any other path. ## Tasks From b425fdc970c502b48b2dbf810ab2d3bff8c89855 Mon Sep 17 00:00:00 2001 From: Robert Gering Date: Fri, 12 Jun 2026 18:54:19 +0200 Subject: [PATCH 2/2] Rework usage-rule staleness check to template version MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Address code-review findings on the staleness mechanism added earlier in this branch. - Stamp an integer template version (`template-vN`) into the rule instead of the plugin version; /reindex reads the same number from init/SKILL.md (single source of truth) and compares by equality - No more false-positive nudges on unrelated plugin version bumps; the marker only changes when the template content changes - Legacy rules (no template-v marker but a "managed by the" comment) are now detected and nudged; opt-out is deleting the marker line - Equality compare on bare integers avoids semver mis-ordering (1.9 vs 1.10) - Capture both template versions for the nudge text - Drop {{VERSION}} substitution — the marker is now literal, removing the literal-write risk - README describes the staleness flag as a foreground read-only check, not background-agent work - Restore dropped directives: be selective (no bulk-read), fix stale knowledge promptly Co-Authored-By: Claude Opus 4.8 (1M context) --- plugins/knowledge-system/README.md | 3 ++- plugins/knowledge-system/skills/init/SKILL.md | 17 +++++++++-------- .../knowledge-system/skills/reindex/SKILL.md | 16 +++++++++++++--- 3 files changed, 24 insertions(+), 12 deletions(-) diff --git a/plugins/knowledge-system/README.md b/plugins/knowledge-system/README.md index c7df844..5958590 100644 --- a/plugins/knowledge-system/README.md +++ b/plugins/knowledge-system/README.md @@ -47,9 +47,10 @@ Lightweight, native knowledge management for Claude Code projects. Build up a pe - **proactively proposes new cross-links** between files that discuss the same concepts but don't link each other - backfills missing `createdAt` / `updatedAt` from git history - updates `reindexedAt` and `pluginVersion` -- flags the managed `knowledge-system-usage.md` when a newer plugin template has shipped (nudges you to re-run `/init`; read-only — never edits `.claude/rules/`) - appends a short bullet-point summary to `.claude/logs/reindex.md` +Separately, **before** dispatching that agent, `/reindex` runs a quick foreground, read-only check: if this project's `knowledge-system-usage.md` is on an older template than the plugin currently ships (compared by an integer template version stamped into the file), it nudges you to re-run `/init`. It only flags — it never edits `.claude/rules/`. + **Why a background agent.** A thorough QA pass reads many files and reasons over the whole graph — that's slow. Running it in the foreground would block your session for minutes. As a background agent, you type `/reindex` and keep working; the summary comes back when it's done. **Why Sonnet 1M.** Cross-reference detection and duplicate analysis need to hold the whole knowledge graph in context. The 1M window makes that a single pass instead of a paginated mess. Quality of judgment matters here — `/reindex` runs rarely, so model cost isn't the bottleneck. diff --git a/plugins/knowledge-system/skills/init/SKILL.md b/plugins/knowledge-system/skills/init/SKILL.md index ef81003..157479e 100644 --- a/plugins/knowledge-system/skills/init/SKILL.md +++ b/plugins/knowledge-system/skills/init/SKILL.md @@ -64,15 +64,15 @@ Skip this step if `_index.md` already exists. ### 3. Write the usage rule -Read the plugin version from `${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json` (`version` field) and substitute it for `{{VERSION}}` in the marker below. Then write `.claude/rules/knowledge-system-usage.md` with this content (overwrite any existing plugin-managed version): +Write `.claude/rules/knowledge-system-usage.md` with this **exact** content (overwrite any existing plugin-managed version). The marker carries a **template version** (`template-v1` below) — a counter that is bumped **only when the template content here changes**, independent of the plugin version. `/reindex` reads this same number and flags any project copy whose marker differs. (Maintainer note: when you edit the template below, increment `template-vN` here; that single number is the source of truth `/reindex` compares against.) ```markdown --- description: Knowledge system — when to consult/curate, index-load fallback, commands --- - - + + # Project Knowledge System @@ -94,15 +94,16 @@ unexpected behavior (look for a documented gotcha first). - **Open-ended question** → `/query ""` — a cheap Haiku subagent answers without pulling full files into context. -Skip for trivial or self-contained changes, or when you already have the context. +Be selective — pull only the few relevant entries the index points to, never bulk-read the whole base. Skip for trivial or self-contained changes, or when you already have the context. ## Curate at key moments Store a learning with `/curate "" [file...]` (it picks the right layer and maintains frontmatter) when: about to push or open a PR (non-obvious patterns, decisions, gotchas in the diff); after a surprising bug fix; the user -corrects your approach ("always do Y"); or you notice stale knowledge. Capture -the *why*, not volatile values; skip trivia, secrets, and the obvious. +corrects your approach ("always do Y"); or you notice stale knowledge (fix it +promptly — wrong docs mislead a later `/query`). Capture the *why*, not volatile +values; skip trivia, secrets, and the obvious. ## Other commands @@ -134,8 +135,8 @@ The block (exact content): The project's knowledge index is auto-loaded below. Query detailed entries with `/query`, store new insights with `/curate`, run a QA pass -with `/reindex`. See `.claude/rules/knowledge-system-usage.md` for the -full directives. +with `/reindex`. See `.claude/rules/knowledge-system-usage.md` for when +to use each and the full command list. @.claude/knowledge/_index.md diff --git a/plugins/knowledge-system/skills/reindex/SKILL.md b/plugins/knowledge-system/skills/reindex/SKILL.md index c0ff3fe..917ffc3 100644 --- a/plugins/knowledge-system/skills/reindex/SKILL.md +++ b/plugins/knowledge-system/skills/reindex/SKILL.md @@ -22,7 +22,15 @@ Run a thorough, cross-cutting QA pass over `.claude/knowledge/` as a background - Check that `.claude/knowledge/_index.md` exists. If it does not: inform the user that the knowledge system is not initialized and suggest `/init`. Stop. - Check that `.claude/logs/` exists — create it if missing. - Read the plugin version from `${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json` (`version` field). You will pass this to the agent so it can stamp `pluginVersion`. -- **Usage-rule staleness check** (foreground, read-only — `/reindex` never writes to `.claude/rules/`): read `.claude/rules/knowledge-system-usage.md` and look for a `knowledge-system-usage vX.Y.Z` marker comment near the top. If that version is older than the plugin version read above, remember a stale-rule nudge for step 3. If the marker is absent (the user removed it to opt out) or the file does not exist, skip silently. +- **Usage-rule staleness check** (foreground, read-only — `/reindex` never writes to `.claude/rules/`). Compares *template versions*, not plugin versions: + 1. Read the current template version: in `${CLAUDE_PLUGIN_ROOT}/skills/init/SKILL.md`, find the `knowledge-system-usage template-v` marker inside the step-3 template block — `` is the current version (an integer). + 2. Read `.claude/rules/knowledge-system-usage.md` and classify: + - **File missing** → skip silently. + - **Has a `knowledge-system-usage template-v` marker** → if `M` ≠ ``, remember a stale-rule nudge for step 3, capturing both `M` and ``. If `M` == ``, it is current — do nothing. + - **No `template-v` marker but the file still contains a `managed by the` plugin comment** → it predates the template-version scheme (legacy): remember a stale-rule nudge marked "legacy" (no `M` to show). + - **Neither marker present** → the user deleted the managed marker to opt out → skip silently. + - Compare by **equality only** (`M` ≠ ``), never order — version numbers are bare integers and any mismatch means "re-run `/init`". + - Note: this runs after the `_index.md` precondition above, so a project missing `_index.md` is sent to `/init` (which refreshes the rule anyway) rather than nudged here. - Capture today's date as `YYYY-MM-DD` (UTC) — pass this to the agent so the run is tagged with a consistent date. - Parse `$ARGUMENTS`: if it contains `--dry-run`, set `{{DRY_RUN}}` to `true`; otherwise `false`. This must be resolved before substitution so the placeholder never lands literally in the agent prompt. @@ -41,9 +49,11 @@ Immediately report to the user (in the channel, not as a separate tool call): > Reindex started as a background agent. It will walk the knowledge base, rebuild indexes, validate and propose cross-references, backfill frontmatter, and append a summary to `.claude/logs/reindex.md`. You'll be notified when the report is ready — typical run: 1–3 minutes. -If the step-1 staleness check flagged the usage rule, append one line (substitute the actual versions): +If the step-1 staleness check flagged the usage rule, append one line, using the captured `M`/``: -> ⚠ Your `.claude/rules/knowledge-system-usage.md` is v\ but the plugin is v\. Re-run `/init` to refresh the managed template — your knowledge files are untouched. +> ⚠ Your `.claude/rules/knowledge-system-usage.md` is on an older template (`template-v`, current is `template-v`) — re-run `/init` to refresh it. Your knowledge files are untouched. + +For a **legacy** file (no `template-v` marker), drop the parenthetical and say it predates the current template: "…is on a legacy template — re-run `/init` to refresh it." Return control. Do not block.