@heihei0299/matt-skills 2.0.2 → 2.1.0

package/template/.opencode/CONTEXT.md

@@ -5,7 +5,7 @@ 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 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.
+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 the explicitly allowed distributable skills via `.agents/skills`. The workspace also retains repo-local maintenance skills that are never distributed. The workspace content is projected 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** (上游仓库):
@@ -13,27 +13,27 @@ mattpocock/skills — the source of the 26 skill bodies (skills/engineering + sk
 _Avoid_: source repo, skill origin
 
 **Proprietary Skill** (独有技能):
-A skill that does not exist upstream and lives only in this repo (currently ci-guard, tdd-implement, grill-to-spec, diagnose-fix, commit-check and scaffold-functional-test). 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.
+A skill that does not exist upstream and lives only in this repo (currently ci-guard, tdd-implement, grill-to-spec, diagnose-fix, commit-check, scaffold-functional-test and show-me). Before adding a new skill, check the Upstream Repository first; only skills absent there qualify as proprietary. The 7 proprietary skills are classified as 5 distributable (`tdd-implement`, `diagnose-fix`, `grill-to-spec`, `scaffold-functional-test`, `show-me`) and 2 repo-local (`ci-guard`, `commit-check`). The default programming set includes 4 proprietary skills: `tdd-implement`, `diagnose-fix`, `grill-to-spec` and `show-me`; `scaffold-functional-test` is distributable but optional. Repo-local skills serve matt-skills maintenance and are never distributed. 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/` (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).
+The root-level working copies of the template content — `.agents/skills/` (upstream plus all proprietary skills, 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 project only the distributable subset: `.agents/skills/` → `template/.agents/skills/`, `.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: 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.
+Everything under `template/` — the distributable snapshot of workspace content: only allowed skills under `.agents/skills/` (single source for user projects), harness skill dirs `.pi/skills/` + `.opencode/skills/` as empty placeholders for project custom skills, distributable 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. Repo-local skills and commands remain workspace-only. 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 (`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`.
+A repository initialized by copying `template/` into its root (`cp -r template/. <target>/`). It then loads all distributable shared skills from its own `.agents/skills/`, project-local custom skills from `.pi/skills/` / `.opencode/skills/` (if any), the distributable 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`. Repo-local matt-skills maintenance skills are not part of a Target Repository by default.
 _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>/`). 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.
+The one-time action of setting up a Target Repository: copying `template/` into its root (`cp -r template/. <target>/`). All distributable skills are already included via `template/.agents/skills/`; no separate upstream fetch is needed. Repo-local skills are intentionally absent. Copying, not inheriting — no runtime relationship survives the copy.
 _Avoid_: inherit, bootstrap
 
 **Sync** (同步):
-`matt-skills sync` 同步 Target Repository 的模板与技能：`--dry-run` 仅对比不写盘（`check`，`--json` 可解析，有差异 `exit 1`），默认安全增量（`AGENTS.md` 有定制如 `tdd-implement` 则跳过，`.agents/skills` 按默认范围 26 `rm+cp` 覆盖但不删多余技能，`template/.opencode/.pi` 增量 `add/update`，旧镜像 `.pi/skills` + `.opencode/skills` 中残留的共享技能自动清理但保留项目自定义）、`--all` 仅更新同名技能内容（存在则覆盖，不存在则新增）并更新 `AGENTS.md`（不跳过定制），不删多余技能。`update` 已合并到 `sync` 并删除。
+`matt-skills sync` 同步 Target Repository 的模板与技能：`--dry-run` 仅对比不写盘（`check`，`--json` 可解析，有差异 `exit 1`），默认安全增量（`AGENTS.md` 有定制如 `tdd-implement` 则跳过，`.agents/skills` 按默认 programming 范围覆盖但不删多余技能，`template/.opencode/.pi` 增量 `add/update`，旧镜像 `.pi/skills` + `.opencode/skills` 中残留的共享技能自动清理但保留项目自定义）、`--all` 仅更新同名可分发技能内容（存在则覆盖，不存在则新增）并更新 `AGENTS.md`（不跳过定制），不删多余技能。Repo-local skill 永远不新增、不覆盖、不删除，只在发现历史副本时提示保留。`update` 已合并到 `sync` 并删除。
 _Avoid_: update, force sync
 
 ## Skill Design

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

@@ -11,7 +11,7 @@ Every **Long-Horizon Skill** must carry a positive **Turn Continuity** rule of i
 - 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`](.agents/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), especially the Red-Green continuity section.
 
 ## 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`](.agents/skills/tdd-implement/references/stages.md) stage ③/⑥/⑦/A2-A4 Git 安全红线 and [`commit-check/SKILL.md`](.agents/skills/commit-check/SKILL.md) ③ 目录卫生.
