@heihei0299/matt-skills 1.3.0 → 1.3.2

package/README.md

@@ -11,7 +11,7 @@ template/
 └── .opencode/        分发内容（目标仓库的 opencode 项目配置）
     ├── skills/       5 个独有技能（tdd-implement、grill-to-spec、diagnose-fix、commit-check、instance-test）
     ├── agents/       issue-audit 子代理定义
-    ├── commands/     issue-audit + 9 个显式触发技能命令（grill-to-spec/wayfinder/to-spec/to-tickets/triage/improve-codebase-architecture/teach/handoff/writing-great-skills）
+    ├── commands/     issue-audit + 9 个显式触发技能命令（grill-to-spec/wayfinder/to-spec/to-tickets/triage/improve-codebase-architecture/teach/handoff/writing-for-agents）
     ├── docs/agents/  5 个分文件（运行时纪律 / 技能设计 / issue tracker / triage labels / domain）
     ├── CONTEXT.md    术语表
     ├── package.json  插件依赖清单
@@ -36,11 +36,13 @@ npx @heihei0299/matt-skills init
 **增量同步（已有项目）**：已有项目更新到最新模板与技能：
 
 ```sh
-npx @heihei0299/matt-skills sync            # 增量同步，直接更新
-npx @heihei0299/matt-skills sync --force    # 同上（直接覆盖）
+npx @heihei0299/matt-skills sync                                 # 默认仅对比不写盘（check），有差异 exit 1，--json 可解析
+npx @heihei0299/matt-skills sync --apply                         # 安全增量：AGENTS.md 定制跳过，上游技能强制覆盖但不删
+npx @heihei0299/matt-skills sync --force                         # 硬盖：AGENTS.md 备份后硬盖，技能与模板全量 add/update/remove
+npx @heihei0299/matt-skills sync --apply --dest <path> --upstream <url> --ref <ref> --json  # 选项可组合
 ```
 
-`sync` 专为已有项目设计：自动检测 `AGENTS.md` 是否存在，存在则增量更新模板与上游技能（直接覆盖，`AGENTS.md` 会备份），不存在则等同全新 `init`。与 `init --force` 的区别：`sync` 语义更明确，建议已有项目优先用 `sync`。
+`sync` 专为已有项目设计，三档语义：默认 `check` 仅对比不写盘（打印“上游 HEAD / 本地非独有 vs 上游 / 新增/更新/删除/一致”表，`--json` 可解析，有差异 `exit 1`）；`--apply` 安全增量写盘（`AGENTS.md` 若含独有路由如 `tdd-implement` 则跳过，`.agents/skills` 对上游技能 `rm+cp force` 覆盖但不 `remove`，`template/.opencode/.pi` 增量 `add/update`）；`--force` 硬盖（`AGENTS.md` 备份 `.bak` 后强制覆盖，技能与模板均 `add/update/remove` 全做）。`--dest`、`--upstream`、`--ref`、`--json` 在三档均可透传。
 
 上游没有 `tdd-implement`、`grill-to-spec`、`diagnose-fix`、`commit-check`，复制天然不冲突。目标仓库会话即自动加载全部技能（上游在 `.agents/skills/`、独有在 `.opencode/skills/`；pi 侧独有在 `.pi/skills/`）与项目级全局配置（行为路由表、分文件约定）；`issue-audit` 以子代理 + 命令形式分发（`.opencode/agents/`、`.opencode/commands/`）；9 个显式触发技能注册为 opencode 命令（`.opencode/commands/`，`/命令名` 触发）。
 
@@ -115,14 +117,16 @@ pi 下对应能力以内置工具或已装扩展为准（`AGENTS.md`「能力边
 仓库内提供安装管理 CLI（`bin/cli.js`，依赖 `prompts`，见 `package.json`），同时作为 npm 包 `@heihei0299/matt-skills` 分发（`npx @heihei0299/matt-skills <command>`）：
 
 ```sh
-node bin/cli.js init [--dest <dir>] [--force]   # 初始化项目：template + 上游技能
-node bin/cli.js sync [--dest <dir>] [--force]   # 同步已有项目到最新（直接覆盖）
-node bin/cli.js list [--json]                   # 列出 .agents/skills/ 下全部技能及描述
-node bin/cli.js install [选项]                  # 把技能复制到目标工具目录（交互式选择）
+node bin/cli.js init [--dest <dir>] [--force]                                           # 初始化项目：template + 上游技能
+node bin/cli.js sync [--apply|--force] [--dest <path>] [--upstream <url>] [--ref <ref>] [--json]  # 同步已有项目到最新
+node bin/cli.js list [--json]                                                           # 列出 .agents/skills/ 下全部技能及描述
+node bin/cli.js install [选项]                                                          # 把技能复制到目标工具目录（交互式选择）
+node bin/cli.js check [--json] [--upstream <url>] [--ref <ref>]                        # 只读检查上游技能是否最新（等价 sync 默认）
 ```
 
