@heihei0299/matt-skills 2.1.9 → 3.0.0

package/template/.opencode/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 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.
+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) and the explicitly allowed distributable Skills. The Workspace also retains repo-local maintenance Skills that are never distributed. The Template Snapshot projects the project skeleton; the CLI assembles selected distributable Skills from the Workspace when initializing or synchronizing a Target Repository. The Workspace copy also serves this repo's own sessions.
 _Avoid_: skill distribution repo
 
 **Upstream Repository** (上游仓库):
-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`.
+mattpocock/skills — the source of the 26 Skill bodies (skills/engineering + skills/productivity) that are mirrored into this repo's Workspace canonical Skill source and then distributed by the CLI. 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/` (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).
+The root-level working copies of the template content — `.agents/skills/` (upstream plus all proprietary Skills, the canonical shared Skill source), `.opencode/` (issue-audit agent, explicit-Skill commands), `.pi/` (pi-agent prompts: `issue-audit`), `AGENTS.md`, `CONTEXT.md`, `docs/`. This is where the repo's own sessions load, modify and test the content. The Template Snapshot projects only the distributable configuration and skeleton: `.opencode/commands/*.md` → `template/.opencode/commands/`, `.pi/prompts/issue-audit.md` → `template/.pi/prompts/issue-audit.md`, and root-level `CONTEXT.md` and `docs/agents/` → `template/.opencode/` + `template/.pi/`. The CLI assembles selected shared Skills from the canonical source into a Target Repository. 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 Snapshot).
 _Avoid_: working copy, source repo
 
 **Template Snapshot** (模板快照):
-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.
+Everything under `template/` — the distributable snapshot of project skeleton content: 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/`, and AGENTS.md at the top level. It is generated by `node scripts/build-template.js` and used to initialize other repositories. Shared Skills and repo-local Skills remain in the Workspace; the CLI distributes only the selected shared Skills. The sync direction for the skeleton is one-way: Workspace → Template Snapshot. Template structure tests guard the content the snapshot owns.
 _Avoid_: release snapshot, published snapshot
 
 **Target Repository** (目标仓库):
-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.
+A repository initialized by copying the Template Snapshot skeleton into its root and then receiving selected distributable shared Skills from the CLI. It loads 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 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.
+The one-time action of setting up a Target Repository: copying the Template Snapshot skeleton into its root, then having the CLI create its shared Skill directory and copy the selected distributable Skills from the Workspace canonical source. 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` 按默认 programming 范围覆盖但不删多余技能，`template/.opencode/.pi` 增量 `add/update`，旧镜像 `.pi/skills` + `.opencode/skills` 中残留的共享技能自动清理但保留项目自定义）、`--all` 仅更新同名可分发技能内容（存在则覆盖，不存在则新增）并更新 `AGENTS.md`（不跳过定制），不删多余技能。Repo-local skill 永远不新增、不覆盖、不删除，只在发现历史副本时提示保留。`update` 已合并到 `sync` 并删除。
+`matt-skills sync` 同步 Target Repository 的 skeleton 与 Skills：`--dry-run` 仅对比不写盘（`check`，`--json` 可解析，有差异 `exit 1`），默认安全增量（`AGENTS.md` 有定制如 `tdd-implement` 则跳过，canonical shared Skills 按默认 programming 范围覆盖但不删多余，Template Snapshot 的 `.opencode` / `.pi` 配置增量 add/update，`.pi/skills` 与 `.opencode/skills` 中已有的 project-local Skill 不按名称删除，避免把项目自定义 Skill 误删）、`--all` 仅更新同名可分发 Skill 内容（存在则覆盖，不存在则新增）并更新 `AGENTS.md`（不跳过定制），不删多余 Skill。Repo-local Skill 永远不新增、不覆盖、不删除，只在发现历史副本时提示保留。`update` 已合并到 `sync` 并删除。
 _Avoid_: update, force sync
 
 ## Skill Design

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 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.
+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) and the explicitly allowed distributable Skills. The Workspace also retains repo-local maintenance Skills that are never distributed. The Template Snapshot projects the project skeleton; the CLI assembles selected distributable Skills from the Workspace when initializing or synchronizing a Target Repository. The Workspace copy also serves this repo's own sessions.
 _Avoid_: skill distribution repo
 
 **Upstream Repository** (上游仓库):
-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`.
+mattpocock/skills — the source of the 26 Skill bodies (skills/engineering + skills/productivity) that are mirrored into this repo's Workspace canonical Skill source and then distributed by the CLI. 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/` (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).
+The root-level working copies of the template content — `.agents/skills/` (upstream plus all proprietary Skills, the canonical shared Skill source), `.opencode/` (issue-audit agent, explicit-Skill commands), `.pi/` (pi-agent prompts: `issue-audit`), `AGENTS.md`, `CONTEXT.md`, `docs/`. This is where the repo's own sessions load, modify and test the content. The Template Snapshot projects only the distributable configuration and skeleton: `.opencode/commands/*.md` → `template/.opencode/commands/`, `.pi/prompts/issue-audit.md` → `template/.pi/prompts/issue-audit.md`, and root-level `CONTEXT.md` and `docs/agents/` → `template/.opencode/` + `template/.pi/`. The CLI assembles selected shared Skills from the canonical source into a Target Repository. 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 Snapshot).
 _Avoid_: working copy, source repo
 
 **Template Snapshot** (模板快照):
