@geeseeker/easyai-dev 3.0.0-alpha.1 → 3.0.1

package/skeleton/.agents/skills/pm-task-planning/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: pm-task-planning
+description: PM 任务规划（约束集驱动）— PM 完成需求澄清后激活，将设计文档转化为约束集格式的任务定义。新任务创建前必须经过此流程。
+---
+
+# PM 任务规划（约束集驱动）
+
+## 适用场景
+
+PM 完成 `pm-brainstorm`（需求澄清 + 设计确认）后，**必须**激活本 Skill 将设计转化为可执行的约束集任务。
+
+## 核心理念
+
+> 来源：ccg-workflow spec-research / spec-plan
+
+- PM 产出的**不是** TODO List，而是**约束集**
+- 每条约束缩小执行者的解空间，使执行者可"零决策"机械执行
+- 所有技术决策**必须**在规划阶段完成，禁止推迟到实现阶段
+- 约束集必须精准到可验证：含具体参数、明确边界、可测量标准
+
+## HARD-GATE
+
+```
+1. 设计文档未持久化到 .docs/design/ 前，不得进入本流程。
+2. plan_validate() 检测到反面模式时，必须修正后才能创建任务。
+3. conflict_check() 检测到文件冲突时，必须解决后才能创建任务。
+```
+
+## 流程
+
+### Step 1：需求聚焦
+
+- 读取已确认的设计文档（来自 `pm-brainstorm` 的 `.docs/design/{name}.md`）
+- 提取功能边界、技术约束、验收标准草案
+- 确认设计文档路径，后续 `task_create()` 将引用此路径
+
+### Step 2：约束集生成
+
+将需求转化为约束集格式。约束集分三层：
+
+#### 硬约束（不可违反）
+
+技术选型、接口规范、安全要求等确定性决策——执行者必须遵守，无商量余地。
+
+示例：
+- C1: 使用 JWT，TTL=15min，刷新机制=sliding window
+- C2: API 端点遵循 RESTful 规范，路径前缀 `/api/v1/`
+- C3: 密码存储使用 bcrypt，cost=12
+
+#### 软约束（建议遵守）
+
+代码风格偏好、辅助性建议——执行者有小幅调整空间，偏离时需说明理由。
+
+示例：
+- C4: 优先复用 `src/utils/` 中的现有函数
+- C5: 单个函数不超过 30 行
+
+#### 验收标准
+
+可验证的成功判据——每条必须是 yes/no 可判定的。
+
+示例：
+- [ ] 登录成功返回有效 JWT token
+- [ ] 无效凭证返回 401 + 标准错误格式
+- [ ] token 过期后请求返回 401
+
+### Step 3：反面模式自检（HARD-GATE #2）
+
+**必须**在约束集完成后调用 `plan_validate()` 检测以下反面模式：
+
+1. **多方案未选择** — 列出方案但未决定 → 必须选定一个并说明理由
+2. **无决策标准** — 使用"都可以""均可"等模糊词 → 必须给出选择依据
+3. **推迟决策** — 标记"待定""TBD" → 所有决策在此阶段完成
+4. **信息堆砌无结论** — 列举信息无总结 → 以约束或决策收尾
+
+```
+调用方式：plan_validate(content: "约束集完整内容")
+```
+
+- `valid: true` → 继续 Step 4
+- `valid: false` → 修正检测到的反面模式，重新调用直到通过
+
+### Step 4：任务拆分
+
+按约束集拆分为**原子任务**，每个任务满足：
+
+- **单一职责**：一个任务做一件事
+- **可独立验收**：有明确的完成判据
+- **文件范围明确**：列出所有涉及文件/目录
+- **依赖显式化**：如有前置依赖，声明依赖任务 ID
+- **粒度适中**：每个任务执行者在 1-2 个会话内可完成
+
+每个任务包含：
+```
+标题：简洁描述
+约束集：从 Step 2 筛选该任务相关约束
+文件范围：涉及的文件/目录 glob 列表
+验收标准：从 Step 2 筛选该任务相关标准
+设计文档：引用 .docs/design/{name}.md 路径
+```
+
+### Step 5：冲突预检（HARD-GATE #3）
+
+**必须**在创建任务前调用 `conflict_check()` 检测文件范围重叠：
+
+```
+调用方式：conflict_check(files: ["src/auth/*.ts", ...], role: "pm")
+```
+
+- 无冲突 → 继续 Step 6
+- 有冲突 → 向用户呈现冲突报告，解决方案：
+  - 调整文件范围避开冲突
+  - 建立任务依赖（先完成冲突任务）
+  - 使用 `worktree_create()` 物理隔离
+
+### Step 6：任务创建
+
+调用 `task_create()` 创建任务：
+
+```text
+task_create(
+  role: "pm",
+  title: "实现用户认证 API",
+  description: "参见设计文档：.docs/design/user-auth.md\n\n## 约束集\n...",
+  acceptance_criteria: "1. 登录返回 JWT\n2. ...",
+  file_scope: "src/auth/*.ts, src/middleware/jwt.ts",
+  assign_strategy: "independent"
+)
+```
+
+### Step 7：上下文配置
+
+任务创建成功后，为每个任务调用 `context_generate()` 生成 context.jsonl 推荐清单：
+
+```text
+调用方式：context_generate(task_id: "T001", phase: "implement")
+```
+
+审核推荐清单——添加遗漏的必要规范，移除不相关的推荐。
+
+创建完成后向用户汇报：
+
+- 任务 ID 和标题
+- 执行指引（如"请开新会话执行 `/worker T001`"）
+
+## 约束集输出模板
+
+```markdown
+## 约束集
+
+### 硬约束（不可违反）
+- C1: [具体技术决策 + 参数]
+- C2: [接口规范 + 格式要求]
+
+### 软约束（建议遵守）
+- C3: [代码风格偏好]
+- C4: [辅助性建议]
+
+### 文件范围
+- path/to/dir/*.ext
+- path/to/specific-file.ext
+
+### 验收标准
+- [ ] [可验证的成功判据 1]
+- [ ] [可验证的成功判据 2]
+
+### 设计文档
+- .docs/design/{feature-name}.md
+```
+
+## 关键原则
+
+- **缩小解空间** — 每条约束都让执行者少做一个决策
+- **具体可验证** — "使用 bcrypt cost=12"而非"使用安全的密码存储"
+- **YAGNI 无情** — 移除所有"以后可能用到"的约束
+- **原子化拆分** — 任务粒度以 1-2 个执行者会话为标准
+
+## PATEOAS 导航
+
+```markdown
+### 下一步行动
+
+1. [ ] 读取设计文档，提取功能边界和技术约束
+2. [ ] 生成约束集（硬约束 + 软约束 + 验收标准）
+3. [ ] 调用 `plan_validate()` 自检反面模式
+4. [ ] 拆分为原子任务（单一职责 + 文件范围 + 验收标准）
+5. [ ] 调用 `conflict_check()` 检测文件冲突
+6. [ ] 调用 `task_create()` 创建任务
+7. [ ] 调用 `context_generate()` 配置上下文
+
+### 状态快照
+
+- 当前角色：PM
+- 当前阶段：TASK_PLANNING
+- 设计文档：{已读取/未读取}
+- 约束集：{未开始/生成中/已完成}
+- 反面模式自检：{未开始/通过/未通过}
+- 冲突检测：{未开始/通过/有冲突}
+- 任务创建：{未开始/已创建 x 个}
+```