-`init` 选项：`--dest <dir>` 指定目标目录（默认当前目录）；`--force` 覆盖已存在的文件（直接覆盖，`AGENTS.md` 会备份到 `.bak`）（默认跳过），见「初始化」。
-`sync` 选项：`--dest <dir>` 指定目标目录；`--force` 直接覆盖（与默认一致），见「初始化」增量同步。
+`init` 选项：`--dest <path>` 指定目标目录（默认当前目录）；`--force` 覆盖已存在的文件（直接覆盖，`AGENTS.md` 会备份到 `.bak`）（默认跳过），见「初始化」。
+`sync` 选项：`--apply` 安全增量（`AGENTS.md` 定制跳过、技能不删），`--force` 硬盖（`AGENTS.md` 备份后硬盖、技能与模板全量 `remove`）；`--dest <path>` 目标目录；`--upstream <url>` 上游地址；`--ref <ref>` 上游分支；`--json` JSON 输出；默认无参等价 `check` 仅对比不写盘，`--json` 可解析，有差异 `exit 1`。
+`check` 选项：`--json`、`--upstream <url>`、`--ref <ref>`（等价 `sync` 默认 `check`）。
 
 `install` 选项：
 
@@ -136,15 +140,15 @@ node bin/cli.js install [选项]                  # 把技能复制到目标工
 
 本仓库的 `.agents/skills/` 中 **非独有技能** 来自 `mattpocock/skills` 上游。已实现双通道自动同步：
 
-- **本地 CLI**：`matt-skills check`（只读比对）与 `matt-skills update`（一键覆盖本地 `.agents/skills/`，自动处理 `writing-great-skills → writing-for-agents` 重命名与增删）
+- **本地 CLI**：`matt-skills sync` 三档——默认 `check` 只读比对（等价 `matt-skills check`，有差异 `exit 1`，`--json` 可解析）、`matt-skills sync --apply` 安全增量、`matt-skills sync --force` 硬盖；`matt-skills check [--json] [--upstream <url>] [--ref <ref>]` 仍保留为只读别名；`matt-skills update` 已合并到 `sync --apply`（执行提示 `update 已合并到 sync --apply` 且 `exit 1`）
 - **GitHub Actions**：`.github/workflows/sync-upstream.yml` 每周一 02:00 UTC 自动 `check`，有差异则 `apply` 并提 PR（`upstream-sync/<short-sha>`），支持 `workflow_dispatch` 手动触发（`ref`/`dry_run` 参数）
 
 ```sh
-npx @heihei0299/matt-skills check                    # 只读检查，对比本地 vs 上游 HEAD（有差异 exit 1）
-npx @heihei0299/matt-skills check --json             # JSON 输出：{ head, counts, result: { added, updated, renamed, removed, same } }
-npx @heihei0299/matt-skills update --dry-run         # 演练，不写文件
-npx @heihei0299/matt-skills update                   # 覆盖 .agents/skills 非独有技能
-node scripts/sync-upstream.js --check               # 等价底层脚本（CLI check/update 的实现）
+npx @heihei0299/matt-skills sync --json              # 默认 check 只读检查，JSON 输出：{ head, counts, result: { added, updated, renamed, removed, same } }
+npx @heihei0299/matt-skills sync --apply             # 安全增量写盘
+npx @heihei0299/matt-skills sync --force             # 硬盖写盘
+npx @heihei0299/matt-skills check --json             # 等价 sync 默认 check
+node scripts/sync-upstream.js --check               # 等价底层脚本（CLI sync/check 的实现）
 node scripts/sync-upstream.js --apply --dry-run
 ```
 

