@heihei0299/matt-skills 3.0.23 → 3.0.27

package/.agents/skills/initialize-project/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: initialize-project
+description: "Initialize a target repository's agent context by deriving stable project facts, updating AGENTS.md with a compact six-part context block, and writing detailed PROJECT.md context."
+disable-model-invocation: true
+---
+
+# Initialize Project
+
+显式调用本 skill，在目标项目根目录初始化或刷新项目上下文。先读取事实，再写文件；不凭目录名、包名或猜测补全项目目标。
+
+## 1. 收集事实
+
+读取能说明项目真实行为的版本化材料：
+
+- `README.md`、现有 `AGENTS.md`、`PROJECT.md`、`CONTEXT.md` 和相关文档
+- `package.json`、其他 manifest、构建/运行配置
+- 根目录和主要源码目录，定位架构边界、入口、关键职责
+- 测试目录、测试配置和 CI 配置，确认测试规则与稳定命令
+
+优先记录稳定且代理需要知道、但不能从一次查找直接得出的事实。不要把完整命令清单、依赖清单、动态路线图或重复的通用规则写进 `PROJECT.md`。若项目用途、范围、入口或六项内容无法从仓库确认，一次性向用户询问缺失事实后再写入。
+
+文档语言跟随目标仓库的主要语言；没有明确语言信号时跟随用户语言。保留现有文档的其他内容。
+
+## 2. 更新 `AGENTS.md`
+
+维护唯一的受管区块，使用以下标记：
+
+```md
+<!-- matt-skills:managed:start -->
+## 项目上下文
+### 架构边界
+见 `PROJECT.md` 的“架构边界”。
+### 仓库地图
+见 `PROJECT.md` 的“仓库地图”。
+### 标准命令
+见 `PROJECT.md` 的“标准命令”。
+### 测试规则
+见 `PROJECT.md` 的“测试规则”。
+### 项目约束
+见 `PROJECT.md` 的“项目约束”。
+### 完成标准
+见 `PROJECT.md` 的“完成标准”。
+<!-- matt-skills:managed:end -->
+```
+
+- 六个 `###` 标题必须按 `架构边界`、`仓库地图`、`标准命令`、`测试规则`、`项目约束`、`完成标准` 顺序出现。
+- 受管区块总行数必须不超过 30 行；只写简要规则或 `PROJECT.md` 指针，详细事实只放 `PROJECT.md`。
+- 已有完整标记区块时原位替换；没有时追加到文件末尾；不得重排、覆盖或改写其他内容。
+- `AGENTS.md` 不存在时，优先复制目标项目的 `template/AGENTS.md`，再追加区块；模板不可用时创建最小 `AGENTS.md`，只包含该区块。
+- 无论项目是否存在 `CLAUDE.md`，初始化状态和项目上下文都固定维护在 `AGENTS.md`。
+
+## 3. 更新 `PROJECT.md`
+
+维护 `PROJECT.md` 专用受管标记（不要与 `AGENTS.md` 的 CLI 受管标记混用）：
+
+```md
+<!-- initialize-project:start -->
+## 项目概览
+### 项目用途
+### 项目范围
+### 主要入口
+### 架构边界
+### 仓库地图
+### 标准命令
+### 测试规则
+### 项目约束
+### 完成标准
+<!-- initialize-project:end -->
+```
+
+将每个标题填成基于仓库事实的详细说明：
+
+- **项目用途**：解决的问题、服务对象和预期结果。
+- **项目范围**：负责的能力，以及仓库明确排除的范围；没有证据就不臆造非目标。
+- **主要入口**：用户入口、应用/包入口和代理应先看的文档或目录。
+- **架构边界**：模块职责、依赖方向、外部系统边界和不可跨越的层次边界。
+- **仓库地图**：关键目录及其职责；只列影响代理决策的稳定目录。
+- **标准命令**：少量最常用且稳定的开发、验证或发布入口；命令的完整来源仍以 manifest 和配置为准。
+- **测试规则**：测试位置、测试层级、命名/运行约定，以及失败时必须保留的证据。
+- **项目约束**：运行时、兼容性、安全、生成文件、依赖或发布方面的明确约束。
+- **完成标准**：实现、验证、文档、工作区或提交范围方面的交付要求。
+
+`PROJECT.md` 不存在时创建标题 `# Project Context` 后写入区块。已存在且含完整标记时只替换标记内内容；已存在但没有标记时在末尾追加区块，不覆盖自由格式内容。若标记不成对，停止写入并报告，避免破坏文档。不得生成空章节、`TBD` 或未经确认的事实。
+
+## 4. 完成检查
+
+写入后确认：
+
+- `AGENTS.md` 区块只有一份，六个标题顺序正确且总行数不超过 30 行。
+- `PROJECT.md` 区块只有一份，九个章节均有事实内容，且其他内容未改变。
+- 第二次运行会原位替换而不是追加重复内容。
+- 只修改目标 `AGENTS.md`/`PROJECT.md` 和本 skill 需要的文件；不创建备份或额外模板资源。

