@heihei0299/matt-skills 1.3.3 → 1.5.2

package/.agents/skills/ci-guard/SKILL.md

@@ -30,8 +30,6 @@ description: "Guard the GitHub Actions release pipeline: orchestrate workflow fl
 - `jobs` 依赖：`publish.needs: [build, verify]`，**禁止** `needs: build` 单依赖。门禁失效的直接原因就是 `verify` 红仍发包
 - `permissions` 最小化：`verify`/`build` 只需 `contents: read`，仅 `publish` 保留 `contents: write` + `packages: write`（或 `id-token: write` 若用 OIDC）
 - `concurrency`：`group: ci-${{ github.ref }}` + `cancel-in-progress: true`，避免同分支并行互踩
-- `cache`：`rust-cache` 或 `actions/cache` 缓存 `~/.cargo` + `target`，`actions/setup-node` 加 `cache: npm`，避免每次 `npm install` 重装
-- `find changed Rust files`：`git diff origin/main...HEAD` 在 tag 事件下为空，改为 `git diff --name-only HEAD~1...HEAD` 或直接全量 `cargo fmt --check` / `clippy`，避免误跳过
 
 **完成条件**：
 - [ ] `git diff HEAD -- .github/workflows/ci.yml` 显示 `on.push.branches` 存在
@@ -40,23 +38,26 @@ description: "Guard the GitHub Actions release pipeline: orchestrate workflow fl
 
 ---
 
-### ② 预发布 gate —— 在写盘之前变红
+### ② 预发布 gate —— 测试 GitHub Action 流程
 
-本段是**硬门槛**，顺序固定：`fmt → clippy → test → build`，任一步红即阻断 `publish`。
+本段是**硬门槛**，顺序固定：`action lint → workflow dry-run → dispatch 验证`，任一步红即阻断 `publish`。
 
-**fmt / clippy**：
-- `rustfmt --check` 与 `cargo clippy --all-targets -- -D warnings` 必须与本地一致（`rust-toolchain.toml` 锁定 `stable` 版本）
-- 允许的 `-A` 必须显式列出（如本仓 `-A clippy::manual_checked_ops` 等 4 项），不批量 `-A clippy::all`
+**action lint**：
+- `actionlint` 校验 `.github/workflows/ci.yml` 语法与 `on/needs/permissions` 完整性
+- `yamllint` 检查缩进与重复键
 
-**test（关键）**：
-- 落盘测试（如 `web::tests` 直写 `config.json` / `models.json`）**必须**测试隔离：`config_dir()` / `pi_dir()` / `models_path()` 在 `#[cfg(test)]` 下重定向到 `temp/pi-switch-test-<pid>`（参考 `src-rust/proxy.rs:115 init_test_state_dir()`，`config.rs:460` 为未隔离反例；曾用 `PI_SWITCH_CONFIG_DIR` 环境覆盖后被 `20f6f86` 误删，即回归）
-- 若暂未隔离，CI 侧以 `cargo test --release --lib -- --test-threads=1` 串行化为**过渡**（`2d68f62` 方案，322/322 稳定），并在代码侧记录 `TODO(ci-guard): 恢复 config_dir 测试隔离后去掉 --test-threads=1`
-- `verify` 必须跑 `cargo test --lib`（或 `--release --lib` 与发布一致），不跳过；`build` 矩阵 5 目标仅验编译，不代验测试
+**workflow dry-run**：
+- `act --dry-run` 或 `gh workflow view` 模拟 `verify/build/publish` 三 job 依赖与 `if` 条件
+- 校验 `publish.needs` 含 `verify` 且 `workflow_dispatch` 可手动触发
+
+**dispatch 验证**：
+- 通过 `gh workflow run ci.yml --ref main -f dry_run=true` 触发试运行，观察 `verify` 日志与产物上传
+- 失败即阻断 `publish`，日志留存于 Actions
 
 **完成条件**：
-- [ ] 本地 `cargo test --lib -- --test-threads=1` 322/322 且 `cargo test --lib`（并行）亦 322/322 或已记录隔离 TODO
-- [ ] `cargo clippy --all-targets` 0 warning
-- [ ] `npm run build:webui` 在 `verify` 与 `build` 均执行（本仓 WebUI 缺失会导致 `publish` 产物不一致）
+- [ ] `actionlint` 0 error
+- [ ] `act --dry-run` 三 job 依赖正确
+- [ ] `workflow_dispatch` 试运行通过
 
 ---
 
@@ -82,7 +83,6 @@ description: "Guard the GitHub Actions release pipeline: orchestrate workflow fl
 
 - **单依赖 publish**：`needs: build` 是本仓 7 次带病发布的根因
 - **仅 tag 触发**：`push.branches` 缺失导致主干修复无 CI
-- **真实落盘并行测试**：无 `#[cfg(test)]` 隔离的 `config_dir` 直写是偶发红的根因，`--test-threads=1` 只是止血
 - **静默发布**：`publish` 失败不建 issue / 不删 tag，下次 `409` 叠加
 - **`-A clippy::all`**：掩盖真实告警
 
