@shirlytaylor73/superharness 1.5.0

package/plugins/superharness/hooks/workflow-stop.mjs

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+async function readStdinJson() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  const raw = Buffer.concat(chunks).toString('utf8').trim();
+  return raw ? JSON.parse(raw) : {};
+}
+
+function resolvePluginRoot() {
+  return path.resolve(
+    process.env.CLAUDE_PLUGIN_ROOT
+      || process.env.CODEX_PLUGIN_ROOT
+      || process.env.PLUGIN_ROOT
+      || path.join(__dirname, '..'),
+  );
+}
+
+function loadInstalledSkills(pluginRoot) {
+  const skillsDir = path.join(pluginRoot, 'skills');
+  if (!fs.existsSync(skillsDir)) return new Set();
+  return new Set(
+    fs.readdirSync(skillsDir, { withFileTypes: true })
+      .filter((e) => e.isDirectory())
+      .filter((e) => fs.existsSync(path.join(skillsDir, e.name, 'SKILL.md')))
+      .map((e) => e.name),
+  );
+}
+
+const MAX_BLOCKS = 3;
+
+function blockReason({ state, allowedTransitions }) {
+  return [
+    `[Superharness Workflow] 本轮检测到未完成的状态切换。`,
+    ``,
+    `- 当前 state: ${state}`,
+    `- 该 state 要求 agent 在每轮结束前显式调用 transition_state`,
+    ``,
+    `请用 AskUserQuestion 让用户在以下类别的选项中决定本轮去向：`,
+    ``,
+    `1. **继续/调整工作方向** — 1~2 个选项（agent 根据本轮上下文拟）。用户选了 → 继续干。`,
+    `2. **切到允许的下一态** — 列出 [${allowedTransitions.join(', ')}] 里合适的目标。用户选了 → 调 transition_state。`,
+    `3. **终止本轮，让用户先看结果** — 用户选了 → 调 release_stop_block(reason="<原话>") 然后结束输出。`,
+    ``,
+    `(AskUserQuestion 工具会自动提供 "Other" 开放输入。)`,
+  ].join('\n');
+}
+
+export async function main() {
+  let store;
+  try {
+    const input = await readStdinJson();
+    const workspaceRoot = path.resolve(input.cwd || process.cwd());
+    const pluginRoot = resolvePluginRoot();
+    const workflowStateDir = path.join(pluginRoot, 'workflow-state-server');
+
+    // Free-mode check: skip stop-block entirely
+    const { isFreeMode } = await import(pathToFileURL(path.join(pluginRoot, 'hooks', 'lib', 'free-mode-check.mjs')).href);
+    if (await isFreeMode({ pluginRoot, workspaceRoot })) {
+      process.stdout.write(JSON.stringify({}) + '\n');
+      return;
+    }
+
+    const { loadWorkflowConfig, buildWorkflowGraph } = await import(pathToFileURL(path.join(workflowStateDir, 'validate-workflow.js')).href);
+    const { openWorkflowStateStore, getWorkflowState, getTurn, incrementBlockCount, resolveWorkflowDbPath } =
+      await import(pathToFileURL(path.join(workflowStateDir, 'state.js')).href);
+
+    const config = loadWorkflowConfig({ pluginRoot, workspaceRoot });
+    const installedSkills = loadInstalledSkills(pluginRoot);
+    const graph = buildWorkflowGraph(config, { installedSkills });
+
+    store = openWorkflowStateStore({
+      mode: process.env.SUPERHARNESS_WORKFLOW_STATE_MODE,
+      dbPath: process.env.SUPERHARNESS_WORKFLOW_STATE_DB || resolveWorkflowDbPath({ workspaceRoot }),
+    });
+
+    const stateInfo = getWorkflowState(store, { workspaceRoot, workflowGraph: graph });
+    const turn = getTurn(store, { workspaceRoot });
+
+    if (!turn) {
+      process.stdout.write(JSON.stringify({}) + '\n');
+      return;
+    }
+
+    // 1. 本轮 turn_id 内有 source='agent-tool' 的 transition → 放行
+    const hasTransition = store.db.prepare(
+      "SELECT 1 FROM workflow_transition_log WHERE turn_id = ? AND source = 'agent-tool' LIMIT 1"
+    ).get(turn.turn_id);
+    if (hasTransition) {
+      process.stdout.write(JSON.stringify({}) + '\n');
+      return;
+    }
+
+    // 2. 用户已授权 escape → 放行
+    if (turn.stop_block_released === 1) {
+      process.stdout.write(JSON.stringify({}) + '\n');
+      return;
+    }
+
+    // 3. silent_stop_allowed=true → 放行
+    const stateNode = graph.states.get(stateInfo.state);
+    if (stateNode?.silent_stop_allowed) {
+      process.stdout.write(JSON.stringify({}) + '\n');
+      return;
+    }
+
+    // 4. block_count < 3 → 拦截
+    if (turn.block_count < MAX_BLOCKS) {
+      incrementBlockCount(store, { workspaceRoot });
+      const reason = blockReason({
+        state: stateInfo.state,
+        allowedTransitions: stateNode?.next ?? [],
+      });
+      process.stdout.write(JSON.stringify({ decision: 'block', reason }) + '\n');
+      return;
+    }
+
+    // 5. block_count >= 3 → 兜底逃生
+    console.error(`[superharness-stop] escape after ${MAX_BLOCKS} blocks: ws=${workspaceRoot} state=${stateInfo.state}`);
+    process.stdout.write(JSON.stringify({}) + '\n');
+  } catch {
+    // fail-open
+    process.stdout.write(JSON.stringify({}) + '\n');
+  } finally {
+    store?.close?.();
+  }
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  await main();
+}