package/bin/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { readdir, readFile, cp, stat } from 'node:fs/promises';
+import { readdir, readFile, cp, stat, rm, mkdir } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -17,31 +17,27 @@ const HELP = `matt-skills — install and manage this skill collection
 
 Usage:
   matt-skills init [options]                   Initialize a project: template + upstream skills
-  matt-skills sync [options]                   Sync existing project to latest template + skills
+  matt-skills sync [--apply|--force] [--dest <path>] [--upstream <url>] [--ref <ref>] [--json]   Sync existing project to latest template + skills
   matt-skills list [--json]                    List available skills and their descriptions
   matt-skills install [options]                Install skills (interactive by default)
   matt-skills check [--json] [--upstream <url>] [--ref <ref>]
                                               Check if upstream skills are up to date (read-only)
-  matt-skills update [--dry-run] [--force] [--upstream <url>] [--ref <ref>]
-                                              Update .agents/skills from upstream (auto handles renames)
   matt-skills --help                          Show this help
 
 Init options:
   --dest <path>   Target directory (default: current directory)
   --force         Overwrite existing files
 Sync options:
+  --apply         Apply changes (safe incremental, respects custom AGENTS.md)
+  --force         Hard overwrite (backup .bak + full sync)
   --dest <path>   Target directory (default: current directory)
-  --force         Overwrite existing files
+  --upstream <url> Upstream repo URL (default: https://github.com/mattpocock/skills.git)
+  --ref <ref>     Upstream ref (default: HEAD)
+  --json          Output as JSON
 Check options:
   --json          Output as JSON
   --upstream <url> Upstream repo URL (default: https://github.com/mattpocock/skills.git)
   --ref <ref>     Upstream ref (default: HEAD)
-Update options:
-  --dry-run       Show what would change without writing files
-  --force         Force overwrite (default is to overwrite; kept for compatibility)
-  --upstream <url> Upstream repo URL
-  --ref <ref>     Upstream ref
-
 Install options:
   --tools <a,b>   Install for the given tools (codex, pi, opencode, claude); skips tool selection
   --all           Install all skills; skips skill selection
@@ -224,22 +220,69 @@ async function initCommand({ dest, force }) {
   process.stdout.write(`目标路径：${target}\n`);
 }
 
-async function syncCommand({ dest, force }) {
+async function syncCommand({ dest, force, apply, upstreamUrl, ref, json }) {
+  // 默认：仅对比不写盘 (check 模式)，--apply / --force 显式写盘
+  const doApply = apply || force;
+  if (!doApply) {
+    const { compare } = await import('../scripts/sync-upstream.js');
+    const cmp = await compare({ upstreamUrl, ref });
+    if (json) {
+      process.stdout.write(JSON.stringify({ head: cmp.head, counts: cmp.counts, result: cmp.result }, null, 2) + '\n');
+    } else {
+      const lines = [];
+      lines.push(`上游 HEAD: ${cmp.head}`);
+      lines.push(`本地非独有: ${cmp.counts.local}  上游: ${cmp.counts.upstream}`);
+      lines.push('');
+      const totalDiff = cmp.result.added.length + cmp.result.updated.length + cmp.result.removed.length + cmp.result.renamed.length;
+      if (totalDiff === 0) {
+        lines.push('✅ 已是最新，无差异');
+      } else {
+        if (cmp.result.added.length) lines.push(`新增 (${cmp.result.added.length}): ${cmp.result.added.join(', ')}`);
+        if (cmp.result.updated.length) lines.push(`更新 (${cmp.result.updated.length}): ${cmp.result.updated.join(', ')}`);
+        if (cmp.result.renamed.length) lines.push(`重命名 (${cmp.result.renamed.length}): ${cmp.result.renamed.map((r) => `${r.from}→${r.to}`).join(', ')}`);
+        if (cmp.result.removed.length) lines.push(`删除 (${cmp.result.removed.length}): ${cmp.result.removed.join(', ')}`);
+        if (cmp.result.same.length) lines.push(`一致 (${cmp.result.same.length}): ${cmp.result.same.join(', ')}`);
+      }
+      process.stdout.write(lines.join('\n') + '\n');
+    }
+    const { rm } = await import('node:fs/promises');
+    await rm(cmp.dest, { recursive: true, force: true });
+    const hasDiff = cmp.result.added.length + cmp.result.updated.length + cmp.result.removed.length + cmp.result.renamed.length > 0;
+    if (hasDiff) process.exitCode = 1;
+    return;
+  }
+
   const target = dest ? path.resolve(process.cwd(), dest) : process.cwd();
   const marker = path.join(target, 'AGENTS.md');
-  const backup = !force;
   if (!(await pathExists(marker))) {
     process.stdout.write('未检测到现有项目（AGENTS.md 不存在），将执行全新初始化\n');
     await cp(TEMPLATE_DIR, target, { recursive: true, force: true });
     process.stdout.write('模板：已复制（AGENTS.md、.opencode/、.pi/）\n');
-  } else {
+  } else if (force) {
     process.stdout.write('同步：检测到现有项目，将增量更新\n');
-    if (backup) {
-      const cur = path.join(target, 'AGENTS.md');
-      if (await pathExists(cur)) await backupIfExists(cur);
+    await backupIfExists(path.join(target, 'AGENTS.md'));
+    await cp(TEMPLATE_DIR, target, { recursive: true, force: true });
+    process.stdout.write('模板：已覆盖（AGENTS.md、.opencode/、.pi/）\n');
+  } else if (apply) {
+    process.stdout.write('同步：检测到现有项目，将增量更新\n');
+    let skipAgents = false;
+    try {
+      const content = await readFile(path.join(target, 'AGENTS.md'), 'utf8');
+      if (content.includes('tdd-implement')) skipAgents = true;
+    } catch {}
+    if (skipAgents) {
+      await cp(path.join(TEMPLATE_DIR, '.opencode'), path.join(target, '.opencode'), { recursive: true, force: true });
+      await cp(path.join(TEMPLATE_DIR, '.pi'), path.join(target, '.pi'), { recursive: true, force: true });
+      process.stdout.write('模板：已同步（AGENTS.md 跳过，已含定制）\n');
+    } else {
+      await cp(TEMPLATE_DIR, target, { recursive: true, force: true });
+      process.stdout.write('模板：已同步（AGENTS.md、.opencode/、.pi/）\n');
     }
+  } else {
+    // fallback for any other doApply case (should not reach here because !doApply already returned)
+    process.stdout.write('同步：检测到现有项目，将增量更新\n');
     await cp(TEMPLATE_DIR, target, { recursive: true, force: true });
-    process.stdout.write(backup ? '模板：已同步（AGENTS.md、.opencode/、.pi/）\n' : '模板：已覆盖（AGENTS.md、.opencode/、.pi/）\n');
+    process.stdout.write('模板：已同步（AGENTS.md、.opencode/、.pi/）\n');
   }
   const entries = await readdir(SKILLS_DIR, { withFileTypes: true });
   const upstream = entries
@@ -247,6 +290,7 @@ async function syncCommand({ dest, force }) {
     .map((e) => e.name)
     .sort();
   const skillsDir = path.join(target, '.agents', 'skills');
+  await mkdir(skillsDir, { recursive: true });
   let installed = 0;
   let updated = 0;
   for (const name of upstream) {
@@ -258,6 +302,7 @@ async function syncCommand({ dest, force }) {
     }
     const exists = await pathExists(dst);
     if (exists) {
+      await rm(dst, { recursive: true, force: true });
       await cp(src, dst, { recursive: true, force: true });
       updated++;
     } else {
@@ -265,6 +310,20 @@ async function syncCommand({ dest, force }) {
       installed++;
     }
   }
+  if (force) {
+    let localEntries = [];
+    try {
+      localEntries = await readdir(skillsDir, { withFileTypes: true });
+    } catch {}
+    for (const e of localEntries) {
+      if (!e.isDirectory()) continue;
+      if (e.name.endsWith('.bak')) continue;
+      if (e.name === '.git') continue;
+      if (PROPRIETARY_SKILLS.has(e.name)) continue;
+      if (upstream.includes(e.name)) continue;
+      await rm(path.join(skillsDir, e.name), { recursive: true, force: true });
+    }
+  }
   process.stdout.write(`上游技能：新增 ${installed}、更新 ${updated}\n`);
   process.stdout.write(`目标路径：${target}\n`);
 }
@@ -272,13 +331,23 @@ async function syncCommand({ dest, force }) {
 function parseInitArgs(args) {
   let dest;
   let force = false;
+  let apply = false;
+  let json = false;
+  let upstreamUrl;
+  let ref;
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
     if (arg === '--dest') dest = args[++i];
     else if (arg.startsWith('--dest=')) dest = arg.slice('--dest='.length);
     else if (arg === '--force') force = true;
+    else if (arg === '--apply') apply = true;
+    else if (arg === '--json') json = true;
+    else if (arg === '--upstream') upstreamUrl = args[++i];
+    else if (arg.startsWith('--upstream=')) upstreamUrl = arg.slice('--upstream='.length);
+    else if (arg === '--ref') ref = args[++i];
+    else if (arg.startsWith('--ref=')) ref = arg.slice('--ref='.length);
   }
-  return { dest, force };
+  return { dest, force, apply, json, upstreamUrl, ref };
 }
 
 function parseInstallArgs(args) {
@@ -337,44 +406,6 @@ async function checkCommand(args) {
   if (hasDiff) process.exitCode = 1;
 }
 
-async function updateCommand(args) {
-  const { applySync } = await import('../scripts/sync-upstream.js');
-  const dryRun = args.includes('--dry-run');
-  const json = args.includes('--json');
-  const upstreamIdx = args.indexOf('--upstream');
-  const upstreamUrl = upstreamIdx !== -1 ? args[upstreamIdx + 1] : undefined;
-  const refIdx = args.indexOf('--ref');
-  const ref = refIdx !== -1 ? args[refIdx + 1] : undefined;
-  const res = await applySync({ upstreamUrl, ref, dryRun });
-  if (json) {
-    process.stdout.write(JSON.stringify({ head: res.head, result: res.result, actions: res.actions, dryRun }, null, 2) + '\n');
-  } else {
-    const lines = [];
-    lines.push(`上游 HEAD: ${res.head}`);
-    lines.push(`本地非独有: ${res.counts.local}  上游: ${res.counts.upstream}`);
-    lines.push('');
-    const totalDiff = res.result.added.length + res.result.updated.length + res.result.removed.length + res.result.renamed.length;
-    if (totalDiff === 0) {
-      lines.push('✅ 已是最新，无差异');
-    } else {
-      if (res.result.added.length) lines.push(`新增 (${res.result.added.length}): ${res.result.added.join(', ')}`);
-      if (res.result.updated.length) lines.push(`更新 (${res.result.updated.length}): ${res.result.updated.join(', ')}`);
-      if (res.result.renamed.length) lines.push(`重命名 (${res.result.renamed.length}): ${res.result.renamed.map((r) => `${r.from}→${r.to}`).join(', ')}`);
-      if (res.result.removed.length) lines.push(`删除 (${res.result.removed.length}): ${res.result.removed.join(', ')}`);
-      if (res.result.same.length) lines.push(`一致 (${res.result.same.length}): ${res.result.same.join(', ')}`);
-    }
-    process.stdout.write(lines.join('\n') + '\n');
-    if (res.actions.length) {
-      process.stdout.write(`\n已执行 ${res.actions.length} 项:\n`);
-      for (const a of res.actions) process.stdout.write(`  - ${a}\n`);
-    }
-    if (dryRun) process.stdout.write('\n(dry-run，未写文件)\n');
-  }
-  if (!dryRun && res.actions.length) {
-    process.stdout.write('\n提示：请运行 npm test 验证，并按需执行 npm run build:template 更新模板镜像\n');
-  }
-}
-
 async function main() {
   const args = process.argv.slice(2);
   if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
@@ -410,7 +441,8 @@ async function main() {
     return;
   }
   if (command === 'update') {
-    await updateCommand(rest);
+    process.stderr.write('update 已合并到 sync --apply\n');
+    process.exitCode = 1;
     return;
   }
   process.stderr.write(HELP);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heihei0299/matt-skills",
-  "version": "1.3.0",
+  "version": "1.3.2",
   "description": "Agent skills + 项目配置模板：一条命令初始化 opencode / pi-agent 项目（含 mattpocock/skills 上游技能）",
   "type": "module",
   "bin": {

package/template/.opencode/CONTEXT.md

@@ -32,6 +32,10 @@ _Avoid_: inheriting repo, child repo
 The one-time action of setting up a Target Repository: copying `template/` into its root (`cp -r template/. <target>/`), then fetching the 22 upstream skills from the Upstream Repository. Copying, not inheriting — no runtime relationship survives the copy.
 _Avoid_: inherit, bootstrap
 
+**Sync** (同步):
+`matt-skills sync` 同步 Target Repository 的模板与上游技能：默认仅对比不写盘（`check`），`--apply` 为安全增量（`AGENTS.md` 有定制如 `tdd-implement` 则跳过，上游技能直接强制覆盖 `rm+cp` 但不 `remove`，独有技能与 `template/.opencode/.pi` 增量 `add/update`）、`--force` 为硬盖（`AGENTS.md` 备份 `.bak` 后强制覆盖，技能与模板全量 `add/update/remove`）。`update` 已合并到 `sync` 并删除。
+_Avoid_: update, force sync
+
 ## Skill Design
 
 **Turn Continuity** (回合连续性):

package/template/.opencode/commands/{writing-great-skills.md → writing-for-agents.md}

@@ -4,7 +4,7 @@ description: 技能写作参考——编写和编辑技能的最佳实践（词
 
 # Writing Great Skills
 
-加载并执行 writing-great-skills 技能，编写/编辑技能：
+加载并执行 writing-for-agents 技能，编写/编辑技能：
 
 **主题：** $ARGUMENTS
 

package/template/.opencode/docs/agents/skill-design.md

@@ -7,11 +7,11 @@ This spec exists because of a real incident: a long-horizon skill run on a flash
 
 Every **Long-Horizon Skill** must carry a positive **Turn Continuity** rule of its own: the consecutive actions of a stage (red → green → typecheck → next seam) are executed serially **within one turn**, until the stage's exit condition is met. Do not end the turn at "announce the next step" points, and do not wait for the user to say "continue".
 
-- State it **positively** (per the negation principle in `writing-great-skills`): describe the target behaviour, never the banned one.
+- State it **positively** (per the negation principle in `writing-for-agents`): describe the target behaviour, never the banned one.
 - It must be **self-contained** — the skill cannot rely on the harness `/goal` line, because no `/goal` exists when the user does not activate one.
 - Every stage ends on a checkable exit condition; reaching it is the only thing that ends the turn.
 - A sub-step going green (e.g. one seam) is not a stage exit — a stage ends only when all of its seams are complete. Progress output does not itself end the turn: output, then keep executing until one of the three endpoints (compliance checkpoint, external blocker, stage exit) is reached.
-- Canonical example: the 回合连续性 rule in [`.agents/skills/tdd-implement/references/stages.md`](../../skills/tdd-implement/references/stages.md) stage ③.
+- Canonical example: the 回合连续性 rule in [`.agents/skills/tdd-implement/references/stages.md`](.agents/skills/tdd-implement/references/stages.md) stage ③.
 
 ## Rule 2 — Model Selection
 
@@ -31,7 +31,7 @@ Every skill that touches git must preserve history after `BASE_HEAD`: history ma
 
 To achieve "directory clean" (`git status` clean) the skill may only delete its own temporary artifacts (`[DEBUG-...]`, one-off scripts, untracked probe files) — it must never use git-level destructive commands to reach a clean state. The following are forbidden without explicit user confirmation: `git reset --hard`, `git checkout .`, `git clean -fd`, `git stash push --include-untracked` (use `--keep-index` instead and `pop` with verification), `git push --force`, `git rebase -i` and any `reset`/`checkout` that moves `HEAD` backward.
 
-Canonical enforcement: [`tdd-implement/references/stages.md`](../../skills/tdd-implement/references/stages.md) stage ③/⑥/⑦/A2-A4 Git 安全红线 and [`commit-check/SKILL.md`](../../skills/commit-check/SKILL.md) ③ 目录卫生.
+Canonical enforcement: [`tdd-implement/references/stages.md`](.agents/skills/tdd-implement/references/stages.md) stage ③/⑥/⑦/A2-A4 Git 安全红线 and [`commit-check/SKILL.md`](.agents/skills/commit-check/SKILL.md) ③ 目录卫生.
 ## Long-horizon skills inventory
 
 Skills currently classified as Long-Horizon, to be evolved against these rules as they are touched: `tdd-implement` (fixed), `diagnose-fix` (fixed — new orchestration skill for diagnosis + TDD fix, carries its own Turn Continuity rule), `diagnosing-bugs`, `improve-codebase-architecture`, `wayfinder`, `grill-to-spec`, `to-spec`. Backfilling existing skill texts is out of scope for now — these rules bind new and edited skills going forward.

package/template/.pi/CONTEXT.md

@@ -0,0 +1,55 @@
+# matt-skills
+
+The domain vocabulary for this repo — two sections: how this repository is positioned (`## Repository`) and the terms that govern how long-horizon skills are written, reviewed, and evolved (`## Skill Design`). Every term here is a single source of truth; skills and docs reference it rather than restating the definition.
+
+## Repository
+
+**Template Repository** (模板仓库):
+This repository's identity. It is the config repo for mattpocock/skills: it distributes project-level config (AGENTS.md behavior routing, `.opencode/docs/agents/` discipline files, `.opencode/CONTEXT.md` glossary) plus only the Proprietary Skills, not the upstream skill copies. The workspace content is mirrored into `template/` as a Template Snapshot, and initializing a Target Repository is a one-time copy of that snapshot. The workspace copy also serves this repo's own sessions.
+_Avoid_: skill distribution repo
+
+**Upstream Repository** (上游仓库):
+mattpocock/skills — the source of the 22 skill bodies (skills/engineering, 17 skills; skills/productivity, 5 skills) that target repos fetch manually per the README. This repo never copies upstream skills into `template/`.
+_Avoid_: source repo, skill origin
+
+**Proprietary Skill** (独有技能):
+A skill that does not exist upstream and lives only in this repo (currently tdd-implement, grill-to-spec, diagnose-fix and commit-check). Before adding a new skill, check the Upstream Repository first; only skills absent there qualify as proprietary. The issue-audit subagent is NOT a skill: it ships as a subagent + command under `.opencode/` and is distributed through the Template Snapshot without a skill directory.
+_Avoid_: private skill, local skill
+
+**Workspace** (工作区):
+The root-level working copies of the template content — `.agents/skills/` (proprietary skill sources), `.opencode/` (issue-audit agent, explicit-skill commands, plugin manifests), `.pi/` (pi-agent project config: `.pi/skills/` + `.pi/prompts/` issue-audit command), `AGENTS.md`, `CONTEXT.md`, `docs/`. Where this repo's own sessions load, modify, and test the content. The template paths mirror them with a path mapping: `.agents/skills/{tdd-implement,grill-to-spec,diagnose-fix,commit-check}` → `template/.opencode/skills/` and `template/.pi/skills/` (dual mirror), `.opencode/commands/*.md` → `template/.opencode/commands/`, `.pi/prompts/issue-audit.md` → `template/.pi/prompts/issue-audit.md`, root-level `CONTEXT.md` and `docs/agents/` → `template/.opencode/`.
+_Avoid_: working copy, source repo
+
+**Template Snapshot** (模板快照):
+Everything under `template/` — the mirror of the workspace content with the path mapping above (proprietary skills land under `.opencode/skills/` and `.pi/skills/`, opencode commands under `.opencode/commands/`, the pi issue-audit command under `.pi/prompts/`, discipline files and glossary under `.opencode/`, AGENTS.md at the top level), generated by manual sync, used to initialize other repositories. There is no release pipeline; the sync direction is one-way: workspace → snapshot. `test/template-sync.test.js` guards the mirror stays in sync.
+_Avoid_: release snapshot, published snapshot
+
+**Target Repository** (目标仓库):
+A repository initialized by copying `template/` into its root and then fetching the upstream skills per the README. It then loads the upstream skills from its own `.agents/skills/`, the Proprietary Skills from `.opencode/skills/` (directly under opencode) and `.pi/skills/` (auto-discovered under pi), the explicit-skill commands from `.opencode/commands/` (opencode) and the `issue-audit` command from `.pi/prompts/` (pi) / `.opencode/commands/` (opencode), and the project-level global config from `.opencode/` and `AGENTS.md`.
+_Avoid_: inheriting repo, child repo
+
+**Initialize** (初始化):
+The one-time action of setting up a Target Repository: copying `template/` into its root (`cp -r template/. <target>/`), then fetching the 22 upstream skills from the Upstream Repository. Copying, not inheriting — no runtime relationship survives the copy.
+_Avoid_: inherit, bootstrap
+
+**Sync** (同步):
+`matt-skills sync` 同步 Target Repository 的模板与上游技能：默认仅对比不写盘（`check`），`--apply` 为安全增量（`AGENTS.md` 有定制如 `tdd-implement` 则跳过，上游技能直接强制覆盖 `rm+cp` 但不 `remove`，独有技能与 `template/.opencode/.pi` 增量 `add/update`）、`--force` 为硬盖（`AGENTS.md` 备份 `.bak` 后强制覆盖，技能与模板全量 `add/update/remove`）。`update` 已合并到 `sync` 并删除。
+_Avoid_: update, force sync
+
+## Skill Design
+
+**Turn Continuity** (回合连续性):
+The rule that a long-horizon skill must carry a positive instruction to keep executing within a turn — red → green → typecheck → next seam serial in one turn until the stage's exit condition is met. The stage exit is reached when all of its seams are complete — one seam going green is not an exit, and progress output does not itself end the turn. It is the skill's own guard against premature turn-end; it must not rely on the harness `/goal` line (which does not exist when no `/goal` is active).
+_Avoid_: keep going, don't stop
+
+**Chunking** (拆小步 / 进度编排):
+Splitting a giant turn — one large `write` or a batch of `replace`s — into small steps that are individually verified before continuing, so the turn never hits output caps and gets truncated mid-work.
+_Avoid_: step-by-step, take it slow
+
+**Git History Preservation** (Git 历史保护):
+Every git-touching skill must preserve history after `BASE_HEAD=$(git rev-parse HEAD)` recorded at stage entry — history may only be appended. Before any commit or stage exit, verify `git merge-base --is-ancestor $BASE_HEAD HEAD`; if it fails, history was rewritten and must be recovered via `git reflog` before continuing. "Directory clean" (`git status` clean) may only be achieved by deleting the skill's own temporary artifacts (`[DEBUG-...]`, one-off scripts, untracked probe files); destructive git commands `git reset --hard`, `git checkout .`, `git clean -fd`, `git stash push --include-untracked`, `git push --force`, `git rebase -i` are forbidden without explicit user confirmation.
+_Avoid_: force clean, stash all
+
+**Long-Horizon Skill** (长程多阶段技能):
+A skill whose run spans multiple stages or seams executed continuously (e.g. tdd-implement, diagnosing-bugs, improve-codebase-architecture, wayfinder, grill-to-spec, to-spec). The class of skill that must carry a Turn Continuity rule.
+_Avoid_: complex skill, big skill