@@ -92,13 +92,3 @@ description: "Guard the GitHub Actions release pipeline: orchestrate workflow fl
 - 修复：`2d68f62 fix(ci): gate publish on verify and serialize Rust tests`
 - 关联技能：`diagnose-fix`（通用诊断）、`commit-check`（提交前门禁）、`tdd`（测试隔离后的回归）
 
-## 执行清单（粘贴即用）
-
-```markdown
-- [ ] .github/workflows/ci.yml: on.push.branches: [main] 已加
-- [ ] publish.needs: [build, verify]
-- [ ] verify: cargo test --release --lib -- --test-threads=1（或已隔离则去掉该 flag）
-- [ ] config.rs: #[cfg(test)] config_dir/pi_dir → temp（或 TODO 已记录）
-- [ ] workflow_dispatch 可手动触发
-- [ ] npm view 回读 + 失败建 issue
-```

package/.agents/skills/commit-check/SKILL.md

@@ -5,35 +5,32 @@ description: "Run the pre-commit gate before any commit: verify docs match the i
 
 # Commit Check
 
-提交前的**门禁检查**：审查文档 → 对齐 README → 保持目录卫生 → 规范 commit message，四项全过才允许 commit。本技能是轻量检查清单，不重写 code-review 的审查语义（[code-review](.agents/skills/code-review/SKILL.md) 是唯一事实源），也不替代任何完整实现流程——它是任何 commit 前的通用门禁，无论改动来自哪个流程。
+提交前的**门禁检查**：文档一致性 → 保持目录卫生 → 规范 commit message，三项全过才允许 commit。本技能是轻量检查清单，不重写 code-review 的审查语义（[code-review](.agents/skills/code-review/SKILL.md) 是唯一事实源），也不替代任何完整实现流程——它是任何 commit 前的通用门禁，无论改动来自哪个流程。
 
-## 四项检查（全部通过才 commit）
+## 三项检查（全部通过才 commit）
 
-### ① 审查文档
+### ① 文档一致性
+> 覆盖原 ① 审查文档 的全部检查项与原 ② 对齐 README 的全部检查项
 
 - 本次改动涉及的行为/接口/配置/命令是否有对应文档（README、`docs/`、技能正文）描述
 - 文档描述与实现一致：无过期信息、无声称未实现的功能、无遗留的旧接口描述
-- 涉及技能/模板/配置改动时，检查正文引用的路径与实际一致（如相对路径、目录结构）
 - 发现不一致 → 先修文档（或更新实现），再进入下一步
-
-### ② 对齐 README
-
 - 改动涉及项目结构、分发文件、技能/命令清单时，检查 README 中对应的结构说明、映射表、清单是否同步
 - 改动涉及用法/CLI/配置/示例时，检查 README 对应描述与实际一致
 - 存在模板镜像/分发副本时，确认源文件与副本同步（如有守护测试，跑一遍确认）
-- **特例：skill 与 AGENTS.md 的模板同步增量**：若 `git diff HEAD` 仅涉及 `AGENTS.md` 的 `tdd-implement ↔ implement` 路由行 + `.agents/skills/`/`.pi/skills/`/`.opencode/skills/` 的技能文件 + `.gitignore` 的 `.pi/` 忽略，且同目录存在 `AGENTS.md.bak`（模板同步 `sync`/`init --force` 的备份），视为模板同步的预期增量，禁止自动 `checkout -- AGENTS.md` 回滚；存在性按文件系统判（`ls .agents/skills/<name> .pi/skills/<name> .opencode/skills/<name>` 任一存在即算存在，不以 `git ls-files` 为准）；缺技能则正向补齐而非回滚文档
-
-### ③ 保持目录卫生
+- **特例**：`AGENTS.md` 的 `tdd-implement ↔ implement` 路由行 + 技能文件 + `.gitignore` 的 `.pi/` 忽略，且存在 `AGENTS.md.bak` 时，视为模板同步预期增量，不回滚
+### ② 保持目录卫生
 
 - `git status` 确认工作区只含预期改动：无残留未跟踪文件、无临时产物（调试脚本、日志、备份文件、`[DEBUG-...]` 残留）
