@heihei0299/matt-skills 1.3.3 → 1.5.2

package/template/.pi/CONTEXT.md

@@ -5,11 +5,11 @@ The domain vocabulary for this repo — two sections: how this repository is pos
 ## 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.
+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 ALL skills via `.agents/skills` (upstream 26 + proprietary 6). 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/`.
+mattpocock/skills — the source of the 26 skill bodies (skills/engineering + skills/productivity) that are mirrored into this repo's `.agents/skills` and then distributed via the Template Snapshot. This repo syncs them via `scripts/sync-upstream.js` and `matt-skills sync`.
 _Avoid_: source repo, skill origin
 
 **Proprietary Skill** (独有技能):
@@ -17,23 +17,23 @@ A skill that does not exist upstream and lives only in this repo (currently ci-g
 _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/{ci-guard,tdd-implement,grill-to-spec,diagnose-fix,commit-check,scaffold-functional-test}` → `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/`.
+The root-level working copies of the template content — `.agents/skills/` (ALL skills: upstream + proprietary, single source), `.opencode/` (issue-audit agent, explicit-skill commands), `.pi/` (pi-agent prompts: `issue-audit`), `AGENTS.md`, `CONTEXT.md`, `docs/`. Where this repo's own sessions load, modify, and test the content. The template paths mirror them: `.agents/skills/` → `template/.agents/skills/` (full 32-skill snapshot), `.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/` + `template/.pi/`. Harness-specific skill dirs `.pi/skills/` and `.opencode/skills/` are reserved for project-local custom skills (empty placeholders with `.gitkeep` + `README.md` in the template).
 _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.