package/template/.pi/docs/agents/runtime-discipline.md

@@ -1,6 +1,6 @@
 # Runtime Discipline
 
-本仓库会话的运行时纪律，执行口径源自 `.opencode/docs/agents/skill-design.md` 的三条规则（规范正文）。术语定义见 `.opencode/CONTEXT.md`。
+本仓库会话的运行时纪律，执行口径源自 `docs/agents/skill-design.md` 的四条规则（规范正文）。术语定义见 `CONTEXT.md`。
 
 ## 回合连续性规则
 
@@ -11,7 +11,7 @@
 - 外部阻塞：权限拒绝、缺失授权、依赖不可用——明确说明所需授权或替代路径，不静默停止
 - 阶段完成：整个阶段的出口条件满足（如 seam 全绿、typecheck 通过、commit 完成）
 
-预告下一步后立即执行该步骤，禁止把"分析/预告"当作回合终点。随包示例见 `.opencode/skills/tdd-implement/SKILL.md` 与 `references/stages.md` 阶段③ 3e。
+预告下一步后立即执行该步骤，禁止把"分析/预告"当作回合终点。随包示例见 `.agents/skills/tdd-implement/SKILL.md` 与 `references/stages.md` 阶段③ 3e。
 
 ## 运行纪律（长程任务）
 