+Canonical enforcement: [`tdd-implement/references/stages.md`](.agents/skills/tdd-implement/references/stages.md) checks `BASE_HEAD` at every four-stage exit and before commit; multi-issue enforcement lives in [`tdd-implement/references/orchestration.md`](.agents/skills/tdd-implement/references/orchestration.md) A2-A4. Repository-local commit gating remains a workspace-only concern and is not part of the distributable template.
 ## 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.
+Skills currently classified as Long-Horizon, to be evolved against these rules as they are touched: `tdd-implement` (fixed), `diagnose-fix` (fixed — orchestration for diagnosis + TDD fix), `diagnosing-bugs`, `improve-codebase-architecture`, `wayfinder`, `grill-to-spec` (fixed — carries its own Turn Continuity rule), `to-spec`. Backfilling existing skill texts is out of scope for now — these rules bind new and edited skills going forward.

package/template/.opencode/skills/README.md

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

package/template/.pi/CONTEXT.md

@@ -5,7 +5,7 @@ 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 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.
+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 the explicitly allowed distributable skills via `.agents/skills`. The workspace also retains repo-local maintenance skills that are never distributed. The workspace content is projected 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** (上游仓库):
@@ -13,27 +13,27 @@ mattpocock/skills — the source of the 26 skill bodies (skills/engineering + sk
 _Avoid_: source repo, skill origin
 
 **Proprietary Skill** (独有技能):
-A skill that does not exist upstream and lives only in this repo (currently ci-guard, tdd-implement, grill-to-spec, diagnose-fix, commit-check and scaffold-functional-test). 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.
+A skill that does not exist upstream and lives only in this repo (currently ci-guard, tdd-implement, grill-to-spec, diagnose-fix, commit-check, scaffold-functional-test and show-me). Before adding a new skill, check the Upstream Repository first; only skills absent there qualify as proprietary. The 7 proprietary skills are classified as 5 distributable (`tdd-implement`, `diagnose-fix`, `grill-to-spec`, `scaffold-functional-test`, `show-me`) and 2 repo-local (`ci-guard`, `commit-check`). The default programming set includes 4 proprietary skills: `tdd-implement`, `diagnose-fix`, `grill-to-spec` and `show-me`; `scaffold-functional-test` is distributable but optional. Repo-local skills serve matt-skills maintenance and are never distributed. 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/` (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).
+The root-level working copies of the template content — `.agents/skills/` (upstream plus all proprietary skills, 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 project only the distributable subset: `.agents/skills/` → `template/.agents/skills/`, `.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: 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.
+Everything under `template/` — the distributable snapshot of workspace content: only allowed skills under `.agents/skills/` (single source for user projects), harness skill dirs `.pi/skills/` + `.opencode/skills/` as empty placeholders for project custom skills, distributable 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. Repo-local skills and commands remain workspace-only. 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 (`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`.
+A repository initialized by copying `template/` into its root (`cp -r template/. <target>/`). It then loads all distributable shared skills from its own `.agents/skills/`, project-local custom skills from `.pi/skills/` / `.opencode/skills/` (if any), the distributable 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`. Repo-local matt-skills maintenance skills are not part of a Target Repository by default.
 _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>/`). 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.
+The one-time action of setting up a Target Repository: copying `template/` into its root (`cp -r template/. <target>/`). All distributable skills are already included via `template/.agents/skills/`; no separate upstream fetch is needed. Repo-local skills are intentionally absent. Copying, not inheriting — no runtime relationship survives the copy.
 _Avoid_: inherit, bootstrap
 
 **Sync** (同步):
-`matt-skills sync` 同步 Target Repository 的模板与技能：`--dry-run` 仅对比不写盘（`check`，`--json` 可解析，有差异 `exit 1`），默认安全增量（`AGENTS.md` 有定制如 `tdd-implement` 则跳过，`.agents/skills` 按默认范围 26 `rm+cp` 覆盖但不删多余技能，`template/.opencode/.pi` 增量 `add/update`，旧镜像 `.pi/skills` + `.opencode/skills` 中残留的共享技能自动清理但保留项目自定义）、`--all` 仅更新同名技能内容（存在则覆盖，不存在则新增）并更新 `AGENTS.md`（不跳过定制），不删多余技能。`update` 已合并到 `sync` 并删除。
+`matt-skills sync` 同步 Target Repository 的模板与技能：`--dry-run` 仅对比不写盘（`check`，`--json` 可解析，有差异 `exit 1`），默认安全增量（`AGENTS.md` 有定制如 `tdd-implement` 则跳过，`.agents/skills` 按默认 programming 范围覆盖但不删多余技能，`template/.opencode/.pi` 增量 `add/update`，旧镜像 `.pi/skills` + `.opencode/skills` 中残留的共享技能自动清理但保留项目自定义）、`--all` 仅更新同名可分发技能内容（存在则覆盖，不存在则新增）并更新 `AGENTS.md`（不跳过定制），不删多余技能。Repo-local skill 永远不新增、不覆盖、不删除，只在发现历史副本时提示保留。`update` 已合并到 `sync` 并删除。
 _Avoid_: update, force sync
 
 ## Skill Design

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

@@ -11,7 +11,7 @@ Every **Long-Horizon Skill** must carry a positive **Turn Continuity** rule of i
 - 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`](.agents/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), especially the Red-Green continuity section.
 
 ## 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`](.agents/skills/tdd-implement/references/stages.md) stage ③/⑥/⑦/A2-A4 Git 安全红线 and [`commit-check/SKILL.md`](.agents/skills/commit-check/SKILL.md) ③ 目录卫生.