package/skeleton/.agents/skills/pm-task-review/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: pm-task-review
+description: PM 任务验收 — 双阶段验收流程（Stage 1 Spec 合规 → Stage 2 代码质量）。PM 审查执行者完成的任务时激活。
+---
+
+# PM 任务验收（双阶段）
+
+## 适用场景
+
+PM 审查执行者提交验收的任务时，**必须**激活本 Skill。
+
+## 验收原则
+
+- **双阶段不可颠倒**：必须先 Spec 合规，再代码质量
+- **Stage 1 不过不进 Stage 2**：节省审查时间，避免在不合规产出上花费精力
+- **公正客观**：基于证据而非印象
+
+## Stage 1：Spec 合规审查
+
+### 检查清单
+
+1. **读取任务约束集**
+   - 调用 `task_get({ task_id })` 获取 task.md
+   - 逐条列出验收标准
+
+2. **检查验证标记完整性**
+   - 读取 `dev/verification.md`
+   - 确认每个验证类别为 `_PASS` 或 `_NA`（附说明）：
+     - `LINT_PASS ✅` / `LINT_NA ⚠️`（附说明）
+     - `TEST_PASS ✅` / `TEST_NA ⚠️`（附说明）
+     - `MANUAL_PASS ✅` / `MANUAL_NA ⚠️`（附说明）
+   - **不接受 `_FAIL` 或缺失标记 → 直接打回**
+   - **PM 必须验证每个 `_NA` 标记是否有合理说明**
+
+3. **逐条验收标准对照**
+
+   | #   | 验收标准 | 对应产出        | 结果  |
+   | --- | -------- | --------------- | ----- |
+   | 1   | {标准1}  | {对应代码/文件} | ✅/❌ |
+   | 2   | {标准2}  | {对应代码/文件} | ✅/❌ |
+
+4. **约束集遵守度**
+   - 执行者是否只做了约束集要求的事？
+   - 是否存在范围蔓延（做了约束集之外的事）？
+   - 是否存在遗漏（约束集要求但未做的事）？
+
+### Stage 1 判定
+
+- **全部通过** → 进入 Stage 2
+- **任何项不通过** → 打回，附带具体不合规项和修复建议
+  - 调用 `task_transition({ task_id, new_status: "rejected", role: "pm" })`
+  - 在 task.md 追加打回原因
+
+## Stage 2：代码质量审查
+
+### 检查清单
+
+1. **代码风格一致性**
+   - 命名约定是否遵循 `coding-standards.md`？
+   - 缩进、格式是否统一？
+
+2. **架构一致性**
+   - 新代码是否与项目架构保持一致？
+   - 模块划分是否合理？
+   - 依赖方向是否正确？
+
+3. **边界情况处理**
+   - 空值 / 异常输入是否处理？
+   - 错误信息是否有意义？
+   - 并发 / 竞态条件是否考虑？
+
+4. **可维护性**
+   - 代码是否易理解？
+   - 是否有适当注释？
+   - 是否有重复代码可提取？
+
+5. **外部 CLI 独立审查（可选）**
+   - 如果任务复杂度高，可调用外部 CLI（Codex / Claude Code）做独立审查
+   - 外部 CLI 产出写入 `cli/` 目录
+   - 综合各方意见形成最终判断
+
+### Stage 2 判定
+
+- **全部通过** → 验收通过
+  - 调用 `task_transition({ task_id, new_status: "completed", role: "pm" })`
+- **存在问题** → 打回并附带具体改进建议
+  - 问题分级：Critical（必须修复）/ Important（建议修复）/ Minor（可后续优化）
+  - 调用 `task_transition({ task_id, new_status: "rejected", role: "pm" })`
+
+### PM Push Back 权利
+
+如果审查者认为执行者的判断有疑问，PM 有权 Push Back：
+
+1. **技术论证**：提供理由说明为何当前实现不够好
+2. **证据支撑**：展示代码/测试证明替代方案可行
+3. **请求澄清**：要求执行者解释具体设计决策
+
+执行者收到 Push Back 后：
+1. 理解审查者的技术关切
+2. 如审查者正确 → 接受建议并修改
+3. 如坚持原方案 → 提供完整技术论证（非"我觉得没问题"）
+
+## 验收结果输出
+
+```markdown
+## 验收报告
+
+### 任务信息
+
+- 任务 ID：{task_id}
+- 审查时间：{timestamp}
+- 审查者：PM
+
+### Stage 1: Spec 合规 — {PASS/FAIL}
+
+{逐条结果}
+
+### Stage 2: 代码质量 — {PASS/FAIL}
+
+{审查发现}
+
+### 最终判定：{通过 / 打回}
+
+{如果打回，列出具体修改要求}
+```
+
+## PATEOAS 导航
+
+```markdown
+### 下一步行动
+
+1. [ ] 如果通过 → 调用 `task_transition({ task_id, new_status: "completed", role: "pm" })` 标记完成
+2. [ ] 如果通过 → 确认是否需要归档（`task_transition({ task_id, new_status: "archived", role: "pm" })`）
+3. [ ] 如果打回 → 在 task.md 追加打回原因和修复建议
+4. [ ] 如果打回 → 通知用户开新会话执行 `/worker {task_id}` 继续修复
+
+### 状态快照
+
+- 当前角色：PM
+- 当前阶段：REVIEW
+- Stage 1: {PASS/FAIL}
+- Stage 2: {PASS/FAIL/未进入}
+- 最终判定：{通过/打回/审查中}
+```

