adspecs 0.1.38 → 0.1.39

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
     {
       "name": "adspecs",
       "description": "AI Coding研发协同开发插件",
-      "version": "0.1.38",
+      "version": "0.1.39",
       "source": "./",
       "author": {
         "name": "Qingwen Chen",

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "adspecs",
   "displayName": "adspecs AI Plugin",
   "description": "AI first工程规范驱动开发插件",
-  "version": "0.1.38",
+  "version": "0.1.39",
   "author": {
     "name": "Qingwen Chen",
     "email": "cqinwn@qq.com",

package/.codebuddy-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "adspecs",
   "displayName": "adspecs AI 工程规范驱动开发插件",
-  "version": "0.1.38",
+  "version": "0.1.39",
   "description": "AI-first specification-driven development plugin for ECP platform full-lifecycle development",
   "descriptionZh": "AI优先的工程规范驱动开发插件，覆盖需求分析、PRD、系统设计、任务拆解、TDD、代码评审、Wiki同步全流程",
   "author": {

package/.qoder-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "adspecs",
   "displayName": "adspecs AI 工程规范驱动开发插件",
-  "version": "0.1.38",
+  "version": "0.1.39",
   "description": "AI-first specification-driven development plugin for ECP platform full-lifecycle development",
   "descriptionZh": "AI优先的工程规范驱动开发插件，覆盖需求分析、PRD、系统设计、任务拆解、TDD、代码评审、Wiki同步全流程",
   "author": {

package/.workbuddy-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "adspecs",
   "displayName": "adspecs AI 工程规范驱动开发插件",
-  "version": "0.1.38",
+  "version": "0.1.39",
   "description": "AI-first specification-driven development plugin for ECP platform full-lifecycle development",
   "descriptionZh": "AI优先的工程规范驱动开发插件，覆盖需求分析、PRD、系统设计、任务拆解、TDD、代码评审、Wiki同步全流程",
   "author": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adspecs",
-  "version": "0.1.38",
+  "version": "0.1.39",
   "description": "AI first 工程规范驱动开发插件 — 支持 npm 安装和 CLI 初始化",
   "bin": {
     "adspecs": "bin/adspecs.js"

package/skills/project-init/SKILL.md

@@ -28,6 +28,7 @@ argument-hint: "[--project-name <名称>] [--project-dir <目录>] [--company <
 | `web-ui/`     | 前端正式项目                  | 从插件根目录 references/web-ui 复制                                                                                   | 完整 / 轻量        |
 | `service/`    | 后端服务模块目录              | 创建 service 目录 + README.md                                                                                      | 完整 / 轻量        |
 | `.adspecs/`   | 插件运行时配置与脚本          | 从插件根目录 .adspecs 完整复制（含 extensions.yml、feature.json、scripts/）                                       | 简易 / 经典 / 完整 / 轻量 |
+| `hooks/`      | Hook 脚本（SessionStart/Stop 等） | 从插件根目录 hooks/ 完整复制（含 hooks.json、platform.js 等 5 个脚本）                                       | 简易 / 经典 / 完整 / 轻量 |
 
 ## 适用场景
 
@@ -195,6 +196,7 @@ questions: [
 {pwd}/（或 {pwd}/{project_dir}/）
 ├── .adspecs/
 ├── docs/
+├── hooks/
 └── wiki/
 ```
 
@@ -204,6 +206,7 @@ questions: [
 {pwd}/（或 {pwd}/{project_dir}/）
 ├── .adspecs/
 ├── docs/
+├── hooks/
 ├── wiki/
 └── front-demo/
 ```
@@ -214,6 +217,7 @@ questions: [
 {pwd}/（或 {pwd}/{project_dir}/）
 ├── .adspecs/
 ├── docs/
+├── hooks/
 ├── wiki/
 ├── web-ui/
 ├── service/
@@ -283,10 +287,10 @@ questions: [
    - 如果 `TARGET` 存在 → 进入**冲突处理流程**（第 6 步）
 6. **冲突处理流程**（按模式扫描对应区域）：
    - 根据模式扫描 `TARGET` 下对应区域目录的存在情况：
-     - **简易模式**：扫描 `.adspecs/`、`docs/`、`wiki/`
-     - **经典模式**：扫描 `.adspecs/`、`docs/`、`wiki/`、`front-demo/`
-     - **完整模式**：扫描 `.adspecs/`、`docs/`、`wiki/`、`web-ui/`、`service/`、`front-demo/`
-     - **轻量模式**：扫描 `.adspecs/`、`docs/`、`wiki/`、`web-ui/`、`service/`、`front-demo/`（同完整模式扫描范围）
+     - **简易模式**：扫描 `.adspecs/`、`docs/`、`wiki/`、`hooks/`
+     - **经典模式**：扫描 `.adspecs/`、`docs/`、`wiki/`、`front-demo/`、`hooks/`
+     - **完整模式**：扫描 `.adspecs/`、`docs/`、`wiki/`、`web-ui/`、`service/`、`front-demo/`、`hooks/`
+     - **轻量模式**：扫描 `.adspecs/`、`docs/`、`wiki/`、`web-ui/`、`service/`、`front-demo/`、`hooks/`（同完整模式扫描范围）
    - 如果对应区域均不存在 → 视为空目录，直接继续，跳到第 7 步
    - 如果有任意区域已存在 → 使用 **AskUserQuestion** 工具询问用户对**每个已存在的区域**的处理方式，提供以下两个选项：
      - **重新创建**：删除该区域现有文件，使用最新模板重新创建
@@ -300,6 +304,7 @@ questions: [
        .adspecs: "recreate" | "skip" | "create",
        docs:  "recreate" | "skip" | "create",   # create = 原本不存在，直接创建
        wiki: "recreate" | "skip" | "create",
+       hooks: "recreate" | "skip" | "create",
      }
      子目录决策 = {
        conventions_decision: "update" | "skip",   # docs 为 skip 且 40-project_conventions/ 有文件时
@@ -315,6 +320,7 @@ questions: [
        docs:       "recreate" | "skip" | "create",
        wiki:      "recreate" | "skip" | "create",
        front_demo: "recreate" | "skip" | "create",
+       hooks:      "recreate" | "skip" | "create",
      }
      子目录决策 = {
        conventions_decision: "update" | "skip",   # docs 为 skip 且 40-project_conventions/ 有文件时
@@ -332,6 +338,7 @@ questions: [
        web_ui:     "recreate" | "skip" | "create",
        service:    "recreate" | "skip" | "create",
        front_demo: "recreate" | "skip" | "create",
+       hooks:      "recreate" | "skip" | "create",
      }
      子目录决策 = {
        conventions_decision: "update" | "skip",   # docs 为 skip 且 40-project_conventions/ 有文件时
@@ -349,6 +356,7 @@ questions: [
        web_ui:     "recreate" | "skip" | "create",
        service:    "recreate" | "skip" | "create",
        front_demo: "recreate" | "skip" | "create",  # 固定 antd-front-demo
+       hooks:      "recreate" | "skip" | "create",
      }
      子目录决策 = {
        conventions_decision: "update" | "skip",   # docs 为 skip 且 40-project_conventions/ 有文件时
@@ -1096,6 +1104,65 @@ echo "更新了 ${#REPLACE_FILES[@]} 个模板文件，保留了 ${#KEEP_FILES[@
 
 ---
 
+### 阶段 6.8：复制 hooks/ 脚本目录
+
+**适用模式：简易 / 经典 / 完整 / 轻量**
+
+**重要**：hooks 脚本是插件运行时核心组件，负责 SessionStart/Stop 等生命周期事件处理（wiki 同步队列、commit 候选队列、AI 会话日志等）。缺少此目录会导致 `Cannot find module .../hooks/commit-queue.js` 等错误。
+
+根据区域决策执行：
+
+- `hooks` 决策为 `skip` → 输出 `⏭ 阶段 6.8 跳过：hooks/ 已存在，保留现有内容`，进入阶段 7
+- `hooks` 决策为 `recreate` → 执行 `rm -rf "$TARGET/hooks"`，然后按下方步骤完整重建
+- `hooks` 决策为 `create` → 直接按下方步骤创建
+
+从插件根目录完整复制 `hooks/` 目录到目标项目根目录，包含 hooks.json 配置和所有 Node.js 脚本。
+
+#### 源路径
+
+`$PLUGIN_DIR/hooks/`（其中 `PLUGIN_DIR` 为 adspecs 插件根目录，即 `SKILL_DIR/../..`）
+
+#### 目录结构
+
+```
+hooks/
+├── hooks.json            # 跨平台 Hook 配置（SessionStart/PreCompact/PostToolUse/Stop）
+├── platform.js           # 平台检测工具模块（Claude Code / Qoder / WorkBuddy 兼容）
+├── session-start.js      # SessionStart — 注入 using-adspecs 技能引导
+├── wiki-queue.js         # PostToolUse/Stop — wiki 同步队列管理
+├── commit-queue.js       # PostToolUse/Stop — commit 候选队列管理
+└── session-logger.js     # SessionStart/PreCompact/Stop — AI 会话日志管理
+```
+
+#### 执行命令
+
+```bash
+SKILL_DIR="<SKILL.md 所在目录>"
+PLUGIN_DIR="$(cd "$SKILL_DIR/../.." && pwd)"   # adspecs 插件根目录
+
+# 如果 hooks 决策为 recreate，先删除现有目录
+# rm -rf "$TARGET/hooks"
+
+# 从插件根目录完整复制 hooks/
+cp -r "$PLUGIN_DIR/hooks" "$TARGET/hooks"
+
+# 统计复制的文件数量
+find "$TARGET/hooks" -type f | wc -l
+```
+
+**注意**：
+- hooks.json 中的 `${CLAUDE_PLUGIN_ROOT}` 由平台在加载插件时注入，指向插件根目录或项目目录
+- 复制 hooks/ 到项目目录确保脚本在任何平台环境下都能正确解析
+- 不要修改 hooks.json 内容，保持 `${CLAUDE_PLUGIN_ROOT}` 变量引用不变
+
+完成后输出：
+
+- 新建时：`✅ 阶段 6.8 完成：hooks/ 脚本目录已复制（{N} 个文件）`
+- 重建时：`🔄 阶段 6.8 完成：hooks/ 脚本目录已重新复制（{N} 个文件）`
+- 跳过时：`⏭ 阶段 6.8 跳过：hooks/ 已存在，保留现有内容`
+
+---
+
 ### 阶段 7：生成路径配置文件
 
 **适用模式：简易 / 经典 / 完整 / 轻量**
@@ -1181,6 +1248,7 @@ mkdir -p "$TARGET/.adspecs"
 | docs/                     | ✅ 已创建 / 🔄 已重建 / ⏭ 已跳过 | 11 个骨架目录，40 仅创建空目录                                             |
 | └ 40-project_conventions/ | 🔄 已更新 / ⏭ 已跳过             | docs/ 跳过时，40 子目录的更新决策                                          |
 | wiki/                     | ✅ 已创建 / 🔄 已重建 / ⏭ 已跳过 | 基线文件目录 + README.md                                                   |
+| hooks/                    | ✅ 已创建 / 🔄 已重建 / ⏭ 已跳过 | Hook 脚本（hooks.json + platform.js + 4 个事件脚本）                       |
 | .adspecs/project.json     | ✅ 已生成 / 🔄 已更新             | 项目元数据文件（已有字段合并，缺失属性补全）                               |
 | .adspecs/paths.json       | ✅ 已生成 / ⏭ 已存在跳过         | 路径配置文件                                                               |
 
@@ -1195,6 +1263,7 @@ mkdir -p "$TARGET/.adspecs"
 | └ 40-project_conventions/ | 🔄 已更新 / ⏭ 已跳过             | docs/ 跳过时，40 子目录的更新决策                                          |
 | wiki/                     | ✅ 已创建 / 🔄 已重建 / ⏭ 已跳过 | 基线文件目录 + README.md                                                   |
 | front-demo/               | ✅ 已创建 / 🔄 已重建 / ⏭ 已跳过 | {技术栈名}，{N} 个文件                                                     |
+| hooks/                    | ✅ 已创建 / 🔄 已重建 / ⏭ 已跳过 | Hook 脚本（hooks.json + platform.js + 4 个事件脚本）                       |
 | .adspecs/project.json     | ✅ 已生成 / 🔄 已更新             | 项目元数据文件（已有字段合并，缺失属性补全）                               |
 | .adspecs/paths.json       | ✅ 已生成 / ⏭ 已存在跳过         | 路径配置文件                                                               |
 
@@ -1211,6 +1280,7 @@ mkdir -p "$TARGET/.adspecs"
 | web-ui/                   | ✅ 已创建 / 🔄 已重建 / ⏭ 已跳过 | {N} 个文件                                                                 |
 | service/                  | ✅ 已创建 / 🔄 已重建 / ⏭ 已跳过 | 模块 service 目录 + README.md                                              |
 | front-demo/               | ✅ 已创建 / 🔄 已重建 / ⏭ 已跳过 | {技术栈名}，{N} 个文件                                                     |
+| hooks/                    | ✅ 已创建 / 🔄 已重建 / ⏭ 已跳过 | Hook 脚本（hooks.json + platform.js + 4 个事件脚本）                       |
 | .adspecs/project.json     | ✅ 已生成 / 🔄 已更新             | 项目元数据文件（已有字段合并，缺失属性补全）                               |
 | .adspecs/paths.json       | ✅ 已生成 / ⏭ 已存在跳过         | 路径配置文件                                                               |
 
@@ -1227,6 +1297,7 @@ mkdir -p "$TARGET/.adspecs"
 | web-ui/                   | ✅ 已创建 / 🔄 已重建 / ⏭ 已跳过 | React + AntD6 前端项目，{N} 个文件                                         |
 | service/                  | ✅ 已创建 / 🔄 已重建 / ⏭ 已跳过 | Python 后端服务目录 + README.md                                            |
 | front-demo/               | ✅ 已创建 / 🔄 已重建 / ⏭ 已跳过 | Ant Design React，{N} 个文件                                               |
+| hooks/                    | ✅ 已创建 / 🔄 已重建 / ⏭ 已跳过 | Hook 脚本（hooks.json + platform.js + 4 个事件脚本）                       |
 | .adspecs/project.json     | ✅ 已生成 / 🔄 已更新             | 项目元数据文件（已有字段合并，缺失属性补全）                               |
 | .adspecs/paths.json       | ✅ 已生成 / ⏭ 已存在跳过         | 路径配置文件                                                               |
 
@@ -1244,12 +1315,14 @@ mkdir -p "$TARGET/.adspecs"
 {pwd}/{PROJECT_DIR}/（或直接 {pwd}/）
 ├── .adspecs/ (插件配置、脚本、模板 + project.json)
 ├── docs/ (11 个子目录)
+├── hooks/ (Hook 脚本：SessionStart/Stop/PostToolUse 等)
 └── wiki/ (基线文件目录)
 
 **经典模式：**
 {pwd}/{PROJECT_DIR}/（或直接 {pwd}/）
 ├── .adspecs/ (插件配置、脚本、模板 + project.json)
 ├── docs/ (11 个子目录)
+├── hooks/ (Hook 脚本：SessionStart/Stop/PostToolUse 等)
 ├── wiki/ (基线文件目录)
 └── front-demo/ ({技术栈名}前端演示项目)
 
@@ -1257,6 +1330,7 @@ mkdir -p "$TARGET/.adspecs"
 {pwd}/{PROJECT_DIR}/（或直接 {pwd}/）
 ├── .adspecs/ (插件配置、脚本、模板 + project.json)
 ├── docs/ (11 个子目录)
+├── hooks/ (Hook 脚本：SessionStart/Stop/PostToolUse 等)
 ├── wiki/ (基线文件目录)
 ├── web-ui/ (Vue3 壳工程)
 ├── service/
@@ -1267,6 +1341,7 @@ mkdir -p "$TARGET/.adspecs"
 {pwd}/{PROJECT_DIR}/（或直接 {pwd}/）
 ├── .adspecs/ (插件配置、脚本、模板 + project.json)
 ├── docs/ (11 个子目录 + 40-project_conventions/ 含 Python 后端规范 + React 前端规范)
+├── hooks/ (Hook 脚本：SessionStart/Stop/PostToolUse 等)
 ├── wiki/ (基线文件目录)
 ├── web-ui/ (React + AntD6 前端项目)
 ├── service/ (Python + SQLite 后端服务)
@@ -1357,6 +1432,7 @@ mkdir -p "$TARGET/.adspecs"
 - [ ] feature.json 属性补全检查已完成（recreate/skip 时，已对比 references 初始版本并补全缺失属性，已有属性不覆盖）
 - [ ] project.json 属性补全检查已完成（recreate/skip 时，已对比 references 初始版本并补全缺失属性）
 - [ ] .adspecs/project.json 项目元数据文件已生成或更新
+- [ ] hooks/ 脚本目录已从插件根目录完整复制/重建/跳过（所有模式，含 hooks.json + platform.js + 4 个事件脚本）
 - [ ] .adspecs/paths.json 路径配置文件已生成（含 architecture_dir 和 export_dir，或已存在时跳过）
 - [ ] 初始化报告已输出（包含项目信息、模式、技术栈、各区域状态）
 ````

package/src/lib/area-scanner.js

@@ -21,6 +21,7 @@ const AREA_DIRS = {
   webUi: 'web-ui',
   service: 'service',
   frontDemo: 'front-demo',
+  hooks: 'hooks',
 };
 
 /**
@@ -32,14 +33,14 @@ const AREA_DIRS = {
 function getAreaListForMode(mode) {
   switch (mode) {
     case 'simple':
-      return ['adspecs', 'docs', 'wiki'];
+      return ['adspecs', 'docs', 'wiki', 'hooks'];
     case 'classic':
-      return ['adspecs', 'docs', 'wiki', 'frontDemo'];
+      return ['adspecs', 'docs', 'wiki', 'frontDemo', 'hooks'];
     case 'full':
     case 'demo':
-      return ['adspecs', 'docs', 'wiki', 'webUi', 'service', 'frontDemo'];
+      return ['adspecs', 'docs', 'wiki', 'webUi', 'service', 'frontDemo', 'hooks'];
     default:
-      return ['adspecs', 'docs', 'wiki'];
+      return ['adspecs', 'docs', 'wiki', 'hooks'];
   }
 }
 
@@ -83,6 +84,7 @@ function areaDisplayName(areaKey) {
     webUi: 'web-ui',
     service: 'service',
     frontDemo: 'front-demo',
+    hooks: 'hooks',
   };
   return names[areaKey] || areaKey;
 }

package/src/lib/report.js

@@ -265,7 +265,8 @@ function printDirectoryTree(mode, frontDemo) {
       lines.push(`   │       └── frontend-standard/  （${fdLabel} 前端规范）`);
     }
   }
-  lines.push('   ├── wiki/              （基线文件目录）');
+  lines.push('   ├── hooks/             （Hook 脚本：SessionStart/Stop/PostToolUse 等）');
+  lines.push('   └── wiki/              （基线文件目录）');
 
   if (mode === 'full' || mode === 'demo') {
     lines.push('   ├── web-ui/            （前端生产项目）');

package/src/lib/scaffolder.js

@@ -123,6 +123,9 @@ async function scaffold(opts) {
     detail: projectJsonResult,
   });
 
+  // === 阶段 6.8: hooks/ ===
+  report.stages.push(scaffoldHooks(targetDir, pluginDir, decisions.hooks, logger));
+
   // === 阶段 7: paths.json ===
   const pathsResult = writePathsJson(targetDir);
   logger(
@@ -508,6 +511,36 @@ async function scaffoldAdspecs(targetDir, pluginDir, decision, subDecisions, log
   return stage;
 }
 
+/**
+ * 阶段 6.8: hooks/ 脚本目录
+ *
+ * 从插件根目录复制 hooks/ 到目标项目，确保 SessionStart/Stop 等
+ * 生命周期事件脚本（wiki-queue、commit-queue、session-logger）可用。
+ */
+function scaffoldHooks(targetDir, pluginDir, decision, logger) {
+  const hooksDir = path.join(targetDir, 'hooks');
+  const stage = { name: 'hooks/' };
+
+  if (decision === 'skip') {
+    logger(`⏭ 阶段 6.8 跳过：hooks/ 已存在，保留现有内容`);
+    stage.status = 'skipped';
+    return stage;
+  }
+
+  const action = prepareDirByDecision(hooksDir, decision, logger, 'hooks');
+
+  // 从插件根目录复制 hooks/
+  const result = copyDirFiltered(path.join(pluginDir, 'hooks'), hooksDir);
+
+  stage.fileCount = result.fileCount;
+  stage.status = action === 'recreate' ? 'recreated' : 'created';
+
+  const verb = action === 'recreate' ? '重新复制' : '复制';
+  logger(`✅ 阶段 6.8 完成：hooks/ 脚本目录已${verb}（${result.fileCount} 个文件）`);
+
+  return stage;
+}
+
 /**
  * 阶段 6.5: 生成 .adspecs/project.json
  */