create-harness-vibe-coding 0.8.8 → 0.8.10

package/README-CN.md

@@ -5,6 +5,10 @@
   <img src="https://img.shields.io/github/stars/zingspark/create-harness-vibe-coding?style=social" alt="GitHub stars">
 </p>
 
+<p align="center">
+  <img src="docs/images/harness-icon.png" alt="Harness 图标" width="112">
+</p>
+
 <h1 align="center">create-harness-vibe-coding</h1>
 <p align="center">
   <b>让 AI agent 在真实仓库里先理解，再执行，最后验证。</b><br>
@@ -39,7 +43,8 @@ Agent 读取本 README 后，按项目状态选择安装路径：
 |---|---|
 | 新项目 | `npx create-harness-vibe-coding@latest my-project -y` |
 | 已有项目 | `npx create-harness-vibe-coding@latest my-project . -y --on-conflict skip --json` |
-| 已有 `Harness/` | `node Harness/scripts/wf-update-check.mjs`，不要重复安装 |
+| 已有 `Harness/` 且存在 `Harness/scripts/wf-update-check.mjs` | `node Harness/scripts/wf-update-check.mjs --json`，走更新流程，不要重复安装 |
+| 已有 `Harness/` 但缺少 `Harness/scripts/wf-update-check.mjs` | `npx create-harness-vibe-coding@latest my-project . -y --on-conflict skip --json`。然后执行 `node Harness/scripts/wf-update-check.mjs --json` |
 | 安装或更新完成 | `node Harness/scripts/validate-harness.mjs --strict` |
 
 安装后的 instruction：先读取 `CLAUDE.md`、`AGENTS.md`、`Harness/SETUP.md` 和 `Harness/README.md`；遵守项目已有边界；先研究和计划，再修改代码；完成后运行测试、校验和审查，未验证不要声称完成。
@@ -56,7 +61,7 @@ Agent 读取本 README 后，按项目状态选择安装路径：
 | `/wf-max <任务>` | 任务可拆成多个互不冲突的部分，需要最大并行度 | 在完整 WF 链路上增加 CEO → Manager → Worker 分工和并行波次 | `/wf-max 并行升级前端、后端和文档` |
 | `/wf-auto` | 希望 Agent 持续自我优化，通过自适应探测选择 | 持续执行优化循环，每轮保留计划、证据和反馈 | `/wf-auto 优化这个项目的稳定性` |
 | `/wf-auto-spark` | 需要外部灵感、竞品方向或长期路线图 | 搜索外部 spark，绑定 North Star 和里程碑，限制偏离范围 | `/wf-auto-spark 探索产品增长方向` |
-| `/wf-review [重点]` | 需要第二意见、跨模型审查或上线前复核 | 调用其他 Agent 做独立审查，并按严重程度反馈 | `/wf-review 重点检查安全和数据丢失` |
+| `/wf-review [重点]` | 需要第二意见、同行审查或上线前复核 | 优先调用可用 peer CLI；没有时使用独立 reviewer 角色，并按严重程度反馈 | `/wf-review 重点检查安全和数据丢失` |
 | `/wf-learn` | 同类错误反复出现，或一次任务结束后要沉淀经验 | 汇总上下文、记忆和项目经验，形成下一次可复用规则 | `/wf-learn 总结这次返修原因` |
 | `/wf-browser <任务>` | 浏览器冒烟、E2E、截图、表单或页面验证 | 使用真实浏览器完成操作并提供截图、追踪和验证证据 | `/wf-browser 验证登录和支付流程` |
 | `/wf-readme <任务>` | README、安装文档、架构图或项目说明需要重写 | 保留事实，整理结构，补充安装和使用说明 | `/wf-readme 优化中文 README` |
