新增框架整合流程，方便后续新增SKILL等

.opencode/skills/opencode-init/SKILL.md

@@ -1,10 +1,12 @@
 ---
 name: opencode-init
 description: >-
-  初始化新项目的 .opencode 结构。两种触发方式：
+  初始化新项目的 .opencode 结构，以及将实际项目中孵化出的跨项目能力整合回模板框架。
+  三种触发方式：
   （1）首次自动触发 —— 当 `.opencode/.init-done` sentinel 不存在时，
   AGENTS.md 会在会话首次响应前引导 Agent 主动执行本 Skill；
   （2）关键词手动触发 —— "初始化opencode"、"opencode init"、"重置 opencode"、"补 gitignore" 等。
+  （3）框架整合 —— "整合到框架"、"合并到模板"、"加入框架白名单"、"template integration" 等。
   流程：清理模板残留的项目专用数据（changelog/deferred/pitfalls/profile/distillery），
   可选生成 .gitignore 模板，最后写入 `.opencode/.init-done` 标记完成。
   已 init 仓库不会再自动触发，除非用户主动通过关键词请求。
@@ -43,6 +45,16 @@ description: >-
 init 后用户说"补一下 gitignore"或"生成 gitignore" → 只跑阶段 5.5
 ```
 
+### 场景 D：框架整合（反向流程）
+
+```
+1. 在实际项目开发中，孵化出了一个新的跨项目能力（新 Skill / 新数据文件 / 新依赖）
+2. 用户认为该能力应成为模板框架的一部分
+3. 用户说"把这个能力整合到 opencode 框架"
+4. Agent 按"框架整合流程"清单逐项执行，更新本 SKILL.md 各截面
+5. 框架整合流程**不**操作 .init-done，**不**修改项目数据文件
+```
+
 ## 触发条件
 
 本 Skill 由 AGENTS.md 触发，两类入口：
@@ -58,6 +70,12 @@ init 后用户说"补一下 gitignore"或"生成 gitignore" → 只跑阶段 5.5
 - 用户关键词：`补 gitignore` / `生成 gitignore` / `gitignore 模板`
 - 跳过阶段 1-5 和阶段 7 的除"更新 gitignore_generated 字段"外的其他操作
 
+### C. 框架整合（执行框架整合清单）
+
+- 用户关键词：`整合到框架` / `合并到模板` / `加入框架白名单` / `template integration` / `framework sync` / `规模化这个 Skill` / `沉淀到模板`
+- 口头描述"把这个能力加进模板"、"这个 Skill 应该是框架级的"
+- 执行本文件"框架整合流程"章节的完整检核清单，不走阶段 0→7
+
 ## 执行原则（不可协商）
 
 1. **稳定准确 > token 成本**：每一步可以多读、多确认、让用户点头，不要图快
@@ -139,6 +157,7 @@ init 后用户说"补一下 gitignore"或"生成 gitignore" → 只跑阶段 5.5
 | `.opencode/data/profile/user-profile-log.md` | user-profile-log 模板 |
 | `.opencode/data/profile/project-profile.md` | project-profile 模板 |
 | `.opencode/data/profile/project-profile-log.md` | project-profile-log 模板 |
+| `.opencode/data/spec-docs/state.json` | state.json 模板 |
 
 执行要点：
 - 每个重置前**先 Read 现有内容预览前 10 行**给用户，避免误删有价值数据（特别是 deferred/pitfalls 用户可能想保留）
@@ -257,6 +276,8 @@ init 后用户说"补一下 gitignore"或"生成 gitignore" → 只跑阶段 5.5
 - `opencode.json` —— OpenCode 配置文件
 - `.opencode/.init-done` —— **阶段 7 写入**；模板仓库自身不应包含此文件
 - `.opencode/.gitignore` —— node_modules 忽略规则
+- `.opencode/package.json` —— opencode 插件运行时依赖声明（`@opencode-ai/plugin`）
+- `.opencode/package-lock.json` —— 依赖锁定文件，确保跨环境依赖版本一致
 
 ### Skills（规范 Skill 目录白名单）
 
@@ -267,6 +288,7 @@ init 后用户说"补一下 gitignore"或"生成 gitignore" → 只跑阶段 5.5
 - `.opencode/skills/pitfall-journal/`
 - `.opencode/skills/problem-distillery/`
 - `.opencode/skills/profile-memory/`
+- `.opencode/skills/spec-docs/`
 
 > **任何不在此白名单中的 skill 目录**，在阶段 3 中一律删除（视为源项目的项目级 Skill）。
 
@@ -277,6 +299,7 @@ init 后用户说"补一下 gitignore"或"生成 gitignore" → 只跑阶段 5.5
 - `.opencode/data/pitfalls/pitfalls.md`
 - `.opencode/data/distillery/{problems.md, insights.md, golden-rules.md}`
 - `.opencode/data/profile/{user-profile.md, user-profile-log.md, project-profile.md, project-profile-log.md}`
+- `.opencode/data/spec-docs/state.json`
 
 ---
 
@@ -437,6 +460,16 @@ last_distill_date: {{DATE}}
 ## 记录
 ```
 
