@culeo/specx 0.1.0

package/skills/specx-create-design-template/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: specx-create-design-template
+description: 生成适合自己项目的 design 文档模板（功能级）。用于 specx 流程第三步 specx-design，为每个需求生成设计文档时使用。
+category: software-development
+tags: [specx, design, template, project-specific]
+---
+
+# specx-create-design-template：生成项目专属 design 模板
+
+## 触发条件
+
+项目初始化时或引入 specx 时执行一次，生成的功能设计模板供后续每个需求使用。
+
+## 输入
+
+无（纯交互式）
+
+## 输出
+
+`{项目根目录}/docs/specx/templates/` 下的项目专属模板（功能设计文档结构）
+
+---
+
+## 核心概念
+
+这个 skill 生成的是**功能设计文档模板**，不是项目架构描述。
+
+功能设计文档回答的是：**这个具体需求，改哪些文件、加什么代码、调用链是什么**。
+
+每个项目的功能设计文档结构可能不同，取决于：
+- 团队关心的信息（有人要精确到函数签名，有人只关心文件级变更）
+- 平台数量（单平台只需一套实现要点，多平台需要分别写）
+- 团队约束（错误处理规范、线程安全要求等）
+
+---
+
+## Step 0️⃣ 判断项目场景
+
+> 问用户
+
+```
+项目场景：
+A. 0-1 项目 — 从零开始，团队自己定义模板结构
+B. 1-N 项目 — 已有代码，扫描现有设计文档提取结构
+```
+
+---
+
+## 路径 A：0-1 项目（团队定义）
+
+### Step A1️⃣ 确定平台范围
+
+> 问用户
+
+```
+平台范围：
+- 这个项目有哪些平台？（例如：iOS 单平台 / iOS + Android + KMP 多平台）
+- 设计文档是否需要分平台写？
+```
+
+### Step A2️⃣ 确定章节结构
+
+> 问用户，设计文档需要哪些章节
+
+```
+章节结构（描述你的实际情况）：
+功能设计文档包含哪些章节？每个章节回答什么问题？（例如：
+- 功能概述：做什么、放在哪个模块
+- 文件变更：新增/修改哪些文件
+- 调用链：入口到数据的完整路径
+- 平台实现要点：各平台怎么实现
+- 可复用组件：用了哪些既有组件
+- 检查项：review 时关注什么）
+```
+
+### Step A3️⃣ 确定文件级信息粒度
+
+> 问用户，文件变更要精确到什么程度
+
+```
+文件变更信息粒度：
+- 精确到文件名 + 插入点（哪行/哪个方法）
+- 精确到文件名 + 初步代码结构（类名/函数签名）
+- 只写文件名，细节在详细设计阶段补充
+```
+
+### Step A4️⃣ 确定团队检查项
+
+> 问用户，review 时关注什么
+
+```
+团队检查项（可多选，可自定义）：
+A. 线程安全
+B. 内存泄漏
+C. API 兼容性
+D. 错误处理一致性
+E. KMP expect/actual 配对（多平台）
+F. 其他：{描述}
+```
+
+### Step A5️⃣ 生成模板
+
+基于 A1-A4 生成模板。
+
+---
+
+## 路径 B：1-N 项目（从现有文档提取）
+
+### Step B1️⃣ 收集现有设计文档
+
+> 扫描项目目录，收集已有的设计文档
+
+分析 `docs/` 或同等目录下的现有设计文档，记录：
+1. 文档数量和文件名模式
+2. 每个文档的章节结构
+3. 重复出现的章节 vs 偶尔出现的章节
+
+### Step B2️⃣ 提取章节模式
+
+> 从现有文档中提取共性章节
+
+分析以下内容：
+1. **必有章节** — 每个文档都有的是什么
+2. **可选章节** — 部分文档有的分别是什么
+3. **章节粒度** — 文件级变更 vs 代码级细节
+4. **平台处理方式** — 各平台写在一起还是分开
+
+### Step B3️⃣ 提取文件变更模式
+
+> 从代码中验证文档描述的准确性
+
+分析以下内容：
+1. **新增文件位置** — 通常放在哪些目录
+2. **修改文件模式** — 通常改哪些类/方法
+3. **接口定义位置** — 接口放在哪个模块
+
+### Step B4️⃣ 确认团队检查项
+
+> 问用户，检查项是否完整
+
+```
+团队检查项（可多选，可自定义）：
+A. 线程安全
+B. 内存泄漏
+C. API 兼容性
+D. 错误处理一致性
+E. KMP expect/actual 配对（多平台）
+F. 其他：{描述}
+```
+
+### Step B5️⃣ 生成模板
+
+基于 B1-B4 提取的实际情况生成模板。**所有路径用实际值**。
+
+---
+
+## Step 6️⃣ 定义模板章节结构
+
+根据 Step 1 确认的平台数量，决定模板拆分方式：
+
+### 单平台项目
+
+一个主模板，包含所有章节：
+
+```markdown
+## 功能概述
+### 功能位置（所属模块/页面）
+### 依赖关系
+
+## 文件变更
+### 新增文件（含路径）
+### 修改文件（含插入点）
+
+## 调用链
+### 入口 → 中间层 → 数据层
+
+## 可复用组件
+### 已有组件
+### 新增抽象（如需）
+
+## 平台实现（iOS/Android/...)
+### 实现要点
+
+## 检查项
+### {按项目实际检查项填写}
+```
+
+### 多平台项目（如 iOS + KMP）
+
+拆成主模板 + 各平台子模板：
+
+**主模板（design-template.md）：**
+```markdown
+## 功能概述
+### 功能位置（所属模块/页面）
+### 依赖关系
+
+## 调用链
+### 入口 → 中间层 → 数据层
+
+## 可复用组件
+### 已有组件
+### 新增抽象（如需）
+```
+
+**iOS 子模板（design-ios.md）：**
+```markdown
+## iOS 文件变更
+### 新增文件（含路径）
+### 修改文件（含插入点）
+
+## iOS 实现要点
+### 状态管理
+### UI 层
+### 平台特定处理
+```
+
+**KMP 子模板（design-kmp.md）：**
+```markdown
+## KMP 文件变更
+### 新增文件（含路径）
+### 修改文件（含插入点）
+
+## KMP 实现要点
+### expect/actual 配对
+### Shared 层 Flow 处理
+### 平台无关逻辑
+```
+
+> 单平台只生成一个模板文件。多平台生成主模板 + 各平台子模板。文件名由团队决定，上例仅为参考。
+
+---
+
+## Step 7️⃣ 输出到项目目录
+
+将生成的模板写入 `docs/specx/templates/`：
+
+**单平台项目：**
+```
+{项目根目录}/docs/specx/templates/
+└── design-template.md
+```
+
+**多平台项目（如 iOS + KMP）：**
+```
+{项目根目录}/docs/specx/templates/
+├── design-template.md           ← 主模板
+├── design-ios-template.md      ← iOS 平台子模板
+└── design-kmp-template.md      ← KMP 平台子模板
+```
+
+> 文件数量和命名由团队自行决定。上例仅为参考。
+
+---
+
+## 质量检查
+
+生成模板后确认：
+- [ ] 章节回答了"这个功能改哪些文件、加什么代码、怎么串联"
+- [ ] 平台章节按项目实际平台命名
+- [ ] 检查项包含团队既有约束
+- [ ] 用户确认可以接受

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

