alanbox 0.1.1

package/0commondflowv1/src/commands/install.js

@@ -0,0 +1,247 @@
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+
+const INSTALL_TARGETS = new Set(['codex', 'claude', 'both']);
+
+async function runInstall(context = {}) {
+  const packageRoot = path.resolve(__dirname, '..', '..', '..');
+  const home = process.env.USERPROFILE || process.env.HOME;
+  if (!home) {
+    throw new Error('cannot resolve user home directory');
+  }
+
+  const target = await resolveInstallTarget(context.args || {});
+  const installed = [];
+
+  if (target === 'codex' || target === 'both') {
+    installed.push(installCodex({ home, packageRoot }));
+  }
+
+  if (target === 'claude' || target === 'both') {
+    installed.push(installClaude({ home, packageRoot }));
+  }
+
+  console.log('');
+  for (const result of installed) {
+    console.log(`[${result.name}]`);
+    for (const line of result.lines) {
+      console.log(`  ${line}`);
+    }
+  }
+  console.log('');
+  console.log('Restart or refresh the target agent so it can discover the installed skills.');
+}
+
+function installCodex({ home, packageRoot }) {
+  const pluginName = 'alanbox';
+  const pluginRoot = path.join(home, 'plugins', pluginName);
+  const marketplaceRoot = path.join(home, '.agents', 'plugins');
+  const marketplacePath = path.join(marketplaceRoot, 'marketplace.json');
+  const codexHome = process.env.CODEX_HOME || path.join(home, '.codex');
+  const codexSkillsRoot = path.join(codexHome, 'skills');
+  const packageSkillsRoot = path.join(packageRoot, 'skills');
+  const packageHooksRoot = path.join(packageRoot, 'hooks');
+  const packageScriptsRoot = path.join(packageRoot, 'scripts');
+  const packageMcpRoot = path.join(packageRoot, 'mcp');
+
+  replaceDir(path.join(packageRoot, 'plugin'), path.join(pluginRoot, '.codex-plugin'));
+  replaceDir(packageSkillsRoot, path.join(pluginRoot, 'skills'));
+  replaceDir(packageHooksRoot, path.join(pluginRoot, 'hooks'));
+  replaceDir(packageScriptsRoot, path.join(pluginRoot, 'scripts'));
+  replaceDir(packageMcpRoot, path.join(pluginRoot, 'mcp'));
+  copyOptionalFile(path.join(packageRoot, 'README.md'), path.join(pluginRoot, 'README.md'));
+  installSkills(packageSkillsRoot, codexSkillsRoot);
+  installResourceDir(packageHooksRoot, path.join(codexHome, 'hooks', pluginName));
+  installResourceDir(packageMcpRoot, path.join(codexHome, 'mcp', pluginName));
+  ensureMarketplace({ marketplaceRoot, marketplacePath, pluginName });
+
+  return {
+    name: 'codex',
+    lines: [
+      `plugin: ${pluginRoot}`,
+      `skills: ${codexSkillsRoot}`,
+      `hooks: ${path.join(codexHome, 'hooks', pluginName)}`,
+      `mcp: ${path.join(codexHome, 'mcp', pluginName)}`,
+      `marketplace: ${marketplacePath}`,
+    ],
+  };
+}
+
+function installClaude({ home, packageRoot }) {
+  const pluginName = 'alanbox';
+  const claudeHome = process.env.CLAUDE_HOME || path.join(home, '.claude');
+  const pluginRoot = path.join(claudeHome, 'plugins', pluginName);
+  const claudeSkillsRoot = path.join(claudeHome, 'skill');
+  const packageSkillsRoot = path.join(packageRoot, 'skills');
+  const packageHooksRoot = path.join(packageRoot, 'hooks');
+  const packageScriptsRoot = path.join(packageRoot, 'scripts');
+  const packageMcpRoot = path.join(packageRoot, 'mcp');
+
+  replaceDir(packageSkillsRoot, path.join(pluginRoot, 'skills'));
+  replaceDir(packageHooksRoot, path.join(pluginRoot, 'hooks'));
+  replaceDir(packageScriptsRoot, path.join(pluginRoot, 'scripts'));
+  replaceDir(packageMcpRoot, path.join(pluginRoot, 'mcp'));
+  copyOptionalFile(path.join(packageRoot, 'README.md'), path.join(pluginRoot, 'README.md'));
+  installSkills(packageSkillsRoot, claudeSkillsRoot);
+  installResourceDir(packageHooksRoot, path.join(claudeHome, 'hooks', pluginName));
+  installResourceDir(packageMcpRoot, path.join(claudeHome, 'mcp', pluginName));
+
+  return {
+    name: 'claude',
+    lines: [
+      `plugin resources: ${pluginRoot}`,
+      `skills: ${claudeSkillsRoot}`,
+      `hooks: ${path.join(claudeHome, 'hooks', pluginName)}`,
+      `mcp: ${path.join(claudeHome, 'mcp', pluginName)}`,
+    ],
+  };
+}
+
+async function resolveInstallTarget(args) {
+  const explicit = normalizeTarget(args.target || args.to || args.platform);
+  if (explicit) return explicit;
+
+  if (args.both) return 'both';
+  if (args.codex && args.claude) return 'both';
+  if (args.codex) return 'codex';
+  if (args.claude) return 'claude';
+
+  return promptInstallTarget();
+}
+
+function normalizeTarget(value) {
+  if (!value) return '';
+  const normalized = String(value).trim().toLowerCase();
+  if (normalized === 'all') return 'both';
+  if (!INSTALL_TARGETS.has(normalized)) {
+    throw new Error('invalid install target. Use --target codex, --target claude, or --target both.');
+  }
+  return normalized;
+}
+
+async function promptInstallTarget() {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw new Error('install target is required in non-interactive mode. Use --target codex, --target claude, or --target both.');
+  }
+
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const question = (text) => new Promise((resolve) => rl.question(text, resolve));
+
+  try {
+    for (;;) {
+      const answer = String(await question('Install alanbox to [1] Codex, [2] Claude, [3] both? (default: 3) ')).trim().toLowerCase();
+      if (!answer || answer === '3' || answer === 'both' || answer === 'b' || answer === 'all') return 'both';
+      if (answer === '1' || answer === 'codex' || answer === 'c') return 'codex';
+      if (answer === '2' || answer === 'claude' || answer === 'cl') return 'claude';
+      console.log('Please choose 1, 2, 3, codex, claude, or both.');
+    }
+  } finally {
+    rl.close();
+  }
+}
+
+function copyDir(src, dst) {
+  if (!fs.existsSync(src)) return false;
+  fs.mkdirSync(dst, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const from = path.join(src, entry.name);
+    const to = path.join(dst, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(from, to);
+    } else {
+      copyFile(from, to);
+    }
+  }
+  return true;
+}
+
+function replaceDir(src, dst) {
+  if (!fs.existsSync(src)) return false;
+  removeDir(dst);
+  return copyDir(src, dst);
+}
+
+function installResourceDir(src, dst) {
+  if (!fs.existsSync(src)) return false;
+  removeDir(dst);
+  return copyDir(src, dst);
+}
+
+function copyFile(src, dst) {
+  fs.mkdirSync(path.dirname(dst), { recursive: true });
+  fs.copyFileSync(src, dst);
+}
+
+function copyOptionalFile(src, dst) {
+  if (!fs.existsSync(src)) return false;
+  copyFile(src, dst);
+  return true;
+}
+
+function installSkills(srcRoot, dstRoot) {
+  if (!fs.existsSync(srcRoot)) return;
+  fs.mkdirSync(dstRoot, { recursive: true });
+
+  for (const entry of fs.readdirSync(srcRoot, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+
+    const srcSkill = path.join(srcRoot, entry.name);
+    const dstSkill = path.join(dstRoot, entry.name);
+    const skillFile = path.join(srcSkill, 'SKILL.md');
+    if (!fs.existsSync(skillFile)) continue;
+
+    removeDir(dstSkill);
+    copyDir(srcSkill, dstSkill);
+  }
+}
+
+function removeDir(target) {
+  if (!fs.existsSync(target)) return;
+  fs.rmSync(target, { recursive: true, force: true });
+}
+
+function ensureMarketplace({ marketplaceRoot, marketplacePath, pluginName }) {
+  fs.mkdirSync(marketplaceRoot, { recursive: true });
+  const marketplace = fs.existsSync(marketplacePath)
+    ? readJson(marketplacePath)
+    : { name: 'personal', interface: { displayName: 'Personal' }, plugins: [] };
+
+  marketplace.name = marketplace.name || 'personal';
+  marketplace.interface = marketplace.interface || { displayName: 'Personal' };
+  marketplace.plugins = Array.isArray(marketplace.plugins) ? marketplace.plugins : [];
+
+  const entry = {
+    name: pluginName,
+    source: {
+      source: 'local',
+      path: './plugins/alanbox',
+    },
+    policy: {
+      installation: 'AVAILABLE',
+      authentication: 'ON_INSTALL',
+    },
+    category: 'Productivity',
+  };
+
+  const index = marketplace.plugins.findIndex((item) => item.name === pluginName);
+  if (index >= 0) {
+    marketplace.plugins[index] = entry;
+  } else {
+    marketplace.plugins.push(entry);
+  }
+
+  fs.writeFileSync(marketplacePath, JSON.stringify(marketplace, null, 2), 'utf8');
+}
+
+function readJson(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return { name: 'personal', interface: { displayName: 'Personal' }, plugins: [] };
+  }
+}
+
+module.exports = {
+  runInstall,
+};