package/.agents/skills/research/SKILL.md

@@ -7,6 +7,18 @@ Spin up a **background agent** to do the research, so you keep working while it
 
 Its job:
 
+Before fetching remote pages, stage source ingestion:
+
+- Discover/search candidate sources.
+- Rank candidates by first-party authority and relevance.
+- Fetch only the 1–2 strongest sources initially; use a targeted page or section when supported.
+- Inspect those results and identify the remaining uncertainty.
+- Fetch another source only when it contributes independent evidence or resolves that uncertainty.
+- Stop fetching once the question has sufficient evidence.
+
+Do not fetch several URLs merely for coverage or flood one reasoning turn with uninspected output. Broader parallel collection remains valid when the user explicitly requests comprehensive literature coverage, multi-source fact verification, or a survey where breadth is itself the task; batch those sources when possible.
+
+
 1. Investigate the question against **primary sources** (official docs, source code, specs, first-party APIs), not a secondary write-up of them. Follow every claim back to the source that owns it.
 2. Write the findings to a single Markdown file, citing each claim's source.
 3. Save it where the repo already keeps such notes; match the existing convention, and if there is none, put it somewhere sensible and say where.

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

@@ -8,7 +8,25 @@ disable-model-invocation: true
 
 完成已确认的 spec/task。TDD 的红绿语义、测试质量、seam 和 mock 规则以 [tdd](.agents/skills/tdd/SKILL.md) 为唯一事实源；本技能负责 issue 级实现、验证、证据记录与收尾编排。
 
-> Ticket defines WHAT. TDD determines HOW to prove it. Repository determines HOW to implement it.
+## Issue context scope
+
+Implementation context is current-issue scoped.
+
+At issue startup:
+1. Read the current issue body.
+2. Do not read future issue bodies.
+3. Future issues may be inspected only by compact metadata: ID, title, status, and dependency.
+4. Expand another issue only when the current issue explicitly depends on a contract that cannot otherwise be resolved.
+5. Read only the specific dependent section needed.
+
+If the complete active Skill content is already present in the current conversation, do not read the same Skill file again merely to confirm its rules.
+
+Re-read only when:
+- the conversation contains only a partial/summary copy;
+- the file is known to have changed during the session; or
+- the user explicitly requests a fresh read.
+
+This scope does not prohibit current-issue referenced specs, code required to implement the current issue, relevant tests, or a genuinely required dependency contract.
 
 ## 入口
 
@@ -34,7 +52,11 @@ Issue 状态使用 `ready`、`in_progress`、`verified`、`resolved`、`blocked`
 
 ### ② Verify
 
-读取 [verify.md](references/verify.md)，执行当前 issue 所需的最终验证。Verify 只覆盖必要范围，不重复等价验证。
+执行当前 issue 所需的最终验证。Verify 只覆盖必要范围，不重复等价验证。
+
+- ticket 要求真实运行验证时，执行与验收目标匹配的实际验证；
+- 验证通过后不机械重复等价验证；
+- 若修改产生新的 Behavior，返回 Red-Green 对该 Behavior 执行 TDD，完成后再验证受影响范围。
 
 **出口：**当前 issue 所需最终验证通过，并完成要求的真实运行验证；状态进入 `verified`。
 
@@ -73,24 +95,10 @@ Rulings:
 
 读取 [finalize.md](references/finalize.md)。Finalize 只做当前 issue 的状态收敛和 tracker/progress/status 记录，不新增 Behavior、不修改产品实现、不补测试。
 