-- 清理本次改动产生的临时文件（一次性脚本、转储、探针）——仅删本次产生的未跟踪临时产物，禁止为达干净而执行 `git reset --hard`、`git checkout .`、`git clean -fd`、`git stash push --include-untracked`、`git push --force`、`git rebase -i` 等（需显式用户确认；`stash` 如需使用改用 `--keep-index` 并在 `pop` 后校验 `git merge-base --is-ancestor $BASE_HEAD HEAD`）。详见 `CONTEXT.md` Git History Preservation 与 `docs/agents/skill-design.md` Rule 4
+- 无关文件（一次性脚本、转储、探针、调试日志）直接追加至 `.gitignore`，不执行删除；仅对本次产生的 `[DEBUG-...]` 临时产物做受控清理，禁止为达干净而执行 `git reset --hard`、`git checkout .`、`git clean -fd`、`git stash push --include-untracked`、`git push --force`、`git rebase -i` 等（需显式用户确认；`stash` 如需使用改用 `--keep-index` 并在 `pop` 后校验 `git merge-base --is-ancestor $BASE_HEAD HEAD`）。详见 `CONTEXT.md` Git History Preservation 与 `docs/agents/skill-design.md` Rule 4
 - 若本次会话记录了 `BASE_HEAD`，commit 前校验 `git merge-base --is-ancestor $BASE_HEAD HEAD`，失败即经 `git reflog` 恢复后才提交
 - 确认没有敏感信息进入改动（密钥、token、`.env`、私钥）——跑 `scripts/scan-sensitive.sh`，不用手写扫描
 - 提交后工作区应为干净状态（`git status` 无输出）
 
-### ④ 规范 commit message
+### ③ 规范 commit message
 
 - 格式遵循仓库约定（常见：`<type>(<scope>): <subject>`，type 用 feat/fix/docs/chore/refactor/test）
+> 模板：`feat(<scope>): <subject>` / `fix(<scope>): <subject>` — 例 `feat(tdd): add seam login`，`fix(ci): gate publish on verify`
 - subject 描述变更内容而非过程（不说"我做了什么"，说"改成了什么"）
 - 需要时补充 body：动机、影响范围、验收证据（测试结果、同步确认）
 - 一次 commit 只含一个逻辑变更；多主题拆多个 commit
@@ -42,24 +39,22 @@ description: "Run the pre-commit gate before any commit: verify docs match the i
 
 - 不做全量 code review：审查语义以 [code-review](.agents/skills/code-review/SKILL.md) 为唯一事实源，本技能不重写
 - 不替代实现流程的收尾：`tdd-implement` 阶段⑦已含文档对齐与目录卫生，本技能只管独立 commit 的门禁
-- 不顺手重构：只检查与本次改动直接相关的内容，不扩权到无关文档/目录
 - 不发明扫描规则：敏感信息检测跑 `scripts/scan-sensitive.sh`，不每次重写 grep 模式
 
 ## 执行顺序（回合内串行）
 
-1. 跑 ① 审查文档 → ② 对齐 README → ③ 保持目录卫生 → ④ 写 commit message
+1. 跑 ① 文档一致性 → ② 保持目录卫生 → ③ 写 commit message
 2. 任一项发现问题：修复后重跑该项，全部通过才 commit
 3. commit 后确认 `git status` 干净，工作结束
 
-**回合连续性**：四项检查在一个回合内串行完成，不等用户"继续"；发现问题立即修复并重查，直到四项全过或遇到外部阻塞（权限/授权缺失）。
+**回合连续性**：三项检查在一个回合内串行完成，不等用户"继续"；发现问题立即修复并重查，直到三项全过或遇到外部阻塞（权限/授权缺失）。
 
 ## 出口条件
 
-- [ ] 文档审查通过（无过期/不一致描述）
-- [ ] README 对齐（涉及结构/分发改动时已同步）
+- [ ] 文档一致性（文档与 README 均已对齐）
 - [ ] 目录卫生（`git status` 干净，无临时产物/敏感信息）
 - [ ] commit message 规范（遵循仓库格式）
-- 四项全过 → commit
+- 三项全过 → commit
 
 ## 引用
 

package/.agents/skills/diagnose-fix/SKILL.md

@@ -34,7 +34,6 @@ description: "Complete diagnosis→fix→regression channel for bugs: diagnose,
 
 - **无逃生舱**：不存在正确 seam 时，**本身即 finding**——向用户明确说明"架构阻止锁定该 bug"，请求 seam 决策或记录为架构改进建议（可转交 `/improve-codebase-architecture`）；**不得**绕过测试直接改代码。
 - **轻量声明**：本技能不套用 tdd-implement 的重流程——不做逐 todo 的循环编排、不设 seams 确认步骤、无 typecheck/commit 前置门禁；单 seam 修复场景直走红-绿。
-
 **出口条件**：回归测试先红 → 写最小修复 → 回归测试变绿。
 
 ## ③ 回归验证

package/.agents/skills/grill-to-spec/SKILL.md

@@ -57,7 +57,6 @@ disable-model-invocation: true
 | 触发点 | 条件 | 动作 |
 |--------|------|------|
 | ② seam 确认 | 用户不同意 seams | → ① 补充 |
-| ② 综合时 | 关键信息缺失 | → ① 补采 |
 | ② 发布后 | spec 有问题 | → ① 重新循环 |
 
 ## 异常终止
@@ -72,8 +71,6 @@ disable-model-invocation: true
 
 - ① 出口达成后方可进入 ②
 - 全程不写代码、不动源码：唯一允许写入的文件是领域文档（`CONTEXT.md`/ADR）与 spec
