@heihei0299/matt-skills 2.1.5 → 2.1.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. package/.agents/skills/grill-to-spec/SKILL.md +22 -14
  2. package/.agents/skills/grill-to-spec/references/rules.md +21 -7
  3. package/README.md +56 -161
  4. package/package.json +1 -1
  5. package/template/.agents/skills/grill-to-spec/SKILL.md +22 -14
  6. package/template/.agents/skills/grill-to-spec/references/rules.md +21 -7
  7. package/template/.opencode/commands/grill-to-spec.md +1 -1
  8. package/template/AGENTS.md +7 -0
  9. package/template/PROJECT.md +3 -0
package/.agents/skills/grill-to-spec/SKILL.md CHANGED
@@ -6,42 +6,50 @@ disable-model-invocation: true
6
6
 
7
7
  # Grill to Spec
8
8
 
9
- 只做两个上游 skill 的编排：先把想法打磨成共识，再把共识发布成 spec。本 skill 不写代码、不修改源码或测试。
9
+ 只做两个上游 skill 的编排：先把想法打磨成共识，再把共识发布成 spec。本 skill 不写代码、不修改源码或测试、不自动 commit。
10
10
 
11
11
  ## 流程
12
12
 
13
+ ### 0. 预检
14
+
15
+ - 只读确认 issue tracker、目标上下文、feature slug 和已有 spec/issue 状态。
16
+ - tracker 未配置、slug 不明确或目标路径不可写时，在任何 ADR/spec/issue 写入前报告阻塞。
17
+ - 已有同一 feature 的产物先读取并比较；相同共识不重复发布，设计变化进入变更流程。
18
+
13
19
  ### ① 形成共识
14
20
 
15
21
  调用 [`grill-with-docs`](.agents/skills/grill-with-docs/SKILL.md)，由 `grilling` 与 `domain-modeling` 完成采访、术语和设计决策。
16
22
 
17
23
  - glossary 按上游规则 inline 更新；
18
- - 只有确需 ADR 时才创建 ADR；
19
- - 决策共识形成后直接写入 ADR，不向用户展示 ADR 正文，不增加单独确认轮次。
24
+ - 只有同时满足 ADR 条件时才提出 ADR，但 ADR 等最终决策清单确认后再写入；
25
+ - 在本阶段让 [`to-spec`](.agents/skills/to-spec/SKILL.md) 做代码理解和 seam 分析；seam 是共识的一部分，不单独制造发布确认；
26
+ - 形成精简决策清单：目标、范围、关键选择、seam、未纳入范围和待验证假设；只展示清单，不展示任何 ADR/spec/issue 正文或草稿；
27
+ - 用户确认决策清单后，立即进入阶段 ②。
20
28
 
21
- 出口：用户确认共识已达成，且已确定的 glossary/ADR 已写入。
29
+ 出口：决策清单已确认，glossary 已按需更新；尚未确认的 ADR/spec/issue 不写入。
22
30
 
23
31
  ### ② 发布 spec
24
32
 
25
- 将已确认的共识交给 [`to-spec`](.agents/skills/to-spec/SKILL.md)，完成代码库理解、seam 提案和 spec 组装。
33
+ 将已确认的决策清单和 seam 分析交给 `to-spec`；此处只综合、写入和发布，不重新采访或再次确认 seam。
26
34
 
27
- - 将 seam 提案作为共识的一部分确认，不展示由此生成的文档正文；
28
- - 共识（含 seam）达成后，直接写入/发布 spec 与 issue，不设置发布前确认；
29
- - 发布时使用 `ready-for-agent`，格式细则只读取 [`references/rules.md`](references/rules.md)。
35
+ - 按 ADR → spec → issue 的顺序执行；issue 发布成功后设置 `ready-for-agent`；格式细则只读取 [`references/rules.md`](references/rules.md)。
36
+ - 相同 feature 复用已有产物，设计变化按 tracker 的更新语义保留历史；
37
+ - 任一步失败都保留已成功写入的内容，记录状态和失败点，重跑时从第一个未完成出口继续；不回滚、不重复发布。
30
38
 
31
- 出口：spec/issue 已写入或发布，只报告路径或标识、状态和未纳入范围。
39
+ 出口：ADR/spec/issue 已写入或发布，只报告路径或标识、状态和未纳入范围，不复制正文。
32
40
 
33
41
  ## 回合连续性
34
42
 
35
- 本 skill 是 Long-Horizon Skill。阶段 ① 达到出口后立即进入阶段 ②；正常的阶段切换、进度汇报或“接下来生成 spec”不是回合终点。仅在必须获得用户确认的设计问题、明确外部阻塞、用户主动停止或整个 skill 出口时暂停。文档写入/发布不另起确认回合，不要求用户额外回复“继续”。
43
+ 本 skill 是 Long-Horizon Skill。预检、阶段 ①、代码理解、决策清单确认后的阶段 ② 在同一任务链连续执行；进度汇报和阶段切换不是回合终点。仅在需要设计确认、决策清单确认、外部阻塞、用户主动停止或整个 skill 出口时暂停；确认完成后不要求用户额外回复“继续”。
36
44
 
37
45
  ## 本 skill 独有门禁
38
46
 
39
- - ADR：决策共识 → 直接落盘，不展示正文、不设置独立确认；
40
- - spec/issue：共识与 seam 达成后直接写入/发布，不展示正文、不设置发布前确认；
41
- - 全程不写代码、不修改测试、不执行实现。
47
+ - 文档正文永不展示；用户只确认精简决策清单，发布后只接收元数据报告；
48
+ - ADR/spec/issue 不设置额外草稿确认；
49
+ - 不写代码、不修改源码或测试、不自动 commit；实现 tickets 交给 `to-tickets`。
42
50
 