@@ -20,6 +20,7 @@
 - **长程声明**：执行长程技能前，确认技能文本自带长程任务声明与回合连续性规则（Turn Continuity）——阶段内连续动作一回合内完成，不依赖 harness `/goal` 防线。tdd-implement 已内嵌（SKILL.md 声明 + references/stages.md 阶段③规则）。
 - **模型选择**：flash 级模型长程任务卡住概率显著更高；关键长任务优先强模型或 `/goal` 模式。
 - **任务分解（Chunking）**：巨型操作拆小步执行——单次 `write` 超过 ~150 行先写骨架再分批补全；批量 `replace` 超过 ~5 处分批执行，每批后立即验证。tdd-implement 已内嵌该规则（随包分发）。
+- **Git 历史保护（Git History Preservation）**：任何触及 git 的操作必须追加历史、不可改写丢弃。阶段入口记录 `BASE_HEAD=$(git rev-parse HEAD)`，阶段出口与 commit 前校验 `git merge-base --is-ancestor $BASE_HEAD HEAD`，失败即经 `git reflog` 恢复后才继续。"目录卫生"仅删本次产生的 `[DEBUG-...]`/一次性脚本等未跟踪临时文件，禁止为达干净而执行 `git reset --hard`、`git checkout .`、`git clean -fd`、`git stash push --include-untracked`、`git push --force`、`git rebase -i` 等（需显式用户确认）。
 
 ## 执行原则（细则）
 

