create-harness-vibe-coding 0.8.0 → 0.8.2

package/README-CN.md

@@ -15,9 +15,11 @@ npx create-harness-vibe-coding@latest my-project
 已有项目时，不要让 agent 猜。把这句话贴给它：
 
 ```text
-请按照 https://github.com/zingspark/create-harness-vibe-coding 的 README 为当前项目配置 create-harness-vibe-coding；编辑前先扫描项目根目录并询问 Agent-link 安装前置问题；如果 Harness/ 已存在，先询问如何处理再写文件；新项目走 0-1 bootstrap，老项目或老架构升级先 dry-run，保留现有文件，只合并缺失的 Harness 规范，然后遵循 Harness/SETUP.md。
+请完整阅读并严格遵循 https://github.com/zingspark/create-harness-vibe-coding，为当前项目配置 create-harness-vibe-coding。
 ```
 
+复杂规则不塞进这句话里。README 和生成后的 `Harness/SETUP.md` 才是安装、升级、合并和可选能力选择的准则。
+
 ## 你会得到什么
 
 | 文件/能力 | 作用 |
@@ -25,8 +27,8 @@ npx create-harness-vibe-coding@latest my-project
 | `CLAUDE.md` + `AGENTS.md` | 根目录 agent 入口 |
 | `Harness/README.md` | Harness 路由器 |
 | `Harness/tasks/` + `Harness/PROGRESS.md` | 跨会话任务状态 |
-| `.claude/skills/` | Claude Code 的 workflow skill 入口 |
-| `.agents/skills/` | Codex 的 repo skill 入口 |
+| `.claude/skills/` | Claude Code workflow skill 入口 |
+| `.agents/skills/` | Codex repo skill 入口 |
 | `.codex/` | Codex hooks/config |
 | `/wf` / `$wf` | 长任务 workflow |
 | `/wf-max` / `$wf-max` | 最大并行 workflow |
@@ -41,29 +43,31 @@ Claude Code 和 Codex 共用同一套核心 Harness 文档，但发现入口不
 - Codex：`.agents/skills/<name>/SKILL.md`，通常用 `$wf` 或 `/skills` 调用。
 - `.codex/` 只放 Codex 配置和 hooks；不要再使用根目录 `commands/*.toml` 伪装 Codex slash command。
 
-## 新项目
+## 安装或升级路径
 
-```bash
-npx create-harness-vibe-coding@latest my-project
-cd my-project
-```
+写文件前，agent 必须先判断当前项目属于哪一种：
 
-然后让 agent 执行：
+| 项目状态 | 必须怎么做 |
+|---|---|
+| 空项目或新项目 | 运行脚手架，然后遵循 `Harness/SETUP.md` 做 0-1 bootstrap |
+| 已有项目，没有 `Harness/` | 先扫描项目事实，先 `--dry-run`，保留现有文件，只合并缺失的 Harness 指南 |
+| 老项目或老架构迁移 | 现有代码和文档是事实来源，先 dry-run，再用 `Harness/SETUP.md` 从事实中补 PRD、研究、架构和任务计划 |
+| 已经有 `Harness/` | 不要把 `npx` 当更新器；先问用户是运行 `/wf-update` / `$wf-update` / `node Harness/scripts/wf-update-check.mjs`，保持不动，还是批准后移除重装 |
 
-```text
-读 Harness/SETUP.md。把这个项目从想法引导到第一个 vertical slice。
-```
+根目录扫描必须包括：顶层文件、`CLAUDE.md`、`AGENTS.md`、`.claude/`、`.agents/`、`.codex/`、`Harness/`、package 文件、CI 文件、应用入口、测试/构建命令、已有文档、已经安装的 skills/plugins/rules。推荐可选能力前，必须先排除已经安装的能力，避免重复推荐。
 
 ## 已有项目安全合并
 
 ```bash
-# 先预览，不写文件
-npx create-harness-vibe-coding@latest my-app . -y --dry-run
+# 先用机器可读预览，不写文件
+npx create-harness-vibe-coding@latest my-app . -y --dry-run --json
 
 # 只补缺失文件，不覆盖已有文件
-npx create-harness-vibe-coding@latest my-app . -y --on-conflict skip
+npx create-harness-vibe-coding@latest my-app . -y --on-conflict skip --json
 ```
 