43
51
  ## 异常
44
52
 
45
53
  - 用户放弃或没有可形成 spec 的主题时终止；
46
54
  - issue tracker 未配置时报告配置阻塞，不绕过发布；
47
- - 用户改变已确认的设计时回到 ①，不在 ② 静默扩大范围。
55
+ - 用户改变已确认设计时回到阶段 ①，按变更语义保留历史，不静默覆盖。
package/.agents/skills/grill-to-spec/references/rules.md CHANGED
@@ -2,29 +2,43 @@
2
2
 
3
3
  本文件只保存 `grill-to-spec` 相对上游 `grill-with-docs` / `to-spec` 的**增量约束**。Spec 的章节、User Story 形状、Implementation Decisions 等格式全部以 `to-spec` 为唯一事实源，本文件不复制上游模板。
4
4
 
5
+ ## 预检与状态规则
6
+
7
+ - 写入前只读确认 issue tracker、目标上下文、feature slug、已有 spec/issue 和当前状态；tracker 未配置或目标不可写时不写 ADR/spec/issue。
8
+ - feature slug 是 spec 路径和 issue 幂等键；候选不明确或冲突时才询问。
9
+ - 记录共识、ADR、spec、issue、`ready-for-agent` 出口；重跑从第一个未完成出口继续，不重复已成功动作。
10
+ - 已有相同共识的 feature 只报告已有路径或标识；设计变化走变更流程，不创建重复 issue。
11
+
5
12
  ## Glossary 增量规则
6
13
 
7
14
  - 懒创建：首个术语解析时才建 `CONTEXT.md`；多上下文时先确认归属，归属不清则询问。
8
15
  - 只收本上下文特有术语；定义 WHAT 非 HOW，避免把 glossary 变成实现草稿。
9
- - glossary 可按上游流程 inline 更新，不额外增加确认轮次。
16
+ - glossary 可按上游流程 inline 更新，不额外增加确认轮次；设计变化时按历史保留规则修正。
10
17
 
11
18
  ## ADR 增量规则
12
19
 
13
20
  - 只有同时满足“难逆转 / 无上下文费解 / 存在真实权衡”时才提议 ADR。
14
- - 决策共识形成后直接落盘；不向用户展示 ADR 正文，不增加独立确认轮次。
15
- - 不把 ADR 当 glossary 一样静默 inline 更新。
21
+ - ADR 不像 glossary 一样静默 inline 更新；等最终决策清单确认后直接落盘，不展示正文，不增加独立确认轮次。
22
+ - 用户改变决策时不静默覆盖旧 ADR；按项目 ADR 规则追加、废弃或标记 superseded。
16
23
 
17
24
  ## Spec 增量规则
18
25
 
19
26
  - Spec 的结构与字段全部委托 `to-spec`，本文件不维护第二份模板。
20
- - seam 提案作为共识的一部分确认，不展示由此生成的 spec 正文。
21
- - 共识（含 seam）达成后直接写入并标记 `ready-for-agent`，不设置发布前确认。
27
+ - 代码理解和 seam 分析属于共识阶段；seam 纳入最终决策清单，不在发布阶段再次询问。
28
+ - 决策清单确认后直接写入 spec；不展示 spec 正文或草稿。
22
29
  - 全文沿用已经确认的 glossary 词汇，并尊重所触区域既有 ADR。
23
30
 
24
31
  ## Issue 增量规则
25
32
 
26
- - 按已配置的 issue tracker 直接发布 issue；issue 正文不在对话中展示。
27
- - 发布后只报告 issue 标识、状态和未纳入范围，不复制正文。
33
+ - 按已配置的 issue tracker 直接发布唯一 spec issue；implementation tickets 交给 `to-tickets`。
34
+ - issue 正文不在对话中展示；发布成功后设置 `ready-for-agent`。
35
+ - issue 创建成功但 label/status 更新失败时保留 issue，报告标识和失败点，不删除、不误报为 ready。
36
+ - 设计变化委托 tracker 的原生更新语义：本地追加变更记录，远端按 body/comment/关联关系更新；不另造版本模板。
37
+
38
+ ## 失败与 Git 边界
39
+
40
+ - 任一步失败都保留已成功写入的内容并报告部分状态；不做跨文件或跨 tracker 回滚，不盲目重试。
41
+ - 本 skill 不自动创建 Git commit；发布文档与 Git 提交是两个独立出口。
28
42
 
29
43
  ## 反模式
30
44
 
package/README.md CHANGED
@@ -1,32 +1,26 @@
1
1
  # matt-skills
2
2
 
3
- mattpocock/skills（`skills/engineering` + `skills/productivity`）的配置仓库：工作区维护完整 skill 集合，其中一部分 proprietary skill 只供本仓库使用；`template/` 只包含可分发内容，以 npm 包 `@heihei0299/matt-skills` 分发，目标仓库一条命令即完成初始化。
3
+ 面向项目仓库的 Agent skills 与配置模板。模板包含共享 skills、`AGENTS.md`、项目上下文占位文件，以及 pi / opencode 所需的项目配置。
4
4
 
5
- ## 模板结构
5
+ ## 模板内容
6
6
 
7
- ```
7
+ ```text
8
8
  template/