+Everything under `template/` — the mirror of the workspace content: ALL skills under `.agents/skills/` (single source, auto-discovered by pi/codex/claude and, via convention, by opencode from the same path), harness skill dirs `.pi/skills/` + `.opencode/skills/` as empty placeholders for project custom skills, opencode commands under `.opencode/commands/`, the pi issue-audit command under `.pi/prompts/`, discipline files and glossary under `.opencode/` + `.pi/`, AGENTS.md at the top level, generated by `node scripts/build-template.js`, used to initialize other repositories. 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`.
+A repository initialized by copying `template/` into its root (`cp -r template/. <target>/`). It then loads ALL shared skills from its own `.agents/skills/` (single source, 32 skills), project-local custom skills from `.pi/skills/` / `.opencode/skills/` (if any), 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/` + `.pi/` 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.
+The one-time action of setting up a Target Repository: copying `template/` into its root (`cp -r template/. <target>/`). All 32 skills are already included via `template/.agents/skills/`; no separate upstream fetch is needed. 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` 并删除。
+`matt-skills sync` 同步 Target Repository 的模板与技能：默认仅对比不写盘（`check`），`--apply` 为安全增量（`AGENTS.md` 有定制如 `tdd-implement` 则跳过，`.agents/skills` 全量 `rm+cp` 强制覆盖但 `force` 外不 `remove` 多余技能，`template/.agents/.opencode/.pi` 增量 `add/update`，旧镜像 `.pi/skills` + `.opencode/skills` 中残留的共享技能自动清理但保留项目自定义）、`--force` 为硬盖（`AGENTS.md` 备份 `.bak` 后强制覆盖，技能与模板全量 `add/update/remove`，含多余技能删除与旧镜像清理）。`update` 已合并到 `sync` 并删除。
 _Avoid_: update, force sync
 
 ## Skill Design

package/template/.pi/skills/README.md

@@ -0,0 +1,4 @@
+# 项目技能（pi）
+
+此目录用于存放项目自定义技能（project-local skills）。
+共享技能（上游 + 独有）统一在 `.agents/skills/`。

package/template/AGENTS.md

@@ -26,7 +26,7 @@
 
 以全局 AGENTS.md 安全铁律为准，本仓库无附加差异。
 
-## 行为路由
+## 行为路由（默认 22 自动发现，`--all` 展开至 32）
 
 命中即行动，回复中简短声明所用技能与原因。
 
@@ -35,17 +35,15 @@
 - 实现（有 spec）→ implement（无 spec 先 to-spec）；测试先行 → tdd
 - 设计打磨 → grilling；达成共识→spec → grill-to-spec（grilling→domain-modeling→to-spec）
 - 领域术语/ADR → domain-modeling；模块接口 → codebase-design；巨型规划 → wayfinder
-- 诊断 → diagnose-fix（编排 diagnosing-bugs 诊断 + tdd 修复，修复环节强制 TDD）；审查 → code-review；合并冲突 → resolving-merge-conflicts；提交前 → commit-check（审查文档 + 对齐 README + 目录卫生 + commit message）
+- 诊断 → diagnose-fix（编排 diagnosing-bugs + tdd，硬门槛）；审查 → code-review；合并冲突 → resolving-merge-conflicts；提交前 → commit-check（文档一致性 → 目录卫生 → commit message，三项）
 - 分诊 → triage；架构扫描 → improve-codebase-architecture；综合 spec → to-spec；拆票 → to-tickets
-- 教学 → teach；交接 → handoff；技能写作 → writing-for-agents
+- 可选（需 `--all` 才发现）：grill-me / grilling / handoff / teach / to-questionnaire / wait-what / writing-for-agents / ci-guard / scaffold-functional-test / instance-test
 - 兜底 → ask-matt；模板维护 → README.md
 
-显式触发（须用户 `/` 发起）：grill-to-spec、wayfinder、to-spec、to-tickets、triage、improve-codebase-architecture、teach、handoff、writing-for-agents
+显式触发（须用户 `/` 发起，默认 22 中仅 grill-to-spec/wayfinder/to-spec/to-tickets/triage/improve-codebase-architecture 为默认；其余 teach/handoff/writing-for-agents 需 `--all`）：grill-to-spec、wayfinder、to-spec、to-tickets、triage、improve-codebase-architecture、teach、handoff、writing-for-agents
 
 ## 分文件
 
-- 运行时纪律与执行/文档维护细则 → `docs/agents/runtime-discipline.md`
-- 技能设计规范 → `docs/agents/skill-design.md`
 - Issue tracker → `docs/agents/issue-tracker.md`；Triage labels → `docs/agents/triage-labels.md`；Domain docs → `docs/agents/domain.md`
 - 术语表 → `CONTEXT.md`
 

package/template/.opencode/skills/commit-check/SKILL.md

@@ -1,67 +0,0 @@
----
-name: commit-check
-description: "Run the pre-commit gate before any commit: verify docs match the implementation, align README, keep the directory clean, and write a clear commit message. Use whenever the user is about to commit or asks to check anything about the commit — e.g. verifying docs/README are in sync, cleaning up temp files, scanning for secrets/keys/.env in the change, or having you write the commit message. Not for general PR/code review (that's code-review), and not for explaining git/commit conventions (that's a teach task)."
----
-
-# Commit Check
-
-提交前的**门禁检查**：审查文档 → 对齐 README → 保持目录卫生 → 规范 commit message，四项全过才允许 commit。本技能是轻量检查清单，不重写 code-review 的审查语义（[code-review](.agents/skills/code-review/SKILL.md) 是唯一事实源），也不替代任何完整实现流程——它是任何 commit 前的通用门禁，无论改动来自哪个流程。
-
-## 四项检查（全部通过才 commit）
-
-### ① 审查文档
-
-- 本次改动涉及的行为/接口/配置/命令是否有对应文档（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` 为准）；缺技能则正向补齐而非回滚文档
-
-### ③ 保持目录卫生
-
-- `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
-- 若本次会话记录了 `BASE_HEAD`，commit 前校验 `git merge-base --is-ancestor $BASE_HEAD HEAD`，失败即经 `git reflog` 恢复后才提交
-- 确认没有敏感信息进入改动（密钥、token、`.env`、私钥）——跑 `scripts/scan-sensitive.sh`，不用手写扫描
-- 提交后工作区应为干净状态（`git status` 无输出）
-
-### ④ 规范 commit message
-
-- 格式遵循仓库约定（常见：`<type>(<scope>): <subject>`，type 用 feat/fix/docs/chore/refactor/test）
-- subject 描述变更内容而非过程（不说"我做了什么"，说"改成了什么"）
-- 需要时补充 body：动机、影响范围、验收证据（测试结果、同步确认）
-- 一次 commit 只含一个逻辑变更；多主题拆多个 commit
-
-## 不做什么
-
-- 不做全量 code review：审查语义以 [code-review](.agents/skills/code-review/SKILL.md) 为唯一事实源，本技能不重写
-- 不替代实现流程的收尾：`tdd-implement` 阶段⑦已含文档对齐与目录卫生，本技能只管独立 commit 的门禁
-- 不顺手重构：只检查与本次改动直接相关的内容，不扩权到无关文档/目录
-- 不发明扫描规则：敏感信息检测跑 `scripts/scan-sensitive.sh`，不每次重写 grep 模式
-
-## 执行顺序（回合内串行）
-
-1. 跑 ① 审查文档 → ② 对齐 README → ③ 保持目录卫生 → ④ 写 commit message
-2. 任一项发现问题：修复后重跑该项，全部通过才 commit
-3. commit 后确认 `git status` 干净，工作结束
-
-**回合连续性**：四项检查在一个回合内串行完成，不等用户"继续"；发现问题立即修复并重查，直到四项全过或遇到外部阻塞（权限/授权缺失）。
-
-## 出口条件
-
-- [ ] 文档审查通过（无过期/不一致描述）
-- [ ] README 对齐（涉及结构/分发改动时已同步）
-- [ ] 目录卫生（`git status` 干净，无临时产物/敏感信息）
-- [ ] commit message 规范（遵循仓库格式）
-- 四项全过 → commit
-
-## 引用
-
-- 代码审查语义：[code-review](.agents/skills/code-review/SKILL.md)（唯一事实源，本技能不重写）
-- 完整实现流程：[tdd-implement](.agents/skills/tdd-implement/SKILL.md)（含流程内收尾的文档对齐与目录卫生）

package/template/.opencode/skills/diagnose-fix/SKILL.md

@@ -1,66 +0,0 @@
----
-name: diagnose-fix
-description: "Complete diagnosis→fix→regression channel for bugs: diagnose, then fix via a TDD red-green loop with a hard gate (no fix code before a failing regression test). Use when the user says diagnose/debug/fix this, or reports something broken/throwing/failing/slow — prefer this over diagnosing-bugs when a fix is wanted, not just a diagnosis."
----
-
-# Diagnose Fix
-
-诊断 **bug** 并修复的编排技能：诊断语义以 [diagnosing-bugs](.agents/skills/diagnosing-bugs/SKILL.md) 为唯一事实源，修复语义以 [tdd 技能](.agents/skills/tdd/SKILL.md) 为唯一事实源；本技能只编排三个阶段并设一道**硬门槛**，不重写两个上游技能的规则。
-
-本技能是**长程任务**（Long-Horizon Skill）：诊断 → 修复 → 回归在**一个回合内串行完成**，自带**回合连续性**（Turn Continuity）规则（见下文）。术语定义见 `CONTEXT.md`，技能设计规则见 `docs/agents/skill-design.md`。
-
-## 流程速览
-
-```
-① 诊断 → ② TDD 修复（硬门槛）→ ③ 回归验证
-```
-
-## ① 诊断
-
-按 [diagnosing-bugs](.agents/skills/diagnosing-bugs/SKILL.md) 的 Phase 1-4 执行：
-
-1. **反馈回路**（Phase 1）：构建能对 _这个 bug_ 变红的紧致 pass/fail 信号——优先失败测试，其次 curl/CLI/浏览器脚本/重放/一次性 harness 等；没有回路不进入假设。
-2. **复现 + 最小化**（Phase 2）：跑回路看它红，确认失败模式与用户描述一致；逐步删减输入/调用方/配置，只保留 load-bearing 元素。
-3. **假设**（Phase 3）：生成 3-5 个可证伪的排名假设，先展示给用户。
-4. **探针**（Phase 4）：一次只改一个变量，临时探针用 `[DEBUG-...]` 前缀标记。
-
-**出口条件**：反馈回路已红（已实际跑过并确认捕捉到该 bug）、复现已最小化。诊断完成前不写任何修复代码。
-
-## ② TDD 修复（硬门槛）
-
-**TDD 语义（红-绿循环、seam 定义、好测试标准、anti-patterns）以 [tdd 技能](.agents/skills/tdd/SKILL.md) 为唯一事实源**——本技能不重写；进入本阶段前先读取 tdd 技能。
-
-**硬门槛**：写任何修复代码之前，必须已存在一个**失败**的回归测试——把最小复现转写为正确 seam 上的测试，先运行看它红，然后才允许写修复代码让它变绿。
-
-- **无逃生舱**：不存在正确 seam 时，**本身即 finding**——向用户明确说明"架构阻止锁定该 bug"，请求 seam 决策或记录为架构改进建议（可转交 `/improve-codebase-architecture`）；**不得**绕过测试直接改代码。
-- **轻量声明**：本技能不套用 tdd-implement 的重流程——不做逐 todo 的循环编排、不设 seams 确认步骤、无 typecheck/commit 前置门禁；单 seam 修复场景直走红-绿。
-
-**出口条件**：回归测试先红 → 写最小修复 → 回归测试变绿。
-
-## ③ 回归验证
-
-1. 重跑诊断阶段①的**原始反馈回路**（未最小化场景）确认症状消失。
-2. 清理：删除所有 `[DEBUG-...]` 标记的临时探针与一次性 harness（`grep` 前缀确认无残留）。
-3. 在 commit / PR 消息中写明**验证正确的假设**（诊断阶段哪个假设被证实），让下一个调试者受益。
-
-**出口条件**：原始症状消失 + 回归测试绿 + 临时探针清理完成。
-
-## 反模式（不做什么）
-
-完整反模式清单见 [references/anti-patterns.md](references/anti-patterns.md)——正文各阶段规则是正面约束，反模式清单是负向边界；细节只在一处存在，本文件不重复。
-
-## 回合连续性规则
-
-诊断 → 修复 → 回归**在一个回合内串行完成**，不等用户"继续"：构建回路 → 复现 → 假设 → 探针 → 失败测试 → 修复 → 回归 → 清理整条链一气呵成，中途不停顿。
-
-输出只允许发生在以下三种情况：
-- **合规交互点**：技能要求的用户确认——阶段①假设清单展示、阶段②无 seam finding 上报或 seam 决策请求
-- **外部阻塞**：权限拒绝、缺失授权、依赖不可用——明确说明所需授权或替代路径，不静默停止
-- **阶段出口**：整个阶段的出口条件满足（阶段①回路已红 + 复现最小化；阶段②失败测试已红 → 修复变绿；阶段③症状消失 + 回归绿 + 清理完成）
-
-预告下一步后立即执行该步骤，回合终点仅为合规交互点、外部阻塞或阶段出口条件满足。进度输出本身不结束回合——输出后继续执行，直到三类终点之一达成。
-
-## 引用
-
-- 诊断：[diagnosing-bugs](.agents/skills/diagnosing-bugs/SKILL.md)
-- TDD 修复：[tdd 技能](.agents/skills/tdd/SKILL.md)、[tdd/tests.md](.agents/skills/tdd/tests.md)、[tdd/mocking.md](.agents/skills/tdd/mocking.md)

package/template/.opencode/skills/grill-to-spec/SKILL.md

@@ -1,83 +0,0 @@
----
-name: grill-to-spec
-description: "Router：编排 grill-with-docs → to-spec，把模糊想法打磨成可执行 Spec。Use when the user asks to grill/design/polish an idea into a spec——只产出领域文档与 spec，不写代码。"
-disable-model-invocation: true
----
-
-# Grill to Spec
-
-**grill-with-docs**（grilling + domain-modeling）与 **to-spec** 的编排器。本 skill 只做编排：把设计压力测试成共识，把共识综合成 spec 发布——不写代码，不动源码。
-
-## 职责
-
-| 做 | 不做 |
-|----|------|
-| 编排 `grill-with-docs` → `to-spec` 完整通道 | 不编写代码、不修改任何源码（含测试） |
-| 引导用户从模糊想法 → 结构化 spec | 不拆 tickets（`/to-tickets` 职责） |
-| grilling 逐问挑战、打磨设计 | 不调用 `/code-review` |
-| 同步产出领域文档（glossary inline；ADR 草稿经用户确认后落盘） | 阶段②仅综合，不新增采访 |
-| 综合对话为可执行的 spec 文档并发布 | 不维护已发布的 spec |
-| 产出物仅限领域文档与 spec | 实现与修复交给实现类 skill（如 `/tdd-implement`） |
-
-## 流程
-
-```text
-① Grill with docs → ② Synthesize to spec
-```
-
-① 加载 `/grill-with-docs`：grilling 采访（一次一问、等反馈；决策逐条交由用户定夺）+ domain-modeling 产出 glossary/ADR。出口：用户确认共识达成。
-
-   ① 内 ADR 子流转（与 glossary 的 inline 更新严格区分）：
-   1. 触发：仅当 domain-modeling 三条件全满足（难逆转 / 无上下文费解 / 真实权衡）才提议 ADR
-   2. 草稿：按 ADR-FORMAT 把完整标题+正文展示给用户审阅，等待反馈
-   3. 确认：用户显式说「确认/写入」才落盘；用户拒绝则不写、继续访谈；用户要求修改则改草稿重新确认
-   4. 未确认前不得创建或写入 `docs/adr/` 下的任何文件
-
-② 加载 `/to-spec`：探索代码（glossary 词汇贯穿 spec、尊重相关 ADR）→ 确认 seams（既有优先、最高 seam、理想一个）→ 编写 spec 草稿 → 展示给用户确认（只展示等决定，不新增采访提问）→ 发布到 `.scratch/<feature-slug>/spec.md` 并标 `ready-for-agent`。出口：spec 已发布。
-
-## 产出物（格式严格对齐下游技能）
-
-本技能产出物仅以下三种，格式以各技能文件为唯一事实源，不在本技能重写：
-
-| 产出物 | 位置 | 格式来源 |
-|--------|------|----------|
-| Glossary | `CONTEXT.md`（多上下文：`CONTEXT-MAP.md` + 各上下文 `CONTEXT.md`） | [CONTEXT-FORMAT.md](.agents/skills/domain-modeling/CONTEXT-FORMAT.md) |
-| ADR | `docs/adr/NNNN-slug.md`（多上下文：系统级在根，上下文级在 `src/<ctx>/docs/adr/`） | [ADR-FORMAT.md](.agents/skills/domain-modeling/ADR-FORMAT.md) |
-| Spec | 发布到 issue tracker：`.scratch/<feature-slug>/spec.md` | [to-spec 七节模板](.agents/skills/to-spec/SKILL.md) |
-
-三类产出物的格式细则（Glossary 守则 / ADR 守则 / Spec 守则）见 [references/rules.md](references/rules.md)——SKILL.md 不重复细节。
-
-## 不可协商规则（无任何例外）
-
-- **写入 ADR 必须由用户显式确认，无论任何情况、无任何例外**：三条件全满足、决策看似显然、② 补记，均不豁免。ADR 一旦落盘记录不可撤销（可 supersede，但痕迹永存），全部门槛都在写入之前
-- **ADR 与 glossary 不对称**：`CONTEXT.md` 术语可随访谈 inline 更新（domain-modeling 规则），ADR 必须先审草稿、用户确认后才落盘——禁止把 inline 逻辑套用到 ADR
-
-## 回退
-
-| 触发点 | 条件 | 动作 |
-|--------|------|------|
-| ② seam 确认 | 用户不同意 seams | → ① 补充 |
-| ② 综合时 | 关键信息缺失 | → ① 补采 |
-| ② 发布后 | spec 有问题 | → ① 重新循环 |
-
-## 异常终止
-
-| 情况 | 处理 |
-|------|------|
-| 用户中途放弃 / 无主题 | 终止 |
-| tracker 未配置 | 提示 `/setup-matt-pocock-skills`，终止 |
-| ① 超过 5 轮无进展 | 建议暂停或缩小范围 |
-
-## 约束
-
-- ① 出口达成后方可进入 ②
-- 全程不写代码、不动源码：唯一允许写入的文件是领域文档（`CONTEXT.md`/ADR）与 spec
-- ② 探索代码只为确认 seams 与术语——只读不改
-- 产出物格式细则（Glossary/ADR/Spec 守则）与反模式见 [references/rules.md](references/rules.md)，不在本文件重写
-
-## 引用
-
-- [grill-with-docs](.agents/skills/grill-with-docs/SKILL.md)
-- [grilling](.agents/skills/grilling/SKILL.md)
-- [domain-modeling](.agents/skills/domain-modeling/SKILL.md)
-- [to-spec](.agents/skills/to-spec/SKILL.md)

package/template/.opencode/skills/tdd-implement/references/orchestration.md

@@ -1,136 +0,0 @@
-# 多 issue 编排（按依赖分层并行）
-
-本文件仅在多 issue 编排模式下生效；单 issue / 单 spec 走 [stages.md](stages.md) 单线流程，不经过本文件。
-
-多 issue 触发条件：`.scratch/<feature>/issues/` 下存在多个 issue 文件且至少部分含 `Blocked by` 依赖声明。
-
-## 目录
-
-- [A0. 依赖图构建](#a0-依赖图构建)
-- [A1. 拓扑分层](#a1-拓扑分层)
-- [A2. 分层调度](#a2-分层调度)
-- [A3. 子代理契约（单 issue 单代理）](#a3-子代理契约单-issue-单代理)
-- [A4. 全量收敛](#a4-全量收敛)
-- [A5. 回退与冲突](#a5-回退与冲突)
-- [出口条件](#出口条件)
-- [边界](#边界)
-
----
-
-### A0. 依赖图构建
-
-1. 扫描 `.scratch/<feature>/issues/` 下全部 `NN-<slug>.md`，逐文件解析 `Blocked by` 行：
-   - `Blocked by: None` / `Blocked by: （无` / 无此行 → 无依赖（frontier）
-   - `Blocked by: 01, 02` / `Blocked by: 01（…）` → 依赖 `01`、`02` 对应的 issue 文件（按编号前缀匹配）
-   - 无法解析的行 → 视为无依赖，并在编排总结中注明告警
-2. 以 issue 编号为节点、`Blocked by` 为有向边构建 DAG；若检测到环，立即报错并列出环上节点，不进入调度。
-3. 读取 `spec.md`（若存在）作为各子代理的共享上下文；同时读取 `CONTEXT.md` 与 `docs/adr/` 供一致性校验。
-
-### A1. 拓扑分层
-
-对 DAG 做 Kahn 分层（BFS 拓扑）：
-
-```
-L1 = 全部入度为 0 的节点（可立即开始）
-L2 = 移除 L1 后入度为 0 的节点
-…
-Ln = 最后一层
-```
-
-每层内节点互无依赖，可并行；层间有依赖，必须串行。分层结果在编排开始前一次性展示给用户确认（合规交互点），确认后才派发。
-
-### A2. 分层调度
-
-```
-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
-全部层层收敛通过后进入 A4 全量收敛
-```
-
-- **派发纪律**：与阶段⑤双轴审查一致——逐个 `subagent` 派发，禁止 `parallel tasks` 数组（同因：中文报告截断）。
-- **等待语义**：层内任一子代理失败不取消同层其他子代理；待层内全部返回后统一按 A5 处理。
-- **回合连续性**：编排器在层间不结束回合——一层收敛后立即派发下一层，直到全部层完成或外部阻塞；预告下一层后立即执行。
-- **Git 历史保护（正向：仅追加；护栏：禁改写）**：编排器在分层调度前记录 `BASE_HEAD=$(git rev-parse HEAD)`，每层收敛后校验 `git merge-base --is-ancestor $BASE_HEAD HEAD`，失败即经 `git reflog` 恢复；为达 `git status` 干净仅删本次产生的 `[DEBUG-...]`临时产物（正向），护栏：禁止 `git reset --hard`/`git checkout .`/`git clean -fd`/`git stash push --include-untracked`/`git push --force` 等（需显式确认）。
-
-### A3. 子代理契约（单 issue 单代理）
-
-每个子代理是一个**完整的 tdd-implement 单 issue 执行单元**，输入与产出严格界定：
-
-> 编排层为 Feature 层，按 `Blocked by` 分层；每子代理各自治完成完整 tdd-implement 流程，产出独立 commit；禁止跨 issue 改动；输出约束为回执卡片，不透传全量过程日志；主代理验收保证无跨 issue 改动与逐 issue 验收，打回重派直至验收通过才计入层收敛。
-
-- **输入**：
-  - `spec.md`（feature 级共享 spec，若无则以该 issue 正文为准）
-  - 分配的单个 `NN-<slug>.md`（唯一 issue 输入）
-  - `CONTEXT.md` + `docs/adr/`（术语与决策一致性）
-- **执行**：严格走 tdd-implement ①→⑦全流程——①理解需求（读 spec + issue）→ ②确认 seams（该 issue 范围内）→ ③红-绿循环（每 cycle 后 typecheck + 相关测试）→ ④相关测试套件（仅该 issue 相关 + typecheck，不跑全量；全量由编排器在 A2 层收敛/A4 统一执行，单 issue 单线模式仍跑全量）→ ⑤双轴 review → ⑥commit-check 门禁 + commit → ⑦文档对齐（仅该 issue 相关描述）+ `Status: resolved` + `## 实施总结` 落盘 + 目录卫生。TDD 语义以 [tdd 技能](.agents/skills/tdd/SKILL.md) 为唯一事实源，不在子代理内重写。
-- **产出**：
-  - 独立 commit（message 含 issue 编号，如 `feat(<feature>): <issue title> (#NN)`）
-  - 该 issue 文件 `Status: resolved` + 底部 `## 实施总结`
-  - 该 issue 范围内的测试全绿 + typecheck 通过
-- **禁止**：跨 issue 改动；修改其他 issue 文件；跳过 ⑤/⑥ 直接 commit。
-
-#### 输出约束（子代理只返回回执卡片）
-
-子代理不向编排器透传全量过程日志（各 seam 的红-绿细节、typecheck 原始输出、双轴 review 全文、完整测试日志）。只返回一张**回执卡片**（结构化关键信息，中文，≤ 30 行）：
-
-```
-[回执] #NN <issue 标题>
-- 提交：<commit hash> — <message>
-- seams：<清单>
-- 测试：相关测试 <数量> 项全绿 / 失败清单（全量由编排器层收敛/A4 验证）
-- typecheck：通过 / 失败原因
-- review：Standards <通过/问题> / Spec <通过/问题>
-- 验收：checkbox <m/n 全绿，缺口说明>
-- 文档：<更新文件 / 无需更新>
-- 遗留：<如有>
-```
-
-卡片字段缺一不可；缺失字段视为验收不通过。详细过程与证据留在子代理的 commit 与 issue 文件中，编排器按需抽检而非全量消费。
-
-#### 主代理验收（编排器逐 issue 验收）
-
-编排器收到回执后逐 issue 验收，不盲信子代理自检：
-
-1. **落盘校验**：`git log --oneline` 含该 commit 且 message 含 `#NN`；issue 文件 `Status: resolved` 且底部 `## 实施总结` 已落盘。**完成条件：5 项检查表，全部通过才计入层收敛，任一不过即打回重派**（详见 `SKILL.md` 主代理验收）。
-2. **抽检验证**：抽跑该 issue 相关测试（或 `tsc --noEmit` 抽检），不重跑全量套件；抽检失败即打回。
-3. **改动边界**：`git diff <base>..HEAD --name-only` 核对无跨 issue 文件改动；有跨改视为不通过。
-4. **卫生**：`git status` 无 `[DEBUG-...]` 残留与未跟踪临时文件。
-5. **提交关联**：`git log` message 含 `#NN` 且与落盘 commit 一致；缺失或不一致视为不通过。
-
-任一项不通过 → 打回重派该子代理（仅该 issue），层内其他已通过不受影响；验收通过才计入层收敛。验收结论随层收敛一并输出。
-
-子代理内部的回合连续性、任务分解、Todo 规定、Git 历史保护与单线模式完全一致（见 [stages.md 阶段③ 3e/3f/3h](stages.md#阶段-③tdd-开发循环) 与 Git 安全前置）。子代理同样在入口记录 `BASE_HEAD` 并在每阶段出口校验 `git merge-base --is-ancestor $BASE_HEAD HEAD`，禁止 `git reset --hard`/`git checkout .`/`git clean -fd`/`git stash push --include-untracked` 等。
-
-### A4. 全量收敛
-
-全部层逐 issue 验收通过后，编排器执行：
-
-1. **全量测试套件**：跑仓库完整测试套件（阶段④口径），失败则按 A5 回退。
-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 的 `## 实施总结` 已落盘，详查落盘文件）。
-
-### A5. 回退与冲突
-
-- **子代理内回退**：按 [stages.md 回退路由](stages.md#回退路由) 在子代理内闭环（typecheck 失败 → ③、测试失败 → ③、review 不通过 → ③/②/①）。
-- **层收敛失败**：层内任一子代理未达到 `resolved`（测试失败 / review 不通过 / commit-check 门禁失败）→ 该 issue 保持原 `Status`，编排器在层等待结束后报告失败清单，不自动进入下一层；待修复后重派该层失败节点。
-- **全量收敛失败**：A4 全量测试失败 → 定位到失败测试归属的 issue，回到其所在层重派对应子代理。
-- **文件冲突**：同层子代理若触及同一文件，后完成者 rebase 解决冲突后重跑 typecheck + 相关测试；跨层天然串行无冲突。冲突解决禁止使用 `git reset --hard`/`git checkout .`/`git clean -fd`/`git stash push --include-untracked` 丢弃对方提交，rebase 后必校验 `git merge-base --is-ancestor $BASE_HEAD HEAD` 且 `git log --oneline` 含全部层提交；冲突检测以 `git` 合并结果为准，编排器不做静态预判。
-- **环依赖**：A0 检测到环即报错终止，不派发任何子代理。
-
-### 出口条件
-
-- 全部 issue `Status: resolved` + 各自 `## 实施总结` 已落盘
-- 全量测试套件通过
-- 工作区干净（`git status` 无残留）
-
-### 边界
-
-- 单 issue / 单 spec 不走本文件
-- 子代理不跨 issue 改动；编排器不替子代理写实现代码
-- 汇总总结只在对话输出，不落盘额外汇总文件
-- TDD 语义以 [tdd 技能](.agents/skills/tdd/SKILL.md) 为唯一事实源，不在本文件重写
-

package/template/.pi/skills/ci-guard/SKILL.md

@@ -1,104 +0,0 @@
----
-name: ci-guard
-description: "Guard the GitHub Actions release pipeline: orchestrate workflow flow, enforce pre-release verification, and self-correct after publish. Use when CI is flaky/failing, when setting up or editing .github/workflows/ci.yml, or before tagging a release to npm."
----
-
-# CI Guard
-
-**guard** 为领衔词的发布门禁技能：以一次**可复现的失败**为起点，把 `verify → build → publish` 编排成不可绕过的门，把**预发布校验**做成硬门槛，把**发布后自纠**做成闭环。本技能沉淀自 `heihei0299/pi-switch` 23 次运行中 14 次失败的复盘（见 `.scratch/research/ci-actions-调研.md`）——不替代 `diagnose-fix` 的通用诊断，只收敛 CI/发布这一条链。
-
-## 何时用
-
-- Actions 持续红 / 偶发红（尤其是 `verify` 单点红而 `publish` 仍绿）
-- 新建或改动 `.github/workflows/ci.yml`、调整 `cargo test` / `clippy` / `rustfmt` 参数
-- 打 tag 前、发 npm 前、或发布后需要自检/回滚
-
-## 三段式门禁
-
-```
-① 编排 flows → ② 预发布 gate → ③ 发布后自纠
-```
-
-每段有**完成条件**（可验证），未满足不进入下一段。
-
----
-
-### ① 编排 flows —— 让工作流不可被绕过
-
-**做**：
-- `on`：`push.tags: ["v*"]` **必须**同时配 `push.branches: [main]`（或 `master`）+ `pull_request.branches: [main]` + `workflow_dispatch`。否则直推 `main` 的修复（如 `2d68f62`）无法被 CI 验证，tag 才暴露问题
-- `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` 存在
-- [ ] `publish.needs` 包含 `verify`
-- [ ] `workflow_dispatch` 可手动触发全量
-
----
-
-### ② 预发布 gate —— 在写盘之前变红
-
-本段是**硬门槛**，顺序固定：`fmt → clippy → test → build`，任一步红即阻断 `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`
-
-**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 目标仅验编译，不代验测试
-
-**完成条件**：
-- [ ] 本地 `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` 产物不一致）
-
----
-
-### ③ 发布后自纠 —— 发出去的包自己负责
-
-**发布时**：
-- `npm publish --access public` 仅在 `if: startsWith(github.ref, 'refs/tags/v')` 且 `needs` 全绿时执行
-- 发布前 `actions/download-artifact` 校验 `if-no-files-found: error`，发布后 `npm view <pkg>@<version> version` 回读确认
-
-**自纠**：
-- 失败即 **阻断**：`verify` 红 → `publish` 不执行（由 `needs` 保证）；`publish` 自身失败（`409 already exists` / `401`）→ 工作流整体 `failure`，不静默
-- 发布后 30s 内 `curl https://registry.npmjs.org/<pkg>/<version>` 校验可用；失败则 `gh issue create --title "chore(release): vX.Y.Z 发布后自检失败" --body "run: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"` 并 `gh release delete vX.Y.Z --yes`（或 `npm unpublish <pkg>@<version>` 在 72h 内）
-- `workflow_dispatch` 支持 `inputs.rollback_version` 手动回滚
-
-**完成条件**：
-- [ ] `npm view` 回读与 tag 一致
-- [ ] 失败路径有 issue/通知（非静默）
-- [ ] `git tag` 与 `package.json version` 一致（`scripts/release.sh` 或 `npm version` 保证）
-
----
-
-## 反模式
-
-- **单依赖 publish**：`needs: build` 是本仓 7 次带病发布的根因
-- **仅 tag 触发**：`push.branches` 缺失导致主干修复无 CI
-- **真实落盘并行测试**：无 `#[cfg(test)]` 隔离的 `config_dir` 直写是偶发红的根因，`--test-threads=1` 只是止血
-- **静默发布**：`publish` 失败不建 issue / 不删 tag，下次 `409` 叠加
-- **`-A clippy::all`**：掩盖真实告警
-
-## 引用
-
-- 调研：`.scratch/research/ci-actions-调研.md`（23 次运行全量、`proxy.rs:115` vs `config.rs:460` 对比）
-- 修复：`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/template/.pi/skills/ci-guard/agents/openai.yaml

@@ -1,5 +0,0 @@
-interface:
-  display_name: "CI Guard"
-  short_description: "Guard release pipeline: orchestrate flows, enforce verify gate, self-correct after publish"
-policy:
-  allow_implicit_invocation: false

package/template/.pi/skills/commit-check/agents/openai.yaml

@@ -1,5 +0,0 @@
-interface:
-  display_name: "Commit Check"
-  short_description: "提交前门禁：审查文档、对齐 README、保持目录卫生、规范 commit message"
-policy:
-  allow_implicit_invocation: false

package/template/.pi/skills/commit-check/scripts/scan-sensitive.sh

@@ -1,36 +0,0 @@
-#!/usr/bin/env bash
-# Deterministic secret scan for commit-check check ③.
-# The grep patterns are fragile to freehand — run this instead of re-writing
-# the scan every time. Two confidence tiers:
-#   FAIL  — structured secrets (KEY=value assignments, private key blocks)
-#   WARN  — bare keywords (may legitimately appear in docs that mention them)
-# Checks the staged diff (fail) and, unless --staged-only is passed, reports
-# matches in the unstaged diff (warn).
-#
-# Usage:
-#   scripts/scan-sensitive.sh            # staged (fail) + unstaged (warn)
-#   scripts/scan-sensitive.sh --staged-only
-set -euo pipefail
-
-fail_patterns='(api[_-]?key|secret|token|passwd|password)[[:space:]]*[=:][[:space:]]*[^[:space:]]{8,}|BEGIN (RSA|OPENSSH|EC|DSA) PRIVATE KEY'
-warn_patterns='(api[_-]?key|secret|token|passwd|password|\.env)'
-
-fail=0
-
-if git diff --cached -U0 | grep -inE "$fail_patterns"; then
-  echo "❌ Structured secrets found in STAGED diff — remove them before committing." >&2
-  fail=1
-else
-  echo "✅ No structured secrets in staged diff."
-  if git diff --cached -U0 | grep -inE "$warn_patterns"; then
-    echo "⚠  Keyword matches in STAGED diff — eyeball whether they are real secrets." >&2
-  fi
-fi
-
-if [[ "${1:-}" != "--staged-only" ]]; then
-  if git diff -U0 | grep -inE "$fail_patterns"; then
-    echo "⚠  Structured-secret matches in UNSTAGED diff — decide whether they belong in the commit." >&2
-  fi
-fi
-
-exit "$fail"

package/template/.pi/skills/diagnose-fix/agents/openai.yaml

@@ -1,5 +0,0 @@
-interface:
-  display_name: "Diagnose Fix"
-  short_description: "诊断硬 bug 并按 TDD 红-绿修复"
-policy:
-  allow_implicit_invocation: false