@culeo/specx 0.1.0

package/skills/specx-design/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: specx-design
+description: specx 流程第三步 — 实现规划。在既有框架下规划功能落地。
+category: software-development
+tags: [specx, design, implementation]
+---
+
+# specx-design：实现规划
+
+## 触发条件
+
+当 spec.md 完成，需要规划「在现有框架下怎么实现」时使用。
+
+**输入：** `01-clarify.md` + `02-spec.md`
+**输出：** 按 `docs/specx/templates/` 下的项目专属模板填写（文件名和结构由项目模板定义）
+
+## 前置：了解项目背景（可选）
+
+如果对需求背景、领域概念等有疑问，可查阅 `docs/specx/wiki/` 中的已有知识沉淀。
+
+---
+
+## 核心思想
+
+企业项目大多是从 1-N，不存在技术选型问题。
+
+design 的职责是：**在既有框架下，规划这个功能怎么落地。**
+
+| 问题 | 回答 |
+|------|------|
+| 这个功能在现有框架的哪个位置 | 模块 / 页面 / 现有组件 |
+| 模块之间怎么组织 | 划分、依赖关系、平台边界 |
+| **各平台详细设计** | 在平台文档里写具体文件变更和实现要点 |
+
+## 文件产出规范
+
+设计文档（由项目专属模板定义文件名）添加文件头（新建时为 `draft`）：
+
+```yaml
+---
+status: draft
+updated: {YYYY-MM-DD}
+history:
+  - "v1: 初始创建"
+---
+```
+
+新建时为 `draft` 状态。
+
+---
+
+## 流程（Step-by-Step）
+
+### Step 0️⃣ 检查项目专属模板
+
+**先检查** `docs/specx/templates/` 下是否有项目专属模板（项目模板定义了设计文档的文件名和结构）。
+
+**判断：**
+- ✅ 存在 → 用项目专属模板，继续 Step 1
+- ❌ 不存在 → **先跑 `specx-create-design-template` skill 生成专属模板**，再继续
+
+> 项目专属模板是团队自己定义的，比通用模板更贴合项目实际。
+
+---
+
+### Step 1️⃣ 读 spec.md + clarify.md + 项目模板
+
+读三个文件：
+- `01-clarify.md` — 理解功能背景和用户场景
+- `02-spec.md` — 验收标准和功能描述
+- `docs/specx/templates/` 下的项目专属模板 — 了解设计文档格式和必填章节
+
+---
+
+### Step 2️⃣ 规划整体架构
+
+按项目专属模板的格式，填写整体架构章节。
+
+> 整体架构回答：这个功能在现有框架的哪个位置、模块之间怎么组织、各层之间怎么衔接。
+
+---
+
+### Step 3️⃣ 各平台详细设计
+
+按项目专属模板填写。文件名和结构由 `docs/specx/templates/` 下的模板定义。
+
+**模板来源：** `docs/specx/templates/` 下的项目专属模板（Step 0 确认过存在）。
+
+---
+
+## 质量检查
+
+design 完成后自检：
+
+```markdown
+- [ ] 整体架构回答了：功能在现有框架的哪个位置、模块之间怎么组织、各层之间怎么衔接
+- [ ] 各平台详细设计有具体文件变更（精确到包路径和文件名）
+- [ ] 平台边界清晰，没有不清不楚的跨层调用
+- [ ] 和 spec.md 可交叉验证（spec 里的每个验收标准在 design 中有对应实现路径）
+- [ ] 没有引入框架没有的新模式
+- [ ] 可复用组件已列出，没有重复造轮子
+```
+
+---
+
+## 适用项目类型
+
+> 模板从 `docs/specx/templates/` 读取（项目专属）。首次使用需先跑 `specx-create-design-template` 生成模板。
+
+---
+
+## 中断恢复（恢复模式）
+
+> ⚠️ 如果之前中断或未完成，从这里开始
+
+**动作：** 读取 `docs/specx/templates/` 下的项目专属模板，确认设计文档的文件名和结构，然后检查已有文档的完成度。
+
+**判断逻辑：**
+```
+读取设计文档（按模板定义的文件名）：
+  ├── 有整体架构但详细设计为空 → 继续详细设计
+  ├── 整体架构缺失 → 回退 Step 2
+  └── 全部完成 → 跳到质量检查
+```
+
+

