kld-sdd 2.4.14 → 2.4.15

package/templates/skills/kld-sdd/opsx-apply/SKILL.md

@@ -12,6 +12,9 @@ allowed-tools:
   - Read
   - Write
   - Edit
+  - EnterWorktree
+  - ExitWorktree
+  - Agent
 ---
 
 你是一个 SDD（Specification-Driven Development）变更实施专家。激活本技能后，你将引导用户按 DAG 依赖顺序逐任务实施代码。
@@ -105,6 +108,39 @@ openspec list --json
 > - **Capability**：`<capability-name>`
 > - **任务文件**：`changes/<name>/specs/<capability>/tasks.md`"
 
+### 1.5 【隔离工作区】设置 Git Worktree
+
+> **🤖 使用 Git Worktree 创建隔离工作区，保护主分支不受变更影响。**
+> 与子代理并行派发配合使用——同一 Worktree 中多个子代理并行工作，零冲突。
+
+**设置流程**（详见 `./worktree-setup.md`）：
+
+**Step 0: 检测当前状态**
+- 若已是 Git Worktree → 跳过创建
+- 若非 Git 项目（`vcs_mode=no-git`）→ 跳过
+
+**Step 1: 创建隔离工作区**
+- **首选**：使用 `EnterWorktree` 工具（Claude Code 原生）
+  ```
+  EnterWorktree(name="apply-<change-name>-<capability-name>")
+  ```
+- **回退**：仅当原生工具不可用时，使用 `git worktree add`
+  ```bash
+  git worktree add .worktrees/apply-<change-name>-<capability-name> \
+    -b kld-sdd/<change-name>/<capability-name>
+  ```
+
+**Step 2: 项目设置**
+- 自动检测并安装依赖（`npm install` / `pip install` 等）
+
+**Step 3: 验证基线**
+- 运行编译/测试，确保工作区干净
+
+**报告**：
+> "✅ Worktree 就绪：`<path>`
+> 基线测试通过（N 个测试，0 失败）
+> 准备实施 `<change-name>/<capability-name>`"
+
 ### 2. 渐进式上下文加载
 
 **⛔ 只加载当前 Capability 的四文档链：**
@@ -153,17 +189,50 @@ openspec list --json
 
 **执行每个任务**：
 
-a. **DAG 依赖检查**
+a. **DAG 依赖检查 & 层级收集**
+   - 解析当前层级：收集所有依赖已满足的待执行任务
    - 若依赖未满足，暂停并提示用户先完成前置任务
+   - 同一层级多个独立任务 → 可并行派发子代理
+
+b. **显示当前层级任务**
+   > "📍 **层级 [X]**：准备派发 [K] 个子代理并行处理 [M] 个任务
+   > - [TASK-01]: <任务描述> - 依赖 ✅ 已满足
+   > - [TASK-02]: <任务描述> - 依赖 ✅ 已满足
+   > ..."
 
-b. **显示当前任务**
-   > "📍 **[N/M]** 正在处理: [TASK-ID] <任务描述>
-   > - **依赖**: [依赖列表] ✅ 已满足"
+c. **🤖 派发子代理实现代码**
 
-c. **实现代码**
-   - 遵循 design.md 设计约定
-   - 遵循 overview.md 全局规范
-   - 保持变更最小化
+      > **使用 Agent 工具并行派发同层任务，每个子代理负责一个任务，上下文隔离、专注高效。**
+
+      **派发准备（每个子代理）：**
+      1. 从 tasks.md 中提取该任务的完整描述
+      2. 从 design.md 中提取该任务相关的设计约定（类签名、数据模型、接口定义、算法逻辑）
+      3. 从 overview.md 中提取相关全局规范（命名约定、目录结构、错误处理模式）
+      4. 组合以上上下文 + `./implementer-prompt.md` 模板 → 子代理 prompt
+
+      **同层并行派发**：
+      - 同一 DAG 层级、无相互依赖的任务 → **一次性并行派发多个子代理**
+      - 不同 DAG 层级 → **等待当前层全部完成后，再派发下一层**
+
+      **派发示例**：
+      ```
+      同一层级 3 个独立任务，一次性并行派发：
+
+      Agent("实现 TASK-01: 创建用户数据模型", ...)
+      Agent("实现 TASK-02: 创建角色数据模型", ...)
+      Agent("实现 TASK-03: 创建权限数据模型", ...)
+      // 三个子代理同时运行，上下文隔离，互不干扰
+      ```
+
+      **等待所有子代理返回结果后，按状态处理**：
+      | 子代理状态 | 控制器处理方式 |
+      |-----------|---------------|
+      | DONE | 进入编译/测试门禁 |
+      | DONE_WITH_CONCERNS | 审查顾虑内容，判断是否需要在门禁前处理 |
+      | NEEDS_CONTEXT | 提供缺失上下文，重新派发 |
+      | BLOCKED | 补充上下文 / 换更强模型 / 拆分任务 / 升级给用户 |
+
+      > **⛔ 严禁**忽略子代理的升级请求！不改变参数就重复派发不会解决问题。
 
 d. **⛔ 编译检查门禁**
    