-**出口：**当前 issue 已 `resolved`，已满足的 blockers 已解除；仓库内状态变更进入 batch state-sync 集合。
-
-## Batch State Sync
-
-本次执行批次结束后，如仓库内 tracker/progress/status 存在待同步状态，统一写入并最多形成 1 个 batch state-sync commit。该 commit 不混入产品实现，也不属于任何单个 issue 的 `issue_base...issue_head` 范围。
+**出口：**当前 issue 已 `resolved`，已满足的 blockers 已解除。
 
 ## 运行纪律
 
-- Red-Green 必须覆盖当前 issue 的全部待实现 Behavior；Red-Green / Verify 不按 Behavior、阶段或验证动作拆 commit。
-- Verify 通过后形成当前 issue 唯一 delivery commit，再记录 evidence；Finalize 不创建实现 commit。
-- `tdd-implement` 不自动调用 `code-review`，不执行 per-issue Review、batch Review 或 Incremental Review。
 - 已有充分或等价证据时不重复搜索、读取或验证；后续 issue 优先消费 ledger 与 git history。
 - 只有外部阻塞、需要用户决策、destructive / irreversible 操作、安全敏感行为或 ticket/spec 已无法可靠解释时才暂停。
 - 当前 Step 达到出口后立即进入下一 Step；发现失败时保留实际状态，不把失败静默当作完成。
-
-## References
-
-- TDD：[tdd](.agents/skills/tdd/SKILL.md)
-- Verify：[verify.md](references/verify.md)
-- Finalize / State Sync：[finalize.md](references/finalize.md)
-- 多 issue 编排：[orchestration.md](references/orchestration.md)

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

@@ -1,23 +1,14 @@
 # Finalize
 
-仅在当前 issue 完成 Red-Green、Verify、delivery commit 和 Evidence Record 后执行。Finalize 只负责当前 issue 的状态收敛与 tracker/progress/status 记录，不新增产品 Behavior，不修改产品实现，不补测试。
+仅在当前 issue 完成 Red-Green、Verify、delivery commit 和 Evidence Record 后执行。Finalize 只负责当前 issue 的收尾检查与状态收敛，不新增产品 Behavior，不修改产品实现，不补测试。
 
 ## 步骤
 
-1. 确认当前 issue 的必要验证已通过，`issue_head` 已记录为 delivery commit，evidence ledger 包含 Acceptance、TDD、Verify 和 Rulings 结果。
-2. 准备 Acceptance Criteria 与 progress/tracker 的最终状态；外部 tracker 可在此同步，仓库内 tracker/progress/status 只记录为 batch 待同步状态。
+1. 确认当前 issue 的必要验证已通过，`issue_head` 仍指向 delivery commit，evidence ledger 包含 Acceptance、TDD、Verify 和 Rulings 结果。
+2. 确认当前 issue 的实现、测试、交付文档和配置均已包含在 delivery commit 中。
 3. 若发现任何实现、测试、交付文档、配置或验证遗漏，立即停止当前 issue：保持未完成，不标记 `resolved`，不解除 blockers，并报告遗漏请求决策。不得在 Finalize 中补改，也不得自动重新进入 Red-Green 或 Verify。
 4. 仅在未发现上述遗漏后，将当前 issue 标记为 `resolved`，解除已满足的 blockers。
-5. Finalize 不创建 commit；设置最终 `issue_head = HEAD`。
-
-## Batch State Sync
-
-本次执行批次结束后，如仓库内 tracker/progress/status 存在待同步状态，统一写入全部待同步内容并最多创建 1 个 batch state-sync commit。该 commit：
-
-- 不混入产品实现、测试、交付文档或配置；
-- 不属于任何单个 issue 的 `issue_base...issue_head` 范围；
-- 不因 issue 数量增加而拆成多个 status commits；
-- 不触发 `code-review`。
+5. Finalize 不创建 commit，也不改变 `issue_head`。
 
 ## 出口
 
@@ -25,6 +16,5 @@
 - 当前 issue 必要验证已通过；
 - delivery commit 与 evidence ledger 已记录；
 - Finalize 未发现实现、测试、交付文档、配置或验证遗漏；
-- tracker/progress/status 已同步，或已进入本批次唯一的待同步集合；
-- `issue_head = HEAD`；
+- `issue_head` 仍指向 delivery commit；
 - issue 已 `resolved`，已满足的 blockers 已解除。

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

@@ -1,10 +1,12 @@
 # 多 issue 编排
 