package/plugins/superharness/scripts/rollback.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import fs from 'node:fs';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const [, , workspaceRootArg, toStateArg, reasonArg] = process.argv;
+
+if (!workspaceRootArg || !toStateArg || !reasonArg) {
+  console.error('usage: rollback.mjs <workspaceRoot> <to_state> <reason>');
+  process.exit(1);
+}
+
+const workspaceRoot = path.resolve(workspaceRootArg);
+const dbPath = path.join(workspaceRoot, '.superharness', 'workflow-state.db');
+
+if (!fs.existsSync(dbPath)) {
+  console.error('workspace 未初始化，无 state 可回退');
+  process.exit(1);
+}
+
+if (toStateArg === 'systematic_debugging') {
+  console.error('rollback 不支持目标 systematic_debugging（systematic_debugging 是 preemptive 分支，需 previous_state 字段；rollback 只回主流程态）');
+  process.exit(1);
+}
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const pluginRoot = path.resolve(scriptDir, '..');
+const stateModule = await import(pathToFileURL(path.join(pluginRoot, 'workflow-state-server', 'state.js')).href);
+const validateModule = await import(pathToFileURL(path.join(pluginRoot, 'workflow-state-server', 'validate-workflow.js')).href);
+
+const store = stateModule.openWorkflowStateStore({ dbPath });
+
+try {
+  // 1. 校验 to_state 是否在历史中曾以 to_state 出现过
+  const seen = store.prepare(
+    'SELECT 1 FROM workflow_transition_log WHERE workspace_id = ? AND to_state = ? LIMIT 1'
+  ).get(workspaceRoot, toStateArg);
+  if (!seen) {
+    const choices = store.prepare(
+      'SELECT DISTINCT to_state FROM workflow_transition_log WHERE workspace_id = ? ORDER BY id DESC LIMIT 10'
+    ).all(workspaceRoot).map((r) => r.to_state);
+    console.error(`state '${toStateArg}' 未在历史中出现过；可用：${choices.join(', ')}`);
+    process.exit(1);
+  }
+
+  // 2. 取当前 state 用于 stdout 和 log
+  const cur = store.prepare('SELECT state FROM workflow_state WHERE workspace_id = ?').get(workspaceRoot);
+  const fromState = cur?.state ?? null;
+
+  // 3. 加载 workflow graph 解析目标 state 的 active_skill
+  const skillsDir = path.join(pluginRoot, 'skills');
+  const installedSkills = new Set(
+    fs.readdirSync(skillsDir, { withFileTypes: true })
+      .filter((e) => e.isDirectory())
+      .map((e) => e.name),
+  );
+  const config = validateModule.loadWorkflowConfig({ pluginRoot, workspaceRoot });
+  const graph = validateModule.buildWorkflowGraph(config, { installedSkills });
+  const activeSkill = graph.states.get(toStateArg)?.skill ?? null;
+
+  const now = Date.now();
+
+  // 4. 写 workflow_state
+  store.prepare(`
+    UPDATE workflow_state
+       SET state = ?, status = 'active', previous_state = NULL, active_skill = ?, updated_at = ?
+     WHERE workspace_id = ?
+  `).run(toStateArg, activeSkill, now, workspaceRoot);
+
+  // 5. 写 transition_log（source = user-reset）
+  store.prepare(`
+    INSERT INTO workflow_transition_log
+      (workspace_id, from_state, to_state, previous_state, reason, source, turn_id, created_at)
+    VALUES (?, ?, ?, NULL, ?, 'user-reset', NULL, ?)
+  `).run(workspaceRoot, fromState, toStateArg, reasonArg, now);
+
+  // 6. 清零 turn 状态
+  //    注意：workflow_turn.turn_id 是 NOT NULL，不能 SET turn_id = NULL，所以 DELETE。
+  //    下一次 UserPromptSubmit 时 createTurn 会重新 INSERT OR REPLACE。
+  store.prepare('DELETE FROM workflow_turn WHERE workspace_id = ?').run(workspaceRoot);
+
+  console.log(`已从 ${fromState} 回到 ${toStateArg}`);
+  process.exit(0);
+} finally {
+  store.close();
+}