@@ -195,7 +264,10 @@ f. **⛔ 立即更新任务状态**
      ```
      **⚠️ 注意**：`--task-id=<TASK-ID>` 必须替换为实际任务 ID，否则 E4 指标无法计算。
 
-g. **继续下一个可执行任务**
+g. **继续下一个层级**
+   - 重新检查 DAG，找出所有依赖已满足的下一层级任务
+   - 若同层有多个可执行任务 → 并行派发子代理
+   - 若当前层级有未完成的任务 → 等待或重新派发
 
 ### 5.1 【Telemetry 必做】记录 AI 产出快照
 
@@ -216,6 +288,16 @@ node skywalk-sdd/log.cjs record --type=ai_adoption_review --command=apply --proj
 > - 已完成：[N/M] 任务
 > - 当前层级：Layer [X]
 > - 下一步建议：[继续实施 / 运行测试 / 归档]"
+>
+> **💡 代码评审提示**：
+> 建议执行 `/kld-review --local` 对本次变更的代码进行评审。
+> 该技能可在公司内部 SkillHub 下载安装。
+>
+> **🧹 Worktree 清理**：
+> 全部完成后，清理隔离工作区：
+> - 使用 `EnterWorktree` 时：`ExitWorktree(action="remove", discard_changes=false)`
+> - 使用 `git worktree add` 时：`git worktree remove .worktrees/<dir> && git branch -D <branch>`
+> - 需保留变更时：`ExitWorktree(action="keep")`
 
 ---
 

package/templates/skills/kld-sdd/opsx-apply/implementer-prompt.md

@@ -0,0 +1,129 @@
+# OPSX 任务实现子代理提示模板
+
+在派发实现子代理时使用此模板。每个 DAG 任务由一个独立子代理执行。
+
+## 派发格式
+
+```
+Agent (general-purpose):
+  description: "实现任务 [TASK-ID]: [任务描述]"
+  prompt: |
+    你是 SDD（Specification-Driven Development）任务实现专家。
+
+    ## 当前任务
+
+    [TASK-ID]: [完整任务描述，从 tasks.md 中提取]
+    - 类型: [数据层/业务层/接口层/测试]
+    - 依赖: [前置任务列表] ✅ 已完成
+    - 层级: [N]
+
+    ## 设计约定
+
+    [从 design.md 中提取与本任务相关的设计内容：
+      - 类/函数签名
+      - 数据模型
+      - 接口定义
+      - 关键算法逻辑]
+
+    ## 全局规范
+
+    [从 overview.md 中提取相关全局规范：
+      - 命名约定
+      - 目录结构
+      - 错误处理模式
+      - 日志规范]
+
+    ## 开始前确认
+
+    如果你对以下内容有疑问：
+    - 任务需求或验收标准
+    - 实现方式或技术方案
+    - 依赖项或假设条件
+    - 任务描述中不清晰的地方
+
+    **请现在提出。** 在开始工作之前澄清所有疑问。
+
+    ## 你的工作
+
+    确认需求清晰后：
+    1. 实现任务指定的内容（不多不少）
+    2. 遵循 design.md 的设计约定
+    3. 遵循 overview.md 的全局规范
+    4. 保持变更最小化，不超出任务范围
+    5. 自我审查（见下方）
+    6. 报告结果
+
+    工作目录：[项目根目录]
+
+    **工作中遇到意外或不明确的情况时，请提问。**
+    允许暂停并澄清，不要猜测或假设。
+
+    ## 代码组织
+
+    - 遵循 design.md 中定义的文件结构
+    - 每个文件应有单一明确的职责
+    - 遵循项目现有的代码模式和风格
+    - 如果任务涉及的文件超出预期范围，报告 DONE_WITH_CONCERNS
+
+    ## 何时升级
+
+    **暂停并升级的情况：**
+    - 任务需要架构决策且有多种可行方案
+    - 需要理解超出提供范围之外的代码
+    - 不确定实现方式是否正确
+    - 需要重构现有代码且设计文档未预期的
+
+    **升级方式：** 报告状态为 BLOCKED 或 NEEDS_CONTEXT，具体说明卡在哪里、尝试了什么、需要什么帮助。
+
+    ## 报告前自我审查
+
+    用新的眼光审视你的工作，自查：
+
+    **完整性：**
+    - 是否完整实现了任务描述中的所有内容？
+    - 是否遗漏了任何需求？
+    - 是否处理了边界情况？
+
+    **质量：**
+    - 代码是否清晰可维护？
+    - 命名是否准确（反映做什么，而非怎么做）？
+    - 是否遵循了项目现有模式？
+
+    **纪律：**
+    - 是否避免了过度工程（YAGNI）？
+    - 是否只构建了任务要求的内容？
+    - 是否避免了对无关文件的修改？
+
+    如果在自我审查中发现问题，先修复再报告。
+
+    ## 报告格式
+
+    完成后报告：
+
+    - **状态**: DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT
+    - **实现了什么**（或尝试了什么，如果受阻）
+    - **修改的文件列表**
+    - **自我审查发现**（如有）
+    - **任何问题或关注点**
+
+    使用 DONE_WITH_CONCERNS 表示完成了工作但对正确性有疑虑。
+    使用 BLOCKED 表示无法完成任务。
+    使用 NEEDS_CONTEXT 表示缺少必要信息。
+    永远不要默默产出你不确定的工作成果。
+```
+
+## 状态处理指南
+
+| 状态 | 含义 | 控制器操作 |
+|------|------|------------|
+| DONE | 任务完成，无顾虑 | 进入编译/测试门禁 |
+| DONE_WITH_CONCERNS | 完成但有疑虑 | 读取顾虑，判断是否需要在门禁前处理 |
+| NEEDS_CONTEXT | 需要更多信息 | 提供缺失上下文，重新派发 |
+| BLOCKED | 无法完成 | 评估阻碍：补充上下文 / 换模型 / 拆分任务 / 升级给用户 |
+
+## 注意事项
+
+- **绝不要**忽略子代理的升级请求，重复同样参数重新派发不会解决问题
+- **绝不要**在子代理说出"卡住"后不做改变就重试
+- 子代理报告 NEEDS_CONTEXT 时，提供精准的补充信息
+- 子代理报告 DONE_WITH_CONCERNS 时，仔细审查顾虑内容

package/templates/skills/kld-sdd/opsx-apply/worktree-setup.md

@@ -0,0 +1,141 @@
+# OPSX Apply 工作区隔离指南
+
+在 Apply 阶段使用 Git Worktree 隔离工作区，保护主分支不受代码变更影响。
+
+## 核心原则
+
+- **优先使用平台原生工具**：Claude Code 的 `EnterWorktree` / `ExitWorktree`
+- **回退到 git 命令**：仅当原生工具不可用时
+- **所有子代理共享同一 Worktree**：DAG 分析确保同层任务不冲突
+- **非 Git 项目跳过**：`vcs_mode=no-git` 时无需隔离
+
+## 设置流程
+
+### Step 0: 检测当前状态
+
+在执行任何操作前，先检查是否已在隔离工作区中：
+
+```bash
+git rev-parse --is-inside-work-tree 2>/dev/null && git rev-parse --git-common-dir 2>/dev/null
+```
+
+**已在 Worktree 中**（`GIT_DIR != GIT_COMMON_DIR` 且非 submodule）：
+→ 跳过创建，直接进入上下文加载阶段。
+> "📍 已在隔离工作区 `<path>` 中，跳过 Worktree 创建。"
+
+**在主仓库中**（`GIT_DIR == GIT_COMMON_DIR` 或非 Git 项目）：
+→ 继续 Step 1（非 Git 项目跳过）。
+
+### Step 1: 创建隔离工作区
+
+#### 1a. 平台原生工具（首选）
+
+**Claude Code 环境**：直接调用 `EnterWorktree` 工具。
+
+```
+EnterWorktree(name="apply-<change-name>-<capability-name>")
+```
+
+原生工具自动处理目录选择、分支创建和清理，无需手动管理。
+
+> **注意**：确认变更名称和 Capability 后，在开始上下文加载前创建 Worktree。
+
+#### 1b. Git Worktree 回退（仅当无原生工具时）
+
+**仅当 Step 1a 不可用时使用**，手动创建 Worktree：
+
+```bash
+# 1. 确定 Worktree 目录
+WORKTREE_DIR=".worktrees/apply-<change-name>-<capability-name>"
+
+# 2. 验证 .worktrees 已被 gitignore
+git check-ignore -q .worktrees || echo ".worktrees/" >> .gitignore
+
+# 3. 创建 Worktree
+BRANCH="kld-sdd/<change-name>/<capability-name>"
+git worktree add "$WORKTREE_DIR" -b "$BRANCH"
+cd "$WORKTREE_DIR"
+```
+
+**权限错误回退**：如果 `git worktree add` 因沙箱限制失败，告知用户后在当前目录继续工作。
+
+### Step 2: 项目初始设置
+
+在 Worktree 中自动检测并运行项目设置：
+
+```bash
+# Node.js
+[ -f package.json ] && npm install
+
+# Rust
+[ -f Cargo.toml ] && cargo build
+
+# Python
+[ -f requirements.txt ] && pip install -r requirements.txt
+[ -f pyproject.toml ] && poetry install
+
+# Go
+[ -f go.mod ] && go mod download
+```
+
+### Step 3: 验证干净基线
+
+运行测试确保 Worktree 从干净状态开始：
+
+```bash
+# 使用项目对应的测试命令
+npm test / cargo test / pytest / go test ./...
+```
+
+**测试失败**：报告失败，询问用户是否继续。
+**测试通过**：报告就绪。
+
+```
+✅ Worktree 就绪：<full-path>
+   基线测试通过（N 个测试，0 失败）
+   准备实施 <change-name>/<capability-name>
+```
+
+## 清理流程
+
+### 应用完成后
+
+**使用原生工具时**：
+```
+ExitWorktree(action="remove", discard_changes=false)
+```
+
+**使用 git 命令时**：
+```bash
+# 返回主仓库
+cd "$MAIN_REPO"
+
+# 移除 Worktree
+git worktree remove "$WORKTREE_DIR"
+
+# 删除分支
+git branch -D "kld-sdd/<change-name>/<capability-name>"
+```
+
+**保留选项**：若用户需要保留变更待审查，使用 `ExitWorktree(action="keep")`。
+
+## 与子代理的配合
+
+- **所有子代理共享同一 Worktree**
+- DAG 分析确保同层任务不修改相同文件
+- 子代理无需关心 Worktree 存在（透明隔离）
+- 控制器（主会话）负责 Worktree 的创建和清理
+
+## 快速参考
+
+| 场景 | 操作 |
+|------|------|
+| 已在 Worktree 中 | 跳过创建 |
+| 非 Git 项目 | 跳过（`vcs_mode=no-git`） |
+| Claude Code 环境 | 使用 `EnterWorktree` |
+| 无原生工具 | `git worktree add` 回退 |
+| `.worktrees/` 存在 | 直接使用 |
+| `.worktrees/` 不存在 | 创建并验证 gitignore |
+| 权限错误 | 在当前目录继续工作 |
+| 基线测试失败 | 报告 + 询问用户 |
+| 完成 | `ExitWorktree(action="remove")` |