9
- ├── AGENTS.md 项目级全局配置（行为路由 + 分文件指针）
10
- ├── .agents/
11
- │ └── skills/ workspace 的完整 skill 单一源；template 只携带可分发 skill，默认安装 programming 范围，--all 展开全部可分发 skill
12
- ├── .pi/ pi-agent 项目配置
13
- │ ├── skills/ 空占位（项目自定义技能，含 .gitkeep + README.md）
14
- │ ├── prompts/ issue-audit 命令（prompt template）
15
- │ ├── docs/agents/ 5 个分文件镜像
16
- │ └── CONTEXT.md 术语表镜像
17
- └── .opencode/ opencode 项目配置
18
- ├── skills/ 空占位（项目自定义技能，含 .gitkeep + README.md）
19
- ├── agents/ issue-audit 子代理定义
20
- ├── commands/ issue-audit + 可分发的显式触发技能命令（grill-to-spec/wayfinder/to-spec/to-tickets/triage/improve-codebase-architecture/teach/handoff/writing-for-agents）
21
- ├── docs/agents/ 5 个分文件（运行时纪律 / 技能设计 / issue tracker / triage labels / domain）
22
- ├── CONTEXT.md 术语表
23
- ├── package.json 插件依赖清单
24
- └── .gitignore
9
+ ├── AGENTS.md Agent 行为路由与项目上下文入口
10
+ ├── PROJECT.md 目标项目填写的目标、范围和主要入口
11
+ ├── .agents/skills/ 共享 skills 的唯一项目级来源
12
+ ├── .opencode/ opencode agents、commands、docs
13
+ └── .pi/ pi prompts、docs 与项目自定义 skills 占位
25
14
  ```
26
15
 
16
+ - `PROJECT.md` 描述项目是什么；操作规则放在 `AGENTS.md`。
17
+ - `.opencode/CONTEXT.md` / `.pi/CONTEXT.md` 保存领域术语与边界。
18
+ - `.opencode/skills/` 与 `.pi/skills/` 仅用于项目自定义 skills。
19
+ - `ci-guard`、`commit-check` 是本仓库维护用的 repo-local skills，不会分发到目标项目。
20
+
27
21
  ## 独有 skill 分发边界
28
22
 
29
- 本仓库维护 7 个独有（proprietary）skill：
23
+ 本仓库有 7 个独有（proprietary）skills：
30
24
 
31
25
  ### 可分发的 5 个
32
26
 
@@ -36,194 +30,95 @@ template/
36
30
  - `scaffold-functional-test`
37
31
  - `show-me`
38
32
 
39
- 默认 programming 范围中的 4 个独有 skill 是 `tdd-implement`、`diagnose-fix`、`grill-to-spec`、`show-me`；`scaffold-functional-test` 可分发但默认可选。
40
-
41
33
  ### 仓库内部的 2 个
42
34
 
43
35
  - `ci-guard`
44
36
  - `commit-check`
45
37
 
46
- `ci-guard` 和 `commit-check` 只服务 matt-skills 仓库自身，不会通过 `list`、`install`、`init`、`sync`、`--all` 或 global install 分发到用户项目。workspace 保留完整集合，template 只包含可分发集合。
38
+ repo-local skills 不会通过 `init`、`install`、`sync` 分发到用户项目。
47
39
 
48
40
  ## 初始化
49
41
 
50
- 在目标仓库根目录执行一条命令：
42
+ 在目标仓库根目录执行：
51
43
 
52
44
  ```sh
53
- npx @heihei0299/matt-skills init # 默认 programming 范围
54
- npx @heihei0299/matt-skills init --all # 安装全部可分发 skill（含 productivity）
45
+ npx @heihei0299/matt-skills init # 安装默认 programming skills
46
+ npx @heihei0299/matt-skills init --all # 安装全部可分发 skills
55
47
  ```
56
48
 
57
- `init` 默认只在目标没有 `AGENTS.md` 时初始化；已有项目默认跳过以保护定制，显式 `init --all` 会刷新模板并安装/覆盖全部可分发 skill。模板已经包含可分发内容，无需二次拉取上游；repo-local skill 不会进入目标项目。
58
-
59
- 选项：`--dest <path>` 指定目标目录（默认当前目录）；`--all` 包含全部可分发的非默认 skill（包括 productivity 和 optional proprietary）；已有目标使用 `init --all` 刷新，普通 `init` 跳过。
60
- **增量同步（已有项目）**：已有项目更新到最新模板与技能：
49
+ 已有项目同步：
61
50
 
62
51
  ```sh
63
- npx @heihei0299/matt-skills sync # 默认安全增量：同步默认 programming skill（不删多余）
64
- npx @heihei0299/matt-skills sync --all # 同步全部可分发 skill（不删多余）
65
- npx @heihei0299/matt-skills sync --dry-run --json # 预演：只比对不写盘（默认范围，--all 可透传）
66
- npx @heihei0299/matt-skills sync --dest <path> --upstream <url> --ref <ref> --json # 选项可组合
52
+ npx @heihei0299/matt-skills sync # 安全增量同步默认范围
53
+ npx @heihei0299/matt-skills sync --all # 同步全部可分发 skills
54
+ npx @heihei0299/matt-skills sync --dry-run --json
67
55
  ```
68
56
 
69
- `sync` 专为已有项目设计，两档语义：写盘模式下默认同步默认 programming 范围，`--all` 同步全部可分发 skill；`--dry-run` 仅对比上游、不写盘，默认比较 engineering + required 的上游部分，`--all` 比较全量上游范围，打印“上游 HEAD / 本地非独有 vs 上游 / 新增/更新/删除/一致”表，`--json` 可解析，有差异 `exit 1`。上游 dry-run/check 不比较 proprietary，因为它们不属于上游；默认安全增量写盘不删多余，模板配置增量更新，旧镜像中的共享 skill 自动清理但保留项目自定义。repo-local skill 永远不新增、不覆盖、不删除，发现历史副本时只提示保留。`--dest`、`--upstream`、`--ref`、`--json`、`--all`、`--dry-run` 可透传。
70
- 目标仓库会话即自动加载可分发共享技能（`.agents/skills/` 单一源）与项目级全局配置（行为路由表、分文件约定）；项目自定义技能可按需放入 `.pi/skills/` 或 `.opencode/skills/`（按 harness 自动发现）；`issue-audit` 以子代理 + 命令形式分发（`.opencode/agents/`、`.opencode/commands/`）；可分发的显式触发技能注册为 opencode 命令（`.opencode/commands/`，`/命令名` 触发）。
71
- **pi-agent 用户**：初始化命令完全相同。pi 从 `.agents/skills/` 自动发现全部可分发共享技能，无需额外指向；`.pi/skills/` 仅用于项目自定义。首次在目标仓库交互启动时 pi 会询问项目信任，用 `/trust` 保存即可。
72
-
73
- **手动方式（备选）**：无 npx 环境时，将 `template/` 整个文件夹复制到目标仓库根目录即可（已含全部可分发 skill）：
57
+ `init` 默认保护已有 `AGENTS.md`；需要刷新完整模板时使用 `init --all`。`sync` 不删除目标项目的额外文件或自定义 skills。
74
58
 
75
- ```sh
76
- cp -r template/. /path/to/target/
77
- ```
59
+ 默认 programming 范围中的 4 个独有 skills 是 `tdd-implement`、`diagnose-fix`、`grill-to-spec`、`show-me`。
78
60
 
79
- 旧的手动拉取上游步骤已不再需要；若需单独验证上游，仍可：
61
+ ## CLI
80
62
 
81
63
  ```sh