package/plugins/superharness/scripts/set-free-mode.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import fs from 'node:fs';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const [, , workspaceRootArg, actionArg] = process.argv;
+const action = actionArg || 'status';
+
+if (!workspaceRootArg || !['on', 'off', 'status'].includes(action)) {
+  console.error('usage: set-free-mode.mjs <workspaceRoot> [on|off|status]');
+  process.exit(1);
+}
+
+const workspaceRoot = path.resolve(workspaceRootArg);
+const dbPath = path.join(workspaceRoot, '.superharness', 'workflow-state.db');
+
+if (!fs.existsSync(dbPath)) {
+  console.error('workspace 未初始化');
+  process.exit(1);
+}
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const pluginRoot = path.resolve(__dirname, '..');
+const stateModule = await import(pathToFileURL(path.join(pluginRoot, 'workflow-state-server', 'state.js')).href);
+
+const store = stateModule.openWorkflowStateStore({ dbPath });
+
+try {
+  const cur = store.prepare('SELECT state, free_mode, free_started_at FROM workflow_state WHERE workspace_id = ?').get(workspaceRoot);
+  if (!cur) {
+    console.error('workspace state 不存在');
+    process.exit(1);
+  }
+
+  if (action === 'status') {
+    if (cur.free_mode === 1) {
+      console.log(`当前在 free mode（自 ${new Date(cur.free_started_at).toISOString()}）`);
+    } else {
+      console.log('当前不在 free mode');
+    }
+    process.exit(0);
+  }
+
+  if (action === 'on') {
+    if (cur.free_mode === 1) {
+      console.log(`已在 free mode（自 ${new Date(cur.free_started_at).toISOString()}）`);
+      process.exit(0);
+    }
+    const now = Date.now();
+    store.prepare(`UPDATE workflow_state SET free_mode = 1, free_started_at = ?, updated_at = ? WHERE workspace_id = ?`).run(now, now, workspaceRoot);
+    store.prepare(`
+      INSERT INTO workflow_transition_log
+        (workspace_id, from_state, to_state, previous_state, reason, source, turn_id, created_at)
+      VALUES (?, ?, ?, NULL, '[free-on] 用户输入 /free on', 'user-reset', NULL, ?)
+    `).run(workspaceRoot, cur.state, cur.state, now);
+    console.log('已进入 free mode；workflow context 注入已暂停');
+    process.exit(0);
+  }
+
+  if (action === 'off') {
+    if (cur.free_mode === 0) {
+      console.log('未在 free mode，无需操作');
+      process.exit(0);
+    }
+    const now = Date.now();
+    store.prepare(`UPDATE workflow_state SET free_mode = 0, free_started_at = NULL, updated_at = ? WHERE workspace_id = ?`).run(now, workspaceRoot);
+    store.prepare(`
+      INSERT INTO workflow_transition_log
+        (workspace_id, from_state, to_state, previous_state, reason, source, turn_id, created_at)
+      VALUES (?, ?, ?, NULL, '[free-off] 用户输入 /free off', 'user-reset', NULL, ?)
+    `).run(workspaceRoot, cur.state, cur.state, now);
+    console.log('已退出 free mode；workflow 恢复');
+    process.exit(0);
+  }
+} finally {
+  store.close();
+}