package/template/.pi/docs/agents/skill-design.md

@@ -1,18 +1,17 @@
 # Skill Design Spec
 
-The design rules every skill in this repo must obey. Apply them when writing a new skill or editing an existing one. Terms are defined once in [`CONTEXT.md`](../../../.opencode/CONTEXT.md) — reference them there, never restate the definition.
-
-This spec exists because of a real incident: a long-horizon skill run on a flash-class model stopped its turn at "announce the next step" points four times in one session (see `DIAGNOSIS-tdd-implement-stuck.md`). The three rules below are the preventive measures that came out of that diagnosis. They are repo rules, not advice.
+The design rules every skill in this repo must obey. Apply them when writing a new skill or editing an existing one. Terms are defined once in [`CONTEXT.md`](../../CONTEXT.md) — reference them there, never restate the definition.
 
+This spec exists because of a real incident: a long-horizon skill run on a flash-class model stopped its turn at "announce the next step" points four times in one session (see `DIAGNOSIS-tdd-implement-stuck.md`). The four rules below are the preventive measures that came out of that diagnosis and subsequent git-history incidents (see `docs/adr/0003-git-history-preservation.md`). They are repo rules, not advice.
 ## Rule 1 — Turn Continuity
 
 Every **Long-Horizon Skill** must carry a positive **Turn Continuity** rule of its own: the consecutive actions of a stage (red → green → typecheck → next seam) are executed serially **within one turn**, until the stage's exit condition is met. Do not end the turn at "announce the next step" points, and do not wait for the user to say "continue".
 
