aigroup-workflow 1.3.0 → 2.0.0

package/skills/documentation/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: documentation
+description: 在代码变更落地后更新受影响的文档，确保 docs/ 与代码一致。包含必更新清单、更新原则、文档传感器验证。
+---
+
+# 文档更新
+
+代码变更后的文档同步。**只更新受影响的文档**，不做无关改进。
+
+## 协调
+
+直接修改 `docs/` 下的文档；在 session `README.md`（或回报主会话）留变更笔记。完成后运行 `node scripts/hooks/dispatcher.cjs stop` 验证。
+
+## 必更新清单
+
+| 文档 | 触发条件 |
+|------|---------|
+| API 文档 | 接口变更（参数 / 返回值 / 错误码） |
+| README | 安装、使用方式变更 |
+| `docs/ARCHITECTURE.md` | 架构 / 模块边界 / 组件图变更 |
+| 模块 `CLAUDE.md` | 模块行为或入口变更 |
+
+## 按需更新
+
+| 文档 | 触发条件 |
+|------|---------|
+| 代码注释 | 复杂逻辑、关键算法、设计决策 |
+| 配置文档 | 配置项变更（新增 / 默认值 / 移除） |
+| 部署文档 | 部署流程或环境要求变更 |
+
+## 原则
+
+- 只改受影响的文档，不顺手做无关改进
+- 文档描述以代码实际行为为准
+- 删除已不存在功能的描述
+- 沿用现有文档的格式和语气
+
+## Red Flags
+
+| 信号 | 行动 |
+|------|------|
+| 测试未通过就更新文档 | 先完成测试 phase |
+| 文档与代码描述冲突 | 以代码为准修正文档 |
+| dispatcher stop 报错 | 先修 [FAIL] 再 ship |
+| 想跳过文档更新 | 检查是否真的零受影响文档 |

package/skills/{max/workflow/entropy-management → entropy-management}/SKILL.md

@@ -1,124 +1,115 @@
----
-name: entropy-management
-description: 定期维护代码库健康度。扫描架构漂移、过期文档、低质量代码，防止技术债积累。应在完成若干任务后或怀疑代码库退化时触发。
----
-
-# 熵管理（Garbage Collection）
-
-## 概述
-
-AI Agent 会复制仓库中已有的模式——包括不好的模式。随着时间推移，这不可避免地导致漂移。
-手动清理不可持续。熵管理将清理系统化，定期执行，像垃圾回收一样防止技术债积累。
-
-**核心原则**：技术债是高利贷——持续小额偿还远优于积累后大规模清理。
-
-## 铁律
-
-```
-发现的问题不能只修一次——必须同时编码为约束，防止再次发生。
-每次熵管理运行结束后，必须更新质量评分和技术债追踪。
-```
-
-## 触发条件
-
-- 完成 5 个以上任务后（定期维护）
-- Kyle 审查中反复出现同类问题（模式漂移信号）
-- 用户主动要求代码库健康检查
-- 怀疑文档与代码不一致
-- 新成员加入前（确保仓库状态良好）
-
-## 执行流程
-
-### 第一阶段：自动化传感器扫描
-
-运行 Harness 传感器套件收集机器可检测的问题：
-
-```bash
-bash scripts/harness/run-all.sh
-```
-
-记录所有 `[FAIL]` 和 `[WARN]` 项。
-
-### 第二阶段：推理型扫描
-
-自动化传感器无法覆盖的维度，需要人工/Agent 推理检查：
-
-#### 2.1 文档-代码一致性
-
-| 检查项 | 方法 |
-|--------|------|
-| CLAUDE.md 引用路径是否有效 | 逐条验证文件/目录存在 |
-| docs/ 文档描述是否匹配实际行为 | 抽样对比 |
-| SKILL.md 中的流程是否被实际遵循 | 回顾近期任务记录 |
-| 模板是否与当前实践一致 | 对比模板与近期产出 |
-
-#### 2.2 架构漂移检测
-
-| 检查项 | 方法 |
-|--------|------|
-| 是否有文件放在错误目录 | 检查目录约定是否被遵守 |
-| 是否有重复/冗余文件 | 搜索相似文件名和内容 |
-| 技能包结构是否一致 | 抽样检查 SKILL.md 格式 |
-| 协作产物是否在正确位置 | 检查 .dev-agents/shared/ 结构 |
-
-#### 2.3 质量回归检测
-
-| 检查项 | 方法 |
-|--------|------|
-| 近期审查中的高频问题 | 分析 .dev-agents/shared/reviews/ |
-| 是否有被跳过的工作流阶段 | 检查产物完整性 |
-| 是否有"沉默的传感器"（从不报错） | 评估传感器有效性 |
-
-### 第三阶段：修复与编码
-
-对发现的问题分类处理：
-
-| 问题类型 | 处理方式 |
-|---------|---------|
-| 可快速修复的具体问题 | 立即修复（文档更新、文件移动等） |
-| 需要编码为约束的重复模式 | 触发 [转向循环](../../../../docs/steering-loop.md)，添加传感器或更新规则 |
-| 需要架构讨论的系统性问题 | 记录到技术债，与用户讨论 |
-
-### 第四阶段：更新追踪
-
-**必须完成以下更新**（不可跳过）：
-
-1. 更新 `docs/QUALITY_SCORE.md`
-   - 重新评估各维度评分
-   - 添加历史趋势记录
-   - 标注评分变化原因
-
-2. 更新 `docs/tech-debt-tracker.md`
-   - 新发现的技术债添加到"活跃"列表
-   - 已修复的技术债移至"已偿还"列表
-
-3. 更新 `docs/steering-loop.md`
-   - 如果有新增约束，记录到"改进记录"
-
-## 产出清单
-
-每次熵管理运行后，应产出：
-
-```
-✅ 传感器扫描结果（run-all.sh 输出）
-✅ 推理型扫描发现清单
-✅ 修复的问题列表
-✅ 新增的约束/传感器（如有）
-✅ 更新后的 QUALITY_SCORE.md
-✅ 更新后的 tech-debt-tracker.md
-```
-
-## Red Flags — 停下来
-
-| 信号 | 行动 |
-|------|------|
-| 传感器全部通过但直觉上代码库有问题 | 传感器覆盖不足，添加新检查项 |
-| 修复一个漂移又发现三个 | 可能是架构问题，记录技术债后与用户讨论 |
-| 质量评分持续下降 | 需要专项改进，不是熵管理能解决的 |
-| 跳过第四阶段"下次再更新" | 不允许，追踪更新是必须步骤 |
-
-## 关联技能
-
-- **steering-loop** — 将重复问题编码为约束
-- **verification-before-completion** — 修复后验证
-- **systematic-debugging** — 深入调查发现的问题
+---
+name: entropy-management
+description: 定期维护代码库健康度。扫描架构漂移、过期文档、低质量代码，防止技术债积累。应在完成若干任务后或怀疑代码库退化时触发。
+---
+
+# 熵管理（Garbage Collection）
+
+## 概述
+
+AI Agent 会复制仓库中已有的模式——包括不好的模式。随着时间推移，这不可避免地导致漂移。
+手动清理不可持续。熵管理将清理系统化，定期执行，像垃圾回收一样防止技术债积累。
+
+**核心原则**：技术债是高利贷——持续小额偿还远优于积累后大规模清理。
+
+## 铁律
+
+```
+发现的问题不能只修一次——必须同时编码为约束，防止再次发生。
+每次熵管理运行结束后，必须更新质量评分和技术债追踪。
+```
+
+## 触发条件
+
+- 完成 5 个以上任务后（定期维护）
+- Kyle 审查中反复出现同类问题（模式漂移信号）
+- 用户主动要求代码库健康检查
+- 怀疑文档与代码不一致
+- 新成员加入前（确保仓库状态良好）
+
+## 执行流程
+
+### 第一阶段：自动化传感器扫描
+
+运行 Harness 传感器套件收集机器可检测的问题：
+
+```bash
+node scripts/hooks/dispatcher.cjs stop
+```
+
+记录所有 `[FAIL]` 和 `[WARN]` 项。
+
+### 第二阶段：推理型扫描
+
+自动化传感器无法覆盖的维度，需要人工/Agent 推理检查：
+
+#### 2.1 文档-代码一致性
+
+| 检查项 | 方法 |
+|--------|------|
+| CLAUDE.md 引用路径是否有效 | 逐条验证文件/目录存在 |
+| docs/ 文档描述是否匹配实际行为 | 抽样对比 |
+| SKILL.md 中的流程是否被实际遵循 | 回顾近期任务记录 |
+| 模板是否与当前实践一致 | 对比模板与近期产出 |
+
+#### 2.2 架构漂移检测
+
+| 检查项 | 方法 |
+|--------|------|
+| 是否有文件放在错误目录 | 检查目录约定是否被遵守 |
+| 是否有重复/冗余文件 | 搜索相似文件名和内容 |
+| 技能包结构是否一致 | 抽样检查 SKILL.md 格式 |
+| 协作产物是否在正确位置 | 检查 .orchestration/<session>/ 结构 |
+
+#### 2.3 质量回归检测
+
+| 检查项 | 方法 |
+|--------|------|
+| 近期审查中的高频问题 | 分析 .orchestration/<session>/code-reviewer/ |
+| 是否有被跳过的工作流阶段 | 检查产物完整性 |
+| 是否有"沉默的传感器"（从不报错） | 评估传感器有效性 |
+
+### 第三阶段：修复与编码
+
+对发现的问题分类处理：
+
+| 问题类型 | 处理方式 |
+|---------|---------|
+| 可快速修复的具体问题 | 立即修复（文档更新、文件移动等） |
+| 需要编码为约束的重复模式 | 在 `scripts/hooks/checks/` 加 check，让违规自动触发 [FAIL] |
+| 需要架构讨论的系统性问题 | 与用户讨论；动手前先达成共识 |
+
+### 第四阶段：沉淀与追踪
+
+把本次发现和处理沉淀到下列位置（按相关性挑，不必每次都全做）：
+
+- 反复出现的违规模式 → 在 `scripts/hooks/checks/` 加自动化 check
+- 团队级架构决策 / 新约束 → 写进 `docs/PROJECT_CONTEXT.md` 或 `docs/ARCHITECTURE.md`
+- 跨会话需要记得的代码模式 → 写进 `docs/rules/<topic>.md` 或 `docs/red-flags.md`
+- 用户当前活跃状态 / 个人偏好 → 让 Claude 写进原生 memory（`~/.claude/projects/<slug>/memory/`，自动加载）
+- 新增的危险信号 → 加入 `docs/red-flags.md`
+- 新增的强制规则 → 加入 `docs/rules/<topic>.md`
+
+## 产出清单
+
+每次熵管理运行后，应产出：
+
+```
+✅ dispatcher 扫描结果（node scripts/hooks/dispatcher.cjs stop）
+✅ 推理型扫描发现清单
+✅ 修复的问题列表
+✅ 新增的约束 / check / 规则文档（如有）
+```
+
+## Red Flags — 停下来
+
+| 信号 | 行动 |
+|------|------|
+| 传感器全部通过但直觉上代码库有问题 | 传感器覆盖不足，加新 check |
+| 修复一个漂移又发现三个 | 可能是架构问题，先与用户讨论再动 |
+| 反复出现同类问题但没有沉淀为约束 | 必须在 `scripts/hooks/checks/` 加自动检测 |
+
+## 关联技能
+
+- **verification-before-completion** — 修复后验证
+- **systematic-debugging** — 深入调查发现的问题

package/skills/requirement-engineering/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: requirement-engineering
+description: 需求工程 — 在任何创造性工作之前使用。通过协作对话收集需求、系统性验证、产出可作为设计和开发基准的需求文档。
+---
+
+# 需求工程
+
+把模糊想法转化为完整、无歧义、可验证的需求文档。包含两个阶段：**收集**（brainstorming）和**验证**（validation）。
+
+> 只负责"要做什么"，不负责"怎么做"——技术方案在 `architecture-designer` / `writing-plans` 完成。
+
+## 协调
+
+```bash
+# 建 session（若尚未创建）
+node scripts/orchestration/session.cjs init <任务名>
+# 需求文档写入 .orchestration/<session>/architect/requirements.md
+# 验证结论追加到同文件；通过后进入方案设计 phase
+```
+
+## 阶段 1：收集（brainstorming）
+
+1. **探索项目上下文** — 读 文件、文档、近期提交，了解现状
+2. **逐个提问澄清** — 每条消息**只问一个问题**，优先选择题
+3. **识别用户场景** — 谁用？什么场景？期望什么结果？
+4. **定义功能边界** — 做什么、不做什么、优先级
+5. **撰写需求文档** — 保存到 `.orchestration/<session>/architect/requirements.md`
+
+### 需求文档结构
+
+```markdown
+# [功能名] 需求文档
+
+## 背景与目的
+为什么做？解决什么问题？
+
+## 用户场景
+- 场景 1：作为 [角色]，我希望 [行为]，以便 [价值]
+
+## 功能需求（每条可验证）
+- [ ] FR-1：[具体描述 + 通过/不通过标准]
+
+## 约束条件
+- 性能 / 兼容性 / 安全要求
+
+## 非功能需求
+- ...
+
+## 范围排除（不做什么）
+- ...
+
+## 成功标准
+- ...
+```
+
+## 阶段 2：验证（validation）
+
+对收集到的需求逐条验证，不通过不得进入设计。
+
+| 维度 | 检查项 |
+|------|--------|
+| 完整性 | 每场景有对应 FR？异常/非功能需求齐全？范围排除明确？ |
+| 可行性 | 技术可实现？时间合理？与现有系统兼容？ |
+| 无歧义性 | 每条只有一种理解？数值/行为边界明确（"快速"→"200ms 内"）？ |
+| 一致性 | 条目间有矛盾？约束冲突？优先级清晰？ |
+| 可验证性 | 有明确通过/不通过标准？ |
+
+### 验证结论（追加到需求文档末尾）
+
+```markdown
+---
+
+## 需求验证结论
+
+**验证日期**：YYYY-MM-DD
+**结论**：通过 / 有条件通过 / 不通过
+
+- [x] 完整性 / 可行性 / 无歧义性 / 一致性 / 可验证性：通过
+
+### 发现的问题（如有）
+1. [问题] → [修正方案]
+
+### 修改记录
+- [修改内容]
+```
+
+## 铁律
+
+1. 此阶段不做技术方案设计、不选择技术栈、不讨论架构
+2. 每条消息只问一个问题
+3. 每条需求必须可验证（明确通过/不通过标准）
+4. 必须产出需求文档并获得用户确认才能推进
+5. 验证发现的问题必须**现场修正**，不得留到后续阶段
+
+## Red Flags — 停下来
+
+| 信号 | 行动 |
+|------|------|
+| 开始讨论技术方案 | 技术方案属于设计阶段，打住 |
+| 用户说"直接做吧" | 先完成最小需求文档 |
+| 需求描述了多个独立系统 | 先帮用户拆解为子项目 |
+| 需求中有"待定""之后再说" | 现在确定或标记为**明确的开放问题** |
+| 需求可以被两种方式理解 | 选定一种并明确 |
+| 需求之间有矛盾 | 与用户澄清并修正 |
+| 想跳过用户确认 | 用户确认是必须的门禁 |
+| 想跳过验证直接设计 | 不允许 |
+
+## 与其他 skill 的协作
+
+- 若涉及 UI/UX，可派遣对应 design agent 参与需求收集
+- 通过验证的需求文档是 `architecture-designer` / `writing-plans` 的核心输入

package/skills/{max/workflow/subagent-driven-development → subagent-driven-development}/SKILL.md

@@ -11,26 +11,26 @@ description: 当有实现计划且任务相互独立时使用。使用 Agent 工
 
 ```
 ❌ 错误方式（角色切换）：
-   Max 在当前对话里"假装变成 Jarvis"然后开始写代码
-   → 共享上下文、无隔离、Max 的项目管理视角被污染
+   主会话 在当前对话里"假装变成 Jarvis"然后开始写代码
+   → 共享上下文、无隔离、主会话 的项目管理视角被污染
 
 ✅ 正确方式（Agent 工具派遣）：
-   Max 调用 Agent({subagent_type: "jarvis", ...}) → 创建独立子代理
+   主会话 调用 Agent({subagent_type: "jarvis", ...}) → 创建独立子代理
    → 子代理有自己的上下文、技能和门控
-   → 子代理完成后返回结果给 Max → Max 继续协调
+   → 子代理完成后返回结果给 主会话 → 主会话 继续协调
 ```
 
-**铁律：Max 自己绝不写代码。所有开发/审查工作必须通过 Agent 工具委派给隔离的子代理（`.claude/agents/{ella,jarvis,kyle}.md`）。**
+**铁律：主会话 自己绝不写代码。所有开发/审查工作必须通过 Agent 工具委派给隔离的子代理（`.claude/agents/{ella,jarvis,kyle}.md`）。**
 
 ## 铁律
 
 ```
-1. 使用 Agent 工具派遣，不是角色切换。Max 不写代码。
+1. 使用 Agent 工具派遣，不是角色切换。主会话 不写代码。
 2. 每个任务一个全新子代理，禁止复用上下文
 3. 两阶段审查顺序不可颠倒：先规格符合性，再代码质量
 4. 审查不通过 = 修复 + 重新审查，不得跳过
 5. 禁止并行派遣多个实现子代理（避免冲突）
-6. 不让子代理自己读计划文件，由 Max 提取任务全文注入 prompt
+6. 不让子代理自己读计划文件，由 主会话 提取任务全文注入 prompt
 ```
 
 ## 流程
@@ -59,7 +59,7 @@ description: 当有实现计划且任务相互独立时使用。使用 Agent 工
 
 ## 派遣 Jarvis 实现子代理 — 具体操作
 
-Max 必须使用 **Agent 工具** 派遣 Jarvis。以下是具体的调用方式：
+主会话 必须使用 **Agent 工具** 派遣 Jarvis。以下是具体的调用方式：
 
 ### 步骤 1：准备 prompt
 
@@ -77,8 +77,8 @@ prompt 模板：
 
 ## 上下文
 - 该任务在整体计划中的位置：第 N/M 个任务
-- 设计文档路径：.dev-agents/shared/designs/YYYY-MM-DD-xxx-design.md
-- 实现计划路径：.dev-agents/shared/tasks/YYYY-MM-DD-xxx-plan.md
+- 设计文档路径：.orchestration/<session>/architect/YYYY-MM-DD-xxx-design.md
+- 实现计划路径：.orchestration/<session>/planner/YYYY-MM-DD-xxx-plan.md
 
 ## 工作规范
 - 遵循 TDD：先写失败测试 → 确认失败 → 写最小实现 → 确认通过 → 提交
@@ -97,9 +97,9 @@ Agent({
 
 ### 步骤 3：处理返回结果
 
-子代理完成后会返回结果给 Max。Max 根据状态处理：
+子代理完成后会返回结果给 主会话。主会话 根据状态处理：
 
-| 状态 | Max 的处理方式 |
+| 状态 | 主会话 的处理方式 |
 |------|-------------|
 | **DONE** | 进入审查：Agent 工具派遣 Kyle |
 | **DONE_WITH_CONCERNS** | 先评估疑虑，再决定是否审查 |
@@ -132,7 +132,7 @@ Agent({
 Jarvis 修改的文件：
 [此处列出 Jarvis 报告中的变更文件列表]
 
-设计文档路径：.dev-agents/shared/designs/YYYY-MM-DD-xxx-design.md
+设计文档路径：.orchestration/<session>/architect/YYYY-MM-DD-xxx-design.md
 
 ### 检查要求
 - 代码是否实现了计划的每条要求？
@@ -140,7 +140,7 @@ Jarvis 修改的文件：
 - 少做了什么？（遗漏的需求 = 需要补充）
 
 ## 输出
-审查报告保存到 `.dev-agents/shared/reviews/YYYY-MM-DD-xxx-review.md`
+审查报告保存到 `.orchestration/<session>/code-reviewer/YYYY-MM-DD-xxx-review.md`
 结论：通过 / 不通过（附具体问题清单）
   "
 })
@@ -168,7 +168,7 @@ git diff HEAD~1
 - 命名是否清晰？
 
 ## 输出
-在 `.dev-agents/shared/reviews/` 的审查报告中追加 Stage 2 结论
+在 `.orchestration/<session>/code-reviewer/` 的审查报告中追加 Stage 2 结论
 结论：通过 / 不通过（附问题清单和修复建议）
   "
 })
@@ -178,12 +178,12 @@ git diff HEAD~1
 
 ```
 Kyle Stage 1 不通过
-  → Max 提取问题清单
+  → 主会话 提取问题清单
   → Agent 派遣新的 Jarvis 子代理修复
   → Agent 派遣新的 Kyle 重审 Stage 1
 
 Kyle Stage 2 不通过
-  → Max 提取问题清单
+  → 主会话 提取问题清单
   → Agent 派遣新的 Jarvis 子代理修复
   → Agent 派遣新的 Kyle 重审 Stage 2
 ```
@@ -194,7 +194,7 @@ Kyle Stage 2 不通过
 
 | 信号 | 行动 |
 |------|------|
-| Max 自己开始写代码 | 停，使用 Agent 工具派遣 Jarvis |
+| 主会话 自己开始写代码 | 停，使用 Agent 工具派遣 Jarvis |
 | 在当前对话中"变成 Jarvis" | 停，这是角色切换不是子代理 |
 | 在 Stage 1 通过前开始 Stage 2 | 停，先完成规格审查 |
 | 审查发现问题但跳过了 | 停，Jarvis 修复后重审 |