@culeo/specx 0.1.0 → 0.1.2

package/README.md

@@ -88,20 +88,20 @@ specx 是一套企业级研发流程 skill 系列，核心理念是**先签合
 docs/specx/
 ├── spaces/                    # 需求空间（每个需求独立目录）
 │   └── {yyyyMMdd}-{需求摘要}/
-│       ├── Raws/               # 原始需求来源（多源分类）
+│       ├── raws/               # 原始需求来源（多源分类）
 │       │   ├── P001-{需求名称}.md       # 产品需求文档
 │       │   ├── U001-{用户反馈}.md       # 用户输入/语料
 │       │   └── ...
-│       ├── T-01-{子需求名}/
+│       ├── t-01-{子需求名}/
 │       │   ├── 00-子需求.md            # 子需求原始描述（由 demystify 产出）
 │       │   ├── 01-clarify.md           # 澄清记录
 │       │   ├── 02-spec.md              # 规格说明书
 │       │   ├── 03-design.md            # 设计方案
 │       │   └── 04-tasks.md             # 任务清单
-│       └── T-02-{子需求名}/
+│       └── t-02-{子需求名}/
 │           └── ...
 ├── wiki/                      # 项目知识库（归档沉淀）
-├── rule/                      # 框架规范
+├── rules/                      # 框架规范
 └── templates/                 # 项目专属模板
 ```
 
@@ -111,7 +111,7 @@ docs/specx/
 
 - **文件名规范**：`00-子需求.md` / `01-clarify.md` / `02-spec.md` / `03-design.md` / `04-tasks.md`
 - **wiki 知识沉淀**：`docs/specx/wiki/`，由 `specx-archive` 维护
-- **框架规范**：`docs/specx/rule/`，clarify 时跳过已有规范，不重复提问
+- **框架规范**：`docs/specx/rules/`，clarify 时跳过已有规范，不重复提问
 - **项目模板**：`docs/specx/templates/`，首次 design 时生成
 
 ---

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@culeo/specx",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Install specx skills to AI coding agents (Claude Code, Codex, etc.)",
   "type": "module",
   "bin": {
-    "specx": "./specx.js"
+    "specx": "./src/specx.js"
   },
   "dependencies": {
     "commander": "^12.0.0"

package/skills/specx-archive/SKILL.md

@@ -11,7 +11,7 @@ tags: [specx, archive, wiki, knowledge]
 
 当一个子需求完成（clarify → spec → design → code 全部走完）后，用户说"归档"、"沉淀到 wiki"、"完成这个需求"时使用。
 
-**前置判断：** 子需求目录 `T-xx/` 下已有 `clarify.md`、`spec.md`、`design.md`（及可选 `code` 相关文档）。
+**前置判断：** 子需求目录 `t-xx/` 下已有 `clarify.md`、`spec.md`、`design.md`（及可选 `code` 相关文档）。
 
 **不是触发的情况：**
 - 需求还在中途（未完成 code）
@@ -21,11 +21,11 @@ tags: [specx, archive, wiki, knowledge]
 
 ## 输入
 
-- `T-xx/00-子需求.md` — 原始需求
-- `T-xx/01-clarify.md` — 澄清后的需求
-- `T-xx/02-spec.md` — 规格说明书
-- `T-xx/03-design.md` — 设计方案
-- `T-xx/04-tasks.md` — 任务清单（已完成的）
+- `t-xx/00-子需求.md` — 原始需求
+- `t-xx/01-clarify.md` — 澄清后的需求
+- `t-xx/02-spec.md` — 规格说明书
+- `t-xx/03-design.md` — 设计方案
+- `t-xx/04-tasks.md` — 任务清单（已完成的）
 
 ---
 
@@ -54,8 +54,8 @@ docs/specx/wiki/
 
 ### 命名规则
 
-- 文件名：`{T-xx}-{简短英文名}.md`，小写，连字符分隔
-- 示例：`T01-stock-card.md`、`T03-redis-cache.md`
+- 文件名：`{t-xx}-{简短英文名}.md`，小写，连字符分隔
+- 示例：`t01-stock-card.md`、`t03-redis-cache.md`
 
 > 首次归档时由本 skill 创建 `docs/specx/wiki/` 目录和 `README.md`。
 
@@ -137,7 +137,7 @@ docs/specx/wiki/
 **分类：** {entities/features/decisions/components}
 **最后更新时间：** {YYYY-MM-DD}
 **关联需求：**
-- [T-xx](../{需求目录}/T-xx/00-子需求.md)
+- [t-xx](../{需求目录}/t-xx/00-子需求.md)
 
 ---
 
@@ -199,15 +199,15 @@ history:
 
 ## Step 6️⃣ 更新子需求目录状态
 
-在 `T-xx/` 下的 `README.md`（如果没有就创建）标注归档状态：
+在 `t-xx/` 下的 `README.md`（如果没有就创建）标注归档状态：
 
 ```markdown