-- ② 探索代码只为确认 seams 与术语——只读不改
-- 产出物格式细则（Glossary/ADR/Spec 守则）与反模式见 [references/rules.md](references/rules.md)，不在本文件重写
 
 ## 引用
 

package/.agents/skills/scaffold-functional-test/SKILL.md

@@ -66,8 +66,6 @@ description: "Scaffold a repo-specific functional-test skill from spec — use w
 
 - 不替代 `tdd`/`tdd-implement` 的红绿循环与 `commit-check` 门禁
 - 不自动织入每次 `tdd-implement` 或 `commit-check`；仅 `tdd-implement --with-functional` 显式 opt-in
-- 不支持并行执行与 `docker` 隔离
-- 不处理超出混合推导锚点范围的源码静态分析隐式行为挖掘
 
 ## 引用
 

package/.agents/skills/tdd-implement/SKILL.md

@@ -45,4 +45,3 @@ description: "TDD seam red-green loop: use when the user provides a spec/ticket
 - Commit 门禁：[commit-check](.agents/skills/commit-check/SKILL.md)
 - 单线详规：[stages.md](references/stages.md)
 - 多 issue 编排：[orchestration.md](references/orchestration.md)
-- Issue tracker 约定：[issue-tracker.md](../../docs/agents/issue-tracker.md)

package/.agents/skills/tdd-implement/references/orchestration.md

@@ -46,7 +46,7 @@ for each 层 Li in L1..Ln:
   并行派发：为 Li 中每个 issue 启动一个子代理（single 模式，禁止 parallel tasks 数组）
   等待：阻塞直到 Li 全部子代理返回回执卡片
   验收：编排器按 A3 验收清单逐 issue 验收（只认回执卡片的关键信息 + 抽检验证，不消费全量日志）
-  层收敛验证：验收全通过进入全量验证（完成条件 4 项，全部通过才进下一层，任一失败按 A5 回退）：①该层全部 issue 验收通过 ②全量测试套件通过 ③`git status` 卫生（仅删本次临时产物，正向；护栏：禁止 `git reset --hard`/`git checkout .`/`git clean -fd`/`git stash push --include-untracked`）④历史校验 `git merge-base --is-ancestor $BASE_HEAD HEAD` 通过；验收不通过或全量/卫生/历史任一失败按 A5 回退重派该 issue
+  层收敛验证：验收全通过进入全量验证（完成条件 4 项，全部通过才进下一层，任一失败按 A5 回退）：①该层全部 issue 验收通过 ②相关测试套件通过（全量仅在 A4） ③`git status` 卫生（仅删本次临时产物，正向；护栏：禁止 `git reset --hard`/`git checkout .`/`git clean -fd`/`git stash push --include-untracked`）④历史校验 `git merge-base --is-ancestor $BASE_HEAD HEAD` 通过；验收不通过或相关/卫生/历史任一失败按 A5 回退重派该 issue
 全部层层收敛通过后进入 A4 全量收敛
 ```
 
@@ -108,7 +108,7 @@ for each 层 Li in L1..Ln:
 
 全部层逐 issue 验收通过后，编排器执行：
 
-1. **全量测试套件**：跑仓库完整测试套件（阶段④口径），失败则按 A5 回退。
+1. **全量测试套件**：跑仓库完整测试套件（所有 issue 执行完毕后的唯一全量，阶段④与 A2 已改为相关，仅此一次）
 2. **历史校验**：执行 `git merge-base --is-ancestor $BASE_HEAD HEAD`，若为 false 说明编排过程中历史被改写，立即经 `git reflog` 恢复后重跑收敛。
 3. **目录卫生**：`git status` 确认无 `[DEBUG-...]` 残留、无未跟踪临时文件；有残留则仅删本次临时产物后重检，禁止 `git reset --hard`/`git checkout .`/`git clean -fd`/`git stash push --include-untracked` 等。
 4. **汇总总结**：在会话输出汇总各 issue 的回执卡片关键信息（提交 hash / seams / 验收 checkbox / 测试结果 / 文档对齐）；不另写汇总文件，不透传子代理全量日志（各 issue 的 `## 实施总结` 已落盘，详查落盘文件）。

package/.agents/skills/tdd-implement/references/stages.md

@@ -35,7 +35,6 @@
 
 ### 边界
 
-- 本阶段只澄清需求——实现与测试设计在后续阶段进行
 
 ---
 
@@ -61,8 +60,6 @@
 
 - 一个 seam 对应一个公共接口上的一个待测行为（输入 + 预期输出）：一个 seam = 一个测试 + 一个最小实现 cycle；同一接口的多个行为拆分为多个 seam，而非内部函数
 