-仅在存在多个 `Type: task` issue 时生效。每个 issue 都按 `Red-Green → Verify → Record → Finalize` 独立完成；本文件只负责依赖顺序与 batch state sync。
+仅在存在多个 `Type: task` issue 时生效。每个 issue 都按 `Red-Green → Verify → Record → Finalize` 独立完成；本文件只负责依赖顺序、失败关闭与 batch state sync。
 
 ## 1. 构建依赖图
 
-读取每个 issue 的 `Blocked by`：
+构建依赖图时，只提取各 issue 的调度元数据：ID、Status、Blocked by / dependency。
+不得为构建依赖图读取未来 issue 正文、Acceptance Criteria、实现说明或其它 body 内容。
+如果调度元数据位于独立 issue 文件中，使用定点搜索/范围读取只取得对应 metadata 字段；不要全文打开所有 future issue 文件。
 
 - 无依赖时视为可直接调度；
 - 引用了其它 issue 时建立依赖边；
@@ -20,42 +22,22 @@ for each dependency layer:
     issue_base = HEAD
     Red-Green
     Verify
-    Record
+    Record (delivery commit 后设置 issue_head = HEAD)
     Finalize
-    issue_head = HEAD
 ```
 
-- `Red-Green` 与 `Verify` 是当前 issue 的 correctness gate；
-- `Record` 形成当前 issue 唯一 delivery commit，设置 `issue_head` 并记录 evidence ledger；
-- `Finalize` 只收敛状态、解除已满足 blockers，并把仓库内 tracker/progress/status 变更加入 batch state-sync 集合；
-- Issue loop 不调用 `code-review`，不执行 per-issue Review、batch Review 或 Incremental Review。
-
 当前 issue Finalize 完成后，依赖它的 issue 才可进入可执行状态。下一个 issue 以当前 `issue_head` 作为新的 `issue_base`。
 
-## 3. 状态与证据
-
-每个完成 issue 只携带后续调度所需的最小状态：
-
-- `Status`；
-- `issue_base`；
-- `issue_head`；
-- Acceptance、TDD、Verify 和 Rulings evidence；
-- 已解除的 blockers。
-
-Issue evidence 使用 `.scratch/tdd-implement/` ledger。后续 issue 不重复研究前序 issue 已确认且已记录的事实；context compact 后优先使用 ledger 与 git history。Ledger 不保存完整测试输出，只保存命令/场景及结果。
-
-## 4. Batch State Sync
+## 3. Batch State Sync
 
 全部可执行 issue 完成后，如仓库内 tracker/progress/status 存在待同步状态，统一写入并最多创建 1 个 batch state-sync commit。该 commit：
 
 - 不混入产品实现、测试、交付文档或配置；
 - 不属于任何单个 issue 的 `issue_base...issue_head` 范围；
 - 不因 issue 数量增加而拆成多个 status commits；
-- 不触发 `code-review`。
 
 ## 冲突与失败
 
-- `Blocked by` 无法解析、依赖缺失或存在环：停止受影响调度并报告；
 - issue 执行失败：保持未完成，按失败所在 Step 处理；其依赖项继续保持 `blocked`；
 - 多个 issue 修改同一位置且无法安全串行归属：暂停相关 issue，请求用户决定；
 - 外部权限、工具或环境阻塞：记录实际状态，不把失败静默当作完成；
@@ -65,6 +47,5 @@ Issue evidence 使用 `.scratch/tdd-implement/` ledger。后续 issue 不重复
 
 - 所有可执行 issue 均按依赖顺序完成并有 evidence ledger；
 - issue、依赖状态、Acceptance、Verify 与 progress 一致；
-- `tdd-implement` 的 `code-review` 调用次数为 0；
 - 不存在被误当作已完成的 blocked issue；
 - 仓库内状态同步如有需要，只形成最多 1 个 batch state-sync commit。

package/README.md

@@ -28,15 +28,16 @@ template/
 
 ## 独有 skill 分发边界
 
-本仓库有 7 个独有（proprietary）skills：
+本仓库有 8 个独有（proprietary）skills：
 
-### 可分发的 5 个
+### 可分发的 6 个
 
 - `tdd-implement`
 - `diagnose-fix`
 - `grill-to-spec`
 - `scaffold-functional-test`
 - `show-me`
+- `initialize-project`
 
 ### 仓库内部的 2 个
 
@@ -64,7 +65,7 @@ npx @heihei0299/matt-skills sync --dry-run --json
 
 `init` 对已有 `AGENTS.md` 始终跳过；已有项目使用 `sync`。默认 `sync` 保留已有 `AGENTS.md` 和项目规则，`--all` 只扩大技能范围。需要显式刷新 `AGENTS.md` 时使用 `sync --refresh-agents`；无受管区块时会先备份为 `AGENTS.md.bak`。`sync` 不删除目标项目的额外文件或自定义 skills。
 
-默认 programming 范围中的 4 个独有 skills 是 `tdd-implement`、`diagnose-fix`、`grill-to-spec`、`show-me`。
+默认 programming 范围中的 5 个独有 skills 是 `tdd-implement`、`diagnose-fix`、`grill-to-spec`、`show-me`、`initialize-project`。
 
 ## CLI
 

package/config/engineering.json

@@ -16,5 +16,6 @@
   "to-tickets",
   "triage",
   "wayfinder",
-  "wizard"
+  "wizard",
+  "initialize-project"
 ]

package/config/proprietary.json

@@ -6,14 +6,16 @@
     "diagnose-fix",
     "commit-check",
     "scaffold-functional-test",
-    "show-me"
+    "show-me",
+    "initialize-project"
   ],
   "distributable": [
     "tdd-implement",
     "diagnose-fix",
     "grill-to-spec",
     "scaffold-functional-test",
-    "show-me"
+    "show-me",
+    "initialize-project"
   ],
   "repoLocal": [
     "ci-guard",
@@ -23,6 +25,7 @@
     "tdd-implement",
     "diagnose-fix",
     "grill-to-spec",
-    "show-me"
+    "show-me",
+    "initialize-project"
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heihei0299/matt-skills",
-  "version": "3.0.23",
+  "version": "3.0.27",
   "description": "Agent skills + 项目配置模板：一条命令初始化 opencode / pi-agent 项目（含 mattpocock/skills 上游技能）",
   "type": "module",
   "bin": {

package/template/AGENTS.md

@@ -1,15 +1,17 @@
 ## Workflow
 按任务选择最匹配的 skill / 工具：
-* 代码理解 / 定位 / 调用链 / 依赖关系 / 数据流 → `codegraph explore`
+* 需要新增证据的代码理解 / 定位 / 调用链 / 依赖关系 / 数据流 → `codegraph explore`
 * 行为修改 / 功能实现 / bug 修复 / 逻辑调整 → `tdd`
 * 多来源调研 / 方案比较 / 技术选型 / 最佳实践 / 外部实现 → `research`
 `research` 仅用于多来源综合；单一资料、官方文档和实时事实直接查询。
 未命中 skill 时直接执行。明确不改变行为的文案、注释、格式和机械修改无需 `tdd`。
 仅当关键歧义无法从仓库事实解决，且会改变实现、范围、风险或验收结果时询问用户。
-## Context
+## Context / CodeGraph
 以当前代码、配置、测试和版本化文档为事实来源；更具体的项目指令优先。
-代码理解优先使用 `codegraph explore`；已锁定符号时使用 `codegraph node`。
-只获取完成任务所需的最小上下文；信息充分后停止探索。CodeGraph 不足时降级到 `rg` 和必要文件读取。
+- 有 issue/spec 时先读当前 issue；否则从用户问题和最相关 symbol/path 开始。
+- 只按当前未决问题逐步扩展上下文；README/package/tests/docs 按需读取。
+- 当前上下文已有充分且未过时的证据时，不做等价重复读取。
+- 当当前上下文不足、需要新增代码理解证据时，优先使用 `codegraph explore`；结果充分后不再 broad grep/read。
 实现时复用现有抽象、接口和依赖方向，不创建平行实现或无关扩展。
 ## Validation
 验证应足以证明修改正确且未破坏直接受影响行为。

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

@@ -1,15 +0,0 @@
-# Verify
-
-验证必须对应当前最终 diff；实现或测试变化后，只重新验证受影响证据。
-
-## 规则
-
-- 只验证当前 issue 的必要范围，不因进入 Verify 自动扩大验证范围。
-- ticket 要求真实运行验证时，执行与验收目标匹配的实际验证。
-- 验证通过后不机械重复等价验证。
-- 若修改产生新的 Behavior，返回 Red-Green 对该 Behavior 执行 TDD，完成后再验证受影响范围。
-
-## 出口
-
-- 当前 issue 的必要验证通过；
-- 要求的真实运行验证完成。