+### spec-docs/state.json
+
+```json
+{
+  "last_review_date": null,
+  "last_processed_changelog_id": null,
+  "review_count": 0
+}
+```
+
 ### .init-done
 
 阶段 7 写入的 sentinel，YAML 格式，字段固定：
@@ -778,6 +811,123 @@ public/build/
 
 ---
 
+## 框架整合流程（Template Integration）
+
+> 本清单是框架整合的**唯一检核入口**。当在实际项目中创建了新的跨项目级别能力，需要合并回本模板时，Agent 必须按本清单逐项执行，不得跳过任何一步。
+
+### 触发关键词
+
+`整合到框架` / `合并到模板` / `加入框架白名单` / `template integration` / `framework sync` / `规模化这个 Skill` / `沉淀到模板`
+
+### 执行流程
+
+1. **识别整合类型**：判断本次整合属于下方哪一（或几）类
+2. **逐项执行该类的全部检核项**：打勾即改，不可只记 "后续补充"
+3. **交叉验证**：执行完成后，用"框架截面自检"反向核对每项是否存在
+4. **生成报告**：列出每个检核项的完成状态
+
+---
+
+### 整合类型与检核清单
+
+#### 类型 1：新增基础设施 Skill
+
+> 触发条件：在项目中创建了一个服务于 opencode 自身元系统的新 Skill（非项目业务 Skill）
+
+| # | 检核项 | 操作 |
+|---|--------|------|
+| 1.1 | Skill 目录存在 `SKILL.md` 且含正确 frontmatter | 验证 `name`、`description` 字段 |
+| 1.2 | `opencode-init` 规范清单 → Skills 白名单 | 在 `### Skills（规范 Skill 目录白名单）` 下新增条目 |
+| 1.3 | `opencode-init` 清理清单 → 阶段 3 | 检查：新 Skill 如有数据文件，需在 B 组重置列表新增条目 |
+| 1.4 | `epee-orchestrator/registry.md` | 新增条目（格式见 registry.md 注释），类型标注 `基础设施` 或 `个人级` |
+| 1.5 | `AGENTS.md` | 检查：新 Skill 是否被 AGENTS.md 引用？若有，引用路径是否正确？ |
+| 1.6 | `opencode.json` → `instructions` | 检查：新 Skill 是否有数据文件需要注入到会话上下文？若有，追加路径 |
+| 1.7 | Skill 自迭代日志 | 新 Skill 必须包含 `## 自迭代日志` 章节（空白即可） |
+
+#### 类型 2：新增数据文件
+
+> 触发条件：新增或修改了 `.opencode/data/` 下的数据文件（changelog/deferred/pitfalls/distillery/profile/spec-docs 等）
+
+| # | 检核项 | 操作 |
+|---|--------|------|
+| 2.1 | `opencode-init` 规范清单 → 数据占位目录 | 在 `### 数据占位目录` 下新增路径 |
+| 2.2 | `opencode-init` 清理清单 → B 组重置列表 | 在阶段 3 的 B 组表格中新增一行 |
+| 2.3 | `opencode-init` → 模板内容 | 新增该文件的模板内容（最小化版本，含占位注释） |
+| 2.4 | `opencode.json` → `instructions` | 若该数据文件应注入会话上下文，追加到 `instructions` 数组 |
+| 2.5 | 所属 Skill 的 SKILL.md | 若数据文件归属某个 Skill，该 Skill 应引用正确的文件路径 |
+
+#### 类型 3：新增运行时依赖
+
+> 触发条件：新增或修改了 `.opencode/package.json` 中的 `dependencies`
+
+| # | 检核项 | 操作 |
+|---|--------|------|
+| 3.1 | `opencode-init` 规范清单 → 顶层 | 确认 `.opencode/package.json` + `.opencode/package-lock.json` 在顶层 canonical 列表中 |
+| 3.2 | `.opencode/.gitignore` | 确保 **不** 包含 `package.json` 和 `package-lock.json`（这些是基础设施文件，应被 git 跟踪） |
+| 3.3 | `npm install` 后 `package-lock.json` 变更 | 提醒用户提交更新后的 `package-lock.json` |
+| 3.4 | 根目录 `.gitignore`（如存在） | 确认未错误排除 `.opencode/package.json` |
+
+#### 类型 4：修改 AGENTS.md 规则
+
+> 触发条件：在 AGENTS.md 中新增章节、修改规则逻辑、调整 Skill 调度条件
+
+| # | 检核项 | 操作 |
+|---|--------|------|
+| 4.1 | AGENTS.md 引用新 Skill | 检查：新增的 Skill 是否已在 `opencode-init` Skills 白名单？是否已在 `epee-orchestrator/registry.md` 注册？ |
+| 4.2 | AGENTS.md 引用新数据文件 | 检查：路径是否在 `opencode.json` 的 `instructions` 中？是否在 `opencode-init` 数据占位目录中？ |
+| 4.3 | AGENTS.md 引用 `spec-docs` Skill | 检查：`spec-docs` Skill 是否已在 Skills 白名单？（此项为固定检查，因历史上发生过遗漏） |
+| 4.4 | AGENTS.md 引用新 docs/ 文档 | 检查：`docs/` 下的文档路径是否存在？frontmatter 是否完整？（见 `docs/README.md` 元数据标准） |
+
+#### 类型 5：修改 opencode.json 指令注入
+
+> 触发条件：修改了 `opencode.json` 的 `instructions` 数组
+
+| # | 检核项 | 操作 |
+|---|--------|------|
+| 5.1 | 新增路径指向的数据文件存在 | `read` 验证路径可访问 |
+| 5.2 | 数据文件已在 `opencode-init` 数据占位目录中 | 确保 init 流程会保留/重置该文件 |
+| 5.3 | 若路径指向 Skill 内部资源 | 确保该 Skill 在 Skills 白名单中 |
+
+#### 类型 6：新增 docs/ 规范文档
+
+> 触发条件：在 `docs/` 下新增了架构方案/技术规范/项目约定文档，且是框架级别（非项目专属）
+
+| # | 检核项 | 操作 |
+|---|--------|------|
+| 6.1 | `docs/README.md` 目录结构图 | 若新增了子目录分类，更新目录结构图 |
+| 6.2 | 文档 frontmatter 完整 | `id` / `title` / `type` / `status` / `created` / `updated` / `related_changelogs` |
+| 6.3 | 文档编号唯一 | 检查 `id` 不与已有文档重复 |
+| 6.4 | `spec-docs` Skill 可覆盖 | 确认 `spec-docs` 操作 B（周期审查）能发现该文档 |
+
+---
+
+### 框架截面自检（Cross-Section Verification）
+
+> 整合完成后，Agent 必须运行此自检：逐一检查以下 "截面"，确认所有被引用的组件在对应位置都存在。
+
+| 截面 | 检查方式 |
+|------|---------|
+| `AGENTS.md` 引用的 Skill | grep Skill 名 → 必须在 `opencode-init` Skills 白名单中 |
+| `AGENTS.md` 引用的数据文件 | grep 文件路径 → 必须在 `opencode-init` 数据占位目录中 |
+| `AGENTS.md` 引用的 docs/ 文档 | glob 检查文件存在 |
+| `opencode.json` → `instructions` 所列路径 | `read` 逐条验证文件存在 |
+| `opencode.json` → `instructions` 所列路径 | 必须在 `opencode-init` 数据占位目录 或 顶层 canonical 中 |
+| `epee-orchestrator/registry.md` 注册的 Skill | glob 检查对应 `SKILL.md` 存在 |
+| `epee-orchestrator/registry.md` 注册的 Skill | 必须在 `opencode-init` Skills 白名单中（基础设施类 + 个人级） |
+| `.opencode/skills/` 下的 Skill 目录 | 若不在 `epee-orchestrator/registry.md` 中 → 缺失注册 |
+| `.opencode/skills/` 下的 Skill 目录 | 若不在 `opencode-init` Skills 白名单中且非项目级 → 警告 |
+| `.opencode/data/` 下的数据文件 | 若不在 `opencode-init` 数据占位目录中 → 警告 |
+| `.opencode/data/` 下的数据文件 | 若需要注入上下文 → 检查是否在 `opencode.json` → `instructions` 中 |
+
+### 整合自检执行规则
+
+1. **先整合后自检**：先完成所有类型检核项的修改，再跑截面自检
+2. **自检发现缺口 → 回到对应类型的检核清单补充**，不可手动修补绕过
+3. **每项自检必须输出结果**：`✅ 通过` / `❌ 缺失：<具体描述>` / `⚠️ 跳过：<原因>`
+4. **任何 ❌ 结果必须在最终报告前修复**
+
+---
+
 ## 自迭代日志
 
 本节记录使用本 Skill 过程中发现的必要检查项。