-# T-{xx}-{子需求名称}
+# t-{xx}-{子需求名称}
 
 **状态：** ✅ 已归档
 **最后更新时间：** {YYYY-MM-DD}
 **Wiki 沉淀位置：**
-- [T-xx-{slug}](../wiki/{分类}/T-xx-{slug}.md)
+- [t-xx-{slug}](../wiki/{分类}/t-xx-{slug}.md)
 ```
 
 ---
@@ -218,7 +218,7 @@ history:
 [ ] 已读取全部子需求文档（00-子需求/clarify/spec/design/tasks）
 [ ] 判断了正确的 wiki 分类（entities/features/decisions/components）
 [ ] 每个提炼内容写成独立文件
-[ ] 文件名符合命名规则 {T-xx}-{slug}.md
+[ ] 文件名符合命名规则 {t-xx}-{slug}.md
 [ ] 更新了 README.md 索引（顶部插入新行）
 [ ] 标注了子需求目录为已归档
 [ ] 未污染原始文档（clarify/spec/design.md 未被修改）

package/skills/specx-clarify/SKILL.md

@@ -159,7 +159,7 @@ history:
 # {子需求名称}
 
 **所属原始需求：** {需求名称}
-**子需求目录：** T-{序号}-{名称}
+**子需求目录：** t-{序号}-{名称}
 
 ---
 
@@ -207,16 +207,16 @@ history:
 
 ### Step 2.5️⃣ 框架对齐（跳过已定义的）
 
-> ⚠️ 如果 `docs/specx/rule/` 下已有规范，只clarify 框架未定义的部分
+> ⚠️ 如果 `docs/specx/rules/` 下已有规范，只clarify 框架未定义的部分
 
 **动作：**
-1. 扫描 `docs/specx/rule/` 目录下的规范文件
+1. 扫描 `docs/specx/rules/` 目录下的规范文件
 2. 在 clarify-prd 中标注哪些是框架定义的（直接引用，不重复问）
 3. 只对「框架未定义」的部分提问
 
 **扫描范围：**
 ```
-docs/specx/rule/          → 项目框架规范（由项目自己组织子目录结构）
+docs/specx/rules/          → 项目框架规范（由项目自己组织子目录结构）
 ```
 
 **标注示例：**
@@ -252,7 +252,7 @@ history:
 
 # {子需求名称} — 规格说明书
 
-**所属子需求：** T-{序号}-{名称}
+**所属子需求：** t-{序号}-{名称}
 
 ---
 
@@ -505,7 +505,7 @@ history:
 - **两个文件同步更新** — clarify-prd 和 spec 是一体的
 - **clarify 迭代次数不限** — 可能是 1 次，可能是 10 次，都正常
 - **文档状态** — 新建时 `draft`，完成时 `review`
-- **框架已定义的不重复问** — 先扫描 `docs/specx/rule/`，直接引用，只clarify 未定义的部分
+- **框架已定义的不重复问** — 先扫描 `docs/specx/rules/`，直接引用，只clarify 未定义的部分
 - **避免污染上下文** — 框架规范在 rule/ 目录维护，不进clarify过程
 
 ---

package/skills/specx-create-rule/SKILL.md

@@ -36,7 +36,7 @@ tags: [specx, rule, convention, knowledge]
 | **替换** | 现有规则方向正确但表述不对 | 替换原文 |
 
 **判断步骤：**
-1. 读取 `docs/specx/rule/` 下所有现有规则
+1. 读取 `docs/specx/rules/` 下所有现有规则
 2. 与新规则对比：是否同类？是否矛盾？是否重复？
 3. 确定类型后，再执行对应动作
 
@@ -44,9 +44,9 @@ tags: [specx, rule, convention, knowledge]
 
 ## 规则发现路径
 
-### 路径 1：项目初始化时（docs/specx/rule 不存在）
+### 路径 1：项目初始化时（docs/specx/rules 不存在）
 
-**前置判断：** `docs/specx/rule/` 目录不存在
+**前置判断：** `docs/specx/rules/` 目录不存在
 
 **扫描步骤：**
 
@@ -56,7 +56,7 @@ tags: [specx, rule, convention, knowledge]
    - 目录结构约定
    - 常用工具库
    - 分层架构（MVVM / Clean / DDD）
-3. **推断规则** — 从扫描结果推断项目规范，写入 `docs/specx/rule/`
+3. **推断规则** — 从扫描结果推断项目规范，写入 `docs/specx/rules/`
 
 ### 路径 2：对话中途纠正（上下文沉淀）
 
@@ -65,16 +65,16 @@ tags: [specx, rule, convention, knowledge]
 **动作：**
 1. 理解用户纠正的本质（表面修改 vs 原则变更）
 2. 询问用户："是否需要把这个规则固化到项目的规范文档里？"
-3. 如用户确认，从纠正内容中提炼规则，写入 `docs/specx/rule/`
+3. 如用户确认，从纠正内容中提炼规则，写入 `docs/specx/rules/`
 
 ### 路径 3：用户明确提出规则
 
 **前置判断：** 用户说"加上 X 规则"、"规定 Y 这样做"等
 
 **动作：**
-1. **先判断** — 读取 `docs/specx/rule/` 下现有规则，确认是否已有相关规则
+1. **先判断** — 读取 `docs/specx/rules/` 下现有规则，确认是否已有相关规则
 2. 按判断结果执行（新增/冲突/过时/细化/替换）
-3. 更新 `docs/specx/rule/README.md`
+3. 更新 `docs/specx/rules/README.md`
 
 ### 路径 4：意图不明确
 
@@ -88,10 +88,10 @@ tags: [specx, rule, convention, knowledge]
 
 ## 输出结构
 
-### docs/specx/rule/ 目录结构
+### docs/specx/rules/ 目录结构
 
 ```
