kungeskill 0.1.0 → 0.3.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,37 @@
+{
+  "name": "kunge-skills",
+  "owner": {
+    "name": "kunge2013",
+    "email": "kun_ja@163.com"
+  },
+  "description": "OpenSpec-based development workflow skills for Claude Code",
+  "plugins": [
+    {
+      "name": "openspec-workflow",
+      "source": "./plugins/openspec-workflow",
+      "description": "Spec-driven change lifecycle: explore, propose, apply, archive",
+      "author": { "name": "kunge2013" },
+      "license": "MIT",
+      "keywords": ["openspec", "workflow", "spec-driven", "planning"],
+      "category": "workflow"
+    },
+    {
+      "name": "openspec-trace",
+      "source": "./plugins/openspec-trace",
+      "description": "Code analysis and business logic knowledge base",
+      "author": { "name": "kunge2013" },
+      "license": "MIT",
+      "keywords": ["openspec", "knowledge-base", "code-analysis", "documentation"],
+      "category": "documentation"
+    },
+    {
+      "name": "publish",
+      "source": "./plugins/publish",
+      "description": "Package publishing skills — npm, PyPI, and other registries",
+      "author": { "name": "kunge2013" },
+      "license": "MIT",
+      "keywords": ["npm", "publish", "registry", "package"],
+      "category": "devops"
+    }
+  ]
+}

package/README.md

@@ -6,13 +6,48 @@ This marketplace provides reusable skills that enable a spec-driven approach to
 
 ## Installation
 
-### Add the marketplace
+### Option 1: Install kungeskill CLI (Recommended)
+
+Manage skills via npm — install, remove, update skills with one command.
+
+```bash
+# Install globally
+npm install -g kungeskill
+
+# Initialize marketplace cache (first time only)
+kungeskill init
+
+# View available skills
+kungeskill list
+
+# Install a skill (creates symlink in your project)
+cd your-project
+kungeskill add openspec-explore
+```
+
+**CLI Commands:**
+
+| Command | Description |
+|---------|-------------|
+| `kungeskill init` | Download marketplace cache (first time only) |
+| `kungeskill list` | List all available skills |
+| `kungeskill add <skill>` | Install a skill into your project via symlink |
+| `kungeskill remove <skill>` | Remove a skill from your project |
+| `kungeskill view` | Show installed skills with health status |
+| `kungeskill update` | Update marketplace cache to latest |
+| `kungeskill doctor` | Check symlink health and detect broken links |
+
+### Option 2: Claude Code Plugin Marketplace
+
+Install skills via Claude Code's built-in plugin system.
+
+#### Add the marketplace
 
 ```
 /plugin marketplace add kunge2013/skills
 ```
 
-### Install individual plugins
+#### Install individual plugins
 
 ```
 # Spec-driven change lifecycle (explore, propose, apply, archive)
@@ -22,7 +57,7 @@ This marketplace provides reusable skills that enable a spec-driven approach to
 /plugin install openspec-trace@kunge-skills
 ```
 