+Canonical enforcement: [`tdd-implement/references/stages.md`](.agents/skills/tdd-implement/references/stages.md) checks `BASE_HEAD` at every four-stage exit and before commit; multi-issue enforcement lives in [`tdd-implement/references/orchestration.md`](.agents/skills/tdd-implement/references/orchestration.md) A2-A4. Repository-local commit gating remains a workspace-only concern and is not part of the distributable template.
 ## 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.
+Skills currently classified as Long-Horizon, to be evolved against these rules as they are touched: `tdd-implement` (fixed), `diagnose-fix` (fixed — orchestration for diagnosis + TDD fix), `diagnosing-bugs`, `improve-codebase-architecture`, `wayfinder`, `grill-to-spec` (fixed — carries its own Turn Continuity rule), `to-spec`. Backfilling existing skill texts is out of scope for now — these rules bind new and edited skills going forward.

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

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

package/template/AGENTS.md

@@ -1,31 +1,50 @@
-
-## 快速上手
-
-1. 读 `CONTEXT.md`（术语）——没有则跳过
-2. 按行为路由表行动；未命中用 ask-matt 或直接澄清
-3. 探索代码库：直接使用 `codegraph explore`（`codegrafh CLI`）；若无 `.codegraph/` 索引先执行 `codegraph init` 初始化，再 `explore`
-
-
-
-## 行为路由
-命中即行动，回复中简短声明所用 skill 或工具。
-- 理解/定位 → `codegraph explore`
-- 调研/原型 → `research` / `prototype`
-- 修改/实现 → 简单低风险直接执行：理解现状 → 最小修改 → 相关验证；有实际改动且验证通过时按一个用户请求执行一次 `git commit`；测试先行、TDD 或集成测试 → `tdd`；bug、失败、异常或性能问题 → `diagnose-fix`；其它中大型修改 → 先澄清范围、验收和验证方式，再按项目流程执行
-- 审查/设计 → `code-review` / `grilling` / `domain-modeling`
-- 无法归类 → 直接澄清
-
-## 分文件
-
-- Issue tracker → `docs/agents/issue-tracker.md`；Triage labels → `docs/agents/triage-labels.md`；Domain docs → `docs/agents/domain.md`
-- 术语表 → `CONTEXT.md`
-
+## 路由
+命中即执行，并简短声明使用的 skill / 工具。
+* 理解 / 定位 / 调用链 → `codegraph explore`
+* 外部调研 / 方案比较 → `research`
+* 原型 / PoC → `prototype`
+* 简单修改 → 直接实现
+* TDD / 集成测试 → `tdd`
+* bug / 异常 / 性能 → `diagnose-fix`
+* 代码审查 → `code-review`
+* 设计质询 → `grilling`
+* 领域建模 → `domain-modeling`
+* 无法归类 → `ask-matt`
+\仅当关键歧义会改变结果时询问用户。
 ## CodeGraph