+JSON 输出就是 agent 的安装报告：`scan` 代替手写根目录探测，`plan.create` 交给脚本处理，只有 `agent.aiMergeRequired` 里的文件需要 AI 语义比较和用户监督合并。除非这个列表里出现冲突文件，否则不要读取包源码或模板。
+
 `npx` 是安装和安全补缺入口，不是已安装 Harness 的同步更新器。项目里已经有 `Harness/` 后，Claude Code 用 `/wf-update`，Codex 用 `$wf-update`，或者直接运行：
 
 ```bash
@@ -90,33 +94,45 @@ npx create-harness-vibe-coding@latest my-app -y --recommend superpowers,codegrap
 
 本地 workflow：`browser-e2e`、`ui-ux-review`、`ts-react-frontend`、`python-backend`、`github-pr-review`。
 
-外部建议只写入 `Harness/SETUP.md`，不会自动安装第三方技能：`superpowers`、`caveman`、`agent-research`、`codegraph`。
+外部建议只写入 `Harness/SETUP.md`，不会自动安装第三方技能：
+
+| 建议 | 用途 | 链接 |
+|---|---|---|
+| `superpowers` | 社区 skill registry 和 agent workflow | <https://github.com/obra/Superpowers> |
+| `caveman` | 简洁低 token 的 agent 行为和记忆压缩 | <https://github.com/JuliusBrussee/caveman> |
+| `agent-research` | 文献、产品、依赖和生态研究类 agent skills | <https://github.com/lingzhi227/agent-research-skills> |
+| `codegraph` | 代码图谱或仓库地图工具 | <https://github.com/colbymchenry/codegraph> |
+
+这些只是给用户 agent 自行评估的 GitHub 链接。脚手架不维护第三方安装步骤，只在确认项目尚未安装同类能力后记录用户选择。
 
 不加 `-y` 时，CLI 会提供 checkbox/multiselect 选择。
 
 ## Agent-link 安装前置问题
 
-Agent 必须先扫描根目录，再最多问 3 个阻塞问题。扫描要覆盖：
+Agent 应先拿机器可读安装报告，再最多问 3 个阻塞问题：
 
-- `CLAUDE.md`、`AGENTS.md`
-- `.claude/`、`.agents/`、`.codex/`
-- `Harness/`
-- `README.md`
-- package 文件、CI 文件、已有文档目录、应用入口和测试命令
+```bash
+npx create-harness-vibe-coding@latest my-app . -y --dry-run --json
+```
+
+使用 `scan.markers`，不要手写一串根目录探测命令。`plan.create` 由脚本处理；只有 `agent.aiMergeRequired` 里的文件需要 AI 比较并由用户监督合并。
 
 只在影响写入时提问：
 
 - 已有 `CLAUDE.md` 或 `AGENTS.md`：合并缺失 Harness 指南、保持不动，还是跳过？
 - 已有 `Harness/`：走 `/wf-update` / `$wf-update`、dry-run 补缺、保持不动，还是批准后移除重装？
-- 要启用哪些能力：本地 workflow，或只记录外部建议？
+- 排除已安装能力后，还要启用哪些本地 workflow，或只记录哪些外部 GitHub 推荐链接？
 
 默认策略：保留已有文件，只补缺失内容。
 
 ## 验证
 
 ```bash
+# 当前脚手架仓库
 npm test
-node Harness/scripts/validate-harness.mjs
+
+# 生成后的项目完成 bootstrap 后
+node Harness/scripts/validate-harness.mjs --strict
 ```
 
 ## 项目结构

package/README.md

@@ -21,7 +21,7 @@ npx create-harness-vibe-coding@latest my-project
 Already have a project? **Don't read the docs**. Paste this sentence. Your agent handles the rest.
 
 ```text
-Follow the README at https://github.com/zingspark/create-harness-vibe-coding to configure this project with create-harness-vibe-coding; before editing, scan the project root and ask the Agent-link install intake questions; if Harness/ already exists, ask how to handle it before writing; for a new project run the 0-1 bootstrap, and for an existing project or legacy architecture run a dry-run first, preserve existing files, merge only missing Harness guidance, then follow Harness/SETUP.md.
+Read and follow https://github.com/zingspark/create-harness-vibe-coding exactly to configure this project with create-harness-vibe-coding.
 ```
 
 That's it. Two paths into the harness — you type `npx`, or your agent reads the sentence.
@@ -104,16 +104,31 @@ cd my-project
 # Your agent reads Harness/SETUP.md. Done.
 ```
 