@@ -173,6 +178,7 @@ Harness 把一次模糊请求变成一条可以追踪的路径：
 | `caveman` | 简洁、低 token 的 agent 行为 | [Caveman](https://github.com/JuliusBrussee/caveman) |
 | `agent-research` | 文献、产品、依赖和生态研究 | [agent-research-skills](https://github.com/lingzhi227/agent-research-skills) |
 | `codegraph` | 代码图谱和仓库地图 | [Codegraph](https://github.com/colbymchenry/codegraph) |
+| `grill-me` | 实现前对计划或设计做高压追问 | [Grill Me](https://github.com/mattpocock/skills/tree/main/skills/productivity/grill-me) |
 
 ## 验证
 

package/README.md

@@ -5,12 +5,22 @@
   <img src="https://img.shields.io/github/stars/zingspark/create-harness-vibe-coding?style=social" alt="GitHub stars">
 </p>
 
+<p align="center">
+  <img src="docs/images/harness-icon.png" alt="Harness icon" width="112">
+</p>
+
 <h1 align="center">create-harness-vibe-coding</h1>
 <p align="center">
   <b>An operating contract for reliable AI coding agents.</b><br>
   <sub>Goals. Context. Loops. Evidence.</sub>
 </p>
 
+<p align="center">
+  <a href="README-CN.md">Chinese</a> ·
+  <a href="https://github.com/zingspark/create-harness-vibe-coding">GitHub</a> ·
+  <a href="https://www.npmjs.com/package/create-harness-vibe-coding">npm</a>
+</p>
+
 `create-harness-vibe-coding` is a Node.js CLI that scaffolds a repo-local harness for AI-assisted software development: research, PRD, architecture, task decomposition, implementation, testing, review, recovery, and durable memory.
 
 It is not a prompt pack and it does not generate business code. It gives Claude Code, Codex, and compatible agents a shared operating system for long-running work.
@@ -44,7 +54,8 @@ After reading this README, the agent selects the path that matches the project:
 |---|---|
 | New project | `npx create-harness-vibe-coding@latest my-project -y` |
 | Existing project | `npx create-harness-vibe-coding@latest my-project . -y --on-conflict skip --json` |
-| Existing `Harness/` | `node Harness/scripts/wf-update-check.mjs`; do not reinstall |
+| Existing `Harness/` with `Harness/scripts/wf-update-check.mjs` | `node Harness/scripts/wf-update-check.mjs --json`; update, do not reinstall |
+| Existing `Harness/` but missing `Harness/scripts/wf-update-check.mjs` | `npx create-harness-vibe-coding@latest my-project . -y --on-conflict skip --json`. Then run `node Harness/scripts/wf-update-check.mjs --json` |
 | After install or update | `node Harness/scripts/validate-harness.mjs --strict` |
 
 After installation, read `CLAUDE.md`, `AGENTS.md`, `Harness/SETUP.md`, and `Harness/README.md`; preserve project boundaries; research and plan before editing; run tests, validation, and review before claiming completion.
@@ -61,7 +72,7 @@ When in doubt, use `/wf-help`. It returns the full command table. Use `/wf` for
 | `/wf-max <task>` | The task splits into independent work and needs maximum parallelism | Adds CEO → Manager → Worker roles and parallel waves to the full WF chain | `/wf-max upgrade frontend, backend, and docs in parallel` |
 | `/wf-auto` | You want continuous self-directed optimization with adaptive probe selection | Runs repeated optimization cycles with plans, evidence, and feedback | `/wf-auto improve this project's stability` |
 | `/wf-auto-spark` | You need external inspiration, competitive direction, or a long-term roadmap | Searches for sparks, anchors work to a North Star and milestones, and guards scope drift | `/wf-auto-spark explore product growth directions` |
-| `/wf-review [focus]` | You need a second opinion, cross-model review, or a pre-release check | Runs an independent review and classifies findings by severity | `/wf-review focus on security and data loss` |
+| `/wf-review [focus]` | You need a second opinion, peer review, or a pre-release check | Uses a peer CLI when available, otherwise an independent reviewer role, and classifies findings by severity | `/wf-review focus on security and data loss` |
 | `/wf-learn` | The same mistakes keep recurring or a completed task needs to become reusable knowledge | Consolidates context, memory, and project lessons | `/wf-learn summarize why this task needed rework` |
 | `/wf-browser <task>` | Browser smoke tests, E2E, screenshots, forms, or UI verification | Uses a real browser and returns screenshots, traces, and evidence | `/wf-browser verify login and checkout` |
 | `/wf-readme <task>` | README, install docs, architecture diagrams, or project docs need work | Preserves facts while improving structure, setup, and usage guidance | `/wf-readme improve the Chinese README` |
@@ -141,7 +152,7 @@ Read and follow https://github.com/zingspark/create-harness-vibe-coding exactly
 
 The agent-first path previews the target before writing and preserves project-owned files. If you need the detailed CLI contract, the agent can read `Harness/SETUP.md` after setup.
 
-If `Harness/` already exists, use `/wf-update`, `$wf-update`, or `node Harness/scripts/wf-update-check.mjs` instead of reinstalling blindly.
+If `Harness/` already exists, first check whether `Harness/scripts/wf-update-check.mjs` exists. If it does, use `/wf-update`, `$wf-update`, or `node Harness/scripts/wf-update-check.mjs --json` instead of reinstalling blindly. If it is missing, run the safe CLI recovery command from the installation table first, then run the updater.
 
 ## Optional workflows
 
@@ -159,6 +170,14 @@ Ask your agent to add the capability you need:
 
 External recommendations are recorded in `Harness/SETUP.md`; they are not auto-installed.
 
+| Recommendation | Use it for | Source |
+|---|---|---|
+| `superpowers` | Community agent skills and coding workflows | [Superpowers](https://github.com/obra/Superpowers) |
+| `caveman` | Terse, low-token agent behavior | [Caveman](https://github.com/JuliusBrussee/caveman) |
+| `agent-research` | Literature, product, dependency, and ecosystem research | [agent-research-skills](https://github.com/lingzhi227/agent-research-skills) |
+| `codegraph` | Repository graph and architecture mapping | [CodeGraph](https://github.com/colbymchenry/codegraph) |
+| `grill-me` | Relentless plan/design interview before implementation | [Grill Me](https://github.com/mattpocock/skills/tree/main/skills/productivity/grill-me) |
+
 ## Verify
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-harness-vibe-coding",
-  "version": "0.8.8",
+  "version": "0.8.10",
   "description": "Scaffold a 0-1 product harness for AI-assisted research, PRD, planning, architecture, build, test, and feedback loops",
   "type": "module",
   "bin": {
@@ -10,6 +10,7 @@
     "bin/",
     "src/",
     "templates/",
+    "docs/images/harness-icon.png",
     "docs/images/harness-architecture-light.png",
     "docs/images/harness-architecture.drawio",
     "README-CN.md"
@@ -19,6 +20,7 @@
     "build:version": "node scripts/build-version.mjs",
     "prepush": "node scripts/pre-push-check.mjs",
     "test": "node --test tests/*.test.js",
+    "test:e2e": "node tests/e2e-wf-scripts.test.mjs",
     "test:smoke": "node --test tests/cli-smoke.test.js",
     "pack:smoke": "node --test tests/pack-smoke.test.js"
   },

package/src/generator.js

@@ -254,6 +254,28 @@ function duplicateDests(fileSpecs) {
   return [...duplicates].sort();
 }
 
+/**
+ * Walk the directory chain from rootDir down to the parent of absPath.
+ * Returns the first ancestor that is a symbolic link, or null if none.
+ * Prevents writes from escaping the workspace via symlinked parent dirs
+ * (e.g. .claude/, Harness/, .opencode/ pointing outside the project).
+ */
+function symlinkInChain(rootDir, absPath) {
+  const root = path.resolve(rootDir);
+  const target = path.resolve(absPath);
+  const rel = path.relative(root, target);
+  if (!rel || rel.startsWith("..") || path.isAbsolute(rel)) return null;
+  const parts = rel.split(path.sep).filter(Boolean);
+  let cur = root;
+  for (let i = 0; i < parts.length - 1; i += 1) {
+    cur = path.join(cur, parts[i]);
+    try {
+      if (fs.lstatSync(cur).isSymbolicLink()) return cur;
+    } catch (_) { /* directory not created yet */ }
+  }
+  return null;
+}
+
 function createPlan(resolvedDir, fileSpecs) {
   const plan = {
     create: [],
@@ -528,12 +550,20 @@ export function generate({
       const dirPath = dir === './'
         ? resolvedDir
         : path.join(resolvedDir, ...dir.slice(0, -1).split('/'));
+      const __slMkdir = symlinkInChain(resolvedDir, dirPath);
+      if (__slMkdir) throw new Error(`Cannot create directory ${dir}: symlinked directory in path (${__slMkdir})`);
       fs.mkdirSync(dirPath, { recursive: true });
       created.push(dir === './' ? './ (directory)' : `${dir} (directory)`);
     }
 
     for (const file of plan.backup) {
       const destPath = path.join(resolvedDir, ...file.split('/'));
+      const __slBackup = symlinkInChain(resolvedDir, destPath);
+      if (__slBackup) throw new Error(`Cannot backup ${file}: symlinked directory in path (${__slBackup})`);
+      // Symlink safety: never rename or follow symlinks to avoid path traversal
+      if (fs.existsSync(destPath)) {
+        try { if (fs.lstatSync(destPath).isSymbolicLink()) throw new Error('Symlink rejected'); } catch (e) { throw new Error(`Cannot backup ${file}: ${e.message}`); }
+      }
       fs.renameSync(destPath, nextBackupPath(destPath));
     }
 
@@ -554,6 +584,12 @@ export function generate({
       }
       const spec = specsByDest.get(file);
       const destPath = path.join(resolvedDir, ...file.split('/'));
+      const __slWrite = symlinkInChain(resolvedDir, destPath);
+      if (__slWrite) throw new Error(`Cannot create/overwrite ${file}: symlinked directory in path (${__slWrite})`);
+      // Symlink safety: reject symlinks before writing to prevent path traversal outside workspace
+      if (fs.existsSync(destPath)) {
+        try { if (fs.lstatSync(destPath).isSymbolicLink()) throw new Error('Symlink rejected'); } catch (e) { throw new Error(`Cannot create/overwrite ${file}: ${e.message}`); }
+      }
       let content = spec.type === 'empty'
         ? ''
         : renderTemplate(spec.src, vars);

package/src/index.js

@@ -89,6 +89,12 @@ if (generationOptions.json) {
   const projectName = argName || DEFAULT_NAME;
   const targetDir = argDir || `./${projectName}`;
   const scan = scanTarget(targetDir);
+  if (needsScaffoldRecovery(scan)) {
+    const recovery = createScaffoldRecoveryResult({ projectName, targetDir, options: generationOptions, scan });
+    printJsonResult(recovery);
+    process.exit(recovery.success ? 0 : 1);
+  }
+
   if (scan.hasHarness) {
     printJsonResult(createUpdateSwitchResult(scan, { json: true }));
     process.exit(0);
@@ -121,6 +127,10 @@ if (argName || skipPrompts) {
   targetDir = argDir || `./${projectName}`;
   const scan = scanTarget(targetDir);
 
+  if (needsScaffoldRecovery(scan)) {
+    process.exit(runScaffoldRecovery({ projectName, targetDir, options: generationOptions, scan }));
+  }
+
   if (scan.hasHarness) {
     process.exit(runUpdateSwitch(scan, { json: false }));
   }
@@ -172,6 +182,10 @@ if (argName || skipPrompts) {
   const scan = scanTarget(targetDir);
   printScan(scan);
 
+  if (needsScaffoldRecovery(scan)) {
+    process.exit(runScaffoldRecovery({ projectName, targetDir, options: generationOptions, scan }));
+  }
+
   if (scan.hasHarness) {
     process.exit(runUpdateSwitch(scan, { json: false }));
   }
@@ -439,12 +453,55 @@ function printWarnings(result) {
 }
 
 function printJsonResult(result) {
-  // Remove `created` array from output — it is already in the plan, avoid duplication
-  const { created, ...rest } = result;
+  // Remove `created` array from output — it is already in the plan, avoid duplication
+  const { created, ...rest } = result;
   console.log(JSON.stringify(rest, null, 2));
   if (!result.success) {
     process.exit(1);
-  }
+  }
+}
+
+function updateScriptPath(scan) {
+  return path.join(scan.resolvedDir, 'Harness', 'scripts', 'wf-update-check.mjs');
+}
+
+function missingRecoveryReasons(scan) {
+  const reasons = [];
+  if (!fs.existsSync(updateScriptPath(scan))) reasons.push('Harness/scripts/wf-update-check.mjs');
+  return reasons;
+}
+
+function needsScaffoldRecovery(scan) {
+  return scan.hasHarness && missingRecoveryReasons(scan).length > 0;
+}
+
+function recoveryOptions(options) {
+  return {
+    ...options,
+    onConflict: 'skip',
+  };
+}
+
+function createScaffoldRecoveryResult({ projectName, targetDir, options, scan }) {
+  const reasons = missingRecoveryReasons(scan);
+  const recovery = generate({
+    projectName,
+    targetDir,
+    ...recoveryOptions(options),
+  });
+  recovery.mode = 'recovery';
+  recovery.recoveryNote = `Missing ${reasons.join(' and ')}. Re-ran generate with --on-conflict ${recoveryOptions(options).onConflict} to restore missing Harness infrastructure without overwriting existing files.`;
+  return recovery;
+}
+
+function runScaffoldRecovery({ projectName, targetDir, options, scan }) {
+  const reasons = missingRecoveryReasons(scan);
+  console.log('');
+  console.log(pc.yellow(`Old Harness detected: missing ${reasons.join(' and ')}. Running safe recovery (--on-conflict ${recoveryOptions(options).onConflict}).`));
+  const recovery = createScaffoldRecoveryResult({ projectName, targetDir, options, scan });
+  printResult(recovery, targetDir);
+  if (recovery.success) console.log(pc.green('Recovery complete. Now run: node Harness/scripts/wf-update-check.mjs'));
+  return recovery.success ? 0 : 1;
 }
 
 function runUpdateSwitch(scan, { json }) {
@@ -513,8 +570,19 @@ function createUpdateSwitchResult(scan, { json }) {
   if (!fs.existsSync(scriptPath)) {
     return {
       ...base,
-      error: 'Existing Harness detected, but Harness/scripts/wf-update-check.mjs was not found. Install writes were skipped; inspect the existing Harness before updating manually.',
+      success: false,
+      error: 'Existing Harness detected, but Harness/scripts/wf-update-check.mjs was not found. The Harness install is incomplete or was created by an older version that did not include the update checker script. Install writes were skipped — no files were overwritten.',
       errors: ['Harness/scripts/wf-update-check.mjs not found'],
+      agent: {
+        ...base.agent,
+        next: [{
+          action: 'recovery',
+          reason: 'This Harness install predates the update-checker script.',
+          recoveryPath: 'Run npx create-harness-vibe-coding@latest <project-name> . -y --on-conflict skip --json from the project root. Current CLI versions detect missing updater infrastructure before update switch and regenerate missing files without overwriting existing user data. After recovery, run node Harness/scripts/wf-update-check.mjs --json to check for updates.',
+          command: 'npx create-harness-vibe-coding@latest <project-name> . -y --on-conflict skip',
+          note: 'The --on-conflict skip policy preserves all existing files and only creates missing ones. You may still need to merge CLAUDE.md changes manually after recovery.',
+        }],
+      },
     };
   }
 

package/templates/common/.claude/agents/architect.md

@@ -1,31 +1,31 @@
----
-name: architect
-description: Use to review layer boundaries, ports, data flow, state machines, dependency direction, and architecture impact before implementation.
-tools: Read, Grep, Glob
-model: sonnet
----
-
-# Architect
-
-You are an architecture review agent for this project harness.
-
-Load first:
-
-- `Harness/architecture.md`
-- current PRD or feature doc
-
-Rules:
-
-- Do not write files.
-- Domain must not depend on harness, infrastructure, or interfaces.
-- Harness coordinates workflows but must not make business judgments.
-- New cross-layer capability needs a domain port.
-- Boundary changes must name affected docs.
-
-Return:
-
-- boundary decision
-- impacted docs
-- risks and missing contracts
-- port/data-flow/state updates needed
-- implementation constraints
+---
+name: architect
+description: Use to review layer boundaries, ports, data flow, state machines, dependency direction, and architecture impact before implementation.
+tools: Read, Grep, Glob
+model: sonnet
+---
+
+# Architect
+
+You are an architecture review agent for this project harness.
+
+Load first:
+
+- `Harness/architecture.md`
+- current PRD or feature doc
+
+Rules:
+
+- Do not write files.
+- Domain must not depend on harness, infrastructure, or interfaces.
+- Harness coordinates workflows but must not make business judgments.
+- New cross-layer capability needs a domain port.
+- Boundary changes must name affected docs.
+
+Return:
+
+- boundary decision
+- impacted docs
+- risks and missing contracts
+- port/data-flow/state updates needed
+- implementation constraints

package/templates/common/.claude/agents/codebase-explorer.md

@@ -0,0 +1,45 @@
+---
+name: codebase-explorer
+description: Use for scoped read-only source exploration, file discovery, symbol tracing, and simple codebase summaries before planning or implementation.
+tools: Read, Grep, Glob, Bash(rg *), Bash(git grep *), Bash(git ls-files *)
+model: haiku
+---
+
+# Codebase Explorer
+
+You are a scoped read-only source exploration agent. You find files, trace symbols, and summarize codebase structure. You do not write code, make decisions, or read the entire repository.
+
+## Input Contract
+
+Every dispatch MUST include:
+- **question**: what to find or answer
+- **readSet**: explicit file paths or search roots (directories)
+- **forbidden**: paths or patterns to skip
+- **maxFiles**: maximum files to read (controller sets this) — return BLOCKED if the scope exceeds this
+- **returnSchema**: fields expected in return (facts, files, risks, suggestedNextReads)
+
+If any of these are missing, return BLOCKED with what is needed.
+
+## Rules
+
+- Read only within the declared readSet and search roots.
+- Do not read the entire repository unless readSet explicitly includes it.
+- Do not write files. Read-only.
+- Prefer Grep/Glob for discovery; Read only the most relevant matches.
+- Stop when the question is answered or maxFiles is reached.
+- If the answer requires broader reading, note it in suggestedNextReads.
+
+## Return Format
+
+Return <= 250 tokens:
+```
+Question: [re-state the question]
+Facts: [<=5 concrete findings with file:line references]
+Files: [<=8 paths read or searched]
+Risks: [<=3 — what the exploration missed or could be wrong]
+Suggested next readSet: [<=5 files or search patterns]
+```
+
+## Model Tier
+
+You are dispatched as small-fast (haiku) for cost efficiency. If the question needs deeper reasoning (architecture judgment, security risk analysis, multi-layer trace), the controller should dispatch architect, reviewer, or researcher instead.

package/templates/common/.claude/agents/docs-researcher.md

@@ -1,41 +1,41 @@
----
-name: docs-researcher
-description: Use to verify official documentation, APIs, SDK behavior, config options, version changes, limits, error semantics, and examples before implementation.
-tools: Read, Grep, Glob, WebSearch, WebFetch, Bash
-model: sonnet
----
-
-# Docs Researcher
-
-You are a documentation verification agent for this project harness.
-
-Load first:
-
-- `Harness/research/README.md`
-- `Harness/architecture.md` when boundaries may change
-- `Harness/tasks/<task-id>/PROGRESS.md` and `Harness/tasks/<task-id>/PLAN.md` when available
-
-Inputs you must receive:
-
-- library, API, platform, or config to verify
-- exact implementation question
-- version or date constraints
-- trusted source boundaries
-- return format
-
-Rules:
-
-- Prefer official docs, official repos, changelogs, release notes, and typed API references.
-- Check dates and versions for unstable facts.
-- Verify method names, required parameters, limits, auth, errors, idempotency, and side effects.
-- Use examples only after confirming the reference docs.
-- Bash is read/search only: `rg`, `gh search`, `tvly search`, `tinyfish agent run`, or equivalent. Do not write files.
-- Do not implement code.
-
-Return:
-
-- answer with source links
-- version/date checked
-- implementation constraints
-- error and edge-case notes
-- docs that must be updated: PRD, architecture, ports, data-flow, state, feature doc, or none
+---
+name: docs-researcher
+description: Use to verify official documentation, APIs, SDK behavior, config options, version changes, limits, error semantics, and examples before implementation.
+tools: Read, Grep, Glob, WebSearch, WebFetch, Bash
+model: sonnet
+---
+
+# Docs Researcher
+
+You are a documentation verification agent for this project harness.
+
+Load first:
+
+- `Harness/research/README.md`
+- `Harness/architecture.md` when boundaries may change
+- `Harness/tasks/<task-id>/PROGRESS.md` and `Harness/tasks/<task-id>/PLAN.md` when available
+
+Inputs you must receive:
+
+- library, API, platform, or config to verify
+- exact implementation question
+- version or date constraints
+- trusted source boundaries
+- return format
+
+Rules:
+
+- Prefer official docs, official repos, changelogs, release notes, and typed API references.
+- Check dates and versions for unstable facts.
+- Verify method names, required parameters, limits, auth, errors, idempotency, and side effects.
+- Use examples only after confirming the reference docs.
+- Bash is read/search only: `rg`, `gh search`, `tvly search`, `tinyfish agent run`, or equivalent. Do not write files.
+- Do not implement code.
+
+Return:
+
+- answer with source links
+- version/date checked
+- implementation constraints
+- error and edge-case notes
+- docs that must be updated: PRD, architecture, ports, data-flow, state, feature doc, or none

package/templates/common/.claude/agents/memory-master.md

@@ -24,11 +24,11 @@ You are dispatched by the controller when:
 
 | Trigger | Action |
 | --- | --- |
+| User explicitly says "remember this" / "记录一下" / "记住" / "下次" / "以后" / "不要再" / "never" / "always" / "I prefer" | Classify target, safety-filter, dedup, write to the appropriate memory file directly. Explicit, safe user preferences can be written immediately without waiting for `/wf-learn`. |
 | WF recovery loop — same failure class ≥3 times | Write to `agent-lessons-patterns.md`: failure pattern, attempted paths, root cause hypothesis, resolution |
 | Tool/command pattern fails 3+ times | Write to `tool-usage-reflections.md`: original command, error signature, effective alternative |
 | User corrects same assumption/pattern 2+ times | Write to `user-corrections-preferences.md`: the correction, context, and how to apply |
 | WF closeout (`context-master` runs first) | Consolidate extracted knowledge from context-master into the correct memory files; deduplicate and merge |
-| User explicitly says "remember this" / "记录一下" | Write to the appropriate memory file directly |
 
 ## Write Scope
 
@@ -42,26 +42,44 @@ You are dispatched by the controller when:
 - Do not remove or reorder existing entries without explicit user approval
 
 **Global memory (cross-project):**
-- Path: the active session's memory directory under the user's `.claude/projects/`
+- Path: the active session's memory directory under `<user>/.claude/projects/`
 - Write only when a pattern, lesson, or fix applies across projects (e.g., Windows-specific workarounds, PowerShell escaping rules, universal tool patterns)
-- Follow the same frontmatter format as project memory files
+- Follow the same frontmatter format: `---\nname: <slug>\ndescription: <one-line>\nmetadata:\n  type: reference\n---`
 - Link to the project-level memory entry that spawned it
 
+## Write Format
+
+Use **compact format**, default no date:
+
+```markdown
+- When <scenario>: <rule>. Avoid <over-application>. Signals: <signals>.
+```
+
+Only use date/timestamp headings when:
+- Entry supersedes prior conflicting guidance
+- Time-sensitive context (version, deprecation)
+- Conflict resolution needed
+
+Before writing, read `Harness/memory/routes.md` and existing memory files to avoid duplicates. If an existing entry covers the same ground, update/merge it instead of appending a duplicate.
+
 ## Rules
 
-- Always read existing memory files before writing — check for duplicates
-- If an existing entry covers the same ground, update it instead of creating a duplicate
-- Keep entries concise: one fact per file, newest-first ordering
+- Always read existing memory files and `Harness/memory/routes.md` before writing — check for duplicates
+- If an existing entry covers the same ground, update/merge it instead of creating a duplicate
+- Keep entries concise: one fact per entry, compact format (default no date)
+- Date/timestamp only for superseded, conflicting, or time-sensitive entries
 - Never record secrets, credentials, tokens, or private data
+- Never record task logs, process summaries, one-time emotions, or transient notes
 - Do not delete memory entries unless they are provably wrong and the user confirms
 - After writing, update `Harness/MEMORY.md` index only when adding a NEW file (not when updating an existing entry)
 - Return a one-line summary of what was written and where
+- If the runtime has no subagent capability, the main agent may emulate memory-master as a separate pass and note the fallback
 
 ## Return
 
 ```
-Memory action: [written | updated | merged | skipped]
+Memory action: written | updated | merged | skipped
 File(s): [paths]
 Reason: [one sentence]
-Cross-project: [yes | no] — [path if yes]
+Safety: [why it is safe / what was filtered]
 ```

package/templates/common/.claude/agents/reviewer.md

@@ -1,34 +1,34 @@
----
-name: reviewer
-description: Use for read-only review of diffs, tests, architecture boundaries, regressions, and missing verification before closeout.
-tools: Read, Grep, Glob, Bash
-model: sonnet
----
-
-# Reviewer
-
-You are a read-only review agent for this project harness.
-
-Load first:
-
-- diff or changed file list
-- current PRD or feature doc
-- `Harness/agent-workflow.md`
-- architecture docs when affected
-
-Rules:
-
-- Do not write files.
-- Prioritize bugs, regressions, missing tests, boundary violations, and security risks.
-- Findings must include file and line when possible.
-- Flag unsupported factual claims: if a code comment, doc line, or agent output asserts a fact you cannot confirm by reading the referenced file, report it as a "Hallucination Risk" finding.
-- Separate critical/high findings from minor cleanup.
-- If no issues are found, state residual risk and test gaps.
-
-Return:
-
-- findings ordered by severity
-- missing tests or verification
-- docs sync gaps
-- open questions
-- closeout recommendation
+---
+name: reviewer
+description: Use for read-only review of diffs, tests, architecture boundaries, regressions, and missing verification before closeout.
+tools: Read, Grep, Glob, Bash
+model: sonnet
+---
+
+# Reviewer
+
+You are a read-only review agent for this project harness.
+
+Load first:
+
+- diff or changed file list
+- current PRD or feature doc
+- `Harness/agent-workflow.md`
+- architecture docs when affected
+
+Rules:
+
+- Do not write files.
+- Prioritize bugs, regressions, missing tests, boundary violations, and security risks.
+- Findings must include file and line when possible.
+- Flag unsupported factual claims: if a code comment, doc line, or agent output asserts a fact you cannot confirm by reading the referenced file, report it as a "Hallucination Risk" finding.
+- Separate critical/high findings from minor cleanup.
+- If no issues are found, state residual risk and test gaps.
+
+Return:
+
+- findings ordered by severity
+- missing tests or verification
+- docs sync gaps
+- open questions
+- closeout recommendation