package/skeleton/.agents/skills/worker-check/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: worker-check
+description: 执行者自检与验证标记 — 完成编码后的强制验证流程。生成 dev/verification.md，每个验证类别必须为 _PASS 或 _NA（附说明）。在 worker-implement 完成后由 Worker 激活。
+---
+
+# 执行者自检 & 验证标记
+
+## 适用场景
+
+Worker 完成所有编码工作后，提交验收前，**必须**执行本 Skill。
+
+## Iron Law
+
+```
+没有新鲜验证证据，不准声称完成
+NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
+```
+
+如果你没有在本轮消息中运行过验证命令，你就不能声称它通过了。
+
+## Gate 函数
+
+```
+在声称任何状态或表达满意之前：
+
+1. 识别：什么命令能证明这个声明？
+2. 运行：执行完整命令（新鲜的、完整的）
+3. 阅读：完整输出 + 检查退出码 + 数失败数
+4. 验证：输出是否确认了声明？
+   - 如果否：报告实际状态 + 证据
+   - 如果是：带证据声明结果
+5. 然后才能：做出声明
+
+跳过任何步骤 = 欺骗，不是验证
+```
+
+## 三标记验证流程
+
+### 步骤 1：Lint 验证
+
+```bash
+# 运行 lint 检查
+npm run lint    # 或项目实际的 lint 命令
+```
+
+- 粘贴 **完整** 终端输出到 verification.md
+- 根据输出标记：`LINT_PASS ✅`、`LINT_FAIL ❌` 或 `LINT_NA ⚠️`（附说明）
+- 如果失败：修复后重新运行，直到通过
+
+### 步骤 2：测试验证
+
+```bash
+# 运行所有测试
+npm test        # 或项目实际的测试命令
+```
+
+- 粘贴 **完整** 终端输出到 verification.md
+- 根据输出标记：`TEST_PASS ✅`、`TEST_FAIL ❌` 或 `TEST_NA ⚠️`（附说明）
+- 确认：0 failures, 0 errors
+- 如果失败：修复后重新运行，直到通过
+
+### 步骤 3：手动验证
+
+手动验证产出是否满足约束集中的验收标准：
+
+- 逐条对照 task.md 中的验收标准
+- 描述每条标准的验证方式和结果
+- 标记：`MANUAL_PASS ✅`、`MANUAL_FAIL ❌` 或 `MANUAL_NA ⚠️`（附说明）
+
+## 生成 verification.md
+
+将以上三步结果写入 `dev/verification.md`：
+
+```markdown
+# 验证报告
+
+## 任务信息
+
+- 任务 ID：{task_id}
+- 验证时间：{timestamp}
+- 验证者：Worker
+
+## Lint 验证
+
+### 命令
+
+{实际运行的命令}
+
+### 输出
+
+{完整终端输出}
+
+### 标记
+
+LINT_PASS ✅
+
+## 测试验证
+
+### 命令
+
+{实际运行的命令}
+
+### 输出
+
+{完整终端输出}
+
+### 标记
+
+TEST_PASS ✅
+
+## 手动验证
+
+### 验收标准检查
+
+| #   | 验收标准 | 验证方式 | 结果 |
+| --- | -------- | -------- | ---- |
+| 1   | {标准1}  | {方式}   | ✅   |
+| 2   | {标准2}  | {方式}   | ✅   |
+
+### 标记
+
+MANUAL_PASS ✅
+
+## 标记汇总
+
+- LINT_PASS ✅
+- TEST_PASS ✅
+- MANUAL_PASS ✅
+```
+
+### 不适用示例
+
+如果某验证类别不适用，使用 `_NA` 标记并附说明：
+
+```markdown
+## Lint 验证
+
+### 命令
+
+（无命令）
+
+### 输出
+
+项目未配置 lint 工具。
+
+### 标记
+
+LINT_NA ⚠️ — 项目未配置 lint 工具
+```
+
+## Red Flags — 立即停下
+
+| 信号                                     | 含义                      |
+| ---------------------------------------- | ------------------------- |
+| 使用 "should"、"probably"、"seems to"    | 没有运行验证              |
+| 在验证前说 "Great!"、"Done!"、"Perfect!" | 没有证据的满足感          |
+| "lint 通过了所以应该没问题"              | lint ≠ 测试 ≠ 手动验证    |
+| "我很自信"                               | 信心 ≠ 证据               |
+| "之前运行过了"                           | 之前 ≠ 现在，必须重新运行 |
+| "部分检查够了"                           | 部分证明不了什么          |
+
+## 不适用场景
+
+当某验证类别确实不适用时，使用 `_NA` 标记（而非 `_PASS`）：
+
+- **项目无 lint 配置**：声明 `LINT_NA`，附说明「项目未配置 lint 工具」
+- **项目无测试框架**：声明 `TEST_NA`，附说明「项目未配置测试框架」
+- **手动验证不可行**：声明 `MANUAL_NA`，附说明原因及替代验证方案
+
+> ⚠️ `_NA` 标记需 PM 在验收阶段确认合理性。不可用 `_NA` 替代实际验证。
+
+Evidence Gate 接受 `_PASS` 和 `_NA`，拒绝 `_FAIL` 和缺失标记。
+
+**无论是否使用 `_NA` 标记，`verification.md` 必须始终生成。**
+
+## PATEOAS 导航
+
+验证完成后输出：
+
+```markdown
+### 下一步行动
+
+1. [ ] 确认 dev/verification.md 已生成且三标记全部 _PASS 或 _NA（附说明）
+2. [ ] 调用 `task_transition({ task_id, new_status: "under_review" })` 提交验收
+3. [ ] 激活 `common-session-close` Skill 完成会话收尾
+4. [ ] 告知用户回 PM 会话验收
+
+### 状态快照
+
+- 当前角色：Worker
+- 当前阶段：CHECK
+- 标记状态：LINT*{status} | TEST*{status} | MANUAL_{status}
+- 验证文件：dev/verification.md {已生成/未生成}
+```