-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.
+Everything under `template/` — the distributable snapshot of project skeleton content: 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/`, and AGENTS.md at the top level. It is generated by `node scripts/build-template.js` and used to initialize other repositories. Shared Skills and repo-local Skills remain in the Workspace; the CLI distributes only the selected shared Skills. The sync direction for the skeleton is one-way: Workspace → Template Snapshot. Template structure tests guard the content the snapshot owns.
 _Avoid_: release snapshot, published snapshot
 
 **Target Repository** (目标仓库):
-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.
+A repository initialized by copying the Template Snapshot skeleton into its root and then receiving selected distributable shared Skills from the CLI. It loads 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 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.
+The one-time action of setting up a Target Repository: copying the Template Snapshot skeleton into its root, then having the CLI create its shared Skill directory and copy the selected distributable Skills from the Workspace canonical source. 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` 按默认 programming 范围覆盖但不删多余技能，`template/.opencode/.pi` 增量 `add/update`，旧镜像 `.pi/skills` + `.opencode/skills` 中残留的共享技能自动清理但保留项目自定义）、`--all` 仅更新同名可分发技能内容（存在则覆盖，不存在则新增）并更新 `AGENTS.md`（不跳过定制），不删多余技能。Repo-local skill 永远不新增、不覆盖、不删除，只在发现历史副本时提示保留。`update` 已合并到 `sync` 并删除。
+`matt-skills sync` 同步 Target Repository 的 skeleton 与 Skills：`--dry-run` 仅对比不写盘（`check`，`--json` 可解析，有差异 `exit 1`），默认安全增量（`AGENTS.md` 有定制如 `tdd-implement` 则跳过，canonical shared Skills 按默认 programming 范围覆盖但不删多余，Template Snapshot 的 `.opencode` / `.pi` 配置增量 add/update，`.pi/skills` 与 `.opencode/skills` 中已有的 project-local Skill 不按名称删除，避免把项目自定义 Skill 误删）、`--all` 仅更新同名可分发 Skill 内容（存在则覆盖，不存在则新增）并更新 `AGENTS.md`（不跳过定制），不删多余 Skill。Repo-local Skill 永远不新增、不覆盖、不删除，只在发现历史副本时提示保留。`update` 已合并到 `sync` 并删除。
 _Avoid_: update, force sync
 
 ## Skill Design

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

@@ -1,21 +0,0 @@
-# Contract
-
-仅在 `tdd-implement` Step ① 读取。完整跨阶段规则仍以 `stages.md` 为兼容事实源；本文件只提供 Contract 阶段运行所需内容，避免加载其它阶段。
-
-## 操作
-
-1. 读取 spec/task、相关 `CONTEXT.md` 与必要 ADR，并使用仓库规定的代码探索入口理解当前实现。
-2. 提取每条 Acceptance Criterion，建立 Scope Ledger：`必须实现 / 明确不做 / 允许触及`。
-3. 将新发现分类为：当前 Behavior 必须修复、当前 issue 新增 Behavior、后续 ticket、无关项；只有前两类进入本次实现。
-4. 做一次 Preflight：记录 `HEAD`、工作区、`BASE_HEAD=$(git rev-parse HEAD)`、test/typecheck/build、可用 subagent/browser、敏感扫描、真实运行验证路径。
-5. 建立一次验证矩阵，后续复用，不重复探测等价命令。
-6. 定义公共 Seam 与 Behaviors：Behavior 必须映射到 Acceptance Criterion，并明确输入、可观察输出和验证层级。
-7. 已确认且未变化的 seam 直接复用；只有歧义、验收缺口、范围变化、破坏性操作或互斥方案才请求用户确认。
-
-## 出口
-
-- Acceptance Criteria、Scope Ledger 与 Out of Scope 明确；
-- 无待决需求歧义；
-- 验证矩阵和真实运行路径已确定，或明确标为 `blocked/unavailable`；
-- Behaviors/Seams 可追溯；
-- `BASE_HEAD` 已记录。

package/.agents/skills/tdd-implement/references/red-green.md