package/skills/specx-docs-align/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: specx-docs-align
+description: specx 流程第三步 — 文档对齐。通过对话式逐个问题检查 clarify.md、spec.md、design.md 之间的一致性，发现问题立即修正。
+category: software-development
+tags: [specx, requirements, alignment, consistency]
+---
+
+# specx-docs-align：文档对齐检查
+
+## 触发条件
+
+当需要检查 specx 文档链的一致性时使用：
+
+- clarify.md 完成 → 检查与 spec.md 之间是否对齐
+- spec.md 完成 → 检查与 design.md 之间是否对齐
+- 任意文档修改后 → 发现不一致需要修正
+
+**输入：** `01-clarify.md`、`02-spec.md`、`03-design.md`（可选）
+**输出：** 直接修正文档，不输出报告
+
+---
+
+## 核心思想
+
+### 对话式修正，而非报告式
+
+```
+读文档
+    ↓
+发现一个问题
+    ↓
+问一个问题 → 等回答 → 修正文档
+    ↓
+继续检查
+    ↓
+重复，直到无问题
+```
+
+---
+
+## 文档问题类型
+
+| 问题类型 | 说明 | 处理方式 |
+|---------|------|---------|
+| **漂移（Drift）** | clarify.md 说 A，spec.md 写 B | 问：以哪个为准？然后修正 |
+| **冲突（Conflict）** | 两个文档描述互相矛盾 | 问：应该以哪个为准？然后修正 |
+| **遗漏（Gap）** | clarify.md 写了 spec.md 没有 | 问：需要加到 spec.md 吗？ |
+| **过度实现** | spec.md/design.md 超出 clarify.md | 问：这个要保留还是删除？ |
+| **名词不一致** | 同一个东西，不同名字 | 问：统一用哪个词？然后全局替换 |
+
+---
+
+## 流程（Step-by-Step）
+
+### Step 1️⃣ 收集文档
+
+**动作：** 读取同一子需求下的所有相关文档
+
+```
+clarify.md = 01-clarify.md（必须）
+spec.md = 02-spec.md（必须）
+design.md = 03-design.md（如有）
+```
+
+---
+
+### Step 2️⃣ 名词对齐（先做这个）
+
+> ⚠️ 名词不一致是其他所有问题的根源，先统一
+
+**动作：** 扫描三个文档中的关键名词
+
+**发现名词不一致时：**
+```
+发现名词不一致：
+  - clarify.md 用「{词A}」
+  - spec.md 用「{词B}」
+  - design.md 用「{词C}」（如有）
+  
+统一用哪个？
+  A. 「{词A}」
+  B. 「{词B}」
+  C. 「{词C}」
+  D. 其他：{输入}
+```
+
+用户选择后，执行全局替换。
+
+---
+
+### Step 3️⃣ 需求覆盖检查
+
+**动作：** 对比 clarify.md 和 spec.md
+
+**发现遗漏时（clarify.md 有，spec.md 没有）：**
+```
+发现遗漏：
+  - clarify.md 有「{需求点}」
+  - spec.md 没有
+
+需要加到 spec.md 吗？
+  A. 加到 spec.md
+  B. 从 clarify.md 中删除
+  C. 其他：{说明}
+```
+
+**发现过度实现时（spec.md 有，clarify.md 没有）：**
+```
+发现过度实现：
+  - spec.md 有「{需求点}」
+  - clarify.md 没有
+
+这个要保留吗？
+  A. 保留，加到 clarify.md
+  B. 从 spec.md 中删除
+  C. 其他：{说明}
+```
+
+---
+
+### Step 4️⃣ 描述漂移检查
+
+**动作：** 对比同一需求的描述是否一致
+
+**发现漂移或冲突时：**
+```
+发现{漂移/冲突}：
+  - clarify.md：「{描述A}」
+  - spec.md：「{描述B}»
+
+以哪个为准？
+  A. 以 clarify.md 为准 → 修正 spec.md
+  B. 以 spec.md 为准 → 修正 clarify.md
+  C. 综合两者 → 输入：{综合方案}
+```
+
+---
+
+### Step 5️⃣ 设计实现检查（如果 design.md 存在）
+
+**动作：** 对比 spec.md 和 design.md
+
+**发现不一致时：**
+```
+发现设计不一致：
+  - spec.md：「{描述A}」
+  - design.md：「{描述B}»
+
+以哪个为准？
+  A. 以 spec.md 为准 → 修正 design.md
+  B. 以 design.md 为准 → 修正 spec.md
+  C. 其他：{说明}
+```
+
+---
+
+### Step 6️⃣ 完成
+
+**停止条件：**
+```
+✅ 无发现问题
+```
+
+**完成标记：**
+```
+在 01-clarify.md 或 02-spec.md 的更新记录中追加：
+| {YYYY-MM-DD} | docs-align 完成，无问题 |
+
+如果修正了文档内容，在历史中追加记录（保持原状态不变）：
+```yaml
+updated: {YYYY-MM-DD}
+history:
+  - "v1: ..."
+  - "v2: docs-align 修正: {简要说明}"
+```
+```
+
+---
+
+## 修正执行规则
+
+### 修正前必须确认
+
+```
+修正前必须问用户，不能直接改。
+一次只问一个问题。
+等回答后再执行修正。
+```
+
+### 修正后验证
+
+```
+修正后，再次快速扫描相关文档，确认：
+- 没有引入新的不一致
+- 没有遗漏其他相关位置
+```
+
+---
+
+## 重要提示
+
+- **clarify.md 是基准** — spec.md/design.md 不能超出 clarify.md 范围
+- **名词优先统一** — 先统一名词，再检查其他问题
+- **不输出报告** — 直接修正，发现一个修一个
+- **不累积问题** — 发现问题立即问，不堆在一起问
+- **clarify 是源头** — 如果 clarify.md 错了，先修正 clarify.md
+
+---
+
+## 质量检查清单
+
+align 完成后，确认：
+
+```
+align 质量自检
+━━━━━━━━━━━━━━━━━━━━━━
+[ ] 名词已统一（全局替换完成）
+[ ] clarify.md 的每个需求点都有 spec.md 对应
+[ ] spec.md 没有超出 clarify.md 范围
+[ ] 同一需求的描述无漂移
+[ ] 无互相冲突的描述
+[ ] 如有 design.md，已与 spec.md 对齐
+[ ] 无遗漏（clarify.md 有 → spec.md 都有）
+[ ] 无过度实现（spec.md 有 → clarify.md 都有或已确认删除）
+```

