aigroup-workflow 1.3.0 → 2.0.0

package/scripts/hooks/checks/empty-docs.cjs

@@ -0,0 +1,32 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { createReport, ROOT, relPosix } = require('../lib/runner.cjs');
+
+const MIN_BYTES = 50;
+
+function run() {
+  const report = createReport();
+  const docsDir = path.join(ROOT, 'docs');
+  let entries;
+  try {
+    entries = fs.readdirSync(docsDir, { withFileTypes: true });
+  } catch (_error) {
+    return report;
+  }
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
+    const full = path.join(docsDir, entry.name);
+    const size = fs.statSync(full).size;
+    if (size < MIN_BYTES) {
+      report.fail(
+        `${relPosix(full)} 内容过少（${size} bytes）`,
+        '文档不应为空壳，请补充实质内容或删除'
+      );
+    }
+  }
+  return report;
+}
+
+module.exports = { run, section: 'docs 空壳检查' };

package/scripts/hooks/checks/orchestration-artifacts.cjs

@@ -0,0 +1,65 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { createReport, ROOT, relPosix, dirExists } = require('../lib/runner.cjs');
+
+const COORD_ROOT = path.join(ROOT, '.orchestration');
+const STAGE1_RE = /(stage.?1|阶段.?1|规格符合)/i;
+const STAGE2_RE = /(stage.?2|阶段.?2|代码质量)/i;
+
+function run() {
+  const report = createReport();
+  if (!dirExists('.orchestration')) return report;
+
+  const sessions = fs.readdirSync(COORD_ROOT, { withFileTypes: true })
+    .filter(entry => entry.isDirectory() && !entry.name.startsWith('.'));
+
+  for (const session of sessions) {
+    const sessionDir = path.join(COORD_ROOT, session.name);
+    const workers = fs.readdirSync(sessionDir, { withFileTypes: true })
+      .filter(entry => entry.isDirectory());
+
+    for (const worker of workers) {
+      const workerDir = path.join(sessionDir, worker.name);
+      const statusFile = path.join(workerDir, 'status.md');
+
+      // 轻量 worker：只要求 handoff + status，跳过 task.md
+      let lightweight = false;
+      try {
+        const raw = fs.readFileSync(statusFile, 'utf8');
+        lightweight = /^\s*-\s*Lightweight:\s*true/m.test(raw);
+      } catch (_error) { /* fall through */ }
+
+      const required = lightweight
+        ? ['handoff.md', 'status.md']
+        : ['task.md', 'handoff.md', 'status.md'];
+
+      for (const file of required) {
+        const full = path.join(workerDir, file);
+        if (!fs.existsSync(full)) {
+          report.fail(
+            `${relPosix(workerDir)}/ 缺失 ${file}${lightweight ? '（轻量 worker）' : ''}`,
+            '用 node scripts/orchestration/session.cjs add-worker 创建（轻量加 --lightweight）'
+          );
+        }
+      }
+
+      if (worker.name === 'code-reviewer') {
+        const handoff = path.join(workerDir, 'handoff.md');
+        if (fs.existsSync(handoff)) {
+          const content = fs.readFileSync(handoff, 'utf8');
+          if (!STAGE1_RE.test(content) && !STAGE2_RE.test(content)) {
+            report.fail(
+              `${relPosix(handoff)} 缺少阶段标识`,
+              '审查报告必须含 Stage 1 (规格符合性) 和 Stage 2 (代码质量)'
+            );
+          }
+        }
+      }
+    }
+  }
+  return report;
+}
+
+module.exports = { run, section: 'Orchestration 产物检查' };

package/scripts/hooks/checks/structure.cjs

@@ -0,0 +1,23 @@
+'use strict';
+
+const { createReport, dirExists } = require('../lib/runner.cjs');
+
+const REQUIRED_DIRS = [
+  { path: '.orchestration', hint: 'mkdir -p .orchestration' },
+  { path: '.orchestration/.logs', hint: 'mkdir -p .orchestration/.logs' },
+  { path: '.claude/agents', hint: 'agent 定义根' },
+  { path: 'skills', hint: 'skill 根（扁平结构）' },
+  { path: 'docs/rules', hint: '强制规则集' }
+];
+
+function run() {
+  const report = createReport();
+  for (const entry of REQUIRED_DIRS) {
+    if (!dirExists(entry.path)) {
+      report.fail(`缺失目录 ${entry.path}/`, entry.hint);
+    }
+  }
+  return report;
+}
+
+module.exports = { run, section: '基础结构检查' };

package/scripts/hooks/checks/workflow-state.cjs