-docs/specx/rule/
+docs/specx/rules/
 ├── README.md          # 规则总览 & 索引
 ├── naming.md          # 命名规范
 ├── workflow.md        # 开发流程规范
@@ -99,7 +99,7 @@ docs/specx/rule/
 └── architecture.md    # 架构约定
 ```
 
-### docs/specx/rule/README.md 模板
+### docs/specx/rules/README.md 模板
 
 ```markdown
 # 项目规范

package/skills/specx-demystify/SKILL.md

@@ -22,12 +22,12 @@ history:
 
 | 输入 | 说明 |
 |------|------|
-| 原始需求来源 | 一个或多个文件，放入 `docs/specx/spaces/{yyyyMMdd}-{摘要}/Raws/` 目录，只读不修改 |
+| 原始需求来源 | 一个或多个文件，放入 `docs/specx/spaces/{yyyyMMdd}-{摘要}/raws/` 目录，只读不修改 |
 | 项目上下文 | 技术栈（iOS / KMP / Android）、现有框架规范、架构约定 |
 
-### Raws/ 目录规范
+### raws/ 目录规范
 
-所有原始来源文件（PRD、用户反馈、聊天记录、参考文献等）统一放入 `Raws/` 子目录，按分类前缀命名：
+所有原始来源文件（PRD、用户反馈、聊天记录、参考文献等）统一放入 `raws/` 子目录，按分类前缀命名：
 
 | 分类 | 前缀 | 说明 |
 |------|------|------|
@@ -51,7 +51,7 @@ Raws/
 
 | 输出 | 格式 | 说明 |
 |------|------|------|
-| 子需求目录集合 | `docs/specx/spaces/{yyyyMMdd}-{摘要}/T-{编号}-{名称}/00-子需求.md` | 每个子需求独立目录，含独立分析 |
+| 子需求目录集合 | `docs/specx/spaces/{yyyyMMdd}-{摘要}/t-{编号}-{名称}/00-子需求.md` | 每个子需求独立目录，含独立分析 |
 | 拆解决策记录 | 同一 docs 目录下的 `00-拆解策略.md`（可选） | 记录选择策略 A/B 的理由 |
 
 ## 4. 拆解策略（二选一）
@@ -90,7 +90,7 @@ Raws/
 - 检查项目是否已有数据模型规范、状态机模式、数据流约定（如已有项目的 Entity 定义、API 规范层）
 - 对已有抽象层：**不重复拆，直接引用**已有规范的路径/文档
 - 只拆「新增部分」——当前需求引入的新实体、新状态、新数据流
-- 示例：项目已有「商品数据模型」规范 → T-01 不再定义商品模型，改为「按项目现有商品模型扩展新字段」
+- 示例：项目已有「商品数据模型」规范 → t-01 不再定义商品模型，改为「按项目现有商品模型扩展新字段」
 
 **Step 1：识别新增抽象层**
 - 梳理需求涉及的所有「实体」（Entity）—— 有唯一标识、有生命周期的东西