82
- git clone --depth 1 https://github.com/mattpocock/skills.git /tmp/mattpocock-skills
64
+ npx @heihei0299/matt-skills list [--all] [--json]
65
+ npx @heihei0299/matt-skills install [--all] [--tools <list>] [--global] [--dest <dir>]
66
+ npx @heihei0299/matt-skills init [--all] [--dest <dir>]
67
+ npx @heihei0299/matt-skills sync [--all] [--dry-run] [--json] [--dest <dir>]
68
+ npx @heihei0299/matt-skills check [--all] [--json] [--upstream <url>] [--ref <ref>]
83
69
  ```
84
70
 
85
- ## 维护约定
86
-
87
- 改动工作区后，必须同步到 `template/` 对应路径，路径映射如下（同步方向单向：工作区 → 模板快照）：
88
-
89
- | 工作区 | 模板 |
90
- |--------|------|
91
- | `.agents/skills/`（workspace 完整 skill 集合：upstream + proprietary） | `template/.agents/skills/`（仅可分发 skill） |
92
- | `.agents/skills/` 的 harness 占位说明 | `template/.pi/skills/.gitkeep` + `README.md`、`template/.opencode/skills/.gitkeep` + `README.md`（空目录占位，供项目自定义） |
93
- │ │ ├── commands/ issue-audit + 可分发的显式触发技能命令（grill-to-spec/wayfinder/to-spec/to-tickets/triage/improve-codebase-architecture/teach/handoff/writing-for-agents）
94
- | `.pi/prompts/issue-audit.md`（pi 命令：opencode 版适配，去 subagent frontmatter） | `template/.pi/prompts/issue-audit.md` |
95
- | `AGENTS.md` | `template/AGENTS.md`（引用映射为 `.opencode/` 路径） |
96
- | `CONTEXT.md` | `template/.opencode/CONTEXT.md` + `template/.pi/CONTEXT.md` |
97
- | `docs/agents/*` | `template/.opencode/docs/agents/*` + `template/.pi/docs/agents/*`（引用映射为 `.opencode/` 路径） |
98
-
99
- 共享技能统一在 `.agents/skills` 单一源，不再双份镜像到 `.opencode/skills` / `.pi/skills`。
100
- `test/template-sync.test.js` 守护同步（含路径映射），漏同步测试即红。
71
+ 常用选项：
101
72
 
102
- 新增技能前先查上游 `mattpocock/skills` 是否已存在；仅上游没有的技能才作为 proprietary skill 落在本仓库。Proprietary skill 再分为 distributable 和 repo-local：后者只服务本仓库，不进入 template 或任何用户安装路径。上游技能通过 `scripts/sync-upstream.js` 同步到 `.agents/skills` 后，只有可分发内容会进入模板。
103
-
104
- ## harness 支持
105
-
106
- 模板同时面向 opencode 与 pi-agent 两种 harness：技能（Agent Skills 标准）与 `AGENTS.md` 行为路由跨 harness 通用，同一份配置两处均可运行。
107
-
108
- 以下为 opencode 专属能力，**pi 下不可用**（不移植，仅文档注明）：
109
-
110
- - `issue-audit`：opencode 以 subagent + command 形式分发（`.opencode/agents/`、`.opencode/commands/`）；pi 无 subagent 机制，以 prompt template 命令分发（`.pi/prompts/issue-audit.md`，去 subagent 委托、保留完整审计流程）
111
- - codegraph MCP：`opencode.jsonc` 配置的代码图服务，pi 无原生 MCP
112
- - `explore` 子代理、`firecrawl` 网页抓取：opencode 会话能力
113
-
114
- pi 下对应能力以内置工具或已装扩展为准（`AGENTS.md`「能力边界」已按此表述）。
73
+ - `--all`：包含全部可分发 skills，默认范围只包含 programming skills。
74
+ - `--dest <dir>`：指定目标目录。
75
+ - `--tools <list>`：选择 `codex`、`pi`、`opencode` 或 `claude`；项目级共享 skills 统一写入 `.agents/skills/`。
76
+ - `--global`：写入用户级 skills 目录。
77
+ - `--dry-run`：只检查差异，不写入；`--json` 输出机器可读结果。
115
78
 
116
79
  ## Codex CLI 支持
117
80
 
118
- 本仓库将 Codex CLI 作为一等本地 harness 支持。Codex 与 pi、opencode、Claude 共用项目级 `.agents/skills/`，项目级 `AGENTS.md` 继续作为通用行为路由和约束入口。
119
-
120
- - **项目级技能**：`.agents/skills/`（唯一共享源）
121
- - **全局技能**：`~/.codex/skills/`
122
- - **不创建**：项目级 `.codex/skills/` 副本；Codex 技能不单独分叉
123
- - **安装映射**：`--tools codex` 使用 `.agents/skills/`，`--global --tools codex` 使用 `~/.codex/skills/`
124
-
125
- 使用真实 Codex CLI 验证支持：
126
-
127
- ```sh
128
- npm run codex:smoke # 默认 SKIP，不需要 Codex 凭证
129
- CODEX_E2E=1 npm run codex:smoke # 显式运行真实 smoke test
130
- ```
131
-
132
- 真实 smoke test 使用临时 fixture、ephemeral 会话、read-only sandbox 和 JSONL 输出，验证 `AGENTS.md` 与最小 `codex-probe` skill 的 sentinel。结果分为 `PASS`、`SKIP`、`FAIL_ENV` 和 `FAIL_CONTRACT`；环境问题与契约失败分别返回非零退出码。运行结果会记录 `codex --version`，但不绑定最低 CLI 版本。
133
-
134
- 本期不包含 Codex Cloud、Codex-specific commands、plugins 或 MCP 配置。
135
- ## harness 目录结构
136
-
137
- 两个 harness 的技能加载目录结构如下（本项目只分发项目级目录，全局目录由用户自备）：
138
-
139
- ### pi-agent
140
-
141
- - **全局**：`~/.pi/agent/skills/`、`~/.agents/skills/`（用户级技能，自动发现）；配置在 `~/.pi/agent/settings.json`
142
- - **项目**：
143
- - `.agents/skills/` — 可分发共享技能单一源（默认 programming，`--all` 全部可分发，自动发现）
144
- - `.pi/skills/` — 项目自定义技能（pi 标准结构，自动发现，仅放项目本地技能）
145
- - `.pi/prompts/` — pi 命令（prompt template）自动发现，如 `issue-audit.md` → `/issue-audit`
146
- - `.pi/settings.json` — 已简化为空对象（历史指向 `.opencode/skills` 已移除，共享技能走 `.agents/skills`）
147
- ### opencode
148
-
149
- - **项目**：`.agents/skills/`（可分发共享技能单一源，默认 programming，`--all` 全部可分发）、`.opencode/skills/`（项目自定义技能）、`.opencode/agents/`（子代理）、`.opencode/commands/`（命令：issue-audit + 可分发显式触发技能，`/命令名` 触发）、`.opencode/docs/`（文档）
150
-
151
- 同一份技能（Agent Skills 标准）与 `AGENTS.md` 行为路由在两种 harness 下均可加载：pi 与 codex/claude 从 `.agents/skills/` 自动发现；opencode 按本模板约定同样优先读取 `.agents/skills/`（`.opencode/skills/` 仅用于项目自定义）。
152
-
153
- ## 仓库 CLI
154
-
155
- 仓库内提供安装管理 CLI（`bin/cli.js`，依赖 `prompts`，见 `package.json`），同时作为 npm 包 `@heihei0299/matt-skills` 分发（`npx @heihei0299/matt-skills <command>`）：
81
+ Codex 与其他 harness 共用项目级 `.agents/skills/` 唯一共享源；全局 skills 位于 `~/.codex/skills`。
156
82
 
157
83
  ```sh
158
- node bin/cli.js init [--dest <dir>] [--all] # 初始化项目：默认 programming 或全部可分发 skill
159
- node bin/cli.js sync [--all] [--dry-run] [--dest <path>] [--upstream <url>] [--ref <ref>] [--json] # 同步已有项目到最新（默认编程，--all 仅同名 upsert + AGENTS.md）
160
- node bin/cli.js list [--json] [--all] # 列出技能（默认编程）
161
- node bin/cli.js install [选项] # 把技能复制到目标工具目录（交互式选择，默认编程）
162
- node bin/cli.js check [--json] [--all] [--upstream <url>] [--ref <ref>] # 只读检查上游技能是否最新（等价 sync --dry-run，默认范围）
84
+ npm run codex:smoke
85
+ CODEX_E2E=1 npm run codex:smoke
163
86
  ```
164
87
 
165
- `init` 选项：`--dest <path>` 指定目标目录（默认当前目录）；`--all` 包含全部可分发 skill，见「初始化」。
166
- `sync` 选项：写盘时 `--all` 更新全部可分发同名技能内容（存在则覆盖，不存在则新增）并更新 `AGENTS.md`（不跳过定制），不删多余；默认写盘只同步默认 programming；`--dry-run` 只比对上游、不写盘（默认 engineering + required 上游范围，`--all` 为全量上游范围，`--json` 可解析，有差异 `exit 1`）；`--dest <path>` 目标目录；`--upstream <url>` 上游地址；`--ref <ref>` 上游分支；`--json` JSON 输出；默认安全增量会保留目标定制。
167
- `check` 选项：`--json`、`--all`（默认只比较 engineering + required 上游范围；proprietary 不参与上游 compare）、`--upstream <url>`、`--ref <ref>`（等价 `sync --dry-run`）。
168
-
169
- `install` 选项：
88
+ 本项目不包含 Codex Cloud、Codex 专用 commands、plugins 或 MCP 配置。
170
89
 
171
- - `--dest <dir>`：复制到指定目录（覆盖工具映射）
172
- - `--tools <t1,t2>`：指定工具，项目级已统一 `codex/pi/opencode/claude → .agents/skills`（共享技能单一源，`.pi/skills`/`.opencode/skills` 仅用于项目自定义）
173
- - `--global`：安装到全局目录（`~/.codex/skills`、`~/.pi/agent/skills`、`~/.config/opencode/skills`、`~/.claude/skills`）；`--project` 回到项目级
174
- - `--all`：安装全部可分发 skill（交互勾选时默认只列 programming 范围）；`--force`：覆盖已存在的技能
90
+ ## 上游同步
175
91
 
92
+ 非独有 skills 来自 [mattpocock/skills](https://github.com/mattpocock/skills)。
176
93
 
177
- ### 上游同步（自动更新）
178
-
179
- 本仓库的 `.agents/skills/` 中 **非独有技能** 来自 `mattpocock/skills` 上游。已实现双通道自动同步：
180
-
181
- - **本地 CLI**：`matt-skills sync` 两档——`--dry-run` 只读比对（有差异 `exit 1`，`--json` 可解析）、默认安全增量与 `sync --all` 仅同名 upsert + `AGENTS.md`；`matt-skills check [--json] [--upstream <url>] [--ref <ref>]` 为只读别名（等价 `sync --dry-run`）；`matt-skills update` 已合并到 `sync`（执行提示 `update 已合并到 sync` 且 `exit 1`）
182
94
  ```sh
183
- npx @heihei0299/matt-skills sync --dry-run --json # 预演只读检查，JSON 输出：{ head, counts, result: { added, updated, renamed, removed, same } }
184
- npx @heihei0299/matt-skills sync # 默认安全增量（AGENTS.md 定制跳过，默认 programming）
185
- npx @heihei0299/matt-skills sync --all # 仅同名 upsert + AGENTS.md
186
- npx @heihei0299/matt-skills check --json # 等价 sync --dry-run
187
- node scripts/sync-upstream.js --check # 等价底层脚本（CLI sync/check 的实现）
188
- node scripts/sync-upstream.js --apply --dry-run
95
+ npx @heihei0299/matt-skills sync --dry-run --json # 检查上游差异
96
+ npx @heihei0299/matt-skills sync # 同步默认范围
97
+ npx @heihei0299/matt-skills sync --all # 同步全部可分发范围
189
98
  ```
190
99
 
191
- 实现细节：`scripts/sync-upstream.js` 为单一事实源（CLI 与 Actions 共用），以 proprietary 分类契约排除本仓库独有 skill，以 `config/engineering.json` 为编程白名单，以 `config/required.json` 为独有所需白名单；上游通过 `git clone --depth 1 https://github.com/mattpocock/skills.git` 获取，比对 `SKILL.md` 的 sha256，自动处理新增/更新/重命名/删除。上游同步只维护 workspace，模板生成时再按 distributable 边界投影。
192
- 上游重命名映射：`RENAMES = { "writing-great-skills": "writing-for-agents" }`，Actions/CLI 均会删除旧目录并复制新目录。
193
100
  ## 发布
194
101
 
195
- 推送 `v*` 标签自动发布到 npm（GitHub Actions，见 `.github/workflows/ci.yml`）：
102
+ 推送 `v*` 标签会触发 GitHub Actions：全量测试、模板检查和 npm 发布。
196
103
 
197
104
  ```sh
198
- # 1. 确保 main 分支为最新且测试全绿
199
- git checkout main && git pull
200
105
  npm test
201
-
202
- # 2. 打标签并推送（标签即版本，v 前缀自动去除）
203
- git tag v1.0.1
204
- git push origin v1.0.1
205
- ```
206
-
207
- Action 流程：`checkout` → 校验标签在 `main` 分支 → `Node 24` → `npm ci` → `npm test` 全绿 → 以标签为准 `npm version <tag> --no-git-tag-version` → `npm publish --access public`（需在 GitHub Secrets 配置 `NPM_TOKEN`）。
208
-
209
- 本地手动发布（备选）：
210
-
211
- ```sh
212
- npm version <patch|minor|major>
213
- npm publish
106
+ npm run build:template
107
+ git tag vX.Y.Z
108
+ git push origin main vX.Y.Z
214
109
  ```
215
110
 
216
- - `prepublishOnly` 自动跑全量测试（`node --test test/*.test.js`）
217
- - 发布内容 = `bin/` + `template/` + `.agents/skills/` + `scripts/` + `config/` + `README.md`，由 `package.json` 的 `files` 白名单控制，`npm pack` 可预览
218
- - `template/` 与 `.agents/skills/` 是包内容：改动后需重新发版才对目标仓库生效
111
+ 发布需要 GitHub Secrets 中配置 `NPM_TOKEN`。模板或共享 skills 的改动需要新版本才会分发给目标项目。
219
112
 
220
113
  ## 开发
221
114
 
222
115
  ```sh
223
- npm test # 全量测试
224
- npm run build:template # 从 workspace 生成仅含可分发 skill 的 template + 空占位
116
+ npm test
117
+ npm run build:template
225
118
  ```
226
119
 
227
- 交互模式依赖 `prompts`（见 `package.json`）；测试见 `test/cli.test.js`、`test/cli-init.test.js`、`test/template-sync.test.js`。
120
+ 测试位于 `test/`；模板由 `scripts/build-template.js` 从工作区生成，提交前应确保模板同步测试通过。
121
+
122
+ ## 许可证
228
123
 
229
- 用户手动触发的功能测试：`/instance-test`（matt-skills 专属示范，见 `.agents/skills/instance-test/SKILL.md`）——验证 sync 合并 update 后的行为，`references/instances.md` 由 `scaffold-functional-test` 从 spec 生成；通用模板已废弃。新增生成器 `/scaffold-functional-test`（见 `.agents/skills/scaffold-functional-test/SKILL.md`）——读 spec 生成定制化功能测试 skill。
124
+ MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@heihei0299/matt-skills",
3
- "version": "2.1.5",
3
+ "version": "2.1.7",
4
4
  "description": "Agent skills + 项目配置模板：一条命令初始化 opencode / pi-agent 项目（含 mattpocock/skills 上游技能）",
5
5
  "type": "module",
6
6
  "bin": {
package/template/.agents/skills/grill-to-spec/SKILL.md CHANGED
@@ -6,42 +6,50 @@ disable-model-invocation: true
6
6
 
7
7
  # Grill to Spec
8
8
 
9
- 只做两个上游 skill 的编排：先把想法打磨成共识，再把共识发布成 spec。本 skill 不写代码、不修改源码或测试。
9
+ 只做两个上游 skill 的编排：先把想法打磨成共识，再把共识发布成 spec。本 skill 不写代码、不修改源码或测试、不自动 commit。
10
10
 
11
11
  ## 流程
12
12
 
13
+ ### 0. 预检
14
+
15
+ - 只读确认 issue tracker、目标上下文、feature slug 和已有 spec/issue 状态。
16
+ - tracker 未配置、slug 不明确或目标路径不可写时，在任何 ADR/spec/issue 写入前报告阻塞。
17
+ - 已有同一 feature 的产物先读取并比较；相同共识不重复发布，设计变化进入变更流程。
18
+
13
19
  ### ① 形成共识
14
20
 
15
21
  调用 [`grill-with-docs`](.agents/skills/grill-with-docs/SKILL.md)，由 `grilling` 与 `domain-modeling` 完成采访、术语和设计决策。
16
22
 
17
23
  - glossary 按上游规则 inline 更新；
18
- - 只有确需 ADR 时才创建 ADR；
19
- - 决策共识形成后直接写入 ADR，不向用户展示 ADR 正文，不增加单独确认轮次。
24
+ - 只有同时满足 ADR 条件时才提出 ADR，但 ADR 等最终决策清单确认后再写入；
25
+ - 在本阶段让 [`to-spec`](.agents/skills/to-spec/SKILL.md) 做代码理解和 seam 分析；seam 是共识的一部分，不单独制造发布确认；
26
+ - 形成精简决策清单：目标、范围、关键选择、seam、未纳入范围和待验证假设；只展示清单，不展示任何 ADR/spec/issue 正文或草稿；
27
+ - 用户确认决策清单后，立即进入阶段 ②。
20
28
 
21
- 出口：用户确认共识已达成，且已确定的 glossary/ADR 已写入。
29
+ 出口：决策清单已确认，glossary 已按需更新；尚未确认的 ADR/spec/issue 不写入。
22
30
 
23
31
  ### ② 发布 spec
24
32
 
25
- 将已确认的共识交给 [`to-spec`](.agents/skills/to-spec/SKILL.md)，完成代码库理解、seam 提案和 spec 组装。
33
+ 将已确认的决策清单和 seam 分析交给 `to-spec`；此处只综合、写入和发布，不重新采访或再次确认 seam。
26
34
 
27
- - 将 seam 提案作为共识的一部分确认，不展示由此生成的文档正文；
28
- - 共识（含 seam）达成后，直接写入/发布 spec 与 issue，不设置发布前确认；
29
- - 发布时使用 `ready-for-agent`，格式细则只读取 [`references/rules.md`](references/rules.md)。
35
+ - 按 ADR → spec → issue 的顺序执行；issue 发布成功后设置 `ready-for-agent`；格式细则只读取 [`references/rules.md`](references/rules.md)。
36
+ - 相同 feature 复用已有产物，设计变化按 tracker 的更新语义保留历史；
37
+ - 任一步失败都保留已成功写入的内容，记录状态和失败点，重跑时从第一个未完成出口继续；不回滚、不重复发布。
30
38
 
31
- 出口：spec/issue 已写入或发布，只报告路径或标识、状态和未纳入范围。
39
+ 出口：ADR/spec/issue 已写入或发布，只报告路径或标识、状态和未纳入范围，不复制正文。
32
40
 
33
41
  ## 回合连续性
34
42
 
35
- 本 skill 是 Long-Horizon Skill。阶段 ① 达到出口后立即进入阶段 ②；正常的阶段切换、进度汇报或“接下来生成 spec”不是回合终点。仅在必须获得用户确认的设计问题、明确外部阻塞、用户主动停止或整个 skill 出口时暂停。文档写入/发布不另起确认回合，不要求用户额外回复“继续”。
43
+ 本 skill 是 Long-Horizon Skill。预检、阶段 ①、代码理解、决策清单确认后的阶段 ② 在同一任务链连续执行；进度汇报和阶段切换不是回合终点。仅在需要设计确认、决策清单确认、外部阻塞、用户主动停止或整个 skill 出口时暂停；确认完成后不要求用户额外回复“继续”。
36
44
 
37
45
  ## 本 skill 独有门禁
38
46
 
39
- - ADR：决策共识 → 直接落盘，不展示正文、不设置独立确认；
40
- - spec/issue：共识与 seam 达成后直接写入/发布，不展示正文、不设置发布前确认；
41
- - 全程不写代码、不修改测试、不执行实现。
47
+ - 文档正文永不展示；用户只确认精简决策清单，发布后只接收元数据报告；
48
+ - ADR/spec/issue 不设置额外草稿确认；
49
+ - 不写代码、不修改源码或测试、不自动 commit；实现 tickets 交给 `to-tickets`。
42
50
 
43
51
  ## 异常
44
52
 
45
53
  - 用户放弃或没有可形成 spec 的主题时终止；
46
54
  - issue tracker 未配置时报告配置阻塞，不绕过发布；
47
- - 用户改变已确认的设计时回到 ①，不在 ② 静默扩大范围。
55
+ - 用户改变已确认设计时回到阶段 ①，按变更语义保留历史，不静默覆盖。
package/template/.agents/skills/grill-to-spec/references/rules.md CHANGED
@@ -2,29 +2,43 @@
2
2
 
3
3
  本文件只保存 `grill-to-spec` 相对上游 `grill-with-docs` / `to-spec` 的**增量约束**。Spec 的章节、User Story 形状、Implementation Decisions 等格式全部以 `to-spec` 为唯一事实源，本文件不复制上游模板。
4
4
 
5
+ ## 预检与状态规则
6
+
7
+ - 写入前只读确认 issue tracker、目标上下文、feature slug、已有 spec/issue 和当前状态；tracker 未配置或目标不可写时不写 ADR/spec/issue。
8
+ - feature slug 是 spec 路径和 issue 幂等键；候选不明确或冲突时才询问。
9
+ - 记录共识、ADR、spec、issue、`ready-for-agent` 出口；重跑从第一个未完成出口继续，不重复已成功动作。
10
+ - 已有相同共识的 feature 只报告已有路径或标识；设计变化走变更流程，不创建重复 issue。
11
+
5
12
  ## Glossary 增量规则
6
13
 
7
14
  - 懒创建：首个术语解析时才建 `CONTEXT.md`；多上下文时先确认归属，归属不清则询问。
8
15
  - 只收本上下文特有术语；定义 WHAT 非 HOW，避免把 glossary 变成实现草稿。
9
- - glossary 可按上游流程 inline 更新，不额外增加确认轮次。
16
+ - glossary 可按上游流程 inline 更新，不额外增加确认轮次；设计变化时按历史保留规则修正。
10
17
 
11
18
  ## ADR 增量规则
12
19
 
13
20
  - 只有同时满足“难逆转 / 无上下文费解 / 存在真实权衡”时才提议 ADR。
14
- - 决策共识形成后直接落盘；不向用户展示 ADR 正文，不增加独立确认轮次。
15
- - 不把 ADR 当 glossary 一样静默 inline 更新。
21
+ - ADR 不像 glossary 一样静默 inline 更新；等最终决策清单确认后直接落盘，不展示正文，不增加独立确认轮次。
22
+ - 用户改变决策时不静默覆盖旧 ADR；按项目 ADR 规则追加、废弃或标记 superseded。
16
23
 
17
24
  ## Spec 增量规则
18
25
 
19
26
  - Spec 的结构与字段全部委托 `to-spec`，本文件不维护第二份模板。
20
- - seam 提案作为共识的一部分确认，不展示由此生成的 spec 正文。
21
- - 共识（含 seam）达成后直接写入并标记 `ready-for-agent`，不设置发布前确认。
27
+ - 代码理解和 seam 分析属于共识阶段；seam 纳入最终决策清单，不在发布阶段再次询问。
28
+ - 决策清单确认后直接写入 spec；不展示 spec 正文或草稿。
22
29
  - 全文沿用已经确认的 glossary 词汇，并尊重所触区域既有 ADR。
23
30
 
24
31
  ## Issue 增量规则
25
32
 
26
- - 按已配置的 issue tracker 直接发布 issue；issue 正文不在对话中展示。
27
- - 发布后只报告 issue 标识、状态和未纳入范围，不复制正文。
33
+ - 按已配置的 issue tracker 直接发布唯一 spec issue；implementation tickets 交给 `to-tickets`。
34
+ - issue 正文不在对话中展示；发布成功后设置 `ready-for-agent`。
35
+ - issue 创建成功但 label/status 更新失败时保留 issue，报告标识和失败点，不删除、不误报为 ready。
36
+ - 设计变化委托 tracker 的原生更新语义：本地追加变更记录，远端按 body/comment/关联关系更新；不另造版本模板。
37
+
38
+ ## 失败与 Git 边界
39
+
40
+ - 任一步失败都保留已成功写入的内容并报告部分状态；不做跨文件或跨 tracker 回滚，不盲目重试。
41
+ - 本 skill 不自动创建 Git commit；发布文档与 Git 提交是两个独立出口。
28
42
 
29
43
  ## 反模式
30
44
 
package/template/.opencode/commands/grill-to-spec.md CHANGED
@@ -9,5 +9,5 @@ description: 编排 grill-with-docs → to-spec，把设计打磨成共识并发
9
9
  **主题：** $ARGUMENTS
10
10
 
11
11
  - 只编排与产出：设计打磨成共识 → 综合成 spec 发布，不写代码、不动源码
12
- - 产出物限：领域文档（glossary/ADR）与 spec
12
+ - 产出物限：领域文档（glossary/ADR）与一份 spec issue，不拆 implementation tickets
13
13
  - 共识达成后直接写入/发布 ADR、spec 与 issue，不向用户展示正文；只报告路径或标识、状态和范围摘要
package/template/AGENTS.md CHANGED
@@ -11,6 +11,13 @@
11
11
  * 领域建模 → `domain-modeling`
12
12
  * 无法归类 → `ask-matt`
13
13
  \仅当关键歧义会改变结果时询问用户。
14
+
15
+ ## 项目上下文
16
+ 开始任务前按需读取：
17
+ - `PROJECT.md`（若存在）：项目目标、范围和主要入口
18
+ - `README.md`（若存在）：用户视角的使用与开发说明
19
+ - `.opencode/CONTEXT.md`（若存在）：领域术语与边界
20
+
14
21
  ## CodeGraph
15
22
  仓库内代码理解首先使用：
16
23
  ```bash
package/template/PROJECT.md ADDED
@@ -0,0 +1,3 @@
1
+ # Project Context
2
+
3
+ <!-- 请在目标仓库中填写项目目标、范围、主要入口和关键约束。代理操作规则放在 AGENTS.md。 -->