package/skills/specx-executing-plans/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: specx-executing-plans
+description: Use when you have a task list (04-tasks.md) ready and need to implement it — executes tasks in order, marks progress, and stops when blocked.
+category: software-development
+tags: [specx, execution, implementation]
+---
+
+# specx-executing-plans：执行任务清单
+
+## 触发条件
+
+当 `04-tasks.md` 已完成，需要按清单执行编码时使用。
+
+## 输入
+
+- `04-tasks.md`（来自 specx-writing-plans）
+- 对应的设计文档（防止代码漂移的锚点）
+
+## 输出
+
+已完成的代码变更，任务清单更新为已执行状态。
+
+---
+
+## 核心原则
+
+**按计划执行，对照设计文档，不凭空发挥。**
+
+任务清单是行动清单，设计文档是锚点。每个任务完成后，对照设计文档检查是否符合预期。有问题立即停下，不猜。
+
+---
+
+## Step 1️⃣ 加载任务清单和设计文档
+
+1. 读 `04-tasks.md`
+2. 读对应的设计文档
+3. 理解整体结构：有多少任务，依赖关系如何，并行组有哪些
+4. 从 Task 1 开始，按顺序执行
+
+---
+
+## Step 2️⃣ 执行单个任务
+
+对每个任务：
+
+1. **标记进行中**：在清单中标注 `🔄 进行中`
+2. **执行每个 Step**：按清单中的 checkbox 步骤执行
+3. **对照设计文档验证**：检查是否符合设计意图
+4. **运行验证**：检查代码是否符合预期
+4. **标记完成**：标注 `✅ 完成`
+
+---
+
+## Step 3️⃣ 遇到问题立即停下
+
+| 情况 | 处理方式 |
+|------|---------|
+| 缺少依赖 | 停下，问用户 |
+| 测试失败 | 停下，查原因，不盲目修复 |
+| 步骤不清晰 | 停下，问用户 |
+| 发现计划错误 | 停下，反馈给用户 |
+
+> **遇到问题不猜、不跳过、不强行推进。**
+
+---
+
+## Step 4️⃣ 更新任务状态
+
+每完成一个任务，更新 `04-tasks.md`：
+
+```markdown
+### Task 1: {任务描述}
+状态: ✅ 完成
+```
+
+---
+
+## 质量检查
+
+- [ ] 每个 Task 执行后验证通过
+- [ ] 遇到问题立即停下，不盲目继续
+- [ ] 任务状态已更新
+- [ ] 所有 Must 优先级的任务已完成

