refactor(plugin): restructure skills into unified entry skill + commands + hooks

- Replace 5 individual skills with 1 unified codemap skill for smart routing
- Add 5 slash commands (scan, load, query, update, impact) for direct invocation
- Add SessionStart hook to auto-detect .codemap/ and prompt user
- Bump version to 0.2.0
- Update README with new structure, commands, and workflow

Author: invalid

.claude-plugin/marketplace.json

@@ -7,13 +7,13 @@
   },
   "metadata": {
     "description": "AST-based code graph mapping plugin for Claude Code — scan once, persist structural graph, load compact slices to save ~95% tokens",
-    "version": "0.1.0"
+    "version": "0.2.0"
   },
   "plugins": [
     {
       "name": "codemap",
       "description": "AST-based code graph mapping plugin — scan codebase, persist structural graph, load compact slices in future sessions, saving ~95% tokens compared to re-reading all source files",
-      "version": "0.1.0",
+      "version": "0.2.0",
       "source": "./ccplugin",
       "category": "productivity",
       "author": { "name": "killvxk" },

README.md

@@ -71,21 +71,21 @@ Run the following commands inside a Claude Code session (these are slash command
 
 After installation, **restart Claude Code** for the plugin to take effect.
 
-> **原理 / How it works:** Claude Code 读取根目录的 `.claude-plugin/marketplace.json`，其中 `"source": "./ccplugin"` 指向插件目录。然后从 `ccplugin/.claude-plugin/plugin.json` 加载插件清单，自动发现 `ccplugin/skills/` 下的所有 skill。
+> **原理 / How it works:** Claude Code 读取根目录的 `.claude-plugin/marketplace.json`，其中 `"source": "./ccplugin"` 指向插件目录。然后从 `ccplugin/.claude-plugin/plugin.json` 加载插件清单，自动发现 `ccplugin/commands/` 下的斜杠命令、`ccplugin/skills/` 下的 skill、以及 `ccplugin/hooks/` 下的事件钩子。
 >
-> Claude Code reads `.claude-plugin/marketplace.json` at the repo root, where `"source": "./ccplugin"` points to the plugin directory. It then loads `ccplugin/.claude-plugin/plugin.json` and auto-discovers all skills under `ccplugin/skills/`.
+> Claude Code reads `.claude-plugin/marketplace.json` at the repo root, where `"source": "./ccplugin"` points to the plugin directory. It then loads `ccplugin/.claude-plugin/plugin.json` and auto-discovers commands in `ccplugin/commands/`, skills in `ccplugin/skills/`, and hooks in `ccplugin/hooks/`.
 
 #### 5. 验证插件已安装 / Verify plugin installed
 
 重启 Claude Code 后，输入 / After restarting Claude Code, type:
 
 ```
-/scan
+/codemap:codemap-scan
 ```
 
-如果插件正确安装，该 skill 会被识别并触发代码扫描流程。
+如果插件正确安装，该命令会触发代码扫描流程。
 
-If the plugin is installed correctly, this skill will be recognized and trigger the code scan workflow.
+If the plugin is installed correctly, this command will trigger the code scan workflow.
 
 #### 卸载 / Uninstall
 
@@ -175,12 +175,18 @@ CodeMap/
 ├── ccplugin/                   # 插件根目录 (CLAUDE_PLUGIN_ROOT)
 │   ├── .claude-plugin/
 │   │   └── plugin.json         #   插件清单 / Plugin manifest
-│   ├── skills/                         #   Claude Code Skills (自动触发)
-│   │   ├── codemap-scan/SKILL.md       #     全量扫描
-│   │   ├── codemap-load/SKILL.md       #     智能加载
-│   │   ├── codemap-update/SKILL.md     #     增量更新
-│   │   ├── codemap-query/SKILL.md      #     符号查询
-│   │   └── codemap-impact/SKILL.md     #     影响分析
+│   ├── commands/               #   斜杠命令 / Slash commands
+│   │   ├── scan.md             #     /codemap:codemap-scan
+│   │   ├── load.md             #     /codemap:codemap-load
+│   │   ├── update.md           #     /codemap:codemap-update
+│   │   ├── query.md            #     /codemap:codemap-query
+│   │   └── impact.md           #     /codemap:codemap-impact
+│   ├── skills/                 #   自动触发 Skill / Auto-triggering skill
+│   │   └── codemap/SKILL.md    #     统一入口，智能路由 / Unified entry, smart routing
+│   ├── hooks/                  #   事件钩子 / Event hooks
+│   │   ├── hooks.json          #     SessionStart 自动检测
+│   │   └── scripts/
+│   │       └── detect-codemap.sh
 │   └── cli/                    #   CLI 工具
 │       ├── bin/codegraph.js    #     入口 / Entry point
 │       ├── src/                #     源码 / Source
@@ -242,28 +248,39 @@ codegraph impact auth --depth 3 --dir /path/to/project
 
 ---
 
-## Skills
+## Skills & Commands
 
-作为 Claude Code 插件安装后，以下 skill 会根据对话上下文自动触发：
+作为 Claude Code 插件安装后，提供以下能力：
 
-When installed as a Claude Code plugin, these skills auto-trigger based on conversation context:
+When installed as a Claude Code plugin, the following capabilities are available:
 
-| Skill | 触发词 / Triggers On |
+### 自动触发 / Auto-Triggering
+
+`codemap` skill 会根据对话上下文自动激活，智能判断该执行哪个操作。同时 `SessionStart` hook 会在每次会话开始时自动检测 `.codemap/` 是否存在并提示。
+
+The `codemap` skill auto-activates based on conversation context and intelligently routes to the right operation. A `SessionStart` hook also detects `.codemap/` at session start.
+
+### 斜杠命令 / Slash Commands
+
+也可以手动调用：/ You can also invoke manually:
+
+| 命令 / Command | 描述 / Description |
 |-------|------------|
-| `codemap-scan` | "扫描", "索引", "scan", "index", "map codebase" |
-| `codemap-load` | "加载图谱", "项目结构", "load", "code structure" |
-| `codemap-update` | "更新图谱", "refresh", "代码改了" |
-| `codemap-query` | "查找", "谁调用了", "where is", "find function" |
-| `codemap-impact` | "影响范围", "refactor impact", "change impact" |
+| `/codemap:codemap-scan` | 全量扫描项目，生成 .codemap/ 图谱 / Full scan, generate .codemap/ graph |
+| `/codemap:codemap-load [target]` | 加载图谱到上下文（概览/模块/文件）/ Load graph into context |
+| `/codemap:codemap-update` | 增量更新图谱 / Incremental update |
+| `/codemap:codemap-query <symbol>` | 查询符号定义和调用关系 / Query symbol definitions and call relations |
+| `/codemap:codemap-impact <target>` | 分析变更影响范围 / Analyze change impact |
 
 ### 典型工作流 / Typical Workflow
 
 ```
-1. 首次使用 / First time:     /scan           → 生成 .codemap/ 图谱
-2. 新会话开始 / New session:   /load           → 加载概览 (~500 tokens)
-3. 深入模块 / Dive into module: /load auth     → 加载 auth 模块 (~2-5k tokens)
-4. 代码修改后 / After changes: /update         → 增量更新图谱
-5. 重构前 / Before refactor:   /impact auth    → 查看影响范围
+1. 首次使用 / First time:     /codemap:codemap-scan       → 生成 .codemap/ 图谱
+2. 新会话开始 / New session:   (自动检测 / auto-detected)  → SessionStart hook 提示加载
+3. 加载概览 / Load overview:   /codemap:codemap-load       → 加载概览 (~500 tokens)
+4. 深入模块 / Dive into module: /codemap:codemap-load auth → 加载 auth 模块 (~2-5k tokens)
+5. 代码修改后 / After changes: /codemap:codemap-update     → 增量更新图谱
+6. 重构前 / Before refactor:   /codemap:codemap-impact auth → 查看影响范围
 ```
 
 ---

ccplugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codemap",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "AST-based code graph mapping plugin for Claude Code — scan once, persist structural graph, load compact slices to save ~95% tokens",
   "author": {
     "name": "killvxk",

ccplugin/commands/impact.md

@@ -0,0 +1,40 @@
+---
+name: codemap-impact
+description: 分析修改某个模块或文件的影响范围，用于重构前的风险评估
+arguments:
+  - name: target
+    description: 要分析的模块名或文件路径
+    required: true
+  - name: depth
+    description: 依赖追踪深度，默认 3
+    required: false
+---
+
+# CodeMap Impact — 变更影响分析
+
+分析修改某个模块或文件会影响到哪些其他部分，用于重构前的风险评估。
+
+## 执行步骤
+
+### 1. 执行影响分析
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/cli/bin/codegraph.js" impact "{{target}}" --depth {{depth:-3}}
+```
+
+`<target>` 可以是模块名（如 `auth`）或文件路径（如 `src/auth/login.ts`）。
+
+### 2. 展示影响范围
+
+向用户报告：
+- 目标：被分析的模块/文件
+- 直接依赖方：直接导入此模块/文件的模块
+- 传递依赖方：间接受影响的模块（通过依赖链传播）
+- 受影响文件总数
+- 建议关注点：依赖链最深的文件优先关注
+
+### 3. 给出建议
+
+- 影响范围较小（< 5 个文件）→ 可以直接修改
+- 影响范围中等（5-20 个文件）→ 建议分步重构
+- 影响范围较大（> 20 个文件）→ 建议先写迁移计划

ccplugin/commands/load.md

@@ -0,0 +1,48 @@
+---
+name: codemap-load
+description: 从 .codemap/ 加载代码图谱到当前会话上下文，支持加载概览、指定模块或文件
+arguments:
+  - name: target
+    description: 模块名或文件路径。不指定则加载项目概览
+    required: false
+---
+
+# CodeMap Load — 智能加载代码图谱
+
+从 `.codemap/` 读取已缓存的代码图谱，按需注入上下文。相比全量读取源码，可节省约 95% token。
+
+## 执行步骤
+
+### 1. 检测图谱是否存在
+
+```bash
+ls .codemap/graph.json 2>/dev/null && echo "CODEMAP_EXISTS" || echo "NO_CODEMAP"
+```
+
+如果不存在，建议用户先执行 `/codemap:codemap-scan` 生成图谱。
+
+### 2. 检查图谱新鲜度
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/cli/bin/codegraph.js" status
+```
+
+如果图谱可能过期（commit hash 不匹配或距离上次更新很久），建议先执行 `/codemap:codemap-update`。
+
+### 3. 加载策略
+
+#### 无参数
+
+加载项目概览（约 500 token）。使用 Read 工具读取 `.codemap/slices/_overview.json`。
+
+#### 带模块名: `<target>` 是模块名
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/cli/bin/codegraph.js" slice {{target}} --with-deps
+```
+
+加载目标模块的完整切片 + 依赖模块概览。
+
+#### 带文件路径: `<target>` 是文件路径
+
+查找该文件所属模块，加载该模块切片。

ccplugin/commands/query.md

@@ -0,0 +1,36 @@
+---
+name: codemap-query
+description: 在代码图谱中查询函数、类、类型的定义位置和调用关系
+arguments:
+  - name: symbol
+    description: 要查询的符号名称（函数名、类名、类型名）
+    required: true
+  - name: type
+    description: "过滤符号类型: function, class, type"
+    required: false
+---
+
+# CodeMap Query — 符号查询
+
+在代码图谱中搜索函数、类、类型或模块的定义和关联信息。
+
+## 执行步骤
+
+### 1. 执行查询
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/cli/bin/codegraph.js" query "{{symbol}}" {{#type}}--type {{type}}{{/type}}
+```
+
+### 2. 展示结果
+
+向用户展示：
+- 符号类型（函数/类/接口/类型别名）
+- 定义位置（文件:行号）
+- 函数签名（如果是函数）
+- 调用者和被调用者
+- 所属模块
+
+### 3. 深入查看
+
+如果用户需要看源码细节，根据查询结果的文件路径和行号范围，使用 Read 工具读取对应的源码段落。只读取精确需要的代码，而不是整个文件。

ccplugin/commands/scan.md

@@ -0,0 +1,43 @@
+---
+name: codemap-scan
+description: 全量扫描项目代码，生成 AST 结构化图谱到 .codemap/ 目录
+arguments:
+  - name: dir
+    description: 要扫描的目录路径，默认为当前目录
+    required: false
+---
+
+# CodeMap Scan — 全量代码图谱扫描
+
+通过 AST 解析生成项目的结构化代码图谱，存储到 `.codemap/` 目录。
+
+## 执行步骤
+
+### 1. 检测图谱是否已存在
+
+```bash
+ls .codemap/graph.json 2>/dev/null && echo "CODEMAP_EXISTS" || echo "NO_CODEMAP"
+```
+
+- 如果已存在，提醒用户图谱已存在，建议使用 `/codemap:codemap-update` 增量更新。如果用户确认要重新全量扫描，继续执行。
+- 如果不存在，继续执行。
+
+### 2. 执行全量扫描
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/cli/bin/codegraph.js" scan {{dir:-.}}
+```
+
+### 3. 展示扫描摘要
+
+使用 Read 工具读取 `.codemap/slices/_overview.json`，向用户展示：
+- 项目名称、源文件总数与语言分布
+- 检测到的模块列表（各模块文件数、函数数）
+- 入口文件、模块间依赖关系概览
+
+### 4. 提示后续操作
+
+- `/codemap:codemap-load` — 加载项目概览到上下文
+- `/codemap:codemap-load <模块名>` — 加载特定模块详细图谱
+- `/codemap:codemap-query <符号名>` — 查询函数/类的定义和调用关系
+- 图谱已持久化，下次会话只需 `/codemap:codemap-load` 即可恢复上下文

ccplugin/skills/codemap-update/SKILL.md ccplugin/commands/update.mdccplugin/skills/codemap-update/SKILL.md renamed to ccplugin/commands/update.md

@@ -1,13 +1,9 @@
 ---
 name: codemap-update
-description: >
-  Use after code has been modified, after git commits, when the code graph
-  might be outdated, or when the user says "更新图谱", "同步", "refresh",
-  "update map", "代码改了", "图谱过期", "刷新", "重新索引变更".
-  Also use when /load detects the graph commit hash doesn't match current HEAD.
+description: 增量更新代码图谱，只重新解析变更的文件
 ---
 
-# CodeMap Update -- 增量更新图谱
+# CodeMap Update — 增量更新图谱
 
 基于文件哈希比较，只重新解析变更的文件，将更新合并到现有图谱。
 
@@ -28,12 +24,12 @@ CLI 会自动：
 
 ### 2. 展示变更摘要
 
-向用户报告 CLI 输出中的信息：
+向用户报告：
 - 新增文件数 (+N)
 - 修改文件数 (~N)
 - 删除文件数 (-N)
 - 更新耗时
 
 ### 3. 刷新已加载的上下文
 
-如果当前会话已经通过 `/load` 加载了某些模块的图谱，且这些模块受到更新影响，重新执行 `/load` 刷新上下文。
+如果当前会话已经通过 `/codemap:codemap-load` 加载了某些模块的图谱，且这些模块受到更新影响，重新执行加载刷新上下文。

ccplugin/hooks/hooks.json

@@ -0,0 +1,13 @@
+{
+  "hooks": [
+    {
+      "event": "SessionStart",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/detect-codemap.sh"
+        }
+      ]
+    }
+  ]
+}

ccplugin/hooks/scripts/detect-codemap.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+# detect-codemap.sh — SessionStart hook
+# 检测当前工作目录是否有 .codemap/ 图谱，输出提示信息
+
+if [ -f ".codemap/graph.json" ]; then
+  echo "[CodeMap] 检测到 .codemap/ 图谱已存在。建议使用 /codemap:codemap-load 加载项目上下文，或 /codemap:codemap-update 更新图谱。"
+else
+  echo "[CodeMap] 未检测到 .codemap/ 图谱。如需生成代码图谱，请使用 /codemap:codemap-scan。"
+fi