feat: add codebase-wiki plugin

.claude-plugin/marketplace.json

@@ -8,6 +8,18 @@
     "version": "1.0.0"
   },
   "plugins": [
+    {
+      "name": "codebase-wiki",
+      "description": "Codebase knowledge management plugin — analyze repos, build a structured wiki, compare architectures, query design decisions, and track staleness across your organization's repositories",
+      "version": "0.2.0",
+      "author": {
+        "name": "myl17"
+      },
+      "source": "./plugins/codebase-wiki",
+      "category": "developer-tools",
+      "tags": ["codebase", "wiki", "knowledge-management", "code-analysis"],
+      "keywords": ["codebase", "wiki", "knowledge-management", "code-analysis", "architecture", "comparison", "lint"]
+    },
     {
       "name": "switch-provider",
       "description": "Switch Claude Code between AI providers (Anthropic, Z.AI, Kimi, MiniMax) with a single command",

plugins/codebase-wiki/.claude-plugin/plugin.json

@@ -0,0 +1,42 @@
+{
+  "name": "codebase-wiki",
+  "description": "Codebase knowledge management plugin — analyze repos, build a structured wiki, compare architectures, query design decisions, and track staleness across your organization's repositories",
+  "version": "0.2.0",
+  "author": {
+    "name": "myl17"
+  },
+  "homepage": "https://github.com/myl17/codebase-wiki",
+  "repository": "https://github.com/myl17/codebase-wiki",
+  "license": "MIT",
+  "keywords": [
+    "codebase",
+    "wiki",
+    "knowledge-management",
+    "code-analysis",
+    "architecture",
+    "comparison",
+    "lint"
+  ],
+  "commands": {
+    "ingest": {
+      "description": "Extract structural entities from a code repository, map to problem spaces, and evolve concept pages",
+      "file": "commands/ingest.md"
+    },
+    "query": {
+      "description": "Answer questions using the wiki knowledge base",
+      "file": "commands/query.md"
+    },
+    "compare": {
+      "description": "Generate a comparison matrix across repos in a category",
+      "file": "commands/compare.md"
+    },
+    "lint": {
+      "description": "Run programmatic health checks on the wiki",
+      "file": "commands/lint.md"
+    },
+    "evolve-apply": {
+      "description": "Wikipedia-style concept page evolution: merge, split, redirect",
+      "file": "commands/evolve-apply.md"
+    }
+  }
+}

plugins/codebase-wiki/.gitignore

@@ -0,0 +1,11 @@
+.manifest.json
+wiki/eval-history.jsonl
+raw/
+__pycache__/
+*.pyc
+.pytest_cache/
+wiki/repos/*/.hashes.json
+wiki/.obsidian/graph.json
+experiments/
+.claude/
+skills/

plugins/codebase-wiki/README.md

@@ -0,0 +1,49 @@
+# codebase-wiki
+
+> A growing markdown directory maintained by LLM — not a graph database.
+
+A [Claude Code](https://claude.ai/code) plugin that turns source code repositories into a **living, cross-referenced knowledge base**. It implements the [LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) pattern by Andrej Karpathy.
+
+## Install
+
+```
+/plugin marketplace add kossakovsky/cc-plugins
+/plugin install codebase-wiki@cc-plugins
+```
+
+Or install standalone:
+
+```
+/plugin marketplace add myl17/codebase-wiki
+/plugin install codebase-wiki@codebase-wiki
+```
+
+## What it does
+
+Each time you ingest a repo, the LLM reads the source, extracts structural modules (**Entities**), maps them to cross-repo design questions (**Problem Spaces**), and writes or updates **Concept** pages with comparison tables, wikilinks, and source provenance. The `[[wikilink]]` network **is** the graph — open it in Obsidian to see the knowledge structure directly.
+
+## Skills
+
+| Skill | Description |
+|-------|-------------|
+| `/ingest` | Read source → extract entities → map problem spaces → write/update concept pages |
+| `/query` | Answer questions via wikilink traversal + 3-level retrieval escalation |
+| `/compare` | Cross-repo comparison: Concept → Entity → Source code |
+| `/lint` | Full wiki health check: wikilinks, frontmatter, orphans, provenance |
+| `/evolve-apply` | Wikipedia-style concept evolution: merge, split, redirect |
+
+## Quick Start
+
+```
+/ingest /path/to/your/repo my-repo-name
+```
+
+After ingest, open `wiki/` in Obsidian with Graph View to see the wikilink network. Ingest a second repo in the same domain and it will update existing Concept pages with comparisons.
+
+## Documentation
+
+See the [GitHub repo](https://github.com/myl17/codebase-wiki) for full documentation.
+
+## License
+
+MIT

plugins/codebase-wiki/commands/compare.md

@@ -0,0 +1,95 @@
+# /compare — Cross-Repo Comparison
+
+Given repo names or design problem keywords, find the cheapest available information source along the escalation chain and produce a comparison.
+
+**Announce at start:** "Running /compare <repo1> <repo2>..."
+
+## Trigger
+
+```
+/compare <repo1> <repo2> [<repo3> ...] [--concept <keyword>] [--auto]
+/compare --concept <keyword>
+/compare <repo1> <repo2> ... --concept <keyword>
+```
+
+Examples:
+```
+/compare hermes-agent nanobot openclaw
+/compare --concept memory
+/compare hermes-agent openclaw --concept agent
+```
+
+## --auto mode
+
+`--auto` skips user interaction but does NOT skip correctness checks. See each section's `[--auto]` annotation for impact.
+
+```
+          Normal mode           --auto mode
+          ───────────           ───────────
+Self-check MUST RUN             MUST RUN (unchanged)
+Accuracy   MUST RUN → ask user  MUST RUN → write evolve-signals/ → continue
+Structure  MUST RUN → ask user  MUST RUN → write evolve-signals/ → continue
+Archive    ask user              skip (don't archive)
+```
+
+## 3-Level Escalation Chain
+
+### Level 1 — Concept Comparison (cheapest, pre-computed)
+Read `wiki/index.md` → find the Concepts table. For each concept covering the target repos, read the **Comparison** section of the concept page:
+```bash
+grep -A 50 "^## 对比" wiki/concepts/<slug>.md
+```
+Extract the comparison table — this is a pre-computed summary across repos.
+
+### Level 2 — Entity Page (slightly more expensive)
+When Level 1 doesn't cover a particular problem dimension, go to entity pages for the target repos:
+```bash
+ls wiki/repos/<name>/entities/
+```
+Read entity frontmatter (`problem:` field) → identify entities that address the same problem across repos → read their **Key Mechanisms** sections.
+
+### Level 3 — Source Code (most expensive, last resort)
+When Levels 1-2 still leave a specific comparison point unaddressed, read the actual source files (via the `source_files:` field in entity frontmatter). Read only the file and function ranges noted in provenance references.
+
+## STOP 1 — Content Accuracy Self-Check
+
+After producing the comparison output at any level, before presenting to the user:
+
+1. Compare the generated comparison against concept page descriptions. Any inconsistency between what Level 3 source reading shows and what concept pages claim?
+
+2. Check: do concept pages used in the comparison have provenance references? Are descriptions complete?
+
+3. If discrepancies found → **STOP 1a: Content Repair Flow**:
+   - (a) Present diff (old description → new description), inform user of discrepancy
+   - (b) After user confirmation, write correction to wiki page. `[--auto]`: write signal to `evolve-signals/`
+   - (c) Regenerate affected parts of the comparison output
+   - (d) Log append: `[源码验证: <page> <section>修正] [触发: /compare]`
+
+## STOP 2 — Concept Structure Self-Check
+
+After STOP 1 passes, check concept structure:
+
+1. Do any comparison results suggest a concept needs to be split? (Two very different approaches to the same concern, different enough to be independent design spaces)
+2. Do any comparison results suggest concepts need to be merged? (Two concepts where repos choose essentially the same trade-off axis)
+3. Do any comparison results suggest a new concept? (A recurring pattern across repos not yet captured)
+
+If yes → present candidate operations, trigger evolve-apply logic. `[--auto]`: write signal to `evolve-signals/` → continue.
+
+## Archive Decision
+
+After comparison output is finalized:
+
+```
+> Archive this comparison?
+> - A: Don't archive (ad-hoc view)
+> - B: Save to wiki/views/
+> - C: Initiate /ingest <repo> to fold comparison findings into Concept evolution
+```
+
+### Option B — Save as view
+- Write `wiki/views/<YYYY-MM-DD>-compare-<slug>.md`
+- Append to `wiki/log.md` with `[compare]` tag
+- Update `wiki/index.md` `## Views` section
+
+### After B — completion-gate
+Invoke `/completion-gate` as a REQUIRED SUB-SKILL before claiming completion.

plugins/codebase-wiki/commands/completion-gate.md

@@ -0,0 +1,79 @@
+# /completion-gate — Completion Quality Gate
+
+A shared quality gate that must be passed before any wiki write operation can be declared complete. Not a user-invoked skill — referenced by other skills as `REQUIRED SUB-SKILL` at completion.
+
+## Trigger
+
+```
+(not user-invoked — referenced by other skills as REQUIRED SUB-SKILL at completion)
+```
+
+**Announce at start:** Execute silently. On a clean pass, output nothing to the user.
+
+## Iron Law
+
+```
+NO COMPLETION CLAIMS BEFORE THE GATE IS CLEARED
+```
+
+Before claiming "operation complete," every item in this gate must be passed. Skipping any item = not complete.
+
+## The Gate Function
+
+```
+BEFORE claiming any wiki operation is complete:
+
+1. IDENTIFY: Which wiki files does this operation touch?
+2. CHECK: Is each file in the correct state? (operation scope, not full wiki coverage)
+3. VERIFY: Do logs and index reflect this operation?
+4. GATE: All pass → declare complete. Any fails → fix and re-check.
+```
+
+## Non-Negotiable Checklist
+
+### 1. Write Correctness
+
+- [ ] If Entity pages were written → frontmatter has all 6 required fields (`type`, `repo`, `slug`, `problem`, `source_files`, `generated`)
+- [ ] If Concept pages were written →
+  - ① frontmatter `repos:` covers **all** repos discussed in the body? (body has `### repo-name` sections or wikilinks but frontmatter doesn't list it = coverage invisible → BLOCK)
+  - ② For each frontmatter-listed repo, is there at least one `[[repos/<name>/entities/...]]` wikilink in the body? (repos declared in metadata with no wikilink evidence → WARN, log but don't block)
+- [ ] If maintenance files were written (`index.md`, `log.md`, `hot.md`) → format matches spec
+- [ ] Every fact claim in new/changed pages has at least one provenance reference `^[path:line]`
+
+### 2. Incremental Wikilink Validation
+
+- [ ] Every wikilink in files written by this operation resolves to an existing file
+- [ ] For each new concept page: do source entity pages have backlinks added? (`**Associated Concepts**: [[concepts/<slug>]]`)
+- [ ] For each updated concept page: if `repos:` gained a new repo, do that repo's entity pages have backlinks added?
+
+### 3. Maintenance File Sync
+
+- [ ] `wiki/log.md`: new entry appended at bottom, with correct format (`[timestamp] operation detail`)
+- [ ] `wiki/hot.md`: overwritten with current status (last operation, active repos, concept count, pending signal count)
+- [ ] `wiki/index.md`: if repos were added → Repos section updated. If concepts were created/merged → Concepts table updated. If views/insights were archived → Views or Insights section updated.
+
+### 4. Cleanup
+
+- [ ] No leftover `[源码验证:]` markers in commit messages or page bodies (these are transient during-edit markers, should be resolved)
+- [ ] No "I'll do this later" / "TODO" / unfinished write promises in written content
+- [ ] If the operation produced `evolve-signals/` files → remind user: "N evolve signals are pending in evolve-signals/"
+
+## Red Flags
+
+Do NOT claim completion if any of:
+- ① A written file has broken wikilinks (target doesn't exist)
+- ② A written file is missing required frontmatter fields
+- ③ A written concept page has `repos:` in frontmatter that don't match the repos actually discussed in body
+- ④ `wiki/log.md` or `wiki/hot.md` don't reflect this operation
+- ⑤ Source entity pages lack backlinks to newly written concept pages
+- ⑥ The operation produced artifacts outside the wiki directory without updating `.gitignore`
+
+## When To Apply
+
+| Operation | Gate invoked by |
+|-----------|----------------|
+| `/ingest` (write entities + concepts) | `/ingest` itself at completion |
+| `/evolve-apply` (merge/split/redirect) | `/evolve-apply` itself at completion |
+| `/compare` (archive as view → B or C) | `/compare` itself at completion |
+| `/query` (archive as insight → B or C) | `/query` itself at completion |
+| Any manual edit to wiki pages | Editor's responsibility to self-check |