-
-理解/定位代码**必须**使用 `codegrafh CLI`，直接优于 grep/find/读文件——一次调用拿到相关符号逐字源码与调用路径：
-
-- **CLI**：`codegraph explore "<符号名或问题>"` 一次回答大部分代码问题——相关符号的逐字源码 + 调用路径（含 grep 追不上的动态分派跳转）。在 query 中指名文件/符号即可读取其带行号的当前源码，默认 `maxFiles: 12` 覆盖跨 5-8 文件调用链。
-- **初始化**：若根目录无 `.codegraph/`，先执行 `codegraph init` 初始化索引，再 `explore`；已有索引直接 `explore`（硬判定，不回退 explore 子代理）。
-- **已读等价**：返回体含完整源码块的文件视为已 `Read`，不再重复 `read`；仅返回调用路径片段时补一次带行号 `read`。
-- **跨仓/子项目**：仅当探索第二代码库或 monorepo 子项目（根无索引但子目录有）时显式传 `projectPath`。
-与 `research`（后台调研产出 Markdown 文件）分工：`codegraph explore` 为代码定位唯一首选，`research` 仅用于需产出调研文档的后台任务。
+仓库内代码理解首先使用：
+```bash
+codegraph explore "<问题>"
+```
+无 `.codegraph/` 时：
+```bash
+codegraph init
+codegraph explore "<问题>"
+```
+* 优先于 `Read`、`grep`、`rg`、`find` 和代码探索子代理。
+* 从最小必要上下文开始；返回完整源码即视为已读。
+* 信息不足时只针对缺口继续 `explore`；已锁定符号时使用 `codegraph node`。
+* CodeGraph 无法提供必要信息时，才降级到最小必要的读取 / 搜索。
+* `research` 只用于仓库外信息。
+## 执行
+默认闭环：
+```text
+定位 → 实现 → 验证 → 修正
+```
+* 以仓库当前代码、类型、配置、测试和版本化文档为事实来源。
+* 优先复用现有抽象、接口和依赖方向。
+* 不创建平行实现，不扩大任务范围。
+* 简单任务直接执行；复杂任务需要时形成最小可执行计划。
+* 仅在需要用户判断或授权时中断闭环。
+## 验证
+服从全局授权规则。
+* 已授权时执行能证明本次改动正确的最小验证。
+* bug 验证原复现路径；性能问题使用可测量指标。
+* 根据验证反馈修正，不重复等价检查或自动增加 review / CI。
+## Harness
+同类问题反复出现时，优先将约束落实到测试、lint、类型、工具或代码结构，而不是继续扩充本文件。
+## Git
+有实际改动且满足全局规则时，每个用户请求最多一次 commit。
+* 提交前检查 diff。
+* 只 stage 本次任务文件。
+* 不使用 `git add .` / `git add -A`。

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

