@heihei0299/matt-skills 1.0.0

package/bin/cli.js

@@ -0,0 +1,353 @@
+#!/usr/bin/env node
+import { readdir, readFile, cp, stat } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import prompts from 'prompts';
+
+const SKILLS_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '.agents', 'skills');
+const TEMPLATE_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'template');
+const PROPRIETARY_SKILLS = new Set(['tdd-implement', 'grill-to-spec', 'diagnose-fix', 'commit-check']);
+process.stdout.on('error', (err) => {
+  if (err.code === 'EPIPE') process.exit(0);
+  throw err;
+});
+
+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 (backs up overwritten files to .bak)
+  matt-skills list [--json]                    List available skills and their descriptions
+  matt-skills install [options]                Install skills (interactive by default)
+  matt-skills --help                          Show this help
+
+Init options:
+  --dest <path>   Target directory (default: current directory)
+  --force         Overwrite existing files (backs up to .bak)
+Sync options:
+  --dest <path>   Target directory (default: current directory)
+  --force         Overwrite without backup (default: backup to .bak)
+
+Install options:
+  --tools <a,b>   Install for the given tools (codex, pi, opencode, claude); skips tool selection
+  --all           Install all skills; skips skill selection
+  --force         Overwrite existing skills
+  --global        Install to the user's global skill directories
+  --project       Install to project skill directories (default)
+  --dest <path>   Install everything into a single custom directory (overrides --tools)
+`;
+
+function parseFrontmatter(text) {
+  const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return {};
+  const fields = {};
+  for (const line of match[1].split(/\r?\n/)) {
+    const m = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (!m) continue;
+    let value = m[2].trim();
+    if (value.startsWith('"') && value.endsWith('"')) {
+      value = value.slice(1, -1).replace(/\\"/g, '"').replace(/\\\\/g, '\\');
+    }
+    fields[m[1]] = value;
+  }
+  return fields;
+}
+
+async function listSkills() {
+  const entries = await readdir(SKILLS_DIR, { withFileTypes: true });
+  const skills = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (entry.name.endsWith('.bak')) continue;
+    let content;
+    try {
+      content = await readFile(path.join(SKILLS_DIR, entry.name, 'SKILL.md'), 'utf8');
+    } catch {
+      continue;
+    }
+    const { name, description } = parseFrontmatter(content);
+    if (name && description) skills.push({ name, description });
+  }
+  return skills.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+}
+
+async function pathExists(p) {
+  try {
+    await stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function backupIfExists(p) {
+  if (!(await pathExists(p))) return null;
+  const bak = `${p}.bak`;
+  await cp(p, bak, { recursive: true, force: true });
+  return bak;
+}
+
+const TOOLS = ['codex', 'pi', 'opencode', 'claude'];
+
+const PROJECT_DIRS = {
+  codex: '.agents/skills',
+  pi: '.pi/skills',
+  opencode: '.opencode/skills',
+  claude: '.claude/skills',
+};
+
+const GLOBAL_DIRS = {
+  codex: '.codex/skills',
+  pi: '.pi/agent/skills',
+  opencode: '.config/opencode/skills',
+  claude: '.claude/skills',
+};
+
+function toolDir(tool, global) {
+  if (global) return path.join(os.homedir(), GLOBAL_DIRS[tool]);
+  return path.resolve(process.cwd(), PROJECT_DIRS[tool]);
+}
+
+async function promptTools() {
+  const res = await prompts({
+    type: 'multiselect',
+    name: 'tools',
+    message: '选择要安装到的工具',
+    choices: TOOLS.map((t) => ({ title: t, value: t })),
+    instructions: '空格勾选，回车确认',
+  });
+  return Array.isArray(res?.tools) ? res.tools : [];
+}
+
+async function promptSkills(skills) {
+  const res = await prompts({
+    type: 'multiselect',
+    name: 'skills',
+    message: '选择要安装的技能',
+    choices: skills.map((s) => ({ title: s.name, value: s.name })),
+    instructions: '空格勾选，回车确认',
+  });
+  return Array.isArray(res?.skills) ? res.skills : [];
+}
+
+async function installCommand({ dest, all, force, tools, global }) {
+  const skills = await listSkills();
+  let targets;
+  if (dest) {
+    targets = [{ tool: null, dir: path.resolve(process.cwd(), dest) }];
+  } else {
+    const selectedTools = tools
+      ? tools.filter((t) => TOOLS.includes(t))
+      : await promptTools();
+    if (selectedTools.length === 0) {
+      process.stdout.write('未选择任何工具，未安装任何技能\n');
+      return;
+    }
+    targets = selectedTools.map((tool) => ({ tool, dir: toolDir(tool, global) }));
+  }
+  const selected = all ? skills.map((s) => s.name) : await promptSkills(skills);
+  if (selected.length === 0) {
+    process.stdout.write('未选择任何技能，未安装任何技能\n');
+    return;
+  }
+  for (const { tool, dir } of targets) {
+    let installed = 0;
+    let skipped = 0;
+    for (const name of selected) {
+      const dst = path.join(dir, name);
+      if (!force && (await pathExists(dst))) {
+        skipped++;
+        continue;
+      }
+      await cp(path.join(SKILLS_DIR, name), dst, { recursive: true, force: true });
+      installed++;
+    }
+    if (tool) process.stdout.write(`${tool}：已装 ${installed}、跳过 ${skipped}\n`);
+    else process.stdout.write(`已装 ${installed}、跳过 ${skipped}\n`);
+    process.stdout.write(`目标路径：${dir}\n`);
+  }
+}
+
+async function initCommand({ dest, force }) {
+  const target = dest ? path.resolve(process.cwd(), dest) : process.cwd();
+  const marker = path.join(target, 'AGENTS.md');
+  if (!force && (await pathExists(marker))) {
+    process.stdout.write('模板已存在（AGENTS.md），跳过；用 --force 覆盖（自动备份到 .bak）\n');
+  } else {
+    if (force && (await pathExists(marker))) {
+      for (const name of ['AGENTS.md', '.opencode', '.pi']) {
+        const cur = path.join(target, name);
+        if (await pathExists(cur)) await backupIfExists(cur);
+      }
+      await cp(TEMPLATE_DIR, target, { recursive: true, force: true });
+      process.stdout.write('模板：已备份到 .bak 并覆盖（AGENTS.md、.opencode/、.pi/）\n');
+    } else {
+      await cp(TEMPLATE_DIR, target, { recursive: true, force: true });
+      process.stdout.write('模板：已复制（AGENTS.md、.opencode/、.pi/）\n');
+    }
+  }
+  const entries = await readdir(SKILLS_DIR, { withFileTypes: true });
+  const upstream = entries
+    .filter((e) => e.isDirectory() && !PROPRIETARY_SKILLS.has(e.name) && !e.name.endsWith('.bak'))
+    .map((e) => e.name)
+    .sort();
+  const skillsDir = path.join(target, '.agents', 'skills');
+  let installed = 0;
+  let skipped = 0;
+  let backedUp = 0;
+  for (const name of upstream) {
+    const src = path.join(SKILLS_DIR, name);
+    const dst = path.join(skillsDir, name);
+    if (src === dst) {
+      skipped++;
+      continue;
+    }
+    if (!force && (await pathExists(dst))) {
+      skipped++;
+      continue;
+    }
+    if (force && (await pathExists(dst))) {
+      await backupIfExists(dst);
+      backedUp++;
+    }
+    await cp(src, dst, { recursive: true, force: true });
+    installed++;
+  }
+  if (force && backedUp > 0) {
+    process.stdout.write(`上游技能：已装 ${installed}、跳过 ${skipped}、备份 ${backedUp} 到 .bak\n`);
+  } else {
+    process.stdout.write(`上游技能：已装 ${installed}、跳过 ${skipped}\n`);
+  }
+  process.stdout.write(`目标路径：${target}\n`);
+}
+
+async function syncCommand({ dest, force }) {
+  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 {
+    process.stdout.write('同步：检测到现有项目，将增量更新并备份被覆盖文件到 .bak\n');
+    if (backup) {
+      for (const name of ['AGENTS.md', '.opencode', '.pi']) {
+        const cur = path.join(target, name);
+        if (await pathExists(cur)) await backupIfExists(cur);
+      }
+    }
+    await cp(TEMPLATE_DIR, target, { recursive: true, force: true });
+    process.stdout.write(backup ? '模板：已备份并同步（AGENTS.md、.opencode/、.pi/）\n' : '模板：已覆盖（AGENTS.md、.opencode/、.pi/）\n');
+  }
+  const entries = await readdir(SKILLS_DIR, { withFileTypes: true });
+  const upstream = entries
+    .filter((e) => e.isDirectory() && !PROPRIETARY_SKILLS.has(e.name) && !e.name.endsWith('.bak'))
+    .map((e) => e.name)
+    .sort();
+  const skillsDir = path.join(target, '.agents', 'skills');
+  let installed = 0;
+  let updated = 0;
+  let backedUp = 0;
+  for (const name of upstream) {
+    const src = path.join(SKILLS_DIR, name);
+    const dst = path.join(skillsDir, name);
+    if (src === dst) {
+      updated++;
+      continue;
+    }
+    const exists = await pathExists(dst);
+    if (exists) {
+      if (backup) {
+        await backupIfExists(dst);
+        backedUp++;
+      }
+      await cp(src, dst, { recursive: true, force: true });
+      updated++;
+    } else {
+      await cp(src, dst, { recursive: true, force: true });
+      installed++;
+    }
+  }
+  if (backup) {
+    process.stdout.write(`上游技能：新增 ${installed}、更新 ${updated}（已备份 ${backedUp} 到 .bak）\n`);
+  } else {
+    process.stdout.write(`上游技能：新增 ${installed}、更新 ${updated}\n`);
+  }
+  process.stdout.write(`目标路径：${target}\n`);
+}
+
+function parseInitArgs(args) {
+  let dest;
+  let force = false;
+  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;
+  }
+  return { dest, force };
+}
+
+function parseInstallArgs(args) {
+  let dest;
+  let all = false;
+  let force = false;
+  let global = false;
+  let toolsArg;
+  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 === '--all') all = true;
+    else if (arg === '--force') force = true;
+    else if (arg === '--tools') toolsArg = args[++i];
+    else if (arg.startsWith('--tools=')) toolsArg = arg.slice('--tools='.length);
+    else if (arg === '--global') global = true;
+    else if (arg === '--project') global = false;
+  }
+  const tools = toolsArg
+    ? toolsArg.split(',').map((t) => t.trim()).filter(Boolean)
+    : null;
+  return { dest, all, force, global, tools };
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+    process.stdout.write(HELP);
+    return;
+  }
+  const [command, ...rest] = args;
+  if (command === 'list') {
+    const skills = await listSkills();
+    if (rest.includes('--json')) {
+      process.stdout.write(`${JSON.stringify(skills, null, 2)}\n`);
+    } else {
+      for (const skill of skills) {
+        process.stdout.write(`${skill.name} — ${skill.description}\n`);
+      }
+    }
+    return;
+  }
+  if (command === 'init') {
+    await initCommand(parseInitArgs(rest));
+    return;
+  }
+  if (command === 'sync') {
+    await syncCommand(parseInitArgs(rest));
+    return;
+  }
+  if (command === 'install') {
+    await installCommand(parseInstallArgs(rest));
+    return;
+  }
+  process.stderr.write(HELP);
+  process.exitCode = 1;
+}
+
+main().catch((error) => {
+  process.stderr.write(`error: ${error.message}\n`);
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@heihei0299/matt-skills",
+  "version": "1.0.0",
+  "description": "Agent skills + 项目配置模板：一条命令初始化 opencode / pi-agent 项目（含 mattpocock/skills 上游技能）",
+  "type": "module",
+  "bin": {
+    "matt-skills": "bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "template/",
+    ".agents/skills/",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "prepublishOnly": "node --test test/*.test.js"
+  },
+  "dependencies": {
+    "prompts": "^2.4.2"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT"
+}

package/template/.opencode/CONTEXT.md

@@ -0,0 +1,47 @@
+# 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
+
+## 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
+
+**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/.opencode/agents/issue-audit.md

@@ -0,0 +1,52 @@
+---
+description: 审计 feature 的 issue 完成情况（四维：完成度 / spec 遵守 / ADR 遵守 / 文档一致性），输出完整报告（对话 + .scratch/<slug>/audit-<时间戳>.md）。只审计，物理上无法修改其他任何文件。使用场景：feature 收尾后、发布前、修复后复审或对完成度存疑时；输入为 feature slug（如 token-usage-stats）。
+mode: subagent
+permission:
+  read: allow
+  edit:
+    "*": deny
+    ".scratch/*/audit-*.md": allow
+  bash:
+    "*": deny
+    "git status": allow
+    "git status *": allow
+    "git log": allow
+    "git log *": allow
+    "git diff": allow
+    "git diff *": allow
+    "git show": allow
+    "git show *": allow
+    "git rev-parse *": allow
+    "git ls-files": allow
+    "git ls-files *": allow
+    "git grep": allow
+    "git grep *": allow
+    "cargo test --lib": allow
+    "cargo test --lib *": allow
+  task: deny
+---
+
+# Issue Auditor
+
+你是 issue 完成情况的独立审计者，像外部质量审计员一样工作。
+
+## 铁律（不可违背）
+
+- **只审计，不修改任何现有文档与代码。** `edit` 权限被系统强制限制为仅 `.scratch/*/audit-*.md` 可写——你物理上无法修改其他任何文件；不尝试绕过（如通过 bash 写文件）。
+- **不勾选验收标准、不改 Status、不做 triage 流转。**
+- **输入无效立即失败（fail-fast）**：`.scratch/<slug>/` 不存在或为空、缺少 `spec.md`、`issues/` 下没有任何 issue 文件时，不进入审计流程，直接输出失败报告（逐项列出缺失内容）并结束。
+- 只读 git 命令（status/log/diff/show/rev-parse/ls-files/grep）与 `cargo test --lib` 允许用于收集证据；任何写操作命令一律不执行。
+
+## 为什么分四维（不可合并重排）
+
+四维是相互独立的审计轴：完成度（验收标准逐条）可以全绿，而 spec 决策被违背、ADR 被绕过或文档已过期。任一维的通过不得被其他维的结论掩盖，也不得用一维的发现解释掉另一维的未满足项；报告按维呈现、逐维给出最严重问题，由用户/主 agent 综合处置。
+
+## 执行
+
+- 完整流程由任务指令（issue-audit 命令正文）提供：输入来源、四维审计、证据分级（L1/L2/L3）、问题分级、报告模板、出口条件。
+- 严格按任务指令执行，不偏离、不省略任何维度。
+- 报告逐条独立可验证：每个验收标准、每个未满足项自成一条并附证据（文件:行号、测试名、提交哈希），不合并成模糊结论；阻断项写"违反了什么 + 需要什么"，不做过程性修复指示。
+- **结论总览须给出每维最严重问题各一行**（该维无问题时写"无"），不得只给汇总数字。
+- **报告文件名必须为 `audit-<YYYYMMDD-HHMM>.md`，精确到分钟**（如 `audit-20260802-0604.md`），不得省略分钟；同名文件已存在时追加 `-2` 序号，永不覆盖。
+- 报告语言中文；代码标识符、测试名、字段名、提交哈希保留原文。
+- 报告不完整不得结束——四维缺失、未满足项遗漏、证据缺失时继续补齐。

package/template/.opencode/commands/grill-to-spec.md

@@ -0,0 +1,13 @@
+---
+description: 编排 grill-with-docs → to-spec，把设计打磨成共识并发布 spec（只打磨设计与产出文档，不写代码）
+---
+
+# Grill to Spec
+
+开始 `/grill-to-spec` 会话，加载并执行 grill-to-spec 技能（编排 grilling→domain-modeling→to-spec）：
+
+**主题：** $ARGUMENTS
+
+- 只编排与产出：设计打磨成共识 → 综合成 spec 发布，不写代码、不动源码
+- 产出物限：领域文档（glossary/ADR）与 spec
+- ADR 落盘必须经用户显式确认

package/template/.opencode/commands/handoff.md

@@ -0,0 +1,12 @@
+---
+description: 交接——把当前对话压缩为交接文档，供另一个 agent 接手
+---
+
+# Handoff
+
+加载并执行 handoff 技能，压缩当前对话为交接文档：
+
+**目标：** $ARGUMENTS
+
+- 将当前会话状态压缩为结构化交接文档
+- 供另一个 agent 无缝接手继续工作

package/template/.opencode/commands/improve-codebase-architecture.md

@@ -0,0 +1,13 @@
+---
+description: 架构扫描——扫描代码库寻找可深化机会，输出可视化 HTML 报告，然后 grill 选定的一项
+---
+
+# Improve Codebase Architecture
+
+加载并执行 improve-codebase-architecture 技能，扫描代码库：
+
+**范围：** $ARGUMENTS
+
+- 扫描代码库，识别可深化的架构机会
+- 输出可视化 HTML 报告呈现
+- 选定一项后用 grilling 打磨方案

package/template/.opencode/commands/issue-audit.md

@@ -0,0 +1,115 @@
+---
+description: 审计 feature 的 issue 完成情况（四维：完成度 / spec 遵守 / ADR 遵守 / 文档一致性），输出完整报告，只审计不修改
+agent: issue-audit
+subtask: true
+---
+
+# Issue Audit：`$ARGUMENTS`
+
+对 feature `$ARGUMENTS` 执行完整 issue 审计（对应目录 `.scratch/$ARGUMENTS/`），按以下流程执行。
+
+## 铁律（不可违背）
+
+- **不修改任何现有文档与代码。** issue 文件、spec.md、README*、src-rust/、webui/ 等一切现有文件禁止改动。
+- **唯一允许的写入**：新建审计报告 `.scratch/$ARGUMENTS/audit-<YYYYMMDD-HHMM>.md`（时间戳文件名，保留多次审计历史）。不覆盖、不修改任何其他文件，不生成其他产物。
+- **不勾选验收标准、不改 Status、不做 triage 流转。** 状态机是 triage 技能的职责；审计只产出事实结论。
+- **输入无效立即失败（fail-fast）**：`.scratch/$ARGUMENTS/` 不存在或为空、缺少 `spec.md`、`issues/` 下没有任何 issue 文件时，不进入审计流程，直接输出失败报告（逐项列出缺失内容）并结束。
+- 审计与被审计分离：发现问题不修复、不流转，只在报告中记录（阻断项附"需要什么"），处置由用户/主 agent 决定。
+- 只读 git 命令（status/log/diff/show/rev-parse/ls-files/grep）用于收集提交历史证据；任何写操作命令一律不执行。
+- 报告语言中文；代码标识符、测试名、字段名、提交哈希保留原文。
+
+## 输入来源
+
+- `.scratch/$ARGUMENTS/spec.md`（Implementation Decisions、Testing Decisions、Out of Scope）
+- `.scratch/$ARGUMENTS/issues/*.md`（每票验收标准、Blocked by 依赖）
+- `.scratch/$ARGUMENTS/audit-*.md`（历史审计报告，读取最新一份作为对比基线；无则标注"无历史基线"）
+- `docs/adr/*.md`（架构决策，审计对象）
+- `CONTEXT.md`（术语表；违反术语视为 spec 遵守问题）
+- 当前工作树代码 + 只读 git 历史（提交哈希作为"确实做过"的证据）
+
+## 为什么分四维（不可合并重排）
+
+四维是相互独立的审计轴：完成度（验收标准逐条）可以全绿，而 spec 决策被违背、ADR 被绕过或文档已过期。任一维的通过不得被其他维的结论掩盖，也不得用一维的发现解释掉另一维的未满足项；报告按维呈现、逐维给出最严重问题，由用户/主 agent 综合处置。
+
+## 四维审计
+
+1. **完成度**：逐票核对每个 issue 的验收标准（checkboxes）——逐条判定满足/未满足，引用代码位置、单测名、提交哈希作为证据。Blocked by 依赖未满足的票不计入完成度。
+2. **Spec 遵守**：spec.md 的 Implementation Decisions 是否被落实、是否违背；Testing Decisions 的测试是否真实存在（非空头声明）；**Out of Scope 是否被越过**（实现做了 spec 明说不做的事 = 阻断项）。
+3. **ADR 遵守**：每个 `docs/adr/NNNN-*.md` 的决策在当前实现中是否被遵守。
+4. **文档一致性**：README.md / README_ZH.md（及受影响的其他用户文档）与当前实现是否一致——无过期信息、无声称未实现的功能（如 feature 中某 UI 尚未实现，文档不得声称其存在）、命令示例与界面描述与实际一致。
+
+## 证据分级（下结论的纪律）
+
+- **L1 静态**（默认）：读代码、读 git 提交记录、核对单测存在性与断言内容。
+- **L2 测试套件**：运行仓库完整测试套件（本项目：`cargo test --lib` 于项目根；如有 JS 侧测试一并运行）。每次审计必跑。
+- **L3 端到端**：仅在以下情形升级——① 某验收标准明确要求"链路可用/端到端"；② L1 静态核对发现不一致、仅靠静态无法定案。**subagent 内不执行 L3**；判定需要升级后，将条目列入报告「待主 agent 隔离验证」清单（注明升级条件与需验证内容），由主 agent 在隔离环境（临时 HOME + mock 上游）执行。
+- **弱证据不足**：间接、缺失、仅一致的证据不足以支撑"通过"结论；无法取证到位的条目标为非阻断疑点并注明"需要升级证据"。
+
+## 问题分级
+
+- **阻断项（must-fix）**：验收标准未达成、违反 ADR、越过 Out of Scope、违背 spec 决策。
+- **非阻断项（should-note）**：文档措辞、建议性改进、证据仅间接的疑点。
+- feature 结论 = 阻断项数 + 非阻断项数；**阻断为 0 才判定通过**。
+
+## 执行步骤（顺序自包含）
+
+1. 校验输入（fail-fast）：确认 `.scratch/$ARGUMENTS/` 存在且非空、`spec.md` 存在、`issues/` 下至少有一个 issue 文件；任一项不满足 → 输出失败报告（逐项列出缺失内容）并结束，不进入审计、不生成审计报告文件。校验通过后列出 spec、全部 issue、历史审计报告（若有）。
+2. 收集约定：读 spec.md、全部 issues、`docs/adr/`、CONTEXT.md。
+3. 逐票核对（维度 1）：每票验收标准逐条判定，记录证据。
+4. 维度 2：以 spec 决策与 Out of Scope 对照当前代码实现。
+5. 维度 3：以每个 ADR 对照当前实现。
+6. 维度 4：对照 README 等文档与当前实现。
+7. 跑 L2 测试套件（`cargo test --lib`），记录通过数/失败数。
+8. 判定 L3 升级条件，必要时列出待主 agent 隔离验证清单。
+9. 读取最新历史报告（若有）作基线，对比阻断项变化。
+10. 汇总四维报告：对话输出完整报告，并写入 `.scratch/$ARGUMENTS/audit-<YYYYMMDD-HHMM>.md`。
+    - **文件名必须精确到分钟**（如 `audit-20260802-0604.md`），格式为 `audit-` + 年(4)月(2)日(2)-时(2)分(2) + `.md`。不得省略分钟、不得用其他命名。
+    - 同分钟重跑导致同名时追加 `-2`、`-3` 序号（如 `audit-20260802-0604-2.md`），永不覆盖已有文件。
+
+## 报告原则（逐条独立可验证）
+
+- **逐条独立可验证**：每个验收标准、每个未满足项自成一条并附证据（文件:行号、测试名、提交哈希），不合并成模糊结论——读者可逐条复核。
+- **行为性表述**：阻断项写"违反了什么 + 需要什么"，不做过程性修复指示（如"应该打开 X 文件改 Y"）；证据引用（文件:行号）仅为定位证据，不作修复指令。
+- **不合并重排**：四维结论按维呈现、互不遮盖（见「为什么分四维」）。
+
+## 报告模板（强制，四维缺失视为未完成）
+
+```markdown
+# Issue 审计报告：$ARGUMENTS
+
+审计时间：<YYYY-MM-DD HH:MM>（精确到分钟）｜基线：<上次报告文件名 或 "无历史基线">
+
+## 结论总览
+- 阻断项：N 项 / 非阻断项：M 项 → 通过 / 未通过
+- 每维最严重问题：维度1：<票号+一句> ｜ 维度2：<一句> ｜ 维度3：<一句> ｜ 维度4：<一句>（该维无问题写"无"）
+- 与上次审计对比：新增解决 k 项 / 新引入 j 项 / 持续未满足 i 项（无历史基线时写"本次为首份报告"）
+
+## 维度 1 · 完成度（逐票）
+- 01 <标题>：满足 / 未满足（验收标准逐条 + 证据：文件:行号、测试名、提交哈希）
+
+## 维度 2 · Spec 遵守
+- 满足 / 违反（引用 spec 行号 + 代码证据；Out of Scope 检查结果）
+
+## 维度 3 · ADR 遵守
+- 0001 <标题>：遵守 / 违反（证据）
+
+## 维度 4 · 文档一致性
+- README.md：一致 / 过期信息（引用行 + 实现事实）
+
+## 未满足项清单（显式记录）
+- [阻断] <票号> <内容>：原因 + 需要什么
+- [非阻断] <内容>：原因
+
+## 待主 agent 隔离验证（L3 条目，如无则写"无"）
+- <条目>：升级条件 + 需验证内容
+
+## 备注
+- 证据级别说明（哪些条目用了 L1/L2/L3）
+- 本次审计为只读审计，仅新建本报告文件，未修改任何现有文档
+```
+
+## 出口条件（强制）
+
+- 输入无效按 fail-fast 出口：直接输出失败报告（逐项列出缺失内容），不生成审计报告文件。
+- 正常审计：四维全部给出结论、每维最严重问题列出、未满足项逐条列出、证据引用齐全 → 才可结束。
+- 报告不完整（缺维、未满足项遗漏、证据缺失）→ **继续补齐，不得提前结束**。

package/template/.opencode/commands/teach.md

@@ -0,0 +1,12 @@
+---
+description: 教学——在当前工作区内教用户一个新技能或概念
+---
+
+# Teach
+
+加载并执行 teach 技能，在当前工作区内教学：
+
+**主题：** $ARGUMENTS
+
+- 以当前目录为教学工作区（MISSION.md、reference、learning-records、lessons 等）
+- 按 MISSION 目标逐步教学，产出教学材料

package/template/.opencode/commands/to-spec.md

@@ -0,0 +1,13 @@
+---
+description: 把当前对话综合为 spec 并发布到 issue tracker（不采访，只综合已讨论的内容）
+---
+
+# To Spec
+
+加载并执行 to-spec 技能，把当前对话综合为 spec：
+
+**主题：** $ARGUMENTS
+
+- 只综合已讨论的内容，不新增采访提问
+- 按 spec 模板编写并发布到 issue tracker
+- 发布前展示给用户确认