@@ -0,0 +1,174 @@
+---
+name: specx-create-rule
+description: specx 流程辅助 skill — 为企业项目建立和维护开发规范。在适当时机帮助用户将隐性约定显性化，形成可持续遵循的规则文档。
+category: software-development
+tags: [specx, rule, convention, knowledge]
+---
+
+# specx-create-rule：规则建立
+
+## 触发条件
+
+**主动触发（无需用户明确要求）：**
+
+当对话中出现以下信号时，自动考虑触发本 skill：
+- 用户对 AI 输出表达了不满（"不对"、"不是这个意思"、"应该按我的习惯"）
+- 同一类错误出现 2 次以上
+- 用户纠正了 AI 的编码风格或习惯
+- 讨论中涉及项目特有的约束、边界、默认值
+
+**明确触发：**
+
+用户说"加个规则"、"把这个记下来"、"以后都这样写"等明确意图时，直接触发。
+
+---
+
+## 写入前判断（必做）
+
+**在新增/修改任何规则之前，必须先判断属于哪种情况：**
+
+| 类型 | 判断依据 | 动作 |
+|------|---------|------|
+| **新增** | 规则不存在，且不与任何现有规则冲突 | 新增写入 |
+| **冲突** | 新规则与现有规则矛盾 | 询问用户保留哪个，删除另一个 |
+| **过时** | 现有规则已不适用当前场景 | 删除旧规则，写入新规则 |
+| **细化** | 现有规则过于模糊，需补充细节 | 追加到现有规则，不覆盖 |
+| **替换** | 现有规则方向正确但表述不对 | 替换原文 |
+
+**判断步骤：**
+1. 读取 `docs/specx/rule/` 下所有现有规则
+2. 与新规则对比：是否同类？是否矛盾？是否重复？
+3. 确定类型后，再执行对应动作
+
+---
+
+## 规则发现路径
+
+### 路径 1：项目初始化时（docs/specx/rule 不存在）
+
+**前置判断：** `docs/specx/rule/` 目录不存在
+
+**扫描步骤：**
+
+1. **找已有规范** — 检查是否有 `docs/`, `CONTRIBUTING.md`, `.eslintrc`, `tsconfig.json`, `package.json` 等配置文件
+2. **扫描源码** — 用 `search_files` 查找代码中的模式：
+   - 命名风格（驼峰/下划线/匈牙利）
+   - 目录结构约定
+   - 常用工具库
+   - 分层架构（MVVM / Clean / DDD）
+3. **推断规则** — 从扫描结果推断项目规范，写入 `docs/specx/rule/`
+
+### 路径 2：对话中途纠正（上下文沉淀）
+
+**前置判断：** 用户刚刚纠正了 AI 的输出，且同类问题可能出现多次
+
+**动作：**
+1. 理解用户纠正的本质（表面修改 vs 原则变更）
+2. 询问用户："是否需要把这个规则固化到项目的规范文档里？"
+3. 如用户确认，从纠正内容中提炼规则，写入 `docs/specx/rule/`
+
+### 路径 3：用户明确提出规则
+
+**前置判断：** 用户说"加上 X 规则"、"规定 Y 这样做"等
+
+**动作：**
+1. **先判断** — 读取 `docs/specx/rule/` 下现有规则，确认是否已有相关规则
+2. 按判断结果执行（新增/冲突/过时/细化/替换）
+3. 更新 `docs/specx/rule/README.md`
+
+### 路径 4：意图不明确
+
+**前置判断：** 用户说法模糊，无法判断是加规则还是其他操作
+
+**动作：**
+用 `clarify` 提问：
+> "你提到 '{用户原话}'，是想为项目新建一条规则吗？还是其他意图？"
+
+---
+
+## 输出结构
+
+### docs/specx/rule/ 目录结构
+
+```
+docs/specx/rule/
+├── README.md          # 规则总览 & 索引
+├── naming.md          # 命名规范
+├── workflow.md        # 开发流程规范
+├── code-style.md      # 代码风格规范
+└── architecture.md    # 架构约定
+```
+
+### docs/specx/rule/README.md 模板
+
+```markdown
+# 项目规范
+
+> 最后更新：{YYYY-MM-DD}
+> 触发场景：AI 在对话中主动学习并维护
+
+## 索引
+
+| 规则文件 | 适用场景 |
+|---------|---------|
+| naming.md | 变量/文件/目录命名 |
+| workflow.md | 开发流程、提交流程 |
+| code-style.md | 代码风格、格式要求 |
+| architecture.md | 分层、模块边界 |
+
+## 最近新增规则
+
+| 日期 | 规则摘要 | 来源对话 |
+|------|---------|---------|
+| {YYYY-MM-DD} | {规则简述} | {时间戳或上下文} |
+```
+
+### 单条规则模板
+
+```markdown
+## {规则标题}
+
+**类型：** {naming / workflow / code-style / architecture / other}
+**建立时间：** {YYYY-MM-DD}
+**更新于：** {YYYY-MM-DD}
+**触发场景：** {在什么情况下适用}
+**来源：** {对话上下文摘要}
+
+---
+
+**规则内容：**
+{用简洁语言描述规则}
+
+**示例：**
+```demo
+# 正确示例
+{正确写法}
+
+# 错误示例
+{错误写法}
+```
+```
+
+---
+
+## 创建规则质量清单
+
+```
+[ ] 规则有明确的适用场景（何时用）
+[ ] 规则有正反示例（正确 vs 错误）
+[ ] 规则描述无歧义，不会被误解
+[ ] 规则不与现有其他规则冲突
+[ ] 已在 README.md 中建立索引
+[ ] 如是新项目首次建 rule，先扫描源码推断再写入
+```
+
+---
+
+## 重要提示
+
+- **不是一味新增** — 先判断是新增/冲突/过时/细化/替换，再决定动作
+- **规则是沉淀，不是命令** — 不要强制用户接受规则，只是帮他记录
+- **主动但不打扰** — 发现机会时提示用户，但不反复追问
+- **溯源可查** — 每条规则标注来源对话，便于以后回溯
+- **路径 1 扫描时** — 优先看既有配置文件（eslint/tsconfig/prettier），再推断隐式约定
+- **冲突必须由用户决定** — AI 不能单方面决定保留哪个规则