@@ -1,50 +0,0 @@
----
-name: ci-guard
-description: "保护本仓库 GitHub Actions CI/release pipeline：按发布、workflow 维护或发布后故障场景执行必要门禁。Use when CI is flaky/failing, when setting up or editing .github/workflows/ci.yml, or before tagging a release to npm."
----
-
-# CI Guard
-
-本 skill 只编排当前仓库的 CI 与 npm 发布门禁。先读取 `.github/workflows/ci.yml`，以实际 workflow 的 job、input、condition 和权限为事实源；不要假设不存在的 job、input 或自动回滚行为。产品代码 bug 的诊断和修复交给 `diagnose-fix`，不在此重复通用诊断。
-
-## 场景选择
-
-- 用户请求发布、打 release tag 或发布 npm → **发布路径**；
-- 用户修改 workflow，或报告 Actions 红/偶发红 → **workflow 维护路径**；
-- tag 已发布但 registry、release 或 post-check 异常 → **发布后故障路径**。
-
-只执行命中的路径；普通发布不运行与当前 workflow 无关的 lint、dry-run 或 dispatch。
-
-## 发布路径
-
-1. 读取当前 package metadata 和 workflow；确认正式 tag 的 commit 可从 `main` 到达，目标 tag 尚不存在，版本与 tag 约定一致。
-2. 运行项目规定的测试和 `npm pack --dry-run`，确认发布内容和实际结果。
-3. 只有前两步通过后才创建并推送 `vX.Y.Z` tag；不从非 `main` commit 推送正式 tag。
-4. 等待 tag workflow 完成，确认 `verify` 成功后才进入 `publish`，并记录 Actions run URL、job 结论和实际 npm tag。
-5. 使用 `npm view <package>@<version> version` 或 registry API 回读，确认发布版本真实可见。
-
-出口：tag、Actions 和 registry 的实际结果均已记录；任一失败都阻断“发布成功”结论。
-
-## Workflow 维护路径
-
-1. 读取当前 workflow，按实际内容检查触发器、`publish.needs`、job `if`、权限和 concurrency；不硬编码 job 名称。
-2. 只有 workflow 在本次范围内发生变化，或故障需要时，才运行已安装的 `actionlint` / `yamllint`；工具不可用就记录 `unavailable`，不得伪报通过。
-3. 需要 dry-run 或手动 dispatch 时，只使用 workflow 已声明的 input；不得传入未声明的 `dry_run` 等参数。若无安全的 dry-run input，改用静态依赖检查或一次不发布的验证运行。
-4. 失败时区分 workflow wiring、项目测试、授权/registry 和 runner 环境；只修复当前请求范围内的问题。
-
-出口：实际 workflow 结构、检查命令和运行结果均有证据；未验证项明确列出。
-
-## 发布后故障路径
-
-1. 读取对应 Actions run、npm registry 和 Git tag 的实际状态，确认是未发布、发布延迟、重复版本、授权失败还是 post-check 失败。
-2. 创建或补充带 run URL 的 issue，记录 registry 查询结果和失败分类。
-3. 只按照当前 workflow 声明的人工回滚步骤操作；不自行声称删除 release、删除 tag 或 `npm unpublish` 已发生。
-
-出口：故障分类、保留的远端对象和人工下一步均已明确。
-
-## 不做什么
-
-- 不把每次发布都扩展为完整 CI 工具链演练；
-- 不引用不存在的 `build` job、`dry_run` input 或 `rollback_version` input；
-- 不把历史事故描述当成当前仓库事实；
-- 不自动删除 tag/release，不静默吞掉 publish 或 post-check 失败。

package/template/.agents/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/.agents/skills/commit-check/SKILL.md

