Consolidate knowledge-system rules into one per-project surface

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

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"
   },

plugins/knowledge-system/README.md

@@ -49,6 +49,8 @@ Lightweight, native knowledge management for Claude Code projects. Build up a pe
 - updates `reindexedAt` and `pluginVersion`
 - 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.
@@ -112,7 +114,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; `<topic>` to scope, `--full` for everything |
 | `/curate` | Store a new learning in the right layer; merges with existing entries |
@@ -136,7 +138,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 `<!-- BEGIN knowledge-system -->` / `<!-- END knowledge-system -->` 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 +337,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 `<!-- BEGIN knowledge-system -->` and `<!-- END knowledge-system -->` markers
 
 ### User data (remove only if you really want to lose it)

plugins/knowledge-system/skills/init/SKILL.md

@@ -1,15 +1,15 @@
 ---
 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
 ---
 
 # 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: `<!-- BEGIN knowledge-system -->` / `<!-- END knowledge-system -->`) that `@`-imports the knowledge index
 
 User content (created empty once, never overwritten afterwards):
@@ -62,43 +62,56 @@ 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):
+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 usage — always-active directives and index-load fallback
+description: Knowledge system — when to consult/curate, index-load fallback, commands
 ---
 
-<!-- This file is managed by the knowledge-system plugin. -->
-<!-- Safe to delete if you uninstall the plugin. Edit freely if you customize. -->
+<!-- knowledge-system-usage template-v1 — managed by the plugin; re-run /init to refresh (/reindex flags staleness). -->
+<!-- Safe to delete on uninstall. Delete the marker line above to opt out of staleness checks. -->
 
 # 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 "<question>"` — retrieves relevant entries without dragging full files into context.
-- After discovering a pattern, fix, or decision worth preserving: `/curate "<insight>" [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 "<question>"` — a cheap Haiku subagent
+  answers without pulling full files into context.
 
-## Layers
+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.
 
-- `.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 "<insight>" [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 (fix it
+promptly — wrong docs mislead a later `/query`). 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
@@ -122,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
 <!-- END knowledge-system -->

plugins/knowledge-system/skills/reindex/SKILL.md

@@ -22,6 +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/`). 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<N>` marker inside the step-3 template block — `<N>` 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<M>` marker** → if `M` ≠ `<N>`, remember a stale-rule nudge for step 3, capturing both `M` and `<N>`. If `M` == `<N>`, 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` ≠ `<N>`), 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.
 
@@ -40,6 +49,12 @@ 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, using the captured `M`/`<N>`:
+
+> ⚠ Your `.claude/rules/knowledge-system-usage.md` is on an older template (`template-v<M>`, current is `template-v<N>`) — 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.
 
 ### 4. When the agent reports back
@@ -60,7 +75,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