-- State it **positively** (per the negation principle in `writing-great-skills`): describe the target behaviour, never the banned one.
+- State it **positively** (per the negation principle in `writing-for-agents`): describe the target behaviour, never the banned one.
 - It must be **self-contained** — the skill cannot rely on the harness `/goal` line, because no `/goal` exists when the user does not activate one.
 - Every stage ends on a checkable exit condition; reaching it is the only thing that ends the turn.
 - A sub-step going green (e.g. one seam) is not a stage exit — a stage ends only when all of its seams are complete. Progress output does not itself end the turn: output, then keep executing until one of the three endpoints (compliance checkpoint, external blocker, stage exit) is reached.
-- Canonical example: the 回合连续性 rule in [`.agents/skills/tdd-implement/references/stages.md`](../../skills/tdd-implement/references/stages.md) stage ③.
+- Canonical example: the 回合连续性 rule in [`.agents/skills/tdd-implement/references/stages.md`](.agents/skills/tdd-implement/references/stages.md) stage ③.
 
 ## Rule 2 — Model Selection
 
@@ -26,7 +25,13 @@ Giant turns — a single `write` of a large file, or a batch `replace` of a hund
 - A batch of more than ~5 `replace`s: split into batches and verify after each batch.
 
 These thresholds are experience defaults; adjust them as practice shows better values.