-> Seams 定义参考：[tdd 技能](.agents/skills/tdd/SKILL.md#seams--where-tests-go)
-
 ---
 
 ## 阶段 ③：TDD 开发循环
@@ -132,8 +129,6 @@
 - 全部 todo 为 done 才进入阶段④
 - 测试质量规则（公共接口验证、独立断言、mock 边界、重构归属 review）见 tdd 技能，不在本阶段重写
 
-> Mock 指南：[tdd/mocking.md](.agents/skills/tdd/mocking.md)
-> 好测试标准：[tdd/tests.md](.agents/skills/tdd/tests.md)
 
 ---
 
@@ -145,7 +140,7 @@
 
 ### 操作
 
-1. 运行仓库的完整测试套件
+1. 运行仓库的完整测试套件（单线模式的唯一全量；多 issue 子代理此步仅相关，全量由 A4 统一执行）
 2. 检查所有测试是否通过
 
 ### 出口条件
@@ -251,7 +246,7 @@
 
 ## Todo 规定
 
-本节为阶段②/③的共用规定，完成"任务拆分"到"回合内执行"的闭环。
+本节复用 `tdd`/`implement` 的 Todo 规定，`tdd-implement` 仅做多 issue 编排与串联，不再重写层次细节。
 
 ### 拆分层级（大小任务层次）
 

package/README.md

@@ -7,9 +7,15 @@ mattpocock/skills（`skills/engineering` + `skills/productivity`）的配置仓
 ```
 template/
 ├── AGENTS.md         项目级全局配置（行为路由 + 分文件指针）
-├── .pi/              pi-agent 项目配置（pi 标准结构：`.pi/skills/` 直放独有技能，自动发现）
-└── .opencode/        分发内容（目标仓库的 opencode 项目配置）
-    ├── skills/       6 个独有技能（ci-guard、tdd-implement、grill-to-spec、diagnose-fix、commit-check、scaffold-functional-test）
+├── .agents/
+│   └── skills/       32 个技能（上游 26 + 独有 6：ci-guard、tdd-implement、grill-to-spec、diagnose-fix、commit-check、scaffold-functional-test）单一源；模板全量 32，默认安装仅编程相关 22（engineering 18 + 核心独有 4，见 config/engineering.json），--all 展开全量
+├── .pi/              pi-agent 项目配置
+│   ├── skills/       空占位（项目自定义技能，含 .gitkeep + README.md）
+│   ├── prompts/      issue-audit 命令（prompt template）
+│   ├── docs/agents/  5 个分文件镜像
+│   └── CONTEXT.md    术语表镜像
+└── .opencode/        opencode 项目配置
+    ├── skills/       空占位（项目自定义技能，含 .gitkeep + README.md）
     ├── agents/       issue-audit 子代理定义
     ├── 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）
@@ -23,44 +29,40 @@ template/
 在目标仓库根目录执行一条命令：
 
 ```sh
-npx @heihei0299/matt-skills init
+npx @heihei0299/matt-skills init              # 默认仅编程相关 21（engineering + 独有），--all 展开全量 32
+npx @heihei0299/matt-skills init --all       # 安装全量 32（含 productivity）
 ```
 
-`init` 做两件事：
-
-1. 复制 `template/` 快照（`AGENTS.md`、`.opencode/`、`.pi/`）到当前目录；
-2. 把上游技能（engineering 17 个 + productivity 5 个）复制到 `.agents/skills/`。
-
-选项：`--dest <path>` 指定目标目录（默认当前目录）；`--force` 覆盖已存在的文件（直接覆盖，`AGENTS.md` 会备份到 `.bak`）（默认跳过）。
+`init` 做一件事：复制 `template/` 快照（`AGENTS.md`、`.agents/skills/`、`.opencode/`、`.pi/`）到当前目录；模板全量 32，默认仅安装编程相关 24（上游 engineering 桶，见 config/engineering.json + 独有 6），`--all` 展开全量，无需二次拉取上游。
 
+选项：`--dest <path>` 指定目标目录（默认当前目录）；`--force` 覆盖已存在的文件（直接覆盖，`AGENTS.md` 会备份到 `.bak`）（默认跳过）；`--all` 包含非编程技能（productivity，默认仅编程）。
 **增量同步（已有项目）**：已有项目更新到最新模板与技能：
 
 ```sh
-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                                 # 默认仅对比不写盘（check），有差异 exit 1，--json 可解析（仅编程）
+npx @heihei0299/matt-skills sync --all --json                  # 全量对比
+npx @heihei0299/matt-skills sync --apply                         # 安全增量：AGENTS.md 定制跳过，编程技能 rm+cp，不删多余 productivity（默认保留）
+npx @heihei0299/matt-skills sync --apply --all                  # 安全增量全量
+npx @heihei0299/matt-skills sync --force                         # 硬盖编程：AGENTS.md 备份后硬盖，编程技能全量 add/update/remove（含 productivity 删除与旧镜像清理）
+npx @heihei0299/matt-skills sync --force --all                  # 硬盖全量
 npx @heihei0299/matt-skills sync --apply --dest <path> --upstream <url> --ref <ref> --json  # 选项可组合
 ```
 
-`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/`，`/命令名` 触发）。
+`sync` 专为已有项目设计，三档语义：默认 `check` 仅对比不写盘（仅编程，`--all` 展开全量，打印“上游 HEAD / 本地非独有 vs 上游 / 新增/更新/删除/一致”表，`--json` 可解析，有差异 `exit 1`）；`--apply` 安全增量写盘（编程模式：`AGENTS.md` 若含独有路由如 `tdd-implement` 则跳过，`.agents/skills` 按编程子集 `rm+cp force` 覆盖但不 `remove` 多余 productivity，`template/.agents/.opencode/.pi` 按过滤增量 `add/update`，旧镜像 `.pi/skills` + `.opencode/skills` 中残留的共享技能自动清理但保留项目自定义；`--all` 则全量）；`--force` 硬盖（编程模式：`AGENTS.md` 备份 `.bak` 后强制覆盖，编程技能 `add/update/remove` 全做（含 productivity 删除与旧镜像清理）；`--all` 则全量硬盖）。`--dest`、`--upstream`、`--ref`、`--json`、`--all` 在三档均可透传。
+目标仓库会话即自动加载共享技能（`.agents/skills/` 单一源，默认编程 22，`--all` 全量 32）与项目级全局配置（行为路由表、分文件约定）；项目自定义技能可按需放入 `.pi/skills/` 或 `.opencode/skills/`（按 harness 自动发现）；`issue-audit` 以子代理 + 命令形式分发（`.opencode/agents/`、`.opencode/commands/`）；9 个显式触发技能注册为 opencode 命令（`.opencode/commands/`，`/命令名` 触发）。
+**pi-agent 用户**：初始化命令完全相同。pi 从 `.agents/skills/` 自动发现全部共享技能，无需额外指向；`.pi/skills/` 仅用于项目自定义。首次在目标仓库交互启动时 pi 会询问项目信任，用 `/trust` 保存即可。
 
-**pi-agent 用户**：初始化命令完全相同。pi 从 `.pi/skills/` 自动发现独有技能（ci-guard、tdd-implement、grill-to-spec、diagnose-fix、commit-check、scaffold-functional-test），无需任何指向配置；首次在目标仓库交互启动时 pi 会询问项目信任，用 `/trust` 保存即可。
-
-**手动方式（备选）**：无 npx 环境时，将 `template/` 整个文件夹复制到目标仓库根目录，再拉取上游技能：
+**手动方式（备选）**：无 npx 环境时，将 `template/` 整个文件夹复制到目标仓库根目录即可（已含全量技能）：
 
 ```sh
 cp -r template/. /path/to/target/
-git clone --depth 1 https://github.com/mattpocock/skills.git /tmp/mattpocock-skills
-cp -r /tmp/mattpocock-skills/skills/engineering/. .agents/skills/
-cp -r /tmp/mattpocock-skills/skills/productivity/. .agents/skills/
-rm -rf /tmp/mattpocock-skills
 ```
 
-上游没有 `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/`，`/命令名` 触发）。
+旧的手动拉取上游步骤已不再需要；若需单独验证上游，仍可：
 
-**pi-agent 用户**：初始化命令完全相同。pi 从 `.pi/skills/` 自动发现独有技能（ci-guard、tdd-implement、grill-to-spec、diagnose-fix、commit-check、scaffold-functional-test），无需任何指向配置；首次在目标仓库交互启动时 pi 会询问项目信任，用 `/trust` 保存即可。
+```sh
+git clone --depth 1 https://github.com/mattpocock/skills.git /tmp/mattpocock-skills
+```
 
 ## 维护约定
 
@@ -68,18 +70,18 @@ rm -rf /tmp/mattpocock-skills
 
 | 工作区 | 模板 |
 |--------|------|
-| `.agents/skills/{ci-guard,tdd-implement,grill-to-spec,diagnose-fix,commit-check,scaffold-functional-test}/` | `template/.opencode/skills/{ci-guard,tdd-implement,grill-to-spec,diagnose-fix,commit-check,scaffold-functional-test}/` |
-| `.agents/skills/{ci-guard,tdd-implement,grill-to-spec,diagnose-fix,commit-check,scaffold-functional-test}/` | `template/.pi/skills/{ci-guard,tdd-implement,grill-to-spec,diagnose-fix,commit-check,scaffold-functional-test}/` |
+| `.agents/skills/`（全部 32 个：上游 26 + 独有 6） | `template/.agents/skills/`（全量快照，单一源） |
+| `.agents/skills/` 的 harness 占位说明 | `template/.pi/skills/.gitkeep` + `README.md`、`template/.opencode/skills/.gitkeep` + `README.md`（空目录占位，供项目自定义） |
 | `.opencode/agents/issue-audit.md`、`commands/*.md`（issue-audit + 9 个显式技能命令）、`.gitignore`、`package.json`、`package-lock.json` | `template/.opencode/` 同名 |
 | `.pi/prompts/issue-audit.md`（pi 命令：opencode 版适配，去 subagent frontmatter） | `template/.pi/prompts/issue-audit.md` |
 | `AGENTS.md` | `template/AGENTS.md`（引用映射为 `.opencode/` 路径） |
-| `CONTEXT.md` | `template/.opencode/CONTEXT.md` |
-| `docs/agents/*` | `template/.opencode/docs/agents/*`（引用映射为 `.opencode/` 路径） |
+| `CONTEXT.md` | `template/.opencode/CONTEXT.md` + `template/.pi/CONTEXT.md` |
+| `docs/agents/*` | `template/.opencode/docs/agents/*` + `template/.pi/docs/agents/*`（引用映射为 `.opencode/` 路径） |
 
-独有技能需同步**双份**：`.opencode/skills/`（opencode 分发）与 `.pi/skills/`（pi 标准分发）。
+共享技能统一在 `.agents/skills` 单一源，不再双份镜像到 `.opencode/skills` / `.pi/skills`。
 `test/template-sync.test.js` 守护同步（含路径映射），漏同步测试即红。
 
-新增技能前先查上游 `mattpocock/skills` 是否已存在；仅上游没有的技能才作为独有技能落在本仓库（当前独有：ci-guard、tdd-implement、grill-to-spec、diagnose-fix、commit-check、scaffold-functional-test），上游技能一律不进 `template/`。
+新增技能前先查上游 `mattpocock/skills` 是否已存在；仅上游没有的技能才作为独有技能落在本仓库（当前独有：ci-guard、tdd-implement、grill-to-spec、diagnose-fix、commit-check、scaffold-functional-test），上游技能通过 `scripts/sync-upstream.js` 同步到 `.agents/skills` 后随模板分发。
 
 ## harness 支持
 
@@ -101,39 +103,38 @@ pi 下对应能力以内置工具或已装扩展为准（`AGENTS.md`「能力边
 
 - **全局**：`~/.pi/agent/skills/`、`~/.agents/skills/`（用户级技能，自动发现）；配置在 `~/.pi/agent/settings.json`
 - **项目**：
-  - `.pi/skills/` — pi 标准结构，目录内技能**自动发现**（本项目独有技能直放此处）
+  - `.agents/skills/` — 共享技能单一源（默认编程 22，`--all` 全量 32，自动发现）
+  - `.pi/skills/` — 项目自定义技能（pi 标准结构，自动发现，仅放项目本地技能）
   - `.pi/prompts/` — pi 命令（prompt template）自动发现，如 `issue-audit.md` → `/issue-audit`
-  - `.agents/skills/` — 自动发现（上游技能与 workspace 技能在此）
-  - `.pi/settings.json` — `skills` 数组可选，指向额外技能目录（本项目不再使用）
-
+  - `.pi/settings.json` — 已简化为空对象（历史指向 `.opencode/skills` 已移除，共享技能走 `.agents/skills`）
 ### opencode
 
-- **项目**：`.opencode/skills/`（技能）、`.opencode/agents/`（子代理）、`.opencode/commands/`（命令：issue-audit + 9 个显式触发技能，`/命令名` 触发）、`.opencode/docs/`（文档）
-- **全局**：`~/.config/opencode/`（`opencode.json` 配置、`skills/`、`agents/`、`commands/`），按 opencode 官方文档
+- **项目**：`.agents/skills/`（共享技能单一源，默认编程 22，`--all` 全量 32）、`.opencode/skills/`（项目自定义技能）、`.opencode/agents/`（子代理）、`.opencode/commands/`（命令：issue-audit + 9 个显式触发技能，`/命令名` 触发）、`.opencode/docs/`（文档）
+
+同一份技能（Agent Skills 标准）与 `AGENTS.md` 行为路由在两种 harness 下均可加载：pi 与 codex/claude 从 `.agents/skills/` 自动发现；opencode 按本模板约定同样优先读取 `.agents/skills/`（`.opencode/skills/` 仅用于项目自定义）。
 
-同一份技能（Agent Skills 标准）与 `AGENTS.md` 行为路由在两种 harness 下均可加载：opencode 从 `.opencode/skills/`、pi 从 `.pi/skills/` 与 `.agents/skills/`。
 ## 仓库 CLI
 
 仓库内提供安装管理 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 [--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 默认）
+node bin/cli.js init [--dest <dir>] [--force] [--all]                               # 初始化项目：template 全量 32，默认编程 22
+node bin/cli.js sync [--apply|--force] [--all] [--dest <path>] [--upstream <url>] [--ref <ref>] [--json]  # 同步已有项目到最新（默认编程）
+node bin/cli.js list [--json] [--all]                                            # 列出技能（默认编程）
+node bin/cli.js install [选项]                                                 # 把技能复制到目标工具目录（交互式选择，默认编程）
+node bin/cli.js check [--json] [--all] [--upstream <url>] [--ref <ref>]          # 只读检查上游技能是否最新（等价 sync 默认，仅编程）
 ```
 
-`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`）。
+`init` 选项：`--dest <path>` 指定目标目录（默认当前目录）；`--force` 覆盖已存在的文件（直接覆盖，`AGENTS.md` 会备份到 `.bak`）（默认跳过）；`--all` 包含非编程（productivity，默认仅编程 22），见「初始化」。
+`sync` 选项：`--apply` 安全增量（编程默认：`AGENTS.md` 定制跳过、编程技能不删 productivity，旧镜像清理保留项目自定义；`--all` 全量），`--force` 硬盖（编程默认：`AGENTS.md` 备份后硬盖、编程技能与模板全量 `remove` 含 productivity 删除与旧镜像清理；`--all` 全量）；`--all` 展开全量；`--dest <path>` 目标目录；`--upstream <url>` 上游地址；`--ref <ref>` 上游分支；`--json` JSON 输出；默认无参等价 `check` 仅对比不写盘（仅编程，`--all` 全量），`--json` 可解析，有差异 `exit 1`。
+`check` 选项：`--json`、`--all`（默认仅编程）、`--upstream <url>`、`--ref <ref>`（等价 `sync` 默认 `check`）。
 
 `install` 选项：
 
 - `--dest <dir>`：复制到指定目录（覆盖工具映射）
-- `--tools <t1,t2>`：指定工具，项目级映射 `codex→.agents/skills`、`pi→.pi/skills`、`opencode→.opencode/skills`、`claude→.claude/skills`
+- `--tools <t1,t2>`：指定工具，项目级已统一 `codex/pi/opencode/claude → .agents/skills`（共享技能单一源，`.pi/skills`/`.opencode/skills` 仅用于项目自定义）
 - `--global`：安装到全局目录（`~/.codex/skills`、`~/.pi/agent/skills`、`~/.config/opencode/skills`、`~/.claude/skills`）；`--project` 回到项目级
-- `--all`：安装全部技能（默认交互勾选）；`--force`：覆盖已存在的技能
+- `--all`：安装全部技能（默认仅编程 22，`--all` 32，交互勾选时仅列编程）；`--force`：覆盖已存在的技能
 
 
 ### 上游同步（自动更新）
@@ -152,7 +153,7 @@ node scripts/sync-upstream.js --check               # 等价底层脚本（CLI s
 node scripts/sync-upstream.js --apply --dry-run
 ```
 
-实现细节：`scripts/sync-upstream.js` 为单一事实源（CLI 与 Actions 共用），以 `config/proprietary.json` 为独有白名单，上游通过 `git clone --depth 1 https://github.com/mattpocock/skills.git` 获取，比对 `SKILL.md` 的 sha256，自动处理新增/更新/重命名/删除；Actions 提 PR 后需人工合入，合入后按“发布”节打 `v*` 标签即发布（自动 patch 发版可在后续扩展为 PR 合入后自动 bump）。
+实现细节：`scripts/sync-upstream.js` 为单一事实源（CLI 与 Actions 共用），以 `config/proprietary.json` 为独有白名单 + `config/engineering.json` 为编程白名单（engineering 桶即编程，productivity 默认不装，`--all` 展开），上游通过 `git clone --depth 1 https://github.com/mattpocock/skills.git` 获取，比对 `SKILL.md` 的 sha256，自动处理新增/更新/重命名/删除；Actions 提 PR 后需人工合入，合入后按“发布”节打 `v*` 标签即发布（自动 patch 发版可在后续扩展为 PR 合入后自动 bump）。
 上游重命名映射：`RENAMES = { "writing-great-skills": "writing-for-agents" }`，Actions/CLI 均会删除旧目录并复制新目录。
 ## 发布
 
@@ -180,14 +181,14 @@ npm publish
 - `prepublishOnly` 自动跑全量测试（`node --test test/*.test.js`）
 - 发布内容 = `bin/` + `template/` + `.agents/skills/` + `README.md`，由 `package.json` 的 `files` 白名单控制，`npm pack` 可预览
 - `template/` 与 `.agents/skills/` 是包内容：改动后需重新发版才对目标仓库生效
+
 ## 开发
 
 ```sh
-npm test                          # 全量测试 122 项
-npm run build:template            # 从单源生成 template/.opencode/.pi（config/proprietary.json 为单一事实源）
+npm test                          # 全量测试
+npm run build:template            # 从单源生成 template/.agents/skills（全量 32 技能）+ 空占位
 ```
 
 交互模式依赖 `prompts`（见 `package.json`）；测试见 `test/cli.test.js`、`test/cli-init.test.js`、`test/template-sync.test.js`。
 
 用户手动触发的功能测试：`/instance-test`（matt-skills 专属示范，见 `.agents/skills/instance-test/SKILL.md`）——验证 sync 合并 update 后的行为，`references/instances.md` 由 `scaffold-functional-test` 从 spec 生成；通用模板已废弃。新增生成器 `/scaffold-functional-test`（见 `.agents/skills/scaffold-functional-test/SKILL.md`）——读 spec 生成定制化功能测试 skill。
-