@@ -107,24 +107,24 @@ Raws/
 
 ```
 抽象层：
-  T-01: 订单数据模型（Order Entity + 商品线 Item Value Object）
-  T-02: 订单状态机（待支付→已支付→已发货→已完成→已取消，含流转条件）
-  T-03: 订单数据加载/缓存/刷新机制（列表+详情的数据流）
+  t-01: 订单数据模型（Order Entity + 商品线 Item Value Object）
+  t-02: 订单状态机（待支付→已支付→已发货→已完成→已取消，含流转条件）
+  t-03: 订单数据加载/缓存/刷新机制（列表+详情的数据流）
 
 实现层：
-  T-04: 订单列表页（依赖 T-01, T-03）
-  T-05: 订单详情页（依赖 T-01, T-02, T-03）
-  T-06: 退款处理流程（依赖 T-01 订单状态机扩展）
-  T-07: 数据统计看板（依赖 T-01, T-03）
+  t-04: 订单列表页（依赖 t-01, t-03）
+  t-05: 订单详情页（依赖 t-01, t-02, t-03）
+  t-06: 退款处理流程（依赖 t-01 订单状态机扩展）
+  t-07: 数据统计看板（依赖 t-01, t-03）
 ```
 
 #### 依赖关系与执行顺序
 
 ```
 执行顺序：
-  Phase I（独立可并行）：T-01 → T-02 → T-03
-  Phase II（依赖 Phase I）：T-04, T-05, T-06（可并行）
-  Phase III（可选）：T-07
+  Phase I（独立可并行）：t-01 → t-02 → t-03
+  Phase II（依赖 Phase I）：t-04, t-05, t-06（可并行）
+  Phase III（可选）：t-07
 ```
 
 #### 🎯 策略 B：按业务模块拆
@@ -149,10 +149,10 @@ Raws/
 
 ## 6. 输出规范
 
-每个子需求目录 `/T-{编号}-{名称}/` 下：
+每个子需求目录 `/t-{编号}-{名称}/` 下：
 
 ```
-T-001-订单数据模型/
+t-001-订单数据模型/
 ├── 00-子需求.md          # 从原始需求摘录，可独立分析
 └── （后续 clarify/design/writing-plans 产物）
 ```