+### Install or Upgrade Path
+
+Before writing, the agent must identify which path applies:
+
+| Project state | Required action |
+|---------------|-----------------|
+| Empty or new project | Run the scaffold, then follow `Harness/SETUP.md` for 0-1 bootstrap |
+| Existing project, no `Harness/` | Scan project facts first, run `--dry-run`, preserve existing files, merge only missing Harness guidance |
+| Legacy architecture or older project docs | Treat existing code/docs as source of truth, dry-run first, then use `Harness/SETUP.md` to fill facts from observed project reality |
+| Existing `Harness/` | Do not use `npx` as an updater; ask whether to run `/wf-update`, `$wf-update`, `node Harness/scripts/wf-update-check.mjs`, keep untouched, or remove/reinstall after approval |
+
+Root scan must include top-level files, `CLAUDE.md`, `AGENTS.md`, `.claude/`, `.agents/`, `.codex/`, `Harness/`, package files, CI files, app entry points, test/build commands, existing docs, and already-installed skills/plugins/rules. Use that scan before recommending optional capabilities so you do not suggest duplicates.
+
 ### Existing project — safe merge
 
 ```bash
-# Preview first. Always.
-npx create-harness-vibe-coding@latest my-app . -y --dry-run
-
+# Machine-readable preview first. Always.
+npx create-harness-vibe-coding@latest my-app . -y --dry-run --json
+
 # Add only what's missing. Never overwrite.
-npx create-harness-vibe-coding@latest my-app . -y --on-conflict skip
+npx create-harness-vibe-coding@latest my-app . -y --on-conflict skip --json
 ```
 
+The JSON output is the agent's install report: `scan` replaces hand-written root probes, `plan.create` is script-owned, and `agent.aiMergeRequired` is the only list that needs semantic AI review. Do not read package source or templates unless `agent.aiMergeRequired` names a conflicting file.
+
 `npx` is an install and safe-merge entry, not an update engine for an already installed Harness. Once `Harness/` exists, use `/wf-update` in Claude Code, `$wf-update` in Codex, or `node Harness/scripts/wf-update-check.mjs`; root entry conflicts such as `CLAUDE.md`, `AGENTS.md`, `.claude/`, `.agents/`, `.codex/`, and local Harness docs need agent-mediated merge decisions.
 
 | Flag | Does |
@@ -148,24 +163,30 @@ npx create-harness-vibe-coding@latest my-app -y --recommend superpowers,codegrap
 
 External recommendations are recorded in `Harness/SETUP.md` but not installed automatically:
 
-| Recommendation | For |
-|----------------|-----|
-| `superpowers` | Community skill registry and agent workflows |
-| `caveman` | Strict low-abstraction workflow/style capability |
-| `agent-research` | Broader product, dependency, and ecosystem research agents |
-| `codegraph` | Code graph or repository-map tooling |
+| Recommendation | For | Source |
+|----------------|-----|--------|
+| `superpowers` | Community skill registry and agent workflows | <https://github.com/obra/Superpowers> |
+| `caveman` | Terse, low-token agent behavior and memory compression | <https://github.com/JuliusBrussee/caveman> |
+| `agent-research` | Research-agent skills for literature, product, dependency, and ecosystem investigation | <https://github.com/lingzhi227/agent-research-skills> |
+| `codegraph` | Code graph or repository-map tooling | <https://github.com/colbymchenry/codegraph> |
+
+These are links for the user's agent to evaluate. The scaffold does not maintain third-party install steps; it only records selected recommendations after checking what is already installed.
 
 ### Agent-link intake
 
-When your agent reads the one-sentence prompt above, it must first scan the project root, then ask **at most 3 blocking questions** before touching files.
+When your agent reads the one-sentence prompt above, it should get the machine-readable install report before asking broad questions:
+
+```bash
+npx create-harness-vibe-coding@latest my-app . -y --dry-run --json
+```
 