@@ -1,25 +0,0 @@
-# Red-Green
-
-仅在 `tdd-implement` Step ② 读取。TDD 语义以 `.agents/skills/tdd/SKILL.md` 为唯一事实源；本文件只描述交付阶段编排。
-
-## 操作
-
-1. 加载 `tdd` 核心规则；每个 Behavior 只按需读取 `tdd/tests.md` / `tdd/mocking.md`。
-2. Todo 以 Behavior 为粒度；一个 Behavior 是一个 `Red → Green → formatter/typecheck → 最小相关测试` cycle。
-3. 有效 Red 必须从公共接口观察到“目标行为尚未实现”的断言失败；语法错误、fixture/helper 缺失、环境启动失败、timeout 或工具错误都不是有效 Red。
-4. 只写让当前 Behavior Green 的最小实现；每次修改后即时 formatter/typecheck 和最小相关测试。
-5. 每个 Behavior 完成后更新 Todo，然后立即进入下一个 Behavior；一个 Seam 全绿不是阶段出口。
-
-## Turn Continuity / Chunking
-
-- 每个 Behavior 的 Red → Green → 验证在一个回合内连续完成；预告下一步后立即执行。
-- 所有 Behaviors 完成前持续推进，除非遇到合规交互点或明确外部阻塞。
-- 单次 write 超过约 150 行时先骨架后分批；超过约 5 处 replace 时拆批验证。
-
-## 出口
-
-- 所有 Behaviors 都有有效 Red；
-- 最小实现全部 Green；
-- formatter/typecheck 与最小相关测试通过；
-- Todo 全部反映真实完成状态；
-- `BASE_HEAD` 祖先校验通过。

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