-### Update to latest
+#### Update to latest
 
 ```
 /plugin marketplace update kunge-skills
@@ -62,6 +97,7 @@ Code analysis and business logic knowledge base. Enables you to:
 
 - OpenSpec (spec-driven development workflow)
 - Claude Code skills framework
+- Node.js >= 18 (kungeskill CLI)
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kungeskill",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Manage Claude Code skills via symlinks — install, remove, update skills from a marketplace cache",
   "main": "src/cli.js",
   "bin": {
@@ -10,7 +10,9 @@
     "node": ">=18"
   },
   "files": [
-    "src/**/*.js"
+    "src/**/*.js",
+    "plugins/**/*",
+    ".claude-plugin/**/*"
   ],
   "scripts": {
     "start": "node src/cli.js",

package/plugins/openspec-trace/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "openspec-trace",
+  "description": "Code analysis and business logic knowledge base with versioned design documents",
+  "author": { "name": "kunge2013" },
+  "license": "MIT"
+}

package/plugins/openspec-trace/skills/opst-business-search/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: opst-business-search
+description: >
+  检索 openspec/<领域>/<模块>/ 知识库中已归档的业务逻辑文档。支持关键词检索、领域浏览、精确模块查看三种模式。当用户提到"业务检索"、"搜索业务逻辑"、"business-search"、"查找模块"时使用此技能。
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: fangkun
+  version: "1.0"
+  generatedBy: "openspec-trace@1.0.0"
+---
+
+在 openspec/<领域>/<模块>/ 知识库中检索已归档的业务逻辑文档。
+
+## 检索模式
+
+| 模式 | 触发条件 | 示例 |
+|------|----------|------|
+| **关键词检索** | 用户提供具体关键词 | `payment`、`销账`、`write-off` |
+| **浏览模式** | 用户要求"列出所有"或"展示领域" | `列出所有模块`、`展示领域` |
+| **精确查看** | 用户指定具体模块或文档版本 | `查看 billing/payment-processing` |
+
+---
+
+## 工作流
+
+### 步骤 1：解析查询
+
+从用户输入提取关键词，判断检索模式：
+
+- **浏览模式**：用户输入包含"列出"、"所有"、"展示领域"、"list"、"all" → 浏览模式
+- **精确查看**：用户输入包含 `领域/模块` 路径格式（如 `billing/payment-processing`） → 精确查看
+- **关键词检索**：其他情况 → 关键词检索
+
+**若用户未提供任何输入**：使用 **AskUserQuestion** 询问检索关键词，并提供模式选项。
+
+**检查知识库是否存在**：
+
+若 `openspec/openspec-trace/GLOBAL_INDEX.md` 不存在，提示用户先执行 `/opst:code-anysic` 归档业务逻辑后再检索。
+
+### 步骤 2：执行检索
+
+#### 关键词检索模式
+
+1. 读取全局索引：
+   ```
+   Read: openspec/openspec-trace/GLOBAL_INDEX.md
+   ```
+2. 在"按关键词"表中匹配关键词列（精确匹配优先，模糊匹配补充）
+3. 在"按领域"表中匹配模块名称和领域名称
+4. 扫描各模块 INDEX.md 进行深度匹配：
+   ```
+   Glob: openspec/**/INDEX.md
+   ```
+   对每个 INDEX.md：
+   ```
+   Grep: <关键词> → openspec/<领域>/<模块>/INDEX.md
+   ```
+5. 合并结果，按相关性排序（精确匹配 > 模块名匹配 > 内容匹配）
+
+#### 浏览模式
+
+```
+Read: openspec/openspec-trace/GLOBAL_INDEX.md
+```
+直接展示完整的按领域分类树。
+
+#### 精确查看模式
+
+读取指定模块的索引文件：
+```
+Read: openspec/<领域>/<模块>/INDEX.md
+```
+
+若用户还指定了版本号（如 `v1`）：
+```
+Glob: openspec/<领域>/<模块>/v1-*.md
+Read: openspec/<领域>/<模块>/v1-<日期>.md
+```
+
+### 步骤 3：展示结果
+
+#### 关键词检索结果格式
+
+```
+检索关键词："<关键词>"
+
+找到 <N> 个匹配模块：
+
+### <领域>/<模块>
+  领域：<领域>
+  入口：<入口类名>（<HTTP方法> <路径>）
+  版本：v<N>（<日期>）
+  关键词：<keyword1>, <keyword2>, ...
+  摘要：<模块概述>
+```
+
+每个匹配模块后提供 **AskUserQuestion** 后续操作选项：
+- 查看完整 INDEX.md
+- 查看 CHANGELOG.md（版本历史）
+- 阅读指定版本的设计文档
+
+#### 浏览模式结果格式
+
+直接展示 GLOBAL_INDEX.md 内容，然后询问用户是否需要查看某个具体模块。
+
+#### 精确查看结果格式
+
+展示 INDEX.md 完整内容，然后询问用户是否需要阅读具体版本的设计文档。
+
+### 步骤 4（可选）：JSON 输出
+
+若用户要求 JSON 输出（提到 `--json` 或"以 JSON 输出"）：
+
+```json
+{
+  "query": "<关键词>",
+  "mode": "search | browse | exact",
+  "results": [
+    {
+      "domain": "<领域>",
+      "module": "<模块>",
+      "index_path": "openspec/<领域>/<模块>/INDEX.md",
+      "versions": [
+        {
+          "version": "<N>",
+          "date": "<YYYY-MM-DD>",
+          "change": "<变更名>",
+          "doc_path": "openspec/<领域>/<模块>/v<N>-<日期>.md"
+        }
+      ],
+      "keywords": ["<keyword1>", "<keyword2>"],
+      "entry_points": [
+        {
+          "url": "<HTTP方法> <路径>",
+          "method": "<方法名>()",
+          "file": "<Controller文件名>:<行号>"
+        }
+      ],
+      "summary": "<模块概述>"
+    }
+  ]
+}
+```
+
+---
+
+## 注意事项
+
+1. **知识库不存在时**：若 `openspec/openspec-trace/GLOBAL_INDEX.md` 不存在，提示用户先执行 `/opst:code-anysic` 归档业务逻辑后再检索
+2. **无匹配结果时**：展示现有所有领域树，提示用户尝试其他关键词
+3. **关键词模糊匹配**：支持中英文混合匹配（如搜索 "sales" 可匹配中文描述中的"销账"）
+4. **深度查看**：查看设计文档时，如文档较长，优先展示接口定义和业务流程图章节
+5. **版本历史**：展示模块时默认显示最新版本信息，用户可指定查看历史版本

package/plugins/openspec-trace/skills/opst-code-anysic/SKILL.md

@@ -0,0 +1,237 @@
+---
+name: opst-code-anysic
+description: >
+  分析已归档的 OpenSpec 变更代码，提取业务逻辑并自动归档到 openspec/<领域>/<模块>/ 知识库。继承 code2doc-kunge2013 的五段式文档生成逻辑，并扩展为版本化归档、三级索引维护。当用户提到"代码归档"、"业务逻辑归档"、"code-anysic"、"分析变更代码"时使用此技能。
+license: MIT
+compatibility: Requires openspec CLI and git.
+metadata:
+  author: fangkun
+  version: "1.0"
+  generatedBy: "openspec-trace@1.0.0"
+---
+
+分析已归档的 OpenSpec 变更代码，提取业务逻辑并自动归档到 openspec/<领域>/<模块>/ 知识库。
+
+## 工作流
+
+### 步骤 1：确定分析目标
+
+若用户未提供变更名称，列出已归档的变更供选择：
+
+```bash
+ls -t openspec/changes/archive/
+```
+
+使用 **AskUserQuestion** 让用户从列表中选择目标变更。
+
+**重要**：必须经用户确认后才能继续。
+
+### 步骤 2：读取变更上下文
+
+并行读取以下文件，提取功能描述、技术领域、模块名称：
+
+- `openspec/changes/archive/<变更名>/proposal.md`
+- `openspec/changes/archive/<变更名>/design.md`
+- `openspec/changes/archive/<变更名>/tasks.md`
+
+### 步骤 3：分析代码变更
+
+通过 git log 定位该变更对应的 commit 范围，获取涉及的文件列表：
+
+```bash
+git log --oneline -20
+git diff <base-commit>..<head-commit> --name-only
+```
+
+将文件按层次分类：
+
+| 分类 | 匹配模式 |
+|------|----------|
+| Controller | `*Controller.java` |
+| Service | `*Service.java`, `*ServiceImpl.java` |
+| Mapper | `*Mapper.java` |
+| XML | `*Mapper.xml` |
+| Entity | `*Entity.java`, `*DO.java`, `*PO.java` |
+
+使用 **Grep** 提取关键注解：
+
+- `@TableName` → 数据表映射
+- `@RequestMapping` → API 路径前缀
+- `@PostMapping` / `@GetMapping` / `@PutMapping` / `@DeleteMapping` → HTTP 方法与路径
+
+### 步骤 4：确定领域与模块
+
+从 Java 包名推导领域和模块，规则如下：
+
+| 包名示例 | 领域推导 | 模块推导 |
+|----------|----------|----------|
+| `com.example.bill.payment` | `billing` | `payment-processing` |
+| `com.example.invoice.calc` | `invoice` | `calculation` |
+| `com.example.order.service` | `order` | `order-management` |
+
+使用 **AskUserQuestion** 让用户确认或覆盖推导结果（领域名 + 模块名）。
+
+### 步骤 5：生成五段式设计文档
+
+读取各层源码文件（Controller → Service → ServiceImpl → Entity/Mapper → XML），
+继承 code2doc-kunge2013 的五段式结构生成设计文档。
+
+**文档结构**：
+
+```
+---
+domain: <领域>
+module: <模块>
+version: <N>
+date: <YYYY-MM-DD>
+change: <变更名称>
+keywords: [<kw1>, <kw2>, ...]
+code-entry: <Controller类名>（<HTTP方法> <路径>）
+---
+
+# <模块名> — v<N>（<YYYY-MM-DD>）
+
+## 1. 接口定义
+
+| 字段 | 值 |
+|------|----|
+| URL | `<HTTP方法> <路径>` |
+| Controller | `<类名>.<方法名>()` |
+| 入参 | ```json\n{...}\n``` |
+| 出参 | ```json\n{...}\n``` |
+
+## 2. 业务流程图
+
+```mermaid
+flowchart TD
+  ...
+```
+
+## 3. 业务逻辑详情
+
+（SQL 查询 + Java 代码逻辑详解，覆盖核心分支）
+
+## 4. 表结构 ER 图
+
+```mermaid
+erDiagram
+  ...
+```
+
+## 5. 源码文件清单
+
+| 文件 | 类型 | 说明 |
+|------|------|------|
+| ...  | ...  | ...  |
+```
+
+**版本号确定**：
+
+```
+Glob: openspec/<领域>/<模块>/v*.md
+```
+
+取已有文件中最大版本号 N，新版本为 N+1；若目录不存在，从 v1 开始。
+
+### 步骤 6：写入知识库并更新索引
+
+**写入版本化设计文档**：
+
+```
+Write: openspec/<领域>/<模块>/v<N>-<YYYY-MM-DD>.md
+```
+
+**INDEX.md 处理**：
+
+- 若 `openspec/<领域>/<模块>/INDEX.md` 不存在：创建新文件，包含模块概览、版本表、入口点、已知业务规则。
+- 若已存在：Edit INDEX.md，在版本表中追加新版本行。
+
+INDEX.md 格式：
+
+```markdown
+# <模块名> — 模块索引
+
+> 领域：<领域> | 最后更新：<YYYY-MM-DD>
+
+## 模块概览
+
+<功能概述>
+
+## 版本历史
+
+| 版本 | 日期 | 变更 | 文档 |
+|------|------|------|------|
+| v<N> | <日期> | <变更名> | [查看](v<N>-<日期>.md) |
+
+## 入口点
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+
+## 已知业务规则
+
+- <规则 1>
+- <规则 2>
+```
+
+**CHANGELOG.md 处理**：
+
+```
+Append: openspec/<领域>/<模块>/CHANGELOG.md
+```
+
+追加格式：
+
+```markdown
+## v<N> — <YYYY-MM-DD>
+
+**变更**：<变更名>
+
+<本次变更的主要业务逻辑说明>
+```
+
+### 步骤 7：更新全局索引
+
+读取 `openspec/openspec-trace/GLOBAL_INDEX.md`，按以下规则更新：
+
+**按领域表**：若模块是新增的，追加新行：
+
+```
+| <领域> | <模块> | <Controller>（<HTTP方法> <路径>） | <YYYY-MM-DD> | <kw1>, <kw2> |
+```
+
+**按关键词表**：为每个新关键词追加行：
+
+```
+| <关键词> | <领域> | <模块> | [INDEX](openspec/<领域>/<模块>/INDEX.md) |
+```
+
+Write 更新后的 GLOBAL_INDEX.md。
+
+---
+
+## 输出格式
+
+```
+## 归档完成
+
+**变更**：<变更名>
+**知识库路径**：openspec/<领域>/<模块>/
+**版本**：v<N>-<YYYY-MM-DD>.md
+**INDEX.md**：✓ 已创建 / ✓ 已更新
+**CHANGELOG.md**：✓ 已追加
+**GLOBAL_INDEX.md**：✓ 已更新
+
+关键词：<kw1>, <kw2>, ...
+入口点：<Controller>（<HTTP方法> <路径>）
+```
+
+---
+
+## 注意事项
+
+1. 必须经用户确认分析目标后才能继续
+2. 领域和模块名称必须经用户确认
+3. 所有生成文档使用中文，技术术语（类名、方法名、注解）保留英文
+4. 版本号基于现有 v*.md 文件自动递增，不跳号
+5. 若 git diff 无法获取，从 proposal.md/design.md 中推断文件列表

package/plugins/openspec-workflow/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "openspec-workflow",
+  "description": "Spec-driven change lifecycle for Claude Code: explore, propose, apply, archive",
+  "author": { "name": "kunge2013" },
+  "license": "MIT"
+}

package/plugins/openspec-workflow/skills/openspec-apply-change/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: openspec-apply-change
+description: Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.3.1"
+---
+
+Implement tasks from an OpenSpec change.
+
+**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **Select the change**
+
+   If a name is provided, use it. Otherwise:
+   - Infer from conversation context if the user mentioned a change
+   - Auto-select if only one active change exists
+   - If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select
+
+   Always announce: "Using change: <name>" and how to override (e.g., `/opsx:apply <other>`).
+
+2. **Check status to understand the schema**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
+
+3. **Get apply instructions**
+
+   ```bash
+   openspec instructions apply --change "<name>" --json
+   ```
+
+   This returns:
+   - `contextFiles`: artifact ID -> array of concrete file paths (varies by schema - could be proposal/specs/design/tasks or spec/tests/implementation/docs)
+   - Progress (total, complete, remaining)
+   - Task list with status
+   - Dynamic instruction based on current state
+
+   **Handle states:**
+   - If `state: "blocked"` (missing artifacts): show message, suggest using openspec-continue-change
+   - If `state: "all_done"`: congratulate, suggest archive
+   - Otherwise: proceed to implementation
+
+4. **Read context files**
+
+   Read every file path listed under `contextFiles` from the apply instructions output.
+   The files depend on the schema being used:
+   - **spec-driven**: proposal, specs, design, tasks
+   - Other schemas: follow the contextFiles from CLI output
+
+5. **Show current progress**
+
+   Display:
+   - Schema being used
+   - Progress: "N/M tasks complete"
+   - Remaining tasks overview
+   - Dynamic instruction from CLI
+
+6. **Implement tasks (loop until done or blocked)**
+
+   For each pending task:
+   - Show which task is being worked on
+   - Make the code changes required
+   - Keep changes minimal and focused
+   - Mark task complete in the tasks file: `- [ ]` → `- [x]`
+   - Continue to next task
+
+   **Pause if:**
+   - Task is unclear → ask for clarification
+   - Implementation reveals a design issue → suggest updating artifacts
+   - Error or blocker encountered → report and wait for guidance
+   - User interrupts
+
+7. **On completion or pause, show status**
+
+   Display:
+   - Tasks completed this session
+   - Overall progress: "N/M tasks complete"
+   - If all done: suggest archive
+   - If paused: explain why and wait for guidance
+
+**Output During Implementation**
+
+```
+## Implementing: <change-name> (schema: <schema-name>)
+
+Working on task 3/7: <task description>
+[...implementation happening...]
+✓ Task complete
+
+Working on task 4/7: <task description>
+[...implementation happening...]
+✓ Task complete
+```
+
+**Output On Completion**
+
+```
+## Implementation Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Progress:** 7/7 tasks complete ✓
+
+### Completed This Session
+- [x] Task 1
+- [x] Task 2
+...
+
+All tasks complete! Ready to archive this change.
+```
+
+**Output On Pause (Issue Encountered)**
+
+```
+## Implementation Paused
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Progress:** 4/7 tasks complete
+
+### Issue Encountered
+<description of the issue>
+
+**Options:**
+1. <option 1>
+2. <option 2>
+3. Other approach
+
+What would you like to do?
+```
+
+**Guardrails**
+- Keep going through tasks until done or blocked
+- Always read context files before starting (from the apply instructions output)
+- If task is ambiguous, pause and ask before implementing
+- If implementation reveals issues, pause and suggest artifact updates
+- Keep code changes minimal and scoped to each task
+- Update task checkbox immediately after completing each task
+- Pause on errors, blockers, or unclear requirements - don't guess
+- Use contextFiles from CLI output, don't assume specific file names
+
+**Fluid Workflow Integration**
+
+This skill supports the "actions on a change" model:
+
+- **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions
+- **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly