aigroup-workflow 1.2.7 → 2.0.0

package/scripts/orchestration/lib/orchestrator.cjs

@@ -0,0 +1,181 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.resolve(__dirname, '..', '..', '..');
+const COORDINATION_ROOT = path.join(ROOT, '.orchestration');
+
+function toPosix(p) {
+  return p.split(path.sep).join('/');
+}
+
+function relPosix(target) {
+  return toPosix(path.relative(ROOT, target));
+}
+
+function slugify(value, fallback = 'item') {
+  const normalized = String(value || '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return normalized || fallback;
+}
+
+function timestamp() {
+  return new Date().toISOString().replace(/\.\d+Z$/, 'Z');
+}
+
+function sessionDir(sessionName) {
+  const slug = slugify(sessionName, 'session');
+  return path.join(COORDINATION_ROOT, slug);
+}
+
+function workerDir(sessionName, workerName) {
+  return path.join(sessionDir(sessionName), slugify(workerName, 'worker'));
+}
+
+function workerArtifacts(sessionName, workerName) {
+  const dir = workerDir(sessionName, workerName);
+  return {
+    dir,
+    task: path.join(dir, 'task.md'),
+    handoff: path.join(dir, 'handoff.md'),
+    status: path.join(dir, 'status.md')
+  };
+}
+
+function ensureDir(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+
+function writeFile(filePath, content) {
+  ensureDir(path.dirname(filePath));
+  fs.writeFileSync(filePath, content.endsWith('\n') ? content : content + '\n', 'utf8');
+}
+
+function buildTaskFile({ sessionName, workerName, agent, objective, context = [], deliverables = [] }) {
+  const ctx = context.length > 0 ? context.map(line => `- ${line}`).join('\n') : '- _无_';
+  const deliv = deliverables.length > 0 ? deliverables.map(line => `- ${line}`).join('\n') : '- 见 handoff.md 模板';
+  const artifacts = workerArtifacts(sessionName, workerName);
+  return [
+    `# Worker Task: ${workerName}`,
+    '',
+    `- Session: \`${sessionName}\``,
+    `- Agent: \`${agent}\``,
+    `- Created: ${timestamp()}`,
+    `- Handoff: \`${relPosix(artifacts.handoff)}\``,
+    `- Status: \`${relPosix(artifacts.status)}\``,
+    '',
+    '## Objective',
+    objective.trim(),
+    '',
+    '## Context',
+    ctx,
+    '',
+    '## Deliverables',
+    deliv,
+    '',
+    '## Completion Rules',
+    '- 不再向下派遣 subagent，结果写进最终响应',
+    '- 主会话负责把响应抄写进 `handoff.md`',
+    '- 主会话负责更新 `status.md`'
+  ].join('\n');
+}
+
+function buildHandoffFile({ workerName }) {
+  return [
+    `# Handoff: ${workerName}`,
+    '',
+    '## Summary',
+    '- Pending',
+    '',
+    '## Files Changed',
+    '- Pending',
+    '',
+    '## Validation',
+    '- Pending',
+    '',
+    '## Follow-ups',
+    '- Pending'
+  ].join('\n');
+}
+
+function buildStatusFile({ workerName, state = 'not_started', lightweight = false }) {
+  const lines = [
+    `# Status: ${workerName}`,
+    '',
+    `- State: ${state}`,
+    `- Updated: ${timestamp()}`
+  ];
+  if (lightweight) lines.push('- Lightweight: true');
+  return lines.join('\n');
+}
+
+function createWorker(spec) {
+  const { sessionName, workerName, lightweight = false } = spec;
+  if (!sessionName) throw new Error('sessionName is required');
+  if (!workerName) throw new Error('workerName is required');
+  if (!spec.agent) throw new Error('agent is required');
+  if (!spec.objective) throw new Error('objective is required');
+
+  const artifacts = workerArtifacts(sessionName, workerName);
+  ensureDir(artifacts.dir);
+  if (!lightweight) {
+    writeFile(artifacts.task, buildTaskFile(spec));
+  }
+  writeFile(artifacts.handoff, buildHandoffFile({ workerName }));
+  writeFile(artifacts.status, buildStatusFile({ workerName, lightweight }));
+  return { ...artifacts, lightweight };
+}
+
+function isLightweight(statusFile) {
+  try {
+    const raw = fs.readFileSync(statusFile, 'utf8');
+    return /^\s*-\s*Lightweight:\s*true/m.test(raw);
+  } catch (_error) {
+    return false;
+  }
+}
+
+function updateStatus(sessionName, workerName, state, details = '') {
+  const artifacts = workerArtifacts(sessionName, workerName);
+  const lightweight = isLightweight(artifacts.status);
+  const body = [
+    `# Status: ${workerName}`,
+    '',
+    `- State: ${state}`,
+    `- Updated: ${timestamp()}`
+  ];
+  if (lightweight) body.push('- Lightweight: true');
+  if (details) body.push('', details.trim());
+  writeFile(artifacts.status, body.join('\n'));
+  return artifacts.status;
+}
+
+function appendHandoff(sessionName, workerName, sectionTitle, content) {
+  const artifacts = workerArtifacts(sessionName, workerName);
+  const existing = fs.existsSync(artifacts.handoff)
+    ? fs.readFileSync(artifacts.handoff, 'utf8')
+    : buildHandoffFile({ workerName });
+  const block = `\n## ${sectionTitle} (${timestamp()})\n${content.trim()}\n`;
+  writeFile(artifacts.handoff, existing.replace(/\s+$/, '') + block);
+  return artifacts.handoff;
+}
+
+module.exports = {
+  COORDINATION_ROOT,
+  ROOT,
+  sessionDir,
+  workerDir,
+  workerArtifacts,
+  createWorker,
+  updateStatus,
+  appendHandoff,
+  isLightweight,
+  slugify,
+  timestamp,
+  relPosix,
+  toPosix
+};

package/scripts/orchestration/session.cjs

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const {
+  COORDINATION_ROOT,
+  ROOT,
+  sessionDir,
+  workerArtifacts,
+  createWorker,
+  updateStatus,
+  appendHandoff,
+  slugify,
+  relPosix
+} = require('./lib/orchestrator.cjs');
+
+const COMMANDS = ['init', 'add-worker', 'status', 'set-status', 'append', 'list', 'help'];
+
+function usage() {
+  console.log([
+    'Usage:',
+    '  node scripts/orchestration/session.js init <session-name>',
+    '  node scripts/orchestration/session.cjs add-worker <session> <worker> --agent <name> --objective <text>',
+    '                                                       [--context <line>]... [--deliverable <line>]... [--lightweight]',
+    '  node scripts/orchestration/session.js set-status <session> <worker> <state> [--details <text>]',
+    '  node scripts/orchestration/session.js append <session> <worker> <section> --content <text>',
+    '  node scripts/orchestration/session.js status <session>',
+    '  node scripts/orchestration/session.js list',
+    '',
+    'States: not_started | running | blocked | completed | failed',
+    `Coordination root: ${relPosix(COORDINATION_ROOT)}/`
+  ].join('\n'));
+}
+
+const BOOLEAN_FLAGS = new Set(['lightweight']);
+
+function parseFlags(args) {
+  const flags = { context: [], deliverable: [] };
+  const positional = [];
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2);
+      if (BOOLEAN_FLAGS.has(key)) {
+        flags[key] = true;
+        continue;
+      }
+      const value = args[i + 1];
+      if (key === 'context' || key === 'deliverable') {
+        flags[key].push(value);
+      } else {
+        flags[key] = value;
+      }
+      i += 1;
+    } else {
+      positional.push(arg);
+    }
+  }
+  return { flags, positional };
+}
+
+function cmdInit(name) {
+  if (!name) throw new Error('session-name is required');
+  const dir = sessionDir(name);
+  fs.mkdirSync(dir, { recursive: true });
+  const meta = path.join(dir, 'session.json');
+  if (!fs.existsSync(meta)) {
+    fs.writeFileSync(meta, JSON.stringify({
+      name: slugify(name, 'session'),
+      label: name,
+      createdAt: new Date().toISOString()
+    }, null, 2) + '\n', 'utf8');
+  }
+  console.log(relPosix(dir));
+}
+
+function cmdAddWorker(session, worker, flags) {
+  if (!session || !worker) throw new Error('session and worker names are required');
+  if (!flags.agent) throw new Error('--agent is required');
+  if (!flags.objective) throw new Error('--objective is required');
+  const artifacts = createWorker({
+    sessionName: session,
+    workerName: worker,
+    agent: flags.agent,
+    objective: flags.objective,
+    context: flags.context,
+    deliverables: flags.deliverable,
+    lightweight: Boolean(flags.lightweight)
+  });
+  const out = {
+    handoff: relPosix(artifacts.handoff),
+    status: relPosix(artifacts.status)
+  };
+  if (!artifacts.lightweight) out.task = relPosix(artifacts.task);
+  if (artifacts.lightweight) out.lightweight = true;
+  console.log(JSON.stringify(out, null, 2));
+}
+
+function cmdSetStatus(session, worker, state, flags) {
+  if (!session || !worker || !state) throw new Error('session, worker, state are required');
+  const file = updateStatus(session, worker, state, flags.details || '');
+  console.log(relPosix(file));
+}
+
+function cmdAppend(session, worker, section, flags) {
+  if (!session || !worker || !section) throw new Error('session, worker, section are required');
+  if (!flags.content) throw new Error('--content is required');
+  const file = appendHandoff(session, worker, section, flags.content);
+  console.log(relPosix(file));
+}
+
+function cmdStatus(session) {
+  if (!session) throw new Error('session-name is required');
+  const dir = sessionDir(session);
+  if (!fs.existsSync(dir)) {
+    console.log(`(no such session: ${session})`);
+    return;
+  }
+  const workers = fs.readdirSync(dir, { withFileTypes: true })
+    .filter(entry => entry.isDirectory())
+    .map(entry => entry.name);
+  const out = workers.map(worker => {
+    const statusPath = workerArtifacts(session, worker).status;
+    const content = fs.existsSync(statusPath) ? fs.readFileSync(statusPath, 'utf8') : '(missing)';
+    const stateLine = content.split('\n').find(line => line.startsWith('- State:'));
+    return `${worker}\t${stateLine ? stateLine.replace('- State:', '').trim() : '?'}`;
+  });
+  console.log(out.join('\n') || '(no workers)');
+}
+
+function cmdList() {
+  if (!fs.existsSync(COORDINATION_ROOT)) {
+    console.log('(no sessions)');
+    return;
+  }
+  const sessions = fs.readdirSync(COORDINATION_ROOT, { withFileTypes: true })
+    .filter(entry => entry.isDirectory() && !entry.name.startsWith('.'))
+    .map(entry => entry.name);
+  console.log(sessions.join('\n') || '(no sessions)');
+}
+
+function main() {
+  const [, , command, ...rest] = process.argv;
+  if (!command || command === 'help' || !COMMANDS.includes(command)) {
+    usage();
+    process.exit(command && command !== 'help' ? 1 : 0);
+  }
+  const { flags, positional } = parseFlags(rest);
+  try {
+    switch (command) {
+      case 'init':
+        cmdInit(positional[0]);
+        break;
+      case 'add-worker':
+        cmdAddWorker(positional[0], positional[1], flags);
+        break;
+      case 'set-status':
+        cmdSetStatus(positional[0], positional[1], positional[2], flags);
+        break;
+      case 'append':
+        cmdAppend(positional[0], positional[1], positional[2], flags);
+        break;
+      case 'status':
+        cmdStatus(positional[0]);
+        break;
+      case 'list':
+        cmdList();
+        break;
+      default:
+        usage();
+        process.exit(1);
+    }
+  } catch (error) {
+    console.error(`error: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+main();

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** — 深入调查发现的问题