@@ -160,10 +160,10 @@ T-001-订单数据模型/
 `00-子需求.md` 模板：
 
 ```markdown
-## T-{编号}: {子需求名称}
+## t-{编号}: {子需求名称}
 
 ### 来源
-> 摘录自 `Raws/{文件名}`
+> 摘录自 `raws/{文件名}`
 
 {从原始需求中摘录相关段落}
 
@@ -171,8 +171,8 @@ T-001-订单数据模型/
 {明确本子需求包含什么、不包含什么}
 
 ### 依赖
-- 依赖：T-{编号1}, T-{编号2}
-- 被依赖：T-{编号3}, T-{编号4}
+- 依赖：t-{编号1}, t-{编号2}
+- 被依赖：t-{编号3}, t-{编号4}
 
 ### 类型
 - [ ] 抽象层（数据模型/状态机/数据流/领域规则）

package/skills/specx-fix/SKILL.md

@@ -0,0 +1,313 @@
+---
+name: specx-fix
+description: specx 流程的 bug 修复 skill — 自动判断验收 bug（场景 A）和独立 bug（场景 B），提供根因分析、修复方案、归档沉淀
+category: software-development
+tags: [specx, bugfix, debugging]
+---
+
+# specx-fix：Bug 修复
+
+## 触发条件
+
+当用户反馈 bug 相关问题时触发本 skill。不需要用户说特定的关键词，通过上下文自动判断走哪条路径。
+
+## 场景判断（自动）
+
+| 信号 | 场景 A（验收 bug） | 场景 B（独立 bug） |
+|------|-------------------|-------------------|
+| 当前有活跃子需求 `t-xxx/` | ✅ | — |
+| 当前 git 分支是 feature / 需求分支（如 `t-xxx-*`） | ✅ | — |
+| 问题在最近修改的代码范围内 | ✅ | — |
+| 问题在当前子需求的新功能范围内 | ✅ | — |
+| 当前 git 分支是 `fix/*` 或 `hotfix/*` | — | ✅ |
+| 当前 git 分支是 `main` / `master` / `maintenance` | — | ✅ |
+| 没有进行中的子需求 | — | ✅ |
+| 问题在完全不同的模块 | — | ✅ |
+
+**判断逻辑：**
+
+```
+IF 有活跃子需求 t-xxx/ AND
+   (问题在最近改动范围内 OR git 分支是需求分支 OR 问题在新功能范围内):
+  → 场景 A（验收 bug）
+ELSE：
+  → 场景 B（独立 bug）
+```
+
+---
+
+## 场景 A：验收 Bug（开发过程）
+
+### 适用条件
+
+当前正在执行 specx 流程，子需求已实现但验收时发现问题。根因可能在 spec、design 或代码实现中。
+
+### 流程
+
+#### Step A1️⃣ 定位根因环节
+
+判断问题出在哪个环节：
+
+| 根因位置 | 判断依据 | 修复动作 |
+|----------|---------|---------|
+| **spec 遗漏** | 需求定义本身就没覆盖这个场景 / 边界条件 | 更新 `02-spec.md`，然后补 design，重新执行 |
+| **design 遗漏** | spec 定义了但设计方案没覆盖 | 更新 `03-design.md`（或模板定义的文件），重新执行 |
+| **代码实现错** | spec 和 design 都对，代码写错了 | 直接修代码 |
+
+#### Step A2️⃣ 修复
+
+1. 根据根因回退到对应环节修复
+2. 更新下游文档（如果上游改了，下游必须同步）
+3. 在 `04-tasks.md` 末尾追加验收 bug 记录：
+
+```markdown
+### 验收 bug 记录
+
+| 时间 | 描述 | 根因环节 | 修复内容 | 状态 |
+|------|------|---------|---------|------|
+| {YYYY-MM-DD} | {bug描述} | spec / design / 代码 | {修复了什么} | ✅ |
+```
+
+> 如果 `04-tasks.md` 不存在，创建 `t-xxx/99-fix.md`
+
+#### Step A3️⃣ 更新文档状态
+
+涉及修改的文档，状态回退为 `draft`：
+
+```yaml
+---
+status: draft
+updated: {YYYY-MM-DD}
+history:
+  - "v{n}: 验收修复: {摘要}"
+---
+```
+
+#### Step A4️⃣ 回到执行
+
+修复完成后，回到 `specx-executing-plans` 继续执行修改后的任务。
+
+### 场景 A 不做什么
+
+- 不创建新目录
+- 不走独立 bug 的完整文档流程
+- 不归档到 wiki（如果值得归档，等子需求完成时走 archive 流程统一沉淀）
+
+---
+
+## 场景 B：独立 Bug（线上/历史/日常）
+
+### 适用条件
+
+- 无当前需求上下文
+- 线上报障、历史代码问题、日常发现
+- 与当前进行中的需求无关
+
+### 流程
+
+#### Step B1️⃣ 创建 bug 工作空间
+
+```
+docs/specx/fixes/
+└── {yyyyMMdd}-{简短描述}/
+    ├── 00-bug-report.md       # bug 描述 & 复现步骤
+    ├── 01-root-cause.md       # 根因分析
+    ├── 02-fix-plan.md         # 修复方案
+    └── 03-fix-done.md         # 修复验证 & 归档
+```
+
+**命名规则：** `{yyyyMMdd}-{3-5单词描述}`，全小写连字符
+
+#### Step B2️⃣ 00-bug-report.md：Bug 描述
+
+```markdown
+---
+status: draft
+updated: {YYYY-MM-DD}
+history:
+  - "v1: 初始创建"
+---
+
+# {Bug 描述}
+
+## 发现时间
+{YYYY-MM-DD}
+
+## 发现场景
+{在哪发现的，如：线上报障、QA 提测、日常使用}
+
+## 复现步骤
+1. {步骤1}
+2. {步骤2}
+3. {步骤3}
+
+## 预期行为
+{应该是什么}
+
+## 实际行为
+{实际是什么}
+
+## 影响范围
+- [ ] 阻塞（无临时方案，必须修复）
+- [ ] 重要（有临时方案但影响体验）
+- [ ] 轻微（不影响主要流程）
+
+## 截图/日志（如有）
+```
+
+#### Step B3️⃣ 01-root-cause.md：根因分析
+
+```markdown
+---
+status: draft
+updated: {YYYY-MM-DD}
+history:
+  - "v1: 初始创建"
+---
+
+# 根因分析
+
+## 复现验证
+- [ ] 已确认复现
+
+## 定位过程
+{排查步骤记录}
+
+## 根因
+
+### 直接原因
+{最接近表象的原因，如：空指针、类型不匹配、边界条件缺失}
+
+### 根本原因
+{为什么会引入这个 bug，如：spec 未定义边界情况、对 API 行为假设错误、重构遗漏}
+
+## 涉及的代码位置
+- {文件路径}:{行号} — {说明}
+```
+
+#### Step B4️⃣ 02-fix-plan.md：修复方案
+
+```markdown
+---
+status: draft
+updated: {YYYY-MM-DD}
+history:
+  - "v1: 初始创建"
+---
+
+# 修复方案
+
+## 修复策略
+{描述修复方式}
+
+## 文件变更
+| 文件 | 操作 | 说明 |
+|------|------|------|
+| {路径} | 修改/新增 | {说明} |
+
+## 影响分析
+- [ ] 修复会影响其他模块？哪些？
+- [ ] 需要补充单元测试？
+- [ ] 需要补充集成测试？
+
+## 回滚方案
+{如果修复有问题，如何回滚}
+```
+
+#### Step B5️⃣ 修复执行
+
+1. 按修复方案修改代码
+2. 验证修复
+3. 提交代码（建议使用 `fix/` 分支）
+
+#### Step B6️⃣ 03-fix-done.md：修复验证 & 归档
+
+```markdown
+---
+status: archived
+updated: {YYYY-MM-DD}
+history:
+  - "v1: 初始创建"
+  - "v2: 修复完成"
+---
+
+# 修复验证
+
+## 修复内容
+{描述实际改了哪些代码}
+
+## 验证结果
+- [ ] 复现步骤不再触发
+- [ ] 相关测试通过
+
+## 归档到 wiki
+
+### wiki 条目
+docs/specx/wiki/fixes/{slug}.md
+
+```markdown
+# {Bug 描述}
+
+**发现时间：** {YYYY-MM-DD}
+**根因类型：** {逻辑错误 / 边界遗漏 / 类型不匹配 / 并发问题 / 性能 / 其他}
+
+## 根因
+{一句话描述根因}
+
+## 修复方式
+{一句话描述修复方式}
+
+## 涉及文件
+- {文件}:{行号}
+```
+
+### 自检清单
+- [ ] bug-report 和 root-cause 已提炼为 wiki 知识
+- [ ] fix-done 状态为 `archived`
+- [ ] 相关文档状态已更新
+- [ ] 代码已提交
+```
+
+#### Step B7️⃣ 更新 fixes 目录索引
+
+首次使用 `fixes/` 时，在 `docs/specx/fixes/README.md` 创建索引：
+
+```markdown
+# Bug 修复记录
+
+| 日期 | 描述 | 根因类型 | 影响范围 | 状态 |
+|------|------|---------|---------|------|
+| {YYYY-MM-DD} | {描述} | {类型} | {阻塞/重要/轻微} | ✅ |
+```
+
+后续每次修复完成，在表格顶部插入新行。
+
+---
+
+## 公共检查清单
+
+修复完成后确认：
+
+- [ ] bug 已修复并验证
+- [ ] 根因已明确记录（区分直接原因和根本原因）
+- [ ] 修复不会引入新的问题
+- [ ] 相关测试已补充（如有必要）
+- [ ] 场景 B 已归档到 wiki
+
+## 与现有 specx skill 的关系
+
+| 当前流程 | 对应动作 |
+|----------|---------|
+| executing-plans 发现代码实现错 → 场景 A 走代码修复 | 直接在当前子需求修复 |
+| 验收发现 spec 遗漏 → 场景 A 走 spec 回退 | 更新 clarify/spec/design |
+| 验收发现 design 遗漏 → 场景 A 走 design 回退 | 更新 design 文档，重新执行 |
+| 用户报线上 bug → 场景 B | 完整流程 |
+| 日常发现历史代码 bug → 场景 B | 完整流程 |
+
+## 重要提示
+
+- **场景 A 不要过度流程化** — 验收中发现的代码小 bug，定位到根因后快速修掉，不需要走完整 fixes/ 目录。记录到当前子需求即可
+- **场景 B 必须归档到 wiki** — 独立 bug 是项目知识的重要组成部分
+- **区分直接原因和根本原因** — 直接原因是"表象"（空指针），根本原因是"为什么会引入"（spec 未定义边界）
+- **频繁出现同类 bug** → 考虑用 specx-create-rule 建立编码规范
+- **场景判断有歧义时** → 走场景 B（独立 bug 流程更完整，多走流程比漏走好）

package/{specx.js → src/specx.js}

@@ -6,12 +6,13 @@ import path from "path";
 import fs from "fs";
 import os from "os";
 import readline from "readline";
+import { execSync } from "child_process";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
 // ─── Paths ───────────────────────────────────────────────────────
-const SPECX_HOME = process.env.SPECX_HOME || path.resolve(__dirname);
+const SPECX_HOME = process.env.SPECX_HOME || path.resolve(__dirname, "..");
 const SKILLS_DIR = path.join(SPECX_HOME, "skills");
 
 // ─── Registered CLI Targets ──────────────────────────────────────
@@ -28,6 +29,72 @@ const CLI_TARGETS = [
   },
 ];
 
+// ─── Helpers ──────────────────────────────────────────────────────
+function getPackageName() {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(SPECX_HOME, "package.json"), "utf-8"));
+    return pkg.name;
+  } catch {
+    return "@culeo/specx";
+  }
+}
+
+// ─── Detect installed specx skills in a target dir ───────────────
+function findSpecxSkillsInDir(dir) {
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir)
+    .filter((name) => {
+      const skillDir = path.join(dir, name);
+      return fs.statSync(skillDir).isDirectory() && fs.existsSync(path.join(skillDir, "SKILL.md")) && name.startsWith("specx-");
+    })
+    .sort();
+}
+
+// ─── Detect project-level .{claude,codex}/skills/ ────────────────
+function findProjectSpecxDirs(cwd) {
+  const results = [];
+  for (const target of CLI_TARGETS) {
+    const projectDir = path.join(cwd, `.${target.id}`, "skills");
+    const skills = findSpecxSkillsInDir(projectDir);
+    if (skills.length > 0) {
+      results.push({ targetId: target.id, label: target.label, dir: projectDir, skills });
+    } else if (fs.existsSync(projectDir)) {
+      // Dir exists but no specx skills — still a candidate for coverage
+      results.push({ targetId: target.id, label: target.label, dir: projectDir, skills: [] });
+    }
+  }
+  return results;
+}
+
+// ─── Copy skills from source to a destination ────────────────────
+function copySkillsToDir(srcDir, destDir) {
+  const skills = getAvailableSkills();
+  let installCount = 0;
+  let updateCount = 0;
+  for (const skillName of skills) {
+    const skillSrc = path.join(srcDir, skillName);
+    const skillDest = path.join(destDir, skillName);
+    if (!fs.existsSync(skillSrc)) {
+      console.log(`  ✖ ${skillName}: source not found, skipping`);
+      continue;
+    }
+    const existed = fs.existsSync(skillDest);
+    if (existed) {
+      fs.rmSync(skillDest, { recursive: true, force: true });
+    }
+    fs.mkdirSync(destDir, { recursive: true });
+    copyDirSync(skillSrc, skillDest);
+    if (existed) {
+      console.log(`  ↻ ${skillName} updated`);
+      updateCount++;
+    } else {
+      console.log(`  ✓ ${skillName} installed`);
+      installCount++;
+    }
+  }
+  return { installCount, updateCount };
+}
+
 // ─── Interactive Multi-Select ────────────────────────────────────
 function isTTY() {
   return process.stdin.isTTY;
@@ -205,27 +272,143 @@ program
       const finalDir = getFinalDir(targetId, isProject, projectDir);
 
       let installCount = 0;
+      let updateCount = 0;
       for (const skillName of skillsToInstall) {
         const destDir = path.join(finalDir, skillName);
-        if (fs.existsSync(destDir)) {
-          console.log(`  ○ ${target.label}: ${skillName} already installed`);
-          continue;
-        }
         const srcDir = path.join(SKILLS_DIR, skillName);
         if (!fs.existsSync(srcDir)) {
           console.log(`  ✖ ${skillName}: source not found, skipping`);
           continue;
         }
+        const existed = fs.existsSync(destDir);
+        if (existed) {
+          fs.rmSync(destDir, { recursive: true, force: true });
+        }
         fs.mkdirSync(finalDir, { recursive: true });
         copyDirSync(srcDir, destDir);
-        console.log(`  ✓ ${target.label}: ${skillName}`);
-        installCount++;
+        if (existed) {
+          console.log(`  ↻ ${target.label}: ${skillName} updated`);
+          updateCount++;
+        } else {
+          console.log(`  ✓ ${target.label}: ${skillName} installed`);
+          installCount++;
+        }
+      }
+
+      if (installCount > 0 || updateCount > 0) {
+        const parts = [];
+        if (installCount > 0) parts.push(`${installCount} installed`);
+        if (updateCount > 0) parts.push(`${updateCount} updated`);
+        console.log(`\n✓ ${parts.join(", ")} for ${target.label} (${isProject ? "project" : "user"} level)`);
       }
+    }
+  });
+
+// ─── Update Command ──────────────────────────────────────────────
+program
+  .command("update")
+  .description("Update specx CLI (npm) and re-install skills to all installed locations")
+  .action(async () => {
+    console.log("🔄 Updating specx CLI...");
+
+    // Step 1: Update the CLI itself via npm
+    const pkgName = getPackageName();
+    console.log(`  Running: npm update -g ${pkgName}...`);
+    try {
+      execSync(`npm update -g ${pkgName}`, { stdio: "inherit" });
+      console.log("  ✓ npm update complete");
+    } catch (e) {
+      console.error("  ✖ npm update failed. Try with sudo or check your npm setup.");
+      process.exit(1);
+    }
+
+    console.log("\n🔁 Re-installing specx skills...");
+
+    // Step 2: Re-install to all user-level targets that have specx skills installed
+    const userTargets = [];
+    for (const target of CLI_TARGETS) {
+      const targetDir = target.dir();
+      const installedSkills = findSpecxSkillsInDir(targetDir);
+      if (installedSkills.length > 0) {
+        userTargets.push({ target, skills: installedSkills });
+      } else {
+        console.log(`  ○ ${target.label}: no specx skills installed at user level, skipping`);
+      }
+    }
 
-      if (installCount > 0) {
-        console.log(`\n✓ Installed ${installCount} skill(s) to ${target.label} (${isProject ? "project" : "user"} level)`);
+    if (userTargets.length > 0) {
+      console.log("\n📦 User-level targets found:");
+      for (const ut of userTargets) {
+        console.log(`  ${ut.target.label} (${ut.skills.length} skills)`);
+      }
+      console.log("");
+
+      for (const ut of userTargets) {
+        const destDir = ut.target.dir();
+        console.log(`→ ${ut.target.label}...`);
+        const result = copySkillsToDir(SKILLS_DIR, destDir);
+        const parts = [];
+        if (result.installCount > 0) parts.push(`${result.installCount} installed`);
+        if (result.updateCount > 0) parts.push(`${result.updateCount} updated`);
+        console.log(`  ✓ ${parts.join(", ")} for ${ut.target.label} (user level)`);
       }
+    } else {
+      console.log("\n  No user-level specx skills found to update.");
     }
+
+    // Step 3: Check current working directory for project-level installations
+    const cwd = process.cwd();
+    const projectTargets = findProjectSpecxDirs(cwd);
+
+    if (projectTargets.length > 0) {
+      console.log(`\n📁 Project-level specx skills detected in ${cwd}:`);
+      for (const pt of projectTargets) {
+        console.log(`  ${pt.label} (${pt.skills.length} skills) — ${pt.dir}`);
+      }
+      console.log("");
+
+      if (isTTY()) {
+        // Interactive: let user choose which project locations to update
+        const items = projectTargets.map((pt) => ({
+          id: pt.targetId,
+          label: `${pt.label} (${pt.skills.length || 0} skills installed)`,
+          detected: true,
+        }));
+        const selected = await interactiveSelect(
+          items,
+          "📁 Select project-level locations to update:",
+          projectTargets.map((pt) => pt.targetId),
+          false
+        );
+
+        for (const pt of projectTargets) {
+          if (!selected.includes(pt.targetId)) {
+            console.log(`  ○ ${pt.label}: skipped`);
+            continue;
+          }
+          console.log(`→ ${pt.label}...`);
+          const result = copySkillsToDir(SKILLS_DIR, pt.dir);
+          const parts = [];
+          if (result.installCount > 0) parts.push(`${result.installCount} installed`);
+          if (result.updateCount > 0) parts.push(`${result.updateCount} updated`);
+          console.log(`  ✓ ${parts.join(", ")} for ${pt.label} (project level)`);
+        }
+      } else {
+        // Non-interactive: update all
+        for (const pt of projectTargets) {
+          console.log(`→ ${pt.label}...`);
+          const result = copySkillsToDir(SKILLS_DIR, pt.dir);
+          const parts = [];
+          if (result.installCount > 0) parts.push(`${result.installCount} installed`);
+          if (result.updateCount > 0) parts.push(`${result.updateCount} updated`);
+          console.log(`  ✓ ${parts.join(", ")} for ${pt.label} (project level)`);
+        }
+      }
+    } else {
+      console.log("\n  No project-level specx skills detected in current directory.");
+    }
+
+    console.log("\n✓ Update complete!");
   });
 
 // ─── Uninstall Command ───────────────────────────────────────────