package/skills/specx-demystify/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: specx-demystify
+title: 需求拆解与任务化
+description: 将 PRD 或原始需求拆解为可执行的子任务清单（子需求），为后续 clarify → design → writing-plans 提供输入。核心策略：抽象层优先，先拆数据模型/状态机/数据流地基，后拆页面/交互实现层。
+status: final
+updated: 2026-06-04
+history:
+  - 2026-05-28: 新增决策树（核心复杂度定位）、Step 0 前置检查（已有抽象层不重复拆）
+  - 2026-06-04: 迁移到 Raws/ 多源分类 + 00-子需求.md 命名规范
+---
+
+# specx-demystify — 需求拆解与任务化
+
+## 1. 触发条件
+
+在以下情况**必须**执行 demystify：
+- 接收到原始需求文档（PRD / BRD / 产品需求 / 用户反馈等），需要拆解为可执行任务
+- 用户明确要求「拆需求」、「任务化」、「分解」
+- 进入 specx 流程的第一步（demystify → clarify → design → writing-plans）
+
+## 2. 输入
+
+| 输入 | 说明 |
+|------|------|
+| 原始需求来源 | 一个或多个文件，放入 `docs/specx/spaces/{yyyyMMdd}-{摘要}/Raws/` 目录，只读不修改 |
+| 项目上下文 | 技术栈（iOS / KMP / Android）、现有框架规范、架构约定 |
+
+### Raws/ 目录规范
+
+所有原始来源文件（PRD、用户反馈、聊天记录、参考文献等）统一放入 `Raws/` 子目录，按分类前缀命名：
+
+| 分类 | 前缀 | 说明 |
+|------|------|------|
+| 产品需求文档 | `P` | 正式 PRD / BRD / 产品需求 |
+| 用户输入/语料 | `U` | 用户反馈、聊天记录、访谈纪要 |
+| 参考文献 | `R` | 架构规范、竞品分析、技术参考 |
+| 设计稿 | `D` | Figma / Sketch 导出的 UI spec、设计说明 |
+
+格式：`{前缀}{序号}-{描述}.md`
+
+示例：
+```
+Raws/
+├── P001-用户中心PRD.md
+├── P002-订单模块补充.md
+├── U001-用户反馈汇总.md
+└── R001-现有订单数据模型.md
+```
+
+## 3. 输出
+
+| 输出 | 格式 | 说明 |
+|------|------|------|
+| 子需求目录集合 | `docs/specx/spaces/{yyyyMMdd}-{摘要}/T-{编号}-{名称}/00-子需求.md` | 每个子需求独立目录，含独立分析 |
+| 拆解决策记录 | 同一 docs 目录下的 `00-拆解策略.md`（可选） | 记录选择策略 A/B 的理由 |
+
+## 4. 拆解策略（二选一）
+
+### 4.1 策略选择决策树
+
+执行拆解前先回答一个问题：
+
+> **这个需求的核心复杂度在哪里？**
+
+| 核心复杂度 | 选策略 |
+|-----------|--------|
+| 在**数据/状态领域**（实体定义、状态流转、领域规则、跨页面数据同步） | **策略 A**（抽象层优先） |
+| 在**交互/展示领域**（页面布局、动效、内容展示、用户操作流程） | **策略 B**（按业务模块拆） |
+
+如果**两者都有**（多数需求如此），以主导复杂度为准，允许辅策略补充。
+
+### 🎯 策略 A：抽象层优先 ★ 推荐
+
+**适用场景**：核心复杂度在数据/状态领域——实体定义、状态机、数据流、领域规则，或多个实现层共享同一数据底座。
+
+**核心思路**：先识别需求背后的「抽象层」（数据模型、状态机、数据流、领域规则），再识别「实现层」（页面、交互、UI 组件）。抽象层是所有实现层共用的地基。
+
+#### 如何识别抽象层 vs 实现层
+
+| 维度 | 抽象层（先拆） | 实现层（后拆） |
+|------|---------------|---------------|
+| 本质 | 数据是什么、状态怎么流转 | 数据在哪里展示、用户怎么操作 |
+| 复用性 | 被多个实现层依赖 | 依赖抽象层 |
+| 变更影响 | 变则牵一发动全身 | 变则仅改局部 |
+| 例子 | 订单状态机、商品数据模型、缓存刷新机制 | 订单列表页、订单详情页、退款弹窗 |
+
+#### 拆解步骤
+
+**Step 0（前置检查）：确认已有抽象层**
+- 检查项目是否已有数据模型规范、状态机模式、数据流约定（如已有项目的 Entity 定义、API 规范层）
+- 对已有抽象层：**不重复拆，直接引用**已有规范的路径/文档
+- 只拆「新增部分」——当前需求引入的新实体、新状态、新数据流
+- 示例：项目已有「商品数据模型」规范 → T-01 不再定义商品模型，改为「按项目现有商品模型扩展新字段」
+
+**Step 1：识别新增抽象层**
+- 梳理需求涉及的所有「实体」（Entity）—— 有唯一标识、有生命周期的东西
+- 梳理所有「值对象」（Value Object）—— 没有唯一标识、按值相等判断的东西
+- 梳理「状态机」—— 实体有哪些状态、状态如何流转、流转条件是什么
+- 梳理「数据流」—— 数据从哪里来（API/本地/推送）、怎么缓存、怎么刷新、怎么同步
+
+**Step 2：识别实现层**
+- 上层抽象完成后，再看这些抽象在什么场景/页面上被消费
+- 每个独立的用户可见界面 = 一个实现层子需求
+- 实现层子需求必须标明依赖哪些抽象层子需求
+
+#### 拆解示例（订单管理后台）
+
+```
+抽象层：
+  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）
+```
+
+#### 依赖关系与执行顺序
+
+```
+执行顺序：
+  Phase I（独立可并行）：T-01 → T-02 → T-03
+  Phase II（依赖 Phase I）：T-04, T-05, T-06（可并行）
+  Phase III（可选）：T-07
+```
+
+#### 🎯 策略 B：按业务模块拆
+
+**适用场景**：核心复杂度在交互/展示领域——页面布局、动效、内容展示、用户操作流程，数据逻辑简单。
+
+**方案**：直接按业务模块/用户故事拆分子需求，每块自包含。相当于「实现层」的拆法，省略抽象层拆分。
+
+---
+
+## 5. 质量检查清单
+
+输出前逐一确认：
+
+- [ ] 选择了正确的拆解策略（抽象层优先 or 按业务模块）
+- [ ] 抽象层子需求都被**独立识别**，未与实现层混在一起
+- [ ] 实现层子需求明确标注了依赖的抽象层子需求编号
+- [ ] 每个子需求的粒度可用 AI coding 一次完成（参考 writing-plans 的粒度原则）
+- [ ] 子需求总数在合理范围（5~15 个，超出需考虑合并或分层）
+- [ ] 抽象层子需求的执行顺序必须优先于所有依赖它的实现层子需求
+- [ ] **Step 0 前置检查已执行**——确认了哪些抽象层已存在（引用路径），只拆新增部分
+
+## 6. 输出规范
+
+每个子需求目录 `/T-{编号}-{名称}/` 下：
+
+```
+T-001-订单数据模型/
+├── 00-子需求.md          # 从原始需求摘录，可独立分析
+└── （后续 clarify/design/writing-plans 产物）
+```
+
+`00-子需求.md` 模板：
+
+```markdown
+## T-{编号}: {子需求名称}
+
+### 来源
+> 摘录自 `Raws/{文件名}`
+
+{从原始需求中摘录相关段落}
+
+### 范围
+{明确本子需求包含什么、不包含什么}
+
+### 依赖
+- 依赖：T-{编号1}, T-{编号2}
+- 被依赖：T-{编号3}, T-{编号4}
+
+### 类型
+- [ ] 抽象层（数据模型/状态机/数据流/领域规则）
+- [ ] 实现层（页面/交互/UI 组件）
+```