@@ -1,95 +0,0 @@
----
-name: commit-check
-description: "检查 matt-skills 当前 staged commit 的范围、敏感信息和 commit message，并按改动路径执行对应同步检查。"
-disable-model-invocation: true
----
-
-# Commit Check
-
-用户显式调用 `/commit-check` 后运行本技能。它是提交前的 staged commit gate：检查将要提交的内容是否属于当前逻辑变更、是否包含敏感信息、以及 commit message 是否可追溯。
-
-本技能只检查，不负责 staging，不执行 `git commit`，也不要求整个工作区干净。通过后报告 `ready to commit`，由调用方执行提交。
-
-## 三项核心 gate
-
-### ① Staged scope
-
-- 读取 `git diff --cached --name-status` 和 `git diff --cached`。
-- staged diff 必须非空，并且只包含当前用户请求的逻辑变更。
-- 列出 staged 文件和关键 diff，无法确认范围时报告疑点并阻塞。
-- 调用方负责 `git add`；本技能不自动 stage、unstage 或清理文件。
-- 工作区可以保留其它未暂存修改；不以 `git status` 全干净作为出口条件。
-
-### ② Sensitive scan
-
-运行确定性扫描脚本，不手写 grep：
-
-```bash
-bash .agents/skills/commit-check/scripts/scan-sensitive.sh --staged-only
-```
-
-- 结构化 secret assignment 和 private key block → **fail**。
-- 普通 `api_key`、`secret`、`token`、`password`、`.env` 等关键词 → **warning**，由调用方人工确认。
-- 扫描只针对 staged diff；不因未暂存内容阻塞本次 commit。
-
-### ③ Commit message
-
-- 使用 `<type>(<scope>): <subject>` 基本格式；`type` 使用 `feat`、`fix`、`docs`、`chore`、`refactor`、`test` 等仓库约定值。
-- subject 描述变更结果，不描述操作过程。
-- body 可选；只有确实需要时补充动机、影响范围或验收证据。
-- 一个 commit 只表达一个逻辑变更；多主题拆分提交。
-- 本技能检查并给出 message 结论，但不代替调用方执行 commit。
-
-## matt-skills 路径适配
-
-以下 staged 路径触发 matt-skills 专属检查；普通源码或测试 commit 不触发这些额外检查：
-
-```text
-README.md
-AGENTS.md
-CONTEXT.md
-docs/agents/**
-template/**
-.agents/skills/**
-config/**
-scripts/build-template.js
-.opencode/commands/**
-.pi/prompts/**
-```
-
-相关路径变更时：
-
-- README、公开行为、命令、配置或流程描述变化 → 检查对应文档与实现一致；
-- `AGENTS.md`、`CONTEXT.md`、`docs/agents/`、`template/`、技能或镜像变化 → 运行相关模板/契约测试，至少覆盖 `test/template-sync.test.js`；
-- `commit-check` 自身变化 → 运行 `test/commit-check.test.js` 和 `test/commit-check-scan.test.js`；
-- `tdd-implement` 变化 → 运行 `test/tdd-implement-stages.test.js`；
-- `config/`、构建脚本、opencode command 或 pi prompt 变化 → 运行对应 CLI、模板或命令测试；
-- 只检查本次 staged 路径相关的内容，不通读全部 README、docs 或模板。
-
-这些是 matt-skills 的条件化仓库检查，不改变上面的三项核心 gate。
-
-## Git history pointer
-
-遵循 `CONTEXT.md` 和 `docs/agents/` 中的 Git History Preservation 规则。本技能只在当前会话存在 `BASE_HEAD` 时执行必要祖先校验：
-
-```bash
-git merge-base --is-ancestor "$BASE_HEAD" HEAD
-```
-
-完整的禁止命令、恢复和 stash 规则只在仓库级文档维护，不在本技能重复展开。
-
-## 执行顺序与出口
-
-1. 检查 staged scope，确认 staged diff 非空且属于当前逻辑变更。
-2. 执行 `scan-sensitive.sh --staged-only`。
-3. 检查 commit message。
-4. 根据 staged 路径执行必要的 matt-skills 条件化检查。
-5. 输出 staged 文件、三项 gate 结果、warning、条件化检查结果和 `ready to commit` 或具体阻塞项。
-
-发现阻塞项时停止并报告；不自动修复、不自动 stage、不自动 commit。
-
-## 不负责的内容
-
-- 不做完整代码审查；审查语义由对应审查流程负责。
-- 不执行测试先行、typecheck、build、真实运行或 tracker 收尾；这些属于对应实现流程。
-- 不成为任何实现流程的自动子步骤；仅按 staged 路径提供本仓库提交 gate。

package/template/.agents/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/.agents/skills/commit-check/scripts/scan-sensitive.sh

@@ -1,29 +0,0 @@
-#!/usr/bin/env bash
-# Deterministic staged-diff secret scan for commit-check.
-# FAIL: structured assignments and private-key blocks.
-# WARN: bare keywords that may legitimately appear in documentation.
-set -euo pipefail
-
-if [[ $# -gt 1 || ( $# -eq 1 && "$1" != "--staged-only" ) ]]; then
-  echo "usage: $0 [--staged-only]" >&2
-  exit 2
-fi
-
-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)'
-
-staged_diff=$(git diff --cached -U0)
-fail=0
-
-if grep -inE "$fail_patterns" <<< "$staged_diff"; then
-  echo "❌ Structured secrets found in STAGED diff — remove them before committing." >&2
-  fail=1
-else
-  echo "✅ No structured secrets in staged diff."
-fi
-
-if grep -inE "$warn_patterns" <<< "$staged_diff"; then
-  echo "⚠  Keyword matches in STAGED diff — eyeball whether they are real secrets." >&2
-fi
-
-exit "$fail"

package/template/.opencode/commands/commit-check.md

@@ -1,9 +0,0 @@
----
-description: 检查 matt-skills 当前 staged commit 的范围、敏感信息和 commit message
----
-
-# Commit Check
-
-加载并执行 `commit-check` 技能，检查当前 staged diff。技能只做 gate，不自动 staging 或 commit。
-
-**范围：** $ARGUMENTS