-Root scan checklist: list top-level files, detect `CLAUDE.md`, `AGENTS.md`, `.claude/`, `.agents/`, `.codex/`, `Harness/`, package files, CI files, docs folders, and obvious app entry points.
+Use `scan.markers` instead of manual top-level probes. Ask **at most 3 blocking questions** before touching files. Files in `plan.create` are handled by the script; only files in `agent.aiMergeRequired` need AI comparison and user-supervised merge decisions.
 
 Ask these only when they affect writes:
 
 - If `CLAUDE.md` or `AGENTS.md` already exists, should missing Harness guidance be merged, kept separate, or skipped?
 - If `Harness/` already exists, should the agent run update/dry-run, merge missing files, keep it untouched, or remove/reinstall after approval?
-- Which optional capabilities should be enabled: local workflows (`browser-e2e`, `ui-ux-review`, `ts-react-frontend`, `python-backend`, `github-pr-review`) and recommendation-only external options (`Superpowers`, `Caveman`, `agent research`, `code graph`)?
+- Which optional capabilities should be enabled, after excluding capabilities already installed: local workflows (`browser-e2e`, `ui-ux-review`, `ts-react-frontend`, `python-backend`, `github-pr-review`) and recommendation-only external links (`Superpowers`, `Caveman`, `agent research`, `code graph`)?
 
 Harness docs always live in root `Harness/`; do not route Harness files through `docs/`. If a file already exists, the agent asks first. The default is always **preserve**.
 
@@ -178,12 +199,15 @@ Harness docs always live in root `Harness/`; do not route Harness files through
 "/wf-update" or "$wf-update"           # pull latest harness improvements
 ```
 
-### Verify
-
-```bash
-npm test
-node Harness/scripts/validate-harness.mjs
-```
+### Verify
+
+```bash
+# In this package repo
+npm test
+
+# In a generated project after bootstrap
+node Harness/scripts/validate-harness.mjs --strict
+```
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-harness-vibe-coding",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "Scaffold a 0-1 product harness for AI-assisted research, PRD, planning, architecture, build, test, and feedback loops",
   "type": "module",
   "bin": {

package/src/generator.js

@@ -377,7 +377,7 @@ function registerExternalRecommendations(file, content, selectedRecommendations)
   if (!selectedRecommendations.length || file !== 'Harness/SETUP.md') return content;
 
   const lines = selectedRecommendations.map(item => (
-    `- \`${item.id}\` - ${item.description} Recommendation only; not installed by this scaffold. Use the discovery/install hint: ${item.installHint}`
+    `- \`${item.id}\` - ${item.description} Recommendation only; not installed by this scaffold. Source: ${item.url}`
   ));
 
   return `${content.trimEnd()}\n\n## Selected External Recommendations\n\n${lines.join('\n')}\n`;

package/src/index.js