+## Rule 4 — Git History Preservation
+
+Every skill that touches git must preserve history after `BASE_HEAD`: history may only be appended, never rewritten or dropped. The skill must record `BASE_HEAD=$(git rev-parse HEAD)` at stage entry, and verify `git merge-base --is-ancestor $BASE_HEAD HEAD` at every stage exit and before any commit — failure means history was rewritten and the skill must recover via `git reflog` before continuing.
+
+To achieve "directory clean" (`git status` clean) the skill may only delete its own temporary artifacts (`[DEBUG-...]`, one-off scripts, untracked probe files) — it must never use git-level destructive commands to reach a clean state. The following are forbidden without explicit user confirmation: `git reset --hard`, `git checkout .`, `git clean -fd`, `git stash push --include-untracked` (use `--keep-index` instead and `pop` with verification), `git push --force`, `git rebase -i` and any `reset`/`checkout` that moves `HEAD` backward.
 
+Canonical enforcement: [`tdd-implement/references/stages.md`](.agents/skills/tdd-implement/references/stages.md) stage ③/⑥/⑦/A2-A4 Git 安全红线 and [`commit-check/SKILL.md`](.agents/skills/commit-check/SKILL.md) ③ 目录卫生.
 ## Long-horizon skills inventory
 
 Skills currently classified as Long-Horizon, to be evolved against these rules as they are touched: `tdd-implement` (fixed), `diagnose-fix` (fixed — new orchestration skill for diagnosis + TDD fix, carries its own Turn Continuity rule), `diagnosing-bugs`, `improve-codebase-architecture`, `wayfinder`, `grill-to-spec`, `to-spec`. Backfilling existing skill texts is out of scope for now — these rules bind new and edited skills going forward.

package/template/AGENTS.md

@@ -37,10 +37,10 @@
 - 领域术语/ADR → domain-modeling；模块接口 → codebase-design；巨型规划 → wayfinder
 - 诊断 → diagnose-fix（编排 diagnosing-bugs 诊断 + tdd 修复，修复环节强制 TDD）；审查 → code-review；合并冲突 → resolving-merge-conflicts；提交前 → commit-check（审查文档 + 对齐 README + 目录卫生 + commit message）
 - 分诊 → triage；架构扫描 → improve-codebase-architecture；综合 spec → to-spec；拆票 → to-tickets
-- 教学 → teach；交接 → handoff；技能写作 → writing-great-skills
+- 教学 → teach；交接 → handoff；技能写作 → writing-for-agents
 - 兜底 → ask-matt；模板维护 → README.md
 
-显式触发（须用户 `/` 发起）：grill-to-spec、wayfinder、to-spec、to-tickets、triage、improve-codebase-architecture、teach、handoff、writing-great-skills
+显式触发（须用户 `/` 发起）：grill-to-spec、wayfinder、to-spec、to-tickets、triage、improve-codebase-architecture、teach、handoff、writing-for-agents
 
 ## 分文件