package/skills/specx-writing-plans/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: specx-writing-plans
+description: Use after specx-design completes — converts the design document into an actionable task list with file changes, dependencies, and parallel execution groups.
+category: software-development
+tags: [specx, planning, spec-driven]
+---
+
+# specx-writing-plans：设计文档转任务清单
+
+## 触发条件
+
+当 specx-design 完成设计文档后，需要拆解为可执行任务时使用。
+
+## 前置：了解项目背景（可选）
+
+如果对需求背景、领域概念等有疑问，可查阅 `docs/specx/wiki/` 中的已有知识沉淀。
+
+## 输入
+
+- specx-design 的输出（项目模板定义的文件名和结构）
+
+## 输出
+
+`04-tasks.md`，保存在子需求目录下。
+
+文档包含：
+- 任务清单（带编号、文件变更、依赖关系）
+- 优先级（MoSCoW）
+- 并行执行组
+- 依赖关系图
+
+---
+
+## 核心原则
+
+**从设计文档推导任务，不凭空想象。**
+
+每个任务对应设计文档中的一个或一组文件变更。
+
+---
+
+## Step 1️⃣ 分析设计文档结构
+
+读 specx-design 的输出，回答：
+
+1. 涉及哪些模块/平台？（iOS / Android / KMP / Shared）
+2. 有哪些文件变更？（新增文件、修改文件）
+3. 哪些可以并行，哪些必须串行？
+
+---
+
+## Step 2️⃣ 提取任务
+
+从设计文档中的文件变更推导任务。
+
+对于每个任务，记录：
+
+- **任务描述**：做什么（动词 + 对象）
+- **文件变更**：改哪个文件、新增哪个文件
+- **涉及模块**：哪个平台
+
+---
+
+## Step 3️⃣ 标记并行组
+
+对于每个任务，回答：
+
+- 它依赖哪个任务的完成？
+- 哪个任务依赖它？
+
+标记：
+- `[P]` = 可并行（无前置依赖）
+- 无标记 = 有依赖，必须串行
+
+---
+
+## Step 4️⃣ 分配优先级（MoSCoW）
+
+| 优先级 | 含义 |
+|--------|------|
+| **Must** | 必须做，没有它功能不可用 |
+| **Should** | 应该做，重要但非关键 |
+| **Could** | 可以做，提升体验，非必需 |
+| **Won't** | 这次不做，明确排除 |
+
+---
+
+## Step 5️⃣ 输出任务清单
+
+每个任务用 `Task N` 编号，编号体现依赖关系。
+
+文件顶部添加文件头（新建时为 `draft`）：
+
+```yaml
+---
+status: draft
+updated: {YYYY-MM-DD}
+history:
+  - "v1: 初始创建"
+---
+```
+
+新建时为 `draft` 状态。
+
+```markdown
+## 任务清单：{功能名称}
+
+### Task 1: {任务描述}
+
+**文件变更：**
+- 新增：`{文件路径}`
+- 修改：`{文件路径}`
+
+**模块：** {iOS / KMP / Android / Shared}
+**优先级：** {Must / Should / Could / Won't}
+
+**执行步骤：**
+- [ ] **Step 1:** {具体操作}
+- [ ] **Step 2:** {具体操作}
+
+---
+
+### Task 2: {任务描述}
+
+**文件变更：** ...
+**模块：** ...
+**优先级：** {Must / Should / Could / Won't}
+**依赖：** Task 1
+
+**执行步骤：**
+- [ ] **Step 1:** {具体操作}
+
+---
+
+### Task 3: {任务描述} [P]  ← 无依赖，可与 Task 1 并行
+
+...
+```
+
+> `[P]` = 可并行。标注在任务标题后，同行有多个 `[P]` 表示可并行执行。
+
+---
+
+### 依赖关系图
+
+```mermaid
+graph LR
+    Task 1 --> Task 2
+    Task 1 --> Task 3
+    Task 2 --> Task 4
+    Task 3 --> Task 4
+```
+
+**检查：**
+- [ ] 无循环依赖（每个节点只指向编号更大的任务）
+- [ ] 每个有依赖的任务都明确了依赖哪个 Task
+
+---
+
+## 粒度标准
+
+AI  coding 的粒度不看人类时间，看文件数量和跨层程度。
+
+| 类型 | 判断标准 | 处理方式 |
+|------|---------|---------|
+| **过大** | 涉及 5+ 个文件，或跨 3+ 层，或多平台同时改 | 按模块或平台拆成多个子任务 |
+| **合适** | 涉及 1-4 个文件，同一层或相邻层 | 保持 |
+| **过小** | 只需改 1 个文件的 1 处（如加个参数、改个注释） | 合并到相邻任务 |
+
+**判断维度：**
+- **文件数量** — 例如：单任务涉及多少文件
+- **跨层程度** — 例如：只改 UI / 改 UI+数据层 / 改 UI+数据层+网络层
+- **多平台** — 例如：是否 iOS / Android / KMP 同时改
+
+---
+
+## 质量检查
+
+- [ ] 每个任务有明确的文件变更
+- [ ] 优先级已标注（Must / Should / Could）
+- [ ] 并行任务已标记 `[P]`
+- [ ] 依赖关系无循环
+- [ ] 依赖关系图已绘制