@@ -81,11 +81,19 @@ const generationOptions = {
 const DEFAULT_NAME = 'my-vibe-project';
 
 // --json: machine-readable output, no prompts, no decorative output
-if (generationOptions.json) {
-  const projectName = argName || DEFAULT_NAME;
-  const targetDir = argDir || `./${projectName}`;
-  const result = generate({ projectName, targetDir, ...generationOptions });
-  printJsonResult(result);
+if (generationOptions.json) {
+  const projectName = argName || DEFAULT_NAME;
+  const targetDir = argDir || `./${projectName}`;
+  const scan = scanTarget(targetDir);
+  const result = generate({ projectName, targetDir, ...generationOptions });
+  result.scan = createJsonScan(scan);
+  result.agent = createAgentGuidance(result, {
+    projectName,
+    targetDir,
+    options: generationOptions,
+    scan,
+  });
+  printJsonResult(result);
   // printJsonResult exits with 1 on failure; we only reach here on success
   process.exit(0);
 }
@@ -377,7 +385,7 @@ function printOptions() {
     console.log('');
     console.log(pc.bold('External recommendations:'));
     for (const item of catalog.externalRecommendations) {
-      console.log(`  ${pc.cyan(item.id)} - ${item.description} (${item.installMode})`);
+      console.log(`  ${pc.cyan(item.id)} - ${item.description} (${item.installMode}) ${item.url || ''}`.trimEnd());
     }
   }
   console.log('');
@@ -429,6 +437,17 @@ function scanTarget(targetDir) {
     ? fs.readdirSync(resolvedDir)
     : [];
   const hasHarness = isDirectory && fs.existsSync(path.join(resolvedDir, 'Harness'));
+  const hasClaude = isDirectory && fs.existsSync(path.join(resolvedDir, 'CLAUDE.md'));
+  const hasAgents = isDirectory && fs.existsSync(path.join(resolvedDir, 'AGENTS.md'));
+  const hasAgentSkills = isDirectory && fs.existsSync(path.join(resolvedDir, '.agents'));
+  const hasCodex = isDirectory && fs.existsSync(path.join(resolvedDir, '.codex'));
+  const hasDocs = isDirectory && fs.existsSync(path.join(resolvedDir, 'docs'));
+  const hasReadme = isDirectory && fs.existsSync(path.join(resolvedDir, 'README.md'));
+  const hasPackageJson = isDirectory && fs.existsSync(path.join(resolvedDir, 'package.json'));
+  const hasPyproject = isDirectory && fs.existsSync(path.join(resolvedDir, 'pyproject.toml'));
+  const hasGoMod = isDirectory && fs.existsSync(path.join(resolvedDir, 'go.mod'));
+  const hasGithub = isDirectory && fs.existsSync(path.join(resolvedDir, '.github'));
+  const hasGitignore = isDirectory && fs.existsSync(path.join(resolvedDir, '.gitignore'));
 
   return {
     resolvedDir,
@@ -436,15 +455,196 @@ function scanTarget(targetDir) {
     isDirectory,
     entries,
     hasHarness,
-    hasClaude: isDirectory && fs.existsSync(path.join(resolvedDir, 'CLAUDE.md')),
-    hasAgents: isDirectory && fs.existsSync(path.join(resolvedDir, 'AGENTS.md')),
-    hasAgentSkills: isDirectory && fs.existsSync(path.join(resolvedDir, '.agents')),
-    hasCodex: isDirectory && fs.existsSync(path.join(resolvedDir, '.codex')),
-    hasDocs: isDirectory && fs.existsSync(path.join(resolvedDir, 'docs')),
+    hasClaude,
+    hasAgents,
+    hasAgentSkills,
+    hasCodex,
+    hasDocs,
+    hasReadme,
+    hasPackageJson,
+    hasPyproject,
+    hasGoMod,
+    hasGithub,
+    hasGitignore,
     needsConflictPolicy: exists && (!isDirectory || entries.length > 0 || hasHarness),
   };
 }
 
+function createJsonScan(scan) {
+  const topLevelEntries = scan.entries.slice(0, 50);
+
+  return {
+    resolvedDir: scan.resolvedDir,
+    exists: scan.exists,
+    isDirectory: scan.isDirectory,
+    entryCount: scan.entries.length,
+    topLevelEntries,
+    topLevelEntriesTruncated: scan.entries.length > topLevelEntries.length,
+    needsConflictPolicy: scan.needsConflictPolicy,
+    markers: {
+      hasHarness: scan.hasHarness,
+      hasClaude: scan.hasClaude,
+      hasAgents: scan.hasAgents,
+      hasAgentSkills: scan.hasAgentSkills,
+      hasCodex: scan.hasCodex,
+      hasDocs: scan.hasDocs,
+      hasReadme: scan.hasReadme,
+      hasPackageJson: scan.hasPackageJson,
+      hasPyproject: scan.hasPyproject,
+      hasGoMod: scan.hasGoMod,
+      hasGithub: scan.hasGithub,
+      hasGitignore: scan.hasGitignore,
+    },
+  };
+}
+
+function createAgentGuidance(result, { projectName, targetDir, options, scan }) {
+  const attentionFiles = [...new Set([
+    ...(result.plan?.conflict || []),
+    ...(result.plan?.skip || []),
+  ])].sort();
+  const aiMergeRequired = attentionFiles.map(file => createFileGuidance(file));
+  const hasBlockingConflicts = (result.plan?.conflict || []).length > 0;
+  const safeMergeCommand = commandFor(projectName, targetDir, {
+    ...options,
+    dryRun: false,
+    onConflict: 'skip',
+    json: true,
+  });
+  const previewCommand = commandFor(projectName, targetDir, {
+    ...options,
+    dryRun: true,
+    json: true,
+  });
+  const next = [];
+
+  if (scan.hasHarness) {
+    next.push({
+      action: 'stop',
+      reason: 'Harness already exists; use wf-update or Harness/scripts/wf-update-check.mjs instead of reinstalling blindly.',
+    });
+  } else if (result.dryRun && !hasBlockingConflicts) {
+    next.push({
+      action: 'install',
+      command: safeMergeCommand,
+      reason: 'Dry-run has no blocking conflicts; let the script create missing files.',
+    });
+  } else if (result.dryRun && hasBlockingConflicts) {
+    next.push({
+      action: 'safe-merge',
+      command: safeMergeCommand,
+      reason: 'Default dry-run found existing files; rerun with --on-conflict skip so the script creates missing files and preserves existing ones.',
+    });
+  } else if (result.success) {
+    next.push({
+      action: 'bootstrap',
+      command: 'Read Harness/SETUP.md and use this JSON plan before opening any package templates.',
+      reason: 'Scaffold files were written; bootstrap project facts from local evidence.',
+    });
+  } else {
+    next.push({
+      action: 'inspect-errors',
+      reason: 'Generation failed before safe scaffold output was available.',
+    });
+  }
+
+  if (aiMergeRequired.length > 0) {
+    next.push({
+      action: 'ai-merge',
+      files: aiMergeRequired.map(item => item.file),
+      reason: 'Only these existing/conflicting files need semantic review. Files in plan.create are script-owned.',
+    });
+  }
+
+  return {
+    sourceOfTruth: 'Use this JSON scan/plan first. Do not read package source or templates unless aiMergeRequired lists a file.',
+    previewCommand,
+    safeMergeCommand,
+    scriptHandled: {
+      create: result.plan?.create?.length || 0,
+      mkdir: result.plan?.mkdir?.length || 0,
+      backup: result.plan?.backup?.length || 0,
+      overwrite: result.plan?.overwrite?.length || 0,
+    },
+    aiMergeRequired,
+    next,
+  };
+}
+
+function createFileGuidance(file) {
+  const normalized = file.replace(/\\/g, '/');
+  const guidance = {
+    file: normalized,
+    templateHint: templateHintFor(normalized),
+    requiresUserConsent: false,
+    defaultAction: 'preserve',
+    reason: 'Existing file or path needs semantic review before any merge.',
+  };
+
+  if (normalized.endsWith('/')) {
+    return {
+      ...guidance,
+      templateHint: null,
+      defaultAction: 'stop',
+      reason: 'A file blocks a required scaffold directory. Stop and ask before moving or replacing it.',
+    };
+  }
+
+  if (normalized === 'CLAUDE.md' || normalized === 'AGENTS.md') {
+    return {
+      ...guidance,
+      requiresUserConsent: true,
+      reason: 'Root agent entry contract. Preserve project rules and ask before merging Harness startup guidance.',
+    };
+  }
+
+  if (normalized === 'README.md') {
+    return {
+      ...guidance,
+      reason: 'Project-owned public/development documentation. Preserve by default; append development notes only after review.',
+    };
+  }
+
+  if (normalized === 'Harness/README.md' || normalized === 'Harness/MEMORY.md') {
+    return {
+      ...guidance,
+      reason: 'Harness router/registry conflict. Merge only missing routing or registration entries.',
+    };
+  }
+
+  return guidance;
+}
+
+function templateHintFor(file) {
+  if (file === 'Harness/SETUP.md') return 'templates/common/SETUP.md';
+  return `templates/common/${file}`;
+}
+
+function commandFor(projectName, targetDir, options) {
+  const args = [
+    'npx',
+    'create-harness-vibe-coding@latest',
+    projectName,
+    targetDir,
+    '-y',
+  ];
+
+  if (options.dryRun) args.push('--dry-run');
+  if (options.onConflict) args.push('--on-conflict', options.onConflict);
+  if (options.withOptions?.length) args.push('--with', options.withOptions.join(','));
+  if (options.withoutOptions?.length) args.push('--without', options.withoutOptions.join(','));
+  if (options.externalOptions?.length) args.push('--recommend', options.externalOptions.join(','));
+  if (options.preset) args.push('--preset', options.preset);
+  if (options.json) args.push('--json');
+
+  return args.map(shellQuoteArg).join(' ');
+}
+
+function shellQuoteArg(arg) {
+  if (/^[A-Za-z0-9@._/\\:-]+$/.test(arg)) return arg;
+  return JSON.stringify(arg);
+}
+
 function printScan(scan) {
   if (!scan.exists) return;
 

package/src/prompts.js

@@ -73,7 +73,7 @@ export async function askOptionalSelections(catalog) {
   const externalOptions = (catalog.externalRecommendations || []).map(item => ({
     value: item.id,
     label: item.title,
-    hint: `${item.description} Recommendation only.`,
+    hint: item.url ? `${item.description} ${item.url}` : `${item.description} Recommendation only.`,
   }));
 
   const selectedLocal = localOptions.length

package/templates/common/.claude/agents/tdd-guide.md

@@ -0,0 +1,55 @@
+---
+name: tdd-guide
+description: Test-Driven Development specialist enforcing write-tests-first methodology. Use PROACTIVELY when writing new features, fixing bugs, or refactoring code. Ensures 80%+ test coverage.
+tools: Read, Write, Edit, Bash, Grep, Glob
+model: sonnet
+---
+
+# TDD Guide Agent
+
+Enforces TDD workflow. Load `Harness/TDD-GUIDE.md` first, then ECC testing rules for the project stack.
+
+## Inputs Required
+
+- Task description and acceptance criteria from PLAN.md
+- Current test coverage status
+- Stack-specific testing tools (Jest, Pytest, Go test, etc.)
+
+## Workflow
+
+1. READ acceptance criteria
+2. WRITE failing test (RED)
+3. VERIFY test fails for expected reason
+4. Report test file path and expected failure to Implementer
+
+Do NOT write implementation code. Only tests.
+
+## Allowed Write Set
+
+- Test files only (`*.test.ts`, `*.test.tsx`, `test_*.py`, `*_test.go`, etc.)
+- Test fixtures and mocks
+- Test configuration files
+
+## Forbidden
+
+- Production/source code changes
+- Loosening existing test assertions
+- Deleting existing tests without explicit approval
+
+## Verification
+
+- Test MUST fail before handing off to Implementer
+- Test MUST cover acceptance criteria + error paths
+- Run `node Harness/scripts/validate-harness.mjs` after significant test additions
+
+## Return Format
+
+```text
+Agent: tdd-guide
+Task: <task-id>
+Tests written: <file paths>
+Coverage before: X%
+Expected coverage after: Y%
+Failing tests: <list of test names and expected failure reasons>
+Next: Dispatch Implementer to make tests pass
+```

package/templates/common/.claude/settings.json

@@ -63,6 +63,28 @@
           }
         ]
       }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node Harness/scripts/wf-mode-hook.mjs"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node Harness/scripts/wf-mode-hook.mjs"
+          }
+        ]
+      }
     ]
   }
 }

package/templates/common/.claude/skills/tdd/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: tdd
+description: Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions "red-green-refactor", or wants integration tests.
+---
+
+# TDD Adapter
+
+Thin tool adapter. Authoritative guide: `Harness/TDD-GUIDE.md`.
+
+## Invocation
+
+- Claude Code: use `/tdd` or select the `tdd` skill.
+- Codex CLI or IDE: use `$tdd` or `/skills` then choose `tdd`.
+
+## Load
+
+1. `Harness/TDD-GUIDE.md`
+2. ECC stack-specific testing rules (e.g., `typescript/testing.md`, `python/testing.md`)
+3. Current task `PLAN.md`
+
+## Rules
+
+1. **RED first**: Write failing test before ANY implementation code.
+2. **GREEN minimal**: Write only enough code to pass the test.
+3. **REFACTOR safe**: Improve code while keeping all tests green.
+4. **Coverage gate**: ≥80% before marking task complete.
+5. **Test names**: Describe behavior — `test('returns X when Y')`.
+6. **AAA structure**: Arrange → Act → Assert.
+7. **Error paths**: Test failure cases, not just happy path.
+8. **WF-MAX**: Test Writer agent dispatched BEFORE Implementer in every wave.