@@ -1,254 +0,0 @@
-# 三阶段详细定义 + Finalize
-
-单 `spec` / 单 `task` 与多 `task` 共用下列三个交付阶段；Verify 通过后执行 Finalize 收尾，Finalize 不计入阶段。多 issue 的依赖图、Kahn 分层、层收敛、最终收敛和回退/冲突处理见 [orchestration.md](orchestration.md)。TDD 语义以 [tdd 技能](.agents/skills/tdd/SKILL.md) 为唯一事实源，不在此重写。
-
-## 目录
-
-- [① Contract：明确交付契约](#阶段-①-contract明确交付契约)
-- [② Red-Green：行为级 TDD](#阶段-②-red-green行为级-tdd)
-- [③ Verify：最终验证与审查](#阶段-③-verify最终验证与审查)
-- [Finalize：非阶段交付收尾](#finalize非阶段交付收尾)
-- [跨阶段运行纪律](#跨阶段运行纪律)
-- [状态统一](#状态统一)
-- [回退路由](#回退路由)
-
----
-## 不可省略的质量门禁
-
-无论单 issue 还是多 issue，以下门禁都必须形成证据：
-
-1. 当前 issue 的范围、Acceptance Criteria 和 Out of Scope 明确；
-2. 产品实现之前存在有效 Red；
-3. 最终 diff 对应的相关测试和 typecheck 通过；
-4. ticket 要求真实运行时，真实运行验证已完成；
-5. 当前稳定 diff 已完成一次 `code-review` 且无 blocking finding；
-6. README/docs 与实现一致；
-7. 每个 issue 形成独立、可追溯的 commit；
-8. Tracker 状态与真实完成度一致。
-
-Seam 或专项测试绿色不等于 issue 完成；只有三个阶段与 Finalize 全部通过，issue 才能标记为 `resolved`。
-
-
-## 阶段 ① Contract：明确交付契约
-
-### 入口条件
-
-- 用户提供单个 `spec`、等价 spec 或 `Type: task` issue。
-- `research`、`prototype`、`grilling` 等非实现入口已分流。
-
-### 操作
-
-1. 完整读取入口；按需读取 `CONTEXT.md` 的相关术语和与本次 spec、触及符号或失败证据有关的 ADR。
-2. 使用仓库规定的代码探索入口。探索结果含完整源码时视为已读，不再次 `read` 同一文件，除非文件发生漂移或只返回调用路径。
-3. 逐条提取 Acceptance Criteria，并写出本 issue 的 **Scope Ledger**：
-
-   ```text
-   必须实现：当前 issue 要求的行为
-   明确不做：后续 tickets 和 Out of Scope
-   允许触及：预计受影响的模块、组件、接口
-   ```
-
-4. 实现或 Review 中发现的新问题必须归类为：
-   - 当前 Behavior 必须修复；
-   - 当前 issue 需要新增 Behavior；
-   - 后续 ticket；
-   - 与当前 feature 无关。
-
-   只有前两类进入当前实现；第 2 类必须补回 Contract 和验证矩阵，第 3、4 类保留记录，不无记录地扩大范围。
-5. 完成一次 **Preflight** 并记录真实结果：
-   - 当前 `HEAD`、工作区状态和 `BASE_HEAD=$(git rev-parse HEAD)`；
-   - 可用的 test、typecheck、build 命令；
-   - `code-review` 可用性；
-   - 可用的 browser 或 Playwright 路径；
-   - ticket 要求的真实运行验证方式。
-6. 建立一次验证矩阵，列出 targeted tests、typecheck、必要 build、smoke/package check 和真实运行验证，并记录各项的触发条件，后续只复用这份矩阵。
-7. 识别公共测试边界和 Behaviors。一个 Seam 是一个公共可观察边界；一个 Behavior 是一个红-绿 cycle；一个 Seam 可以包含多个 Behaviors。每个 Behavior 明确输入、可观察输出、对应 Acceptance Criterion 和验证层级。
-8. spec 已确认且未变化的 Seam 直接复用；只有出现需求歧义、验收缺口、范围变化、破坏性操作或互斥方案时才请求用户确认。
-
-### 出口条件
-
-- 能用自己的话复述需求和每条 Acceptance Criterion；
-- Scope Ledger 已记录，且明确什么不做；
-- 无未澄清歧义；
-- 验证矩阵已建立；
-- 工具、命令和真实运行路径已确认可用，或已记录为 `blocked/unavailable` 及替代路径；
-- `BASE_HEAD` 已记录。
-
----
-
-## 阶段 ② Red-Green：行为级 TDD
-
-### 入口条件
-
-- Contract 出口条件全部满足。
-
-### 操作
-
-1. 在本阶段入口加载 [tdd 技能](.agents/skills/tdd/SKILL.md) 的相关规则一次；每个 Behavior 只按需读取对应的 `tdd/tests.md` 和 `tdd/mocking.md` reference，不重复阅读全文。
-2. 按 Behavior 建立 Todo，而不是按 Seam 建立 Todo。推荐层级：
-   - 大任务：整个 issue；
-   - 中任务：Seam；
-   - Todo：一个 Behavior cycle；
-   - Subtodo：`B1-R` 红 → `B1-G` 绿 → `B1-T` typecheck。
-3. 每个 Behavior 连续执行：
-
-   ```text
-   写一个失败测试
-   → 从公共接口确认目标 Behavior 失败
-   → 最小实现
-   → formatter
-   → typecheck
-   → 最小相关测试
-   → 标记该 Behavior completed
-   ```
-
-4. 只有通过公共接口观察到“目标行为尚未实现”的断言失败才是有效 Red。语法错误、缺失 helper/fixture、测试环境启动失败、工具参数错误、timeout 或命令中断都记录为失败类别或 `UNKNOWN`，不能当作有效 Red。
-5. 根据语言做即时验证：Go 修改后立即 `gofmt` 和最小 package test；TS/TSX 修改后立即 parser/typecheck 和最小 component test。批量编辑拆成小批，每批恢复绿色后再继续。
-6. 每个 Behavior 完成后更新实际 Todo 状态，再进入下一个 Behavior；全部 Behaviors completed 后才离开本阶段。
-
-### 回合连续性与 Chunking
-
-- 每个 Behavior 的 Red → Green → formatter → typecheck → 最小相关测试在一个回合内串行完成；确认全绿后立即进入下一个 Behavior。
-- 一个 Seam 全绿只是内部进度，不是阶段出口；阶段出口是所有 Behaviors 红-绿完成且 typecheck 通过。预告下一步后立即执行，直到阶段出口、合规交互点或外部阻塞。
-- 进度输出并入工具调用序列，输出后继续执行；不要把“准备下一步”当作回合终点。
-- 单次 `write` 超过约 150 行时先写骨架再分批补全；批量 `replace` 超过 5 处时拆批，每批后立即验证。
-- `done`、`completed` 等状态只按当前实际推进更新，已完成项永不回退。
-
-### 出口条件
-
-- 所有 Behaviors 都有有效 Red；
-- 所有 Behaviors 的最小实现已 Green；
-- formatter、typecheck 和最小相关测试通过；
-- Todo 清单反映真实状态，全部 Behavior Todo 为 `completed`；
-- `BASE_HEAD` 祖先校验通过。
-
----
-
-## 阶段 ③ Verify：最终验证与审查
-
-### 入口条件
-
-- Red-Green 出口条件满足，当前 diff 稳定。
-
-### 固定顺序
-
-```text
-当前 issue 影响范围测试
-→ 必要 build
-→ 必要真实运行验证
-→ 当前稳定 diff 调用一次 code-review
-→ 修复 blocking finding 后的定向复核
-```
-
-### 测试与真实运行验证
-
-- 单 issue / 单 spec 与多 issue 均只运行当前 issue 影响范围内的测试，按照 Contract 的验证矩阵执行，不同时运行等价命令；不因进入 Verify 自动扩大测试范围。
-- ticket 要求真实运行时，优先使用专用 browser 工具，其次使用项目已有 Playwright；HTTP/CLI 只能补充 API 验证，不能替代 WebUI 验证。
-- 真实进程验证使用隔离配置和临时端口，保存 PID，记录实际请求结果或页面可见结果，结束时清理进程和临时目录。
-
-### Review
-
-1. 当前 issue 的最终 diff 稳定后，调用一次 [code-review](.agents/skills/code-review/SKILL.md)。
-2. `tdd-implement` 只负责 **何时调用 review**；审查维度、reviewer 数量、提示词、上下文与输出格式全部以 `code-review` 为唯一事实源，不在这里复制或弱化。
-3. `code-review` 未完成或存在 blocking finding 时，issue 保持未完成。只修当前 issue blocking finding；其余 findings 按 `code-review` 的分类与输出处理，不无记录地扩大范围。
-4. 修复 blocking finding 后，只运行受影响测试/typecheck 与 finding delta recheck，不再次调用完整 `code-review`。若修复引入新的 Behavior、改变 Scope 或使原 Review 对象不再成立，则回到 Contract/Red-Green，重新形成稳定最终 diff 后再进入 Verify。
-5. Review 结果只在对话/运行记录中消费，不由 `tdd-implement` 额外生成自己的 review 报告格式。
-
-### 出口条件
-
-- 最终 diff 对应的相关测试通过；
-- 必要 typecheck/build 通过；
-- ticket 要求的真实运行验证已完成并记录实际结果；
-- 当前稳定 diff 已完成一次 `code-review`；
-- 无 blocking finding；
-- 受影响范围的最后一次证据对应当前 diff。
-
----
-
-## Finalize：非阶段交付收尾
-
-### 入口条件
-
-- Verify 出口条件满足。
-
-### Commit
-
-1. 如本次实现要求 README/docs/config/package 同步，完成必要更新。
-2. 按当前 issue 范围直接创建一个独立 commit。
-3. 不执行额外敏感信息/安全扫描，不做 `git diff --cached` 复核，也不设置额外 commit message 门禁。
-
-仓库级 Git 安全与历史保护规则仍然适用；Finalize 不重复定义或扩展这些规则。
-
-### Tracker 收尾
-
-Commit 成功后：
-
-- 逐条勾选 Acceptance Criteria；
-- 将 issue 状态改为 `resolved`；
-- 追加实施总结；
-- 更新 `.scratch/<feature>/progress.md` 的 `Status`、`Commit`、`Review`、`Tests`；
-- 记录 commit hash、message、最终测试命令/数量/结果和真实运行结果；
-- 确认下一 issue 的 blockers 已解除。
-
-Finalize 开始后不新增产品 Behavior。若实现、测试或文档不完整，回到对应阶段；只有三个阶段与 Finalize 全部通过，才可把 issue 标记为 `resolved`。
-
-### 出口条件
-
-- commit 已创建且为当前 issue 的独立提交；
-- Acceptance Criteria 全部通过；
-- issue 状态为 `resolved`（无关联 issue 的直接 spec 则在会话中输出总结）；
-- 实施总结和 `progress.md` 已同步。
-
----
-
-## 跨阶段运行纪律
-
-### Tool Failure Budget
-
-```text
-首次失败
-→ 判断失败类别
-→ 最多一次有依据的 fallback
-→ 仍失败则记录 blocked/unavailable 并停止该路径
-```
-
-相同命令或工具参数不原样连续重试；timeout 或中断后缩小到 package、文件或具体 test；model、browser 或 tool 不可用时最多一次 fallback。用户要求停止或 handoff 时立即停止。
-
-### 验证证据失效
-
-任何产品代码或测试文件再次变化，旧的测试、typecheck、build 等受影响证据立即失效，必须重新验证受影响范围。正式 `code-review` 调用本身不因 finding 修复而重复；post-review 修复必须完成受影响验证和 finding delta recheck。若修改引入新的 Behavior、改变 Scope 或使原 Review 对象不再成立，则回到 Contract/Red-Green，重新形成稳定最终 diff 后再进入 Verify。
-
-### Git History Preservation
-
-进入 Contract 时记录 `BASE_HEAD=$(git rev-parse HEAD)`；每个阶段出口和 commit 前都执行：
-
-```bash
-git merge-base --is-ancestor $BASE_HEAD HEAD
-```
-
-失败时先经 `git reflog` 找回被改写的历史，再继续。为达到工作区干净只删除本次产生的 `[DEBUG-...]`、一次性脚本和临时文件；未经用户确认不使用 `git reset --hard`、`git checkout .`、`git clean -fd`、`git stash push --include-untracked`、`git push --force`、`git rebase -i` 或任何让 `HEAD` 后退的命令。需要 stash 时使用 `--keep-index`，pop 后重新校验。
-
----
-
-## 状态统一
-
-```text
-Todo:     pending | in_progress | completed | blocked
-Issue:    ready-for-agent | in_progress | resolved | blocked
-Progress: pending | in_progress | done | blocked
-```
-
-状态转换：Contract 完成后 Issue/Progress 为 `in_progress`；Red-Green 完成后 Behaviors 为 `completed`，Issue 仍为 `in_progress`；Verify 完成后 Issue 仍为 `in_progress`；Finalize 完成后 Issue 为 `resolved`、Progress 为 `done`。外部阻塞记录为 `blocked`，恢复后回到 `in_progress`。
-
----
-
-## 回退路由
-
-| 当前阶段 | 回退条件 | 回退目标 |
-|---|---|---|
-| ① Contract | 需求歧义、验收缺口、范围变化 | → ① 补充契约和验证矩阵 |
-| ② Red-Green | 有效 Red、实现、formatter、typecheck 或相关测试失败 | → ② 修复当前 Behavior |
-| ③ Verify | 测试、build、真实运行或 review finding 失败 | → ② 修复 Behavior；需求偏差 → ① |
-| Finalize | 必要 docs 未同步、commit 失败或 Tracker 信息不完整 | → ①/③ 修复对应问题；仍在 Finalize 完成前解决 |
-
-多 issue 的层收敛、最终收敛、依赖冲突和跨 issue 修改冲突按 [orchestration.md](orchestration.md) A5 回退，不跨 issue 无记录改动。

package/template/.agents/skills/ask-matt/PHASE-BOUNDARIES.md

@@ -1,55 +0,0 @@
-# Phase boundaries
-
-A **phase** is a chunk of work inside a session: the grilling, the implementation, the QA. The definition is fuzzy on purpose: a phase ends when you think *"ok, we're done with that"*.
-
-The **phase boundary** is the gap between two phases, and it is the only place this decision belongs. Mid-phase there is no decision to make: continue, or split the work that's left into subagents. Compacting mid-phase makes the agent lose the thread.
-
-## The five options
-
-| Option       | What it does                                                    |
-| ------------ | --------------------------------------------------------------- |
-| **Continue** | Stay in the session. No context switch at all.                    |
-| **`/clear`** | Empty the context window and start from nothing.                  |
-| **`/handoff`** | Write a portable markdown file and seed a session anywhere with it. |
-| **Subagent** | Send the task to its own context window and get a report back.     |
-| **`/compact`** | Compress this context and seed a fresh session with the summary.  |
-
-## The tree
-
-Work top to bottom at the boundary. The first **yes** wins.
-
-**1. Can you continue in this session?** Two things make the answer yes: the next phase needs this phase as a **primary source**, or you have enough [smart zone](https://www.aihero.dev/ai-coding-dictionary/smart-zone) left (~150k tokens) for the next phase to fit. Grilling → implementation is the standard yes: the implementation wants the reasoning verbatim, not a summary of it. Continue costs nothing and loses nothing, so rule it out before anything else.
-
-**2. Is the context irrelevant to what comes next?** Is everything in this session (the exploration, the decisions, the dead ends) disposable? If so, **`/clear`**. It is the cheapest move on the board: it takes no time and hands back the whole window. `/clear` also isn't terminal: the old session stays resumable.
-
-The cost of getting this wrong is one-way. Clear a *relevant* context and you lose the **why** behind what you built, and no amount of reading the diff back gets it returned.
-
-**3. Do you need to hand off?** `/handoff` is narrow. You need it only when you are:
-
-- swapping to a **new harness** (Claude → Codex),
-- moving to a **new directory** or repo,
-- sending the work to a **colleague**,
-- or forking a side task you found **mid-phase** without derailing what you're doing.
-
-That list is the whole clause. What `/handoff` buys is **portability**: a file that travels. If nothing is travelling, you don't need it.
-
-**4. Can the task be done AFK?** Is it scoped tightly enough to run with you away from the keyboard, no steering? Then send it to a **subagent** and leave this session untouched. Automated review is the standard case: the agent reads the diff and reports, and you aren't needed while it does.
-
-**5. Otherwise, `/compact`.** Relevant context, same harness, same directory, and you need to stay in the loop: this is where the tree lands, and it lands here often. Pass it an instruction (`/compact we're going to QA this area`) so the summary keeps what the next phase needs.
-
-`/compact` is the **default, not the first reach**. It sits at the bottom because the four questions above it are all cheaper or more precise. The failure mode when people start here is a fresh session that is confidently wrong about a decision the summary flattened.
-
-## Primary and secondary sources
-
-Every move except **Continue** turns a **primary source** into a **secondary source**: the session as it happened, replaced by a summary of it. The trade is always the same shape:
-
-| Source                            | Information | Noise | Room to move |
-| --------------------------------- | ----------- | ----- | ------------ |
-| Primary (Continue)                | Full        | Lots  | Little       |
-| Secondary (`/compact`, `/handoff`) | Lossy       | Less  | Lots         |
-
-This is why question 1 comes first. You only pay the lossiness when staying costs more than it saves.
-
-## These are judgement calls
-
-The questions are not objective: each has taste in it, and the same boundary can go two ways on two days. The value is in asking them **in order**, at the boundary rather than in the middle of the work.

package/template/.agents/skills/ask-matt/SKILL.md

@@ -1,90 +0,0 @@
----
-name: ask-matt
-description: Ask which skill or flow fits your situation. A router over the skills in this repo.
-disable-model-invocation: true
----
-
-# Ask Matt
-
-You don't remember every skill, so ask.
-
-A **flow** is a path through the skills. Most paths run along one **main flow**, and two **on-ramps** merge onto it. Everything else is standalone, or a vocabulary layer that runs underneath.
-
-## The main flow: idea → ship
-
-The route most work travels. You have an idea and want it built.
-
-1. **`/grill-with-docs`** sharpens the idea by interview. Start here whenever you are **working in a working directory**: it's stateful, retaining what it learns in `CONTEXT.md` and ADRs. (No working directory? Use `/grill-me` instead, covered under Standalone. Both run the same `/grilling` primitive; `grill-with-docs` is the one that leaves a paper trail, which makes it the better of the two whenever a repo is there to leave it in.)
-2. **Branch: can you settle every question in conversation?** If a question needs a runnable answer (state, business logic, a UI you have to see), detour through a prototype, bridged by **`/handoff`** in both directions (a prototype lives in its own directory, which is exactly what `/handoff` is for; see Phase boundaries):
-   - **`/handoff`** out, then open a fresh session against that file,
-   - **`/prototype`** to answer the question with throwaway code,
-   - **`/handoff`** back what you learned, and reference it from the original idea thread.
-3. **Branch: is this a multi-session build?**
-   - **Yes** → **`/to-spec`** (turn the thread into a spec), then **`/to-tickets`** to split it into tracer-bullet tickets, each declaring its **blocking edges**. On a local tracker that's one file per ticket under `.scratch/<feature>/issues/`, worked blockers-first by hand; on a real tracker the edges become native blocking links, so any ticket whose blockers are done can be grabbed: kick off **`/implement`** per ticket, **`/clear`ing context between each one**. Each ticket is self-contained, so the last one's context is disposable.
-   - **No** → **`/implement`** right here, in the same context window.
-
-   Either way, **`/implement`** builds each issue by driving **`/tdd`** internally (one red-green slice at a time), then closes out by running **`/code-review`**, a two-axis review (Standards + Spec) of the diff, before committing. Reach for **`/tdd`** on its own when you just want to build a concrete behaviour test-first without a full spec, and **`/code-review`** on its own whenever you want to review a branch or PR against a fixed point.
-
-### Context hygiene
-
-Keep steps 1–3 in **one unbroken context window** (don't compact or clear until after `/to-tickets`) so the grilling, spec, and tickets all build on the same thinking. Each `/implement` then starts fresh, working from the ticket.
-
-The limit on this is the **[smart zone](https://www.aihero.dev/ai-coding-dictionary/smart-zone)**: the window (~150k tokens on state-of-the-art models) within which the model still reasons sharply. If a session approaches it before `/to-tickets`, don't push on degraded; `/compact` at the nearest phase boundary and carry on (see Phase boundaries).
-
-## On-ramps
-
-A starting situation that generates work, then merges onto the main flow.
-
-- **Bugs and requests piling up** → **`/triage`**. It moves issues through triage roles and produces agent-ready issues, which **`/implement`** later picks up.
-
-  Triage is only for issues **you didn't create**: bug reports, incoming feature requests, anything that arrives raw. Tickets that `/to-tickets` produced are already agent-ready, so **don't triage them**.
-
-- **Something's broken** → **`/diagnosing-bugs`**. For the hard ones: the bug that resists a first glance, the intermittent flake, the regression that crept in between two known-good states. It refuses to theorise until it has a **tight feedback loop** (one command that already goes red on *this* bug), then fixes with a regression test. Its post-mortem hands off to **`/improve-codebase-architecture`** when the real finding is that there's no good seam to lock the bug down.
-
-- **A huge, foggy effort: a greenfield project or a huge feature build, too big for one session** → **`/wayfinder`**, the most cognitively demanding flow here. When the way from here to the destination isn't visible yet, it charts a **shared map** of **decision tickets** on the issue tracker and resolves them one at a time, producing **decisions, not deliverables**, until the fog is pushed back and the way is clear. Where **`/grill-with-docs`** sharpens an idea you can hold in one session, wayfinder is for the idea you can't, and it's slower and denser, so save it for exactly that, never a well-scoped feature.
-
-  When the map clears, **it hands off, it doesn't build**: merge onto the main flow at **`/to-spec`**, which collapses the map's linked decisions into a buildable plan, then `/to-tickets` and `/implement` as usual. Looping the map straight into `/implement` skips that collapse and throws the linked detail away, so go straight to `/implement` only when the effort turned out genuinely small.
-
-## Codebase health
-
-Not feature work, just upkeep.
-
-- **`/improve-codebase-architecture`** runs whenever you have a spare moment to keep the codebase good for agents to operate in. It surfaces **deepening opportunities**; picking one _generates an idea_ you can take into the main flow at `/grill-with-docs`. It's the survey that finds the candidates; **`/codebase-design`** (below) is the bench you design the chosen one on.
-
-## Vocabulary underneath
-
-Two model-invoked references that run *beneath* the other skills, each the single source of truth for its vocabulary. Reach for them directly when the **words**, not the process, are the problem; or let the skills above pull them in.
-
-- **`/domain-modeling`**: sharpen the project's *domain* language: challenge a fuzzy term, resolve an overloaded word ("account" doing three jobs), record a hard-to-reverse decision as an ADR. It's the active discipline `/grill-with-docs` drives to keep `CONTEXT.md` a clean glossary.
-- **`/codebase-design`** is the deep-module vocabulary (module, interface, depth, seam, adapter, leverage, locality) for designing a module's *shape*: a lot of behaviour behind a small interface at a clean seam. `/tdd` and `/improve-codebase-architecture` both speak it.
-
-## Phase boundaries
-
-A **phase** is a chunk of work inside a session: the grilling, the implementation, the QA. At the **boundary** between two of them you have five options, and picking between them is the fuzziest decision in this whole map:
-
-- **Continue**: stay put. Costs nothing, loses nothing.
-- **`/clear`**: empty the window, when nothing here matters to what's next.
-- **`/handoff`** writes a portable markdown file. Narrow: only for a **new harness**, a **new directory**, a **colleague**, or forking a side task **mid-phase**. What it buys is portability.
-- **Subagent**: send a tightly-scoped task to its own window and get a report back.
-- **`/compact`** compresses this context and seeds a fresh session with it. The **default**, at the bottom of the tree rather than the first reach.
-
-Read [PHASE-BOUNDARIES.md](PHASE-BOUNDARIES.md) for the ordered tree: the five questions, the reasoning behind each branch, and why the primary-source cost makes **Continue** the one to rule out first. Make the decision **at** a boundary; mid-phase, continue or split the rest into subagents.
-
-## Standalone
-
-Off the main flow entirely.
-
-- **`/grill-me`**: the same relentless interview as `/grill-with-docs`, but **stateless**: it saves nothing locally and builds no `CONTEXT.md`. Reach for it when you are **not working in a working directory** (sharpening a plan, a design, a piece of writing, anything with no repo under it). If you are in a working directory, use `/grill-with-docs` instead: it runs the same interview and leaves a paper trail, so it is strictly the better one.
-- **`/grilling`** is the interview primitive itself: rounds, the frontier, facts are the agent's job and decisions are yours. `/grill-me` and `/grill-with-docs` are the two named ways in, and `/triage`, `/wayfinder` and `/improve-codebase-architecture` all run it internally. Reach for it directly only when you want the interview with no wrapper around it.
-- **`/resolving-merge-conflicts`** works an in-progress merge or rebase conflict hunk by hunk, resolving by **intent** traced to each side's primary source rather than by picking lines, then finishes the operation. It never runs `--abort`. Standalone and off every flow: reach for it when you are already mid-conflict.
-- **`/prototype`** is a small, throwaway program that answers one design question: does this state model feel right, or what should this UI look like. Throwaway is a constraint on how the code is written, not a promise to destroy it: the answer folds into the real code, and the prototype itself is kept as a **primary source** on a `prototype/<name>` branch out of main, pointed at from the implementation issue. It's the detour in step 2 of the main flow, but reach for it any time a design question is hard to settle on paper.
-- **`/research`**: delegate reading legwork to a **background agent**: it investigates a question against **primary sources**, then leaves a cited Markdown file in the repo. Keep working while it reads. The file it produces is something to take *into* the main flow at `/grill-with-docs`, since research feeds the thinking rather than replacing it.
-- **`/to-questionnaire`** comes in when the thing blocking you isn't in your head or the codebase but in **someone else's**, and it writes them a questionnaire to fill in. It's the inverse of `/grill-me`: instead of interviewing you about the subject, it interviews you about the **send** (who it's going to, what you need back) and aims the questions at the gap. What comes back is material for `/grill-with-docs` or `/to-spec`.
-- **`/wizard`** is for the steps only a **human** can take: provisioning infrastructure, setting up credentials or CI secrets, clicking through an unfamiliar third-party dashboard, running a one-off migration or cutover. It generates an interactive bash script that opens each URL, captures each value, and writes it into `.env` and GitHub secrets, so the procedure stops being something you re-explain to an agent every time. Model-invoked, so the agent reaches for it the moment it hits a wall only you can pass. If the agent could just do it itself, it should; this is for where a human is genuinely in the loop.
-- **`/wait-what`** is the corrective for a message that didn't land. Use it mid-conversation, inside any other skill, and the agent re-pitches what it just said with the context you were missing, in plain English, using the `CONTEXT.md` vocabulary. It works after the fact; `/grill-with-docs` is the upfront cure, because a shared language agreed early is what stops the jargon arriving at all.
-- **`/teach`**: learn a concept over multiple sessions, using the current directory as a stateful workspace.
-- **`/writing-for-agents`** is the reference for writing documents agents consume: skills, AGENTS.md, pointed-at docs.
-
-## Precondition
-
-**`/setup-matt-pocock-skills`**: run before your first engineering flow to configure the issue tracker, triage labels, and doc layout the other skills assume. Custom issue trackers also work.

package/template/.agents/skills/ask-matt/agents/openai.yaml

@@ -1,5 +0,0 @@
-interface:
-  display_name: "Ask Matt"
-  short_description: "Find the right skill or workflow"
-policy:
-  allow_implicit_invocation: false