package/0commondflowv1/src/commands/swarm/auto.js

@@ -0,0 +1,270 @@
+/**
+ * swarm --auto 命令处理器。
+ * 根据自然语言目标生成本地 GOAP workflow，先推荐/等待确认，再复用 swarm executor 执行。
+ */
+
+const fs = require('fs');
+const readline = require('readline/promises');
+const { stdin: input, stdout: output } = require('process');
+const { buildContext } = require('../../core/prompt-builder');
+const { planWorkflow, workflowToTasks, replanWorkflow, hashPlan } = require('../../core/workflow-planner');
+const {
+  createWorkflowRun,
+  loadWorkflowRun,
+  saveRunMetadata,
+  savePlan,
+  saveState,
+  appendStep,
+  readPlan,
+  readState,
+} = require('../../core/workflow-storage');
+const { executeTaskGraph } = require('../../core/swarm-executor');
+
+async function runAutoSwarm({ args, config, cwd, timeoutMs }) {
+  const namespace = args.namespace || config.defaultNamespace;
+  const maxReplans = args['max-replans'] === undefined ? 1 : Number(args['max-replans']);
+
+  if (args.resume) {
+    await resumeWorkflow({ args, config, cwd, timeoutMs, namespace, maxReplans });
+    return;
+  }
+
+  const goal = args._.join(' ').trim();
+  if (!goal) {
+    throw new Error('missing auto goal. Example: alanbox swarm --auto "帮我检查项目" -a "codex:reviewer:复核代码"');
+  }
+
+  const run = createWorkflowRun({ namespace, goal, cwd });
+  const workflow = planWorkflow({
+    goal,
+    cwd,
+    namespace,
+    agentSpecs: args.agent || [],
+    planHint: args.planHint || '',
+    config,
+  });
+
+  const approved = await ensureApproved({ args, run, workflow, status: 'awaiting_confirmation' });
+  if (!approved) return;
+
+  await executeWorkflow({ args, config, cwd, timeoutMs, run, workflow, maxReplans });
+}
+
+async function resumeWorkflow({ args, config, cwd, timeoutMs, namespace, maxReplans }) {
+  const run = loadWorkflowRun(namespace, args.resume);
+  const workflow = readPlan(run);
+  const state = readState(run);
+  const actualHash = hashPlan(workflow);
+  if (workflow.planHash && workflow.planHash !== actualHash) {
+    throw new Error(`plan hash mismatch for ${run.runId}; refuse to resume a modified plan`);
+  }
+
+  const approved = await ensureApproved({ args, run, workflow, status: state.status || 'awaiting_confirmation', resumed: true });
+  if (!approved) return;
+
+  await executeWorkflow({ args, config, cwd: run.cwd || cwd, timeoutMs, run, workflow, maxReplans });
+}
+
+async function ensureApproved({ args, run, workflow, status, resumed = false }) {
+  savePendingRun({ run, workflow, status, resumed });
+
+  if (args.y) {
+    appendStep(run, { type: 'approval', result: 'approved', source: '-y' });
+    saveState(run, { status: 'approved', approved: true, planHash: workflow.planHash });
+    saveRunMetadata(run, { status: 'approved', planHash: workflow.planHash });
+    return true;
+  }
+
+  if (!isInteractive()) {
+    appendStep(run, { type: 'approval_required', reason: 'non_interactive' });
+    writePlanSummary({ run, workflow, status: 'awaiting_confirmation', stream: process.stderr });
+    process.exitCode = 2;
+    return false;
+  }
+
+  writePlanSummary({ run, workflow, status: resumed ? 'resume_waiting_confirmation' : 'awaiting_confirmation', stream: process.stdout });
+  const rl = readline.createInterface({ input, output });
+  try {
+    const answer = (await rl.question('输入 yes/approve 执行 workflow，其他输入取消：')).trim().toLowerCase();
+    if (!['yes', 'y', 'approve', 'approved'].includes(answer)) {
+      appendStep(run, { type: 'approval', result: 'denied', answer });
+      saveState(run, { status: 'cancelled', approved: false, planHash: workflow.planHash });
+      saveRunMetadata(run, { status: 'cancelled', planHash: workflow.planHash });
+      process.exitCode = 2;
+      return false;
+    }
+  } finally {
+    rl.close();
+  }
+
+  appendStep(run, { type: 'approval', result: 'approved', source: 'tty' });
+  saveState(run, { status: 'approved', approved: true, planHash: workflow.planHash });
+  saveRunMetadata(run, { status: 'approved', planHash: workflow.planHash });
+  return true;
+}
+
+function savePendingRun({ run, workflow, status, resumed }) {
+  savePlan(run, workflow);
+  saveState(run, {
+    status,
+    approved: false,
+    planHash: workflow.planHash,
+    worldState: workflow.worldState,
+    resumeCommand: `alanbox swarm --resume ${run.runId} --namespace ${run.namespace} -y`,
+  });
+  saveRunMetadata(run, { status, planHash: workflow.planHash });
+  appendStep(run, { type: resumed ? 'resume_plan_loaded' : 'plan_created', status, planHash: workflow.planHash });
+}
+
+async function executeWorkflow({ args, config, cwd, timeoutMs, run, workflow, maxReplans }) {
+  const injected = buildContext({
+    context: args.context,
+    contextFile: args['context-file'],
+    skillFile: args['skill-file'],
+    cwd: process.cwd(),
+  });
+  const tasks = workflowToTasks(workflow, run.namespace);
+  appendStep(run, { type: 'execution_started', actionIds: tasks.map((task) => task.id) });
+  saveState(run, {
+    status: 'running',
+    approved: true,
+    planHash: workflow.planHash,
+    worldState: { ...workflow.worldState, approved: true },
+  });
+  saveRunMetadata(run, { status: 'running', planHash: workflow.planHash });
+
+  const result = await executeTaskGraph({
+    args: { ...args, 'parallel-workers': true },
+    config,
+    cwd,
+    timeoutMs,
+    tasks,
+    namespace: run.namespace,
+    runDir: run.runDir,
+    resultDir: run.resultDir,
+    memoryDir: run.memoryDir,
+    injected,
+    failOnHandoffStatus: true,
+    onTaskStart: (task) => appendStep(run, { type: 'action_started', actionId: task.id, beforeState: workflow.worldState }),
+    onTaskFinish: (task, entry) => appendStep(run, {
+      type: 'action_finished',
+      actionId: task?.id,
+      ok: entry.ok,
+      code: entry.code,
+      error: entry.error,
+      handoffStatus: entry.handoff?.status,
+      outputPath: entry.outputPath,
+    }),
+  });
+
+  if (result.success) {
+    saveState(run, {
+      status: 'completed',
+      approved: true,
+      planHash: workflow.planHash,
+      result,
+      worldState: { ...workflow.worldState, executedActions: tasks.map((task) => task.id), goalVerified: true },
+    });
+    saveRunMetadata(run, { status: 'completed', planHash: workflow.planHash });
+    emitExecutionResult(args, run, workflow, result);
+    return;
+  }
+
+  const failures = result.results
+    .filter((item) => !item.ok)
+    .map((item) => ({ id: item.id, error: item.error || item.handoff?.summary || `exit ${item.code}` }));
+  appendStep(run, { type: 'execution_failed', failures });
+
+  if (maxReplans > 0) {
+    const replanned = replanWorkflow({
+      workflow,
+      failures,
+      cwd,
+      namespace: run.namespace,
+      config,
+      planHint: args.planHint || '',
+    });
+    savePlan(run, replanned);
+    saveState(run, {
+      status: 'awaiting_confirmation',
+      approved: false,
+      planHash: replanned.planHash,
+      previousPlanHash: workflow.planHash,
+      failures,
+      replanRemaining: maxReplans - 1,
+    });
+    saveRunMetadata(run, { status: 'awaiting_confirmation', planHash: replanned.planHash });
+    appendStep(run, { type: 'replan_created', previousPlanHash: workflow.planHash, planHash: replanned.planHash });
+    if (args.y && isRetryOnly(workflow, replanned)) {
+      await executeWorkflow({ args: { ...args, y: true }, config, cwd, timeoutMs, run, workflow: replanned, maxReplans: maxReplans - 1 });
+      return;
+    }
+    writePlanSummary({ run, workflow: replanned, status: 'awaiting_confirmation', stream: process.stderr });
+    process.exitCode = 2;
+    return;
+  }
+
+  saveState(run, {
+    status: 'failed',
+    approved: true,
+    planHash: workflow.planHash,
+    failures,
+    result,
+  });
+  saveRunMetadata(run, { status: 'failed', planHash: workflow.planHash });
+  emitExecutionResult(args, run, workflow, result);
+  process.exitCode = 1;
+}
+
+function isRetryOnly(previous, next) {
+  const previousTargets = new Set(previous.actions.map((action) => `${action.type}:${action.target || ''}:${action.provider || 'codex'}`));
+  return next.actions
+    .filter((action) => action.type === 'review')
+    .every((action) => previousTargets.has(`${action.type}:${action.target || ''}:${action.provider || 'codex'}`));
+}
+
+function emitExecutionResult(args, run, workflow, result) {
+  const stream = result.success ? process.stdout : process.stderr;
+  stream.write(`\n[auto-swarm] ${result.success ? 'completed' : 'failed'}\n`);
+  stream.write(`runId: ${run.runId}\n`);
+  stream.write(`runDir: ${run.runDir}\n`);
+  if (result.errors.length) {
+    stream.write(`errors:\n${result.errors.map((item) => `- ${item}`).join('\n')}\n`);
+  }
+}
+
+function writePlanSummary({ run, workflow, status, stream }) {
+  const lines = [
+    '',
+    `# auto workflow 推荐 (${status})`,
+    '',
+    `runId: ${run.runId}`,
+    `runDir: ${run.runDir}`,
+    `目标: ${workflow.goal}`,
+    workflow.planHint ? `补充描述: ${workflow.planHint}` : '',
+    '',
+    '## Action 顺序',
+    ...workflow.phases.map((phase) => {
+      const actionText = phase.actionIds.join(', ');
+      return `- ${phase.title}${phase.parallel ? '（并行）' : ''}: ${actionText}`;
+    }),
+    '',
+    '## 预期 WorldState 变化',
+    ...workflow.expectedWorldStateChanges.map((item) => `- ${item}`),
+    '',
+    '## 风险',
+    ...workflow.risks.map((item) => `- ${item}`),
+    '',
+    `确认执行: alanbox swarm --resume ${run.runId} --namespace ${run.namespace} -y`,
+    '',
+  ].filter((line) => line !== '');
+  stream.write(`${lines.join('\n')}\n`);
+}
+
+function isInteractive() {
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+
+module.exports = {
+  runAutoSwarm,
+};

package/0commondflowv1/src/commands/swarm/custom.js

@@ -0,0 +1,60 @@
+/**
+ * 手动 swarm 命令处理器。
+ * 规划并运行多个 provider worker（Codex / Claude / 已配置 worker），支持默认串行交接与并行执行。
+ *
+ * Worker 规格通过 --worker（或兼容别名 --task）传入，可重复多次：
+ *   "<platform-or-worker>:<role>:<prompt>"
+ */
+
+const path = require('path');
+const { buildContext } = require('../../core/prompt-builder');
+const { parseWorkerSpecs } = require('../../core/workers');
+const { resolveRunDir } = require('../../core/storage');
+const { executeTaskGraph } = require('../../core/swarm-executor');
+
+async function runCustomSwarm({ args, config, cwd, timeoutMs }) {
+  const specs = args.task || [];
+  if (specs.length === 0) {
+    throw new Error('missing --worker. Example: node index.js swarm --worker "codex-e7:lead:..." --worker "codex-19b:reviewer:..."');
+  }
+
+  const injected = buildContext({
+    context: args.context || args._.join(' ').trim(),
+    contextFile: args['context-file'],
+    skillFile: args['skill-file'],
+    cwd: process.cwd(),
+  });
+  const namespace = args.namespace || config.defaultNamespace;
+  const runDir = resolveRunDir(namespace);
+  const resultDir = path.join(runDir, 'results');
+  const memoryDir = path.join(runDir, 'memory');
+  const tasks = parseWorkerSpecs(specs, Boolean(args['parallel-workers'] || args.parallel), config)
+    .map((task) => ({ ...task, namespace }));
+
+  const result = await executeTaskGraph({
+    args,
+    config,
+    cwd,
+    timeoutMs,
+    tasks,
+    namespace,
+    runDir,
+    resultDir,
+    memoryDir,
+    injected,
+  });
+
+  for (const item of result.results) {
+    if (item.error) {
+      console.error(`[swarm][问题] ${item.error}`);
+    }
+  }
+
+  if (result.errors.length > 0) {
+    process.exitCode = 1;
+  }
+}
+
+module.exports = {
+  runCustomSwarm,
+};

package/0commondflowv1/src/commands/swarm/index.js

@@ -0,0 +1,20 @@
+/**
+ * swarm 命令入口与路由。
+ * `--auto` / `--resume` 委托 auto workflow（auto.js），否则走手动 worker 编排（custom.js）。
+ */
+
+const { runAutoSwarm } = require('./auto');
+const { runCustomSwarm } = require('./custom');
+
+async function runSwarm({ args, config, cwd, timeoutMs }) {
+  if (args.auto || args.resume) {
+    await runAutoSwarm({ args, config, cwd, timeoutMs });
+    return;
+  }
+
+  await runCustomSwarm({ args, config, cwd, timeoutMs });
+}
+
+module.exports = {
+  runSwarm,
+};

package/0commondflowv1/src/core/AGENTS.md

@@ -0,0 +1,31 @@
+## core
+
+`0commondflowv1/src/core` 存放 worker 编排协议、handoff 协议、prompt 构造和本地结果存储辅助函数，是 `swarm` 使用的核心逻辑。
+
+**Important:** 这里的输出格式、prompt 协议和路径会被命令、skills、README 和用户历史 run 依赖。改协议或存储结构前，要考虑旧结果读取兼容，并同步更新说明文档。
+
+### Important files
+
+- `workers.js` — 解析 worker spec、解析 `--worker "[spec1,spec2]"` 并行阶段、归一化 worker 名称、构建依赖层。
+- `swarm-executor.js` — 普通 swarm 和 auto workflow 共用的 task graph 执行器；负责 runner 调用、结果写入和 handoff 汇总，`swarm --parallel-workers` 也走这里。
+- `workflow-planner.js` — 本地最小 GOAP planner；把自然语言目标、`-a` agent spec 和 `-p` plan hint 转成 phases/actions/dependencies。
+- `workflow-storage.js` — auto workflow 的 AgentDB-lite 文件存储；写入 run/plan/state/steps JSON，不替代旧 swarm results/memory。
+- `prompt-templates.js` — 从 `0commondflowv1/src/prompt/<role>.md` 读取 auto workflow role 模板并安全 fallback。
+- `handoff.js` — 构造 prior results context，并解析 / 生成 `HANDOFF_JSON`。
+- `prompt-builder.js` — 构造 role、worker、platform、namespace、context、skill 和 task 的最终 prompt。
+- `storage.js` — 写入 worker markdown 输出和 memory JSON；默认根目录是 `%USERPROFILE%\.multirunagent`。
+
+### Implementation notes
+
+- worker spec 应兼容 `codex:role:prompt`、`claude:role:prompt` 和未来 worker 名称形式；普通 swarm 的 `--worker "[spec1,spec2]"` 表示同一阶段并行，阶段之间仍按依赖顺序串行。
+- `HANDOFF_JSON` 稳定字段要保持兼容：`status`、`summary`、`files`、`findings`、`nextSteps`、`artifacts`；`verification` 是可选扩展字段，缺失时不得破坏旧 worker 输出。
+- 子 worker 最终 prompt 协议和 `core/handoff.js` 必须同步维护；artifact 示例应指向 `%USERPROFILE%\.multirunagent\<namespace>`。
+- auto workflow 启用 `failOnHandoffStatus` 时必须要求有效解析到 `HANDOFF_JSON` 且 status 为 `completed`；缺失结构化 handoff 不能被 fallback 误判为成功。
+- 路径片段必须经过清洗，避免 namespace、worker、role、runId 或模板 role 中的特殊字符写出预期目录。
+- 不要把用户级结果存储改回项目内 `.sub-codex`；旧 `.sub-codex` 只作为历史位置看待。
+- auto workflow 没有 dry-run 预览；非交互（无 TTY）且未 `-y` 的真实 auto 请求会保存 pending run 并返回退出码 2，等待 `swarm --resume <runId> --namespace <ns> -y`。
+
+### Verification
+
+- 从包根目录运行：`npm run validate`
+- 存储路径或 prompt 改动后，需实际运行一次 swarm（已无 dry-run 预览）并检查 `%USERPROFILE%\.multirunagent\<namespace>` 下的 `runDir`、`memoryDir` 和注入 prompt。