package/plugins/superharness/skills/brainstorming/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: brainstorming
+description: 在任何创意工作（构建功能、设计组件、新增能力或改动行为）之前必须使用——通过持续盘问用户的意图、需求和约束，按依赖顺序逐枝拆解决策树，达成共识后再动手实现。也可在用户希望被"质询/grill"打磨方案、想做"头脑风暴"或显式说出 "brainstorm" / "grill me" 时触发。
+---
+
+# 头脑风暴：将想法转化为设计
+
+通过有节奏的**盘问**把想法转化为完整的设计和规格说明。盘问不是闲聊——它是对设计树的分层遍历：按依赖顺序先确认根节点，再确认中层，最后确认叶子，每个层级都要逼出明确答案。
+
+首先了解当前项目的上下文（**能查代码就别问**），然后用 ask user question tool / 用户提问工具按同一决策深度批量收集意见。一旦你理解了要构建的内容，就展示设计方案并获得用户批准。
+
+<HARD-GATE>
+在你展示设计方案并获得用户批准之前，不要调用任何实现技能、编写任何代码、搭建任何项目或采取任何实现行动。这适用于所有项目，无论看起来多简单。
+</HARD-GATE>
+
+## 反模式："这个太简单了，不需要设计"
+
+每个项目都要经过这个流程。一个待办事项列表、一个单函数工具、一个配置变更——全都需要。"简单"的项目恰恰是未经检验的假设造成最多浪费的地方。设计可以很简短（对于真正简单的项目几句话就够了），但你必须展示出来并获得批准。
+
+## 盘问风格：不留情面，但不粗暴
+
+把头脑风暴当作"不留情面的盘问"来跑——直到对设计的每一处细节达成共识。这不是态度问题，是对模糊性零容忍。
+
+- **分层盘问决策树：** 设计是一棵树。按依赖顺序遍历——先根节点（目的、约束、范围），再中层（架构选择），最后叶子（实现细节）。**父节点未定，不下钻子节点。**
+- **同深度批量提问：** 使用 ask user question tool / 用户提问工具，在每一轮工具调用中尽量合并当前同一深度的多个决策节点。不要退回普通多轮对话逐个问。
+- **每问必给选项和推荐：** 每个问题节点都提供多个互斥选项 / 方案，以及 1 个开放填写选项（让用户自己填）。从选项中标出 1 个推荐选项，并给出推荐理由。
+- **代码库优先：** 如果某个问题能从代码、文档、commit history 里读出答案，**先去查，别问**。问用户只用来获取代码里没有的信息——意图、偏好、约束。
+- **反馈后重算决策树：** 每轮得到用户意见后，先判断是否需要确认、修剪、重排或细化决策树，再决定下一轮是追问当前深度还是进入下一深度。
+- **追问到底：** 遇到以下情况必须进入下一轮用户提问工具调用继续确认：用户给出选项外且影响决策的回答；回答含糊、矛盾或无法映射到某个选项；用户补充的新目标、新约束或新信息会改变父节点或架构决策。追问要聚焦受影响的节点，不要退回普通多轮消息逐问。
+
+## 检查清单
+
+你必须为以下每个条目创建任务，并按顺序完成：
+
+1. **探索项目上下文** — 检查文件、文档、最近的 commit。能从代码读出的事实就不要问用户。
+2. **提供视觉伴侣**（如果主题涉及视觉问题）— 这是一条独立的消息，不要与澄清问题合并。参见下方的"视觉伴侣"部分。
+3. **分层批量盘问决策树** — 用用户提问工具批量询问同一深度的多个节点，每问提供多个选项、1 个开放填写选项和 1 个推荐选项，按依赖顺序从根到叶
+4. **提出 2-3 种方案** — 附带权衡分析和你的推荐
+5. **展示设计** — 按复杂度分节展示，每节展示后获得用户批准
+6. **编写设计文档** — 保存到 `docs/superharness/specs/YYYY-MM-DD-<topic>-design.md` 并 commit
+7. **规格自检** — 快速内联检查占位符、矛盾、模糊性、范围（详见下方）
+8. **用户审查书面规格** — 在继续之前请用户审查规格文件
+9. **过渡到实现** — transition 到 planning 状态创建实现计划
+
+## 流程图
+
+```dot
+digraph brainstorming {
+    "探索项目上下文\n（能查代码就别问）" [shape=box];
+    "有视觉相关问题?" [shape=diamond];
+    "提供视觉伴侣\n（独立消息，不含其他内容）" [shape=box];
+    "分层批量盘问决策树\n（同深度合并提问）" [shape=box];
+    "提出 2-3 种方案" [shape=box];
+    "分节展示设计" [shape=box];
+    "用户批准设计?" [shape=diamond];
+    "编写设计文档" [shape=box];
+    "规格自检\n（内联修复）" [shape=box];
+    "用户审查规格?" [shape=diamond];
+    "transition 到 planning" [shape=doublecircle];
+
+    "探索项目上下文\n（能查代码就别问）" -> "有视觉相关问题?";
+    "有视觉相关问题?" -> "提供视觉伴侣\n（独立消息，不含其他内容）" [label="是"];
+    "有视觉相关问题?" -> "分层批量盘问决策树\n（同深度合并提问）" [label="否"];
+    "提供视觉伴侣\n（独立消息，不含其他内容）" -> "分层批量盘问决策树\n（同深度合并提问）";
+    "分层批量盘问决策树\n（同深度合并提问）" -> "提出 2-3 种方案";
+    "提出 2-3 种方案" -> "分节展示设计";
+    "分节展示设计" -> "用户批准设计?";
+    "用户批准设计?" -> "分节展示设计" [label="否，修改"];
+    "用户批准设计?" -> "编写设计文档" [label="是"];
+    "编写设计文档" -> "规格自检\n（内联修复）";
+    "规格自检\n（内联修复）" -> "用户审查规格?";
+    "用户审查规格?" -> "编写设计文档" [label="要求修改"];
+    "用户审查规格?" -> "transition 到 planning" [label="批准"];
+}
+```
+
+**终止状态是 transition 到 planning。** 不要调用 frontend-design、mcp-builder 或任何其他实现技能。头脑风暴之后你唯一要进入的状态是 planning。
+
+## 流程详述
+
+**理解想法（决策树式盘问）：**
+
+- **先查代码，再问人：** 在提任何问题之前，先看当前项目状态（文件、文档、最近的 commit）。能从代码读出的事实，绝不浪费用户的时间去问。
+- 在提出详细问题之前，先评估范围：如果需求描述了多个独立子系统（例如"构建一个包含聊天、文件存储、计费和分析的平台"），立即指出这一点。不要花时间用问题去细化一个需要先拆分的项目。
+- 如果项目规模过大，单个规格说明无法覆盖，帮助用户分解为子项目：有哪些独立的部分，它们之间有什么关系，应该按什么顺序构建？然后通过正常的设计流程进行第一个子项目的头脑风暴。每个子项目都有自己的规格 → 计划 → 实现周期。
+- 对于范围适当的项目，**按依赖顺序分层批量盘问决策树**：根节点（目的 / 约束 / 成功标准）→ 中层（架构选择）→ 叶子（实现细节）。父节点未定，不下钻子节点。
+- 使用 ask user question tool / 用户提问工具，每轮尽量合并当前同一深度的多个问题；批量大小由可用工具能力和用户负担决定，不写死数量。
+- 每个问题节点都**提供多个互斥选项 / 方案、1 个开放填写选项（让用户自己填）、1 个推荐选项和推荐理由**。不要只问"是 / 否 / 换一个"。
+- 每轮回答后，先评估用户意见是否改变决策树：确认、修剪、重排或细化节点；下一轮再决定追问当前深度还是进入下一深度。
+- 尽量使用选择题。每轮回答后先把用户意见映射到已给选项或开放选项；若出现选项外且影响决策的答案、无法决策的含糊 / 矛盾表达，或会改变父节点 / 架构决策的新信息，必须用下一轮工具调用继续确认。
+- 重点理解：目的、约束、成功标准。
+
+**探索方案：**
+
+- 提出 2-3 种不同的方案及其权衡
+- 以对话的方式展示选项，保留开放填写入口，并附上你的推荐和理由
+- 先展示你推荐的方案并解释原因
+
+**展示设计：**
+
+- 一旦你认为理解了要构建的内容，就展示设计
+- 每个部分的篇幅与其复杂度匹配：简单的几句话，复杂的最多 200-300 字
+- 每个部分展示后询问是否正确
+- 涵盖：架构、组件、数据流、错误处理、测试
+- 随时准备回头澄清不明确的地方
+
+**面向隔离和清晰的设计：**
+
+- 将系统拆分为更小的单元，每个单元有一个明确的职责，通过定义良好的接口通信，可以独立理解和测试
+- 对于每个单元，你应该能回答：它做什么，如何使用，它依赖什么？
+- 别人能否不看内部实现就理解一个单元的功能？你能否在不影响调用者的情况下修改内部实现？如果不能，边界需要调整。
+- 更小、边界清晰的单元也更便于你工作——你对能一次放入上下文的代码推理得更好，文件越专注你的编辑越可靠。当文件变大时，这通常意味着它承担了过多职责。
+
+**在现有代码库中工作：**
+
+- 在提出更改之前先探索现有结构。遵循现有模式。
+- 如果现有代码存在影响当前工作的问题（例如文件过大、边界不清、职责纠缠），在设计中包含有针对性的改进——就像一个优秀的开发者在工作中改进经手的代码一样。
+- 不要提议无关的重构。专注于服务当前目标的事情。
+
+## 设计之后
+
+**文档：**
+
+- 将验证通过的设计（规格说明）写入 `docs/superharness/specs/YYYY-MM-DD-<topic>-design.md`
+  - （用户对规格位置的偏好优先于此默认值）
+- 如果可用，使用 elements-of-style:writing-clearly-and-concisely 技能
+- 将设计文档 commit 到 git
+
+**规格自检：**
+编写规格文档后，以全新的视角审视它：
+
+1. **占位符扫描：** 有没有"待定"、"TODO"、未完成的章节或模糊的需求？修复它们。
+2. **内部一致性：** 各章节之间有矛盾吗？架构和功能描述匹配吗？
+3. **范围检查：** 这是否聚焦到可以用一个实现计划覆盖，还是需要进一步拆分？
+4. **模糊性检查：** 有没有需求可以被两种方式理解？如果有，选择一种并明确写出来。
+
+发现问题就直接内联修复。无需重新审查——修好继续推进。
+
+**用户审查关卡：**
+规格自检完成后，请用户在继续之前审查书面规格：
+
+> "规格已编写并 commit 到 `<path>`。请审查一下，如果在我们开始编写实现计划之前你想做任何修改，请告诉我。"
+
+等待用户回复。如果他们要求修改，做出修改并重新运行规格自检。只有在用户批准后才继续。
+
+**实现：**
+
+- transition 到 planning 状态创建详细的实现计划
+- 不要调用任何其他技能。planning 是下一步。
+
+## 核心原则
+
+- **每轮同深度批量提问** — 使用用户提问工具，在一轮中尽量合并当前同一深度的多个决策问题
+- **每问必给选项和推荐** — 每个问题节点都提供多个互斥选项 / 方案、1 个开放填写选项、1 个推荐选项和推荐理由
+- **代码库优先** — 能从代码 / 文档 / commit 读出的答案就不要问用户
+- **追问到底** — 对选项外且影响决策的回答、无法映射到选项的含糊 / 矛盾回答、会改变父节点或架构的新信息，必须用下一轮工具调用继续确认
+- **分层推进** — 按依赖顺序遍历决策树，父节点未定不下钻子节点
+- **优先结构化选择** — 用多个清晰选项降低回答成本，同时保留开放填写选项承接意外答案
+- **严格遵循 YAGNI** — 从所有设计中移除不必要的功能
+- **探索替代方案** — 在做决定之前始终提出 2-3 种方案
+- **增量验证** — 展示设计，获得批准后再继续
+- **保持灵活** — 有不明确的地方就回头澄清
+
+## 视觉伴侣
+
+一个基于浏览器的伴侣工具，用于在头脑风暴过程中展示原型、图表和视觉选项。它是一个工具——不是一种模式。接受伴侣意味着它可用于适合视觉呈现的问题；并不意味着每个问题都要通过浏览器。
+
+**提供伴侣：** 当你预计后续问题会涉及视觉内容（原型、布局、图表）时，提供一次以获得同意：
+> "我们接下来讨论的一些内容，如果能在浏览器中展示给你看可能会更直观。我可以在讨论过程中为你制作原型、图表、对比图和其他视觉材料。这个功能还比较新，可能会消耗较多 token。要试试吗？（需要打开一个本地 URL）"
+
+**此提议必须是一条独立的消息。** 不要将它与澄清问题、上下文摘要或任何其他内容合并。消息中应该只包含上述提议，没有其他内容。等待用户回复后再继续。如果他们拒绝，继续纯文本的头脑风暴。
+
+**逐问题决策：** 即使用户接受了，也要对每个问题单独决定是使用浏览器还是终端。判断标准：**用户看到它是否比读到它更容易理解？**
+
+- **使用浏览器** 展示本身就是视觉的内容——原型、线框图、布局对比、架构图、并排视觉设计
+- **使用终端** 展示文本内容——需求问题、概念选择、权衡列表、A/B/C/D 文字选项、范围决策
+
+关于 UI 主题的问题不一定是视觉问题。"在这个上下文中个性化是什么意思？"是一个概念问题——使用终端。"哪种向导布局更好？"是一个视觉问题——使用浏览器。
+
+如果他们同意使用伴侣，在继续之前阅读详细指南：
+`skills/brainstorming/visual-companion.md`
+