@@ -0,0 +1,56 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { createReport, ROOT, relPosix, dirExists } = require('../lib/runner.cjs');
+
+// 真相源：.orchestration/<session>/<worker>/status.md
+// 在 Stop 事件中：若任一 worker state=running，说明主会话要停但 worker 没走到终态。
+// 终态：completed | failed | blocked （完成、失败、主动阻塞都允许 Stop）
+
+const TERMINAL_STATES = new Set(['completed', 'failed', 'blocked']);
+
+function readState(statusFile) {
+  try {
+    const content = fs.readFileSync(statusFile, 'utf8');
+    const match = content.match(/^\s*-\s*State:\s*(\S+)/m);
+    return match ? match[1].toLowerCase() : null;
+  } catch (_error) {
+    return null;
+  }
+}
+
+function run() {
+  const report = createReport();
+  if (!dirExists('.orchestration')) return report;
+
+  const coordRoot = path.join(ROOT, '.orchestration');
+  const sessions = fs.readdirSync(coordRoot, { withFileTypes: true })
+    .filter(entry => entry.isDirectory() && !entry.name.startsWith('.'));
+
+  const stuck = [];
+  for (const session of sessions) {
+    const sessionDir = path.join(coordRoot, session.name);
+    const workers = fs.readdirSync(sessionDir, { withFileTypes: true })
+      .filter(entry => entry.isDirectory());
+
+    for (const worker of workers) {
+      const statusFile = path.join(sessionDir, worker.name, 'status.md');
+      const state = readState(statusFile);
+      if (state === 'running') {
+        stuck.push(relPosix(statusFile));
+      }
+    }
+  }
+
+  if (stuck.length > 0) {
+    report.fail(
+      `以下 worker 仍在 running：${stuck.join(', ')}`,
+      '完成 worker 后运行 `node scripts/orchestration/session.cjs set-status <session> <worker> completed`；主动放弃用 `failed` 或 `blocked`'
+    );
+  }
+
+  return report;
+}
+
+module.exports = { run, section: '工作流 worker 状态检查' };

package/scripts/hooks/dispatcher.cjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+'use strict';
+
+// Hook dispatcher —— 按事件类型路由到对应 checks。
+// 每个 check 模块必须导出 { run(): Report, section: string }。
+// 任一 FAIL → exit 2（错误回注 Claude 上下文）；仅 WARN → exit 0。
+
+const { readJsonStdinSync } = require('./lib/runner.cjs');
+
+const DISPATCH = {
+  'post-edit': [
+    require('./checks/claude-md-size.cjs'),
+    require('./checks/empty-docs.cjs')
+  ],
+  stop: [
+    require('./checks/structure.cjs'),
+    require('./checks/claude-md-size.cjs'),
+    require('./checks/empty-docs.cjs'),
+    require('./checks/delegation-antipatterns.cjs'),
+    require('./checks/workflow-state.cjs'),
+    require('./checks/orchestration-artifacts.cjs')
+  ],
+  'subagent-stop': [
+    require('./checks/structure.cjs'),
+    require('./checks/orchestration-artifacts.cjs')
+  ]
+};
+
+function main() {
+  const [, , event] = process.argv;
+  const checks = DISPATCH[event];
+  if (!checks) {
+    console.error(`unknown event: ${event}`);
+    process.exit(1);
+  }
+
+  readJsonStdinSync();
+
+  const sections = [];
+  let hasFail = false;
+  for (const check of checks) {
+    const report = check.run();
+    if (!report.hasAny()) continue;
+    sections.push(report.render(check.section));
+    if (report.hasFail()) hasFail = true;
+  }
+
+  if (sections.length === 0) process.exit(0);
+
+  const output = sections.join('\n\n');
+  if (hasFail) {
+    console.error('Harness 检测到问题：');
+    console.error('');
+    console.error(output);
+    console.error('');
+    console.error('修复上述 [FAIL] 项后重试。');
+    process.exit(2);
+  }
+
+  console.log(output);
+  process.exit(0);
+}
+
+main();

package/scripts/hooks/lib/runner.cjs

@@ -0,0 +1,81 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.resolve(__dirname, '..', '..', '..');
+
+function readJsonStdinSync() {
+  try {
+    const raw = fs.readFileSync(0, 'utf8');
+    if (!raw.trim()) return {};
+    return JSON.parse(raw);
+  } catch (_error) {
+    return {};
+  }
+}
+
+function createReport() {
+  const issues = [];
+  return {
+    fail(msg, fix) {
+      issues.push({ level: 'FAIL', msg, fix });
+    },
+    warn(msg, fix) {
+      issues.push({ level: 'WARN', msg, fix });
+    },
+    hasFail() {
+      return issues.some(i => i.level === 'FAIL');
+    },
+    hasAny() {
+      return issues.length > 0;
+    },
+    render(section) {
+      if (issues.length === 0) return '';
+      const lines = [`--- ${section} ---`];
+      for (const i of issues) {
+        lines.push(`[${i.level}] ${i.msg}`);
+        if (i.fix) lines.push(`[FIX] ${i.fix}`);
+      }
+      return lines.join('\n');
+    }
+  };
+}
+
+function relPosix(p) {
+  return path.relative(ROOT, p).split(path.sep).join('/');
+}
+
+function fileExists(p) {
+  try {
+    return fs.statSync(path.resolve(ROOT, p)).isFile();
+  } catch (_error) {
+    return false;
+  }
+}
+
+function dirExists(p) {
+  try {
+    return fs.statSync(path.resolve(ROOT, p)).isDirectory();
+  } catch (_error) {
+    return false;
+  }
+}
+
+function readFileSafe(p) {
+  try {
+    return fs.readFileSync(path.resolve(ROOT, p), 'utf8');
+  } catch (_error) {
+    return null;
+  }
+}
+
+module.exports = {
+  ROOT,
+  readJsonStdinSync,
+  createReport,
+  relPosix,
+  fileExists,
+  dirExists,
+  readFileSafe
+};

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();