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

name, phases, description

name	phases	description
opencode-init	all	初始化新项目的 .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 仓库不会再自动触发，除非用户主动通过关键词请求。

OpenCode Init Skill

把从其它项目复制过来（或通过 git clone 模板仓库获得）的 .opencode/ 目录重置为当前新项目的干净起点。

使用场景

场景 A：克隆模板仓库后的首次会话

1. 用户把本模板作为 git 仓库发布
2. 其他人 `git clone <模板仓库>` 得到新项目骨架
3. 用户打开 OpenCode，在该仓库发出任意第一条消息
4. AGENTS.md 检测 .opencode/.init-done 不存在
   → 引导 Agent 暂停用户原始请求，先执行本 Skill
5. Agent 按阶段 0 → 7 跑完，写入 .init-done
6. 后续会话 sentinel 已存在，不再自动触发

场景 B：从已有项目直接复制 .opencode 目录

1. 用户在 "源项目 A" 中使用本 .opencode 模板开发
2. 用户开 "新项目 B"，把 A 的 .opencode/ 整体拷贝到 B
3. 用户在 B 中说"初始化opencode"（或首次会话被 AGENTS.md 触发）
4. 本 Skill 清空 A 遗留的项目数据，重建 registry，生成 .gitignore，写入 sentinel

场景 C：只补 .gitignore

init 后用户说"补一下 gitignore"或"生成 gitignore" → 只跑阶段 5.5

场景 D：框架整合（反向流程）

1. 在实际项目开发中，孵化出了一个新的跨项目能力（新 Skill / 新数据文件 / 新依赖）
2. 用户认为该能力应成为模板框架的一部分
3. 用户说"把这个能力整合到 opencode 框架"
4. Agent 按"框架整合流程"清单逐项执行，更新本 SKILL.md 各截面
5. 框架整合流程**不**操作 .init-done，**不**修改项目数据文件

触发条件

本 Skill 由 AGENTS.md 触发，两类入口：

A. 全流程（阶段 0 → 7）

• .opencode/.init-done 不存在 → 会话首次响应前由 AGENTS.md 自动引导
• 用户关键词：初始化opencode / opencode init / 重置 opencode / reset opencode 等
• 口头描述"把复制过来的 .opencode 清理一下"、"按规范归位一下"

B. 仅补 .gitignore（只跑阶段 5.5）

• 用户关键词：补 gitignore / 生成 gitignore / gitignore 模板
• 跳过阶段 1-5 和阶段 7 的除"更新 gitignore_generated 字段"外的其他操作

C. 框架整合（执行框架整合清单）

• 用户关键词：整合到框架 / 合并到模板 / 加入框架白名单 / template integration / framework sync / 规模化这个 Skill / 沉淀到模板
• 口头描述"把这个能力加进模板"、"这个 Skill 应该是框架级的"
• 执行本文件"框架整合流程"章节的完整检核清单，不走阶段 0→7

执行原则（不可协商）

1. 稳定准确 > token 成本：每一步可以多读、多确认、让用户点头，不要图快
2. 破坏性操作必须 dry-run：删除、重置必须先列清单给用户确认
3. 不可逆操作前提醒 git：开始前先提示用户确认工作区已 commit/stash
4. 模糊就问：分类不清的文件一律问用户，不要猜
5. 幂等：反复运行应当无害（第二次在已干净状态下不会做破坏）
6. 中断可恢复：任何阶段异常 abort 不写入 .init-done，下次会话仍会被 AGENTS.md 触发从头继续

核心流程

阶段 0：前置确认 + 幂等判断

1. 检查当前工作目录下存在 .opencode/
   - 不存在 → 直接结束，提示用户先复制模板
2. 读取 .opencode/.init-done
   - 不存在 → 继续，按"首次 init"路径执行
   - 已存在 → 展示其元数据（initialized_at、project_type 等），提示：
     "检测到本仓库已于 {initialized_at} 完成初始化（project_type: {type}）。
      继续执行会清空 deferred / pitfalls / distillery 等数据文件。确认要继续吗？"
     等用户明确回复"继续"再往下
3. 运行 `git status`：
   - 不是 git 仓库 → 警告但不阻塞，建议手动备份
   - 有未提交改动 → 提醒"建议先 commit 或 stash，便于回滚"，等用户明确回复"继续"
4. 向用户声明本次操作范围（见"分组规则"），请求口头确认启动

阶段 1：递归扫描 .opencode/

1. 【强制】读取 `.opencode/canonical-manifest.json`
   — 此文件是文件分组的唯一数据源，不允许凭记忆或 Skill 描述摘要判断
2. 用 shell 列出 .opencode 下所有文件（含子目录）
3. 把每个文件对照 manifest.json 分成三组：
   - A 组（canonical）：路径在 canonical_root / canonical_opencode_top / canonical_skills 中，原样保留
   - B 组（template-data）：路径在 template_data_files 或 template_phase_files 中，需要删除或重置为模板
   - C 组（foreign）：manifest 三组之外的所有路径，视作未知项
4. 把分组结果用表格汇报给用户：
   | 组 | 路径 | 处理动作 |

阶段 2：处理 C 组（未知文件归位）

对 C 组中的每个文件，逐条询问用户（可一次性列清单批量确认）：

文件特征	建议归属	目标路径
包含 SKILL.md 的目录	Skill（无论通用/项目专属）	.opencode/skills/<skill-name>/
看不出归属	询问用户	—
明显是临时/垃圾文件（*.log、*.tmp、缓存等）	删除（需用户确认）	—

执行要点：

• 先列清单一次性确认，然后批量执行移动/删除，避免交互过于频繁
• 重名冲突：C 组文件若与 A 组规范文件重名，保留 A 组版本，把 C 组备份到 .opencode/_init-backup/ 下让用户自行 diff，不直接覆盖
• 迁移后核查：移动完成后重新扫描，确认 C 组已清空

阶段 3：处理 B 组（源项目数据清理/重置）

按"清理清单"执行：

A. 直接删除

• .opencode/data/ 下所有数据文件的内容（目录保留）
• .opencode/node_modules/（如有）
• .opencode/*.log —— 调试日志

B. 重置为空模板（保留文件，仅清内容）

文件	模板（见"模板内容"节）
.opencode/data/changelog/changelog-full.md	L1 模板
.opencode/data/changelog/changelog-recent.md	L2 模板
.opencode/data/changelog/changelog-headlines.md	L3 模板
.opencode/data/deferred/registry.md	deferred 模板
.opencode/data/pitfalls/pitfalls.md	pitfalls 模板
.opencode/data/distillery/problems.md	problems 模板
.opencode/data/distillery/insights.md	insights 模板
.opencode/data/distillery/golden-rules.md	golden-rules 模板
.opencode/data/profile/user-profile.md	user-profile 模板
.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 模板
.opencode/phase/current.json	current.json 模板
.opencode/phase/data/design/state.json	state.json 模板
.opencode/phase/data/design/concept.md	concept.md 模板
.opencode/phase/data/design/design-outline.md	design-outline.md 模板
.opencode/phase/data/design/qa-quality-report.md	qa-quality-report.md 模板
.opencode/phase/data/design/reference-analysis/gdd-reverse.md	gdd-reverse.md 模板
.opencode/phase/data/design/reference-analysis/community-iteration.md	community-iteration.md 模板

执行要点：

• 每个重置前先 Read 现有内容预览前 10 行给用户，避免误删有价值数据（特别是 deferred/pitfalls 用户可能想保留）
• 如用户对某个数据文件明确说"保留"（例如 golden-rules 想带过去），跳过该文件的重置

阶段 4：重建 registry

打开 .opencode/skills/epee-orchestrator/registry.md：

1. 解析现有条目（每条 ### <skill-name> 块）
2. 删除所有标记为"项目级"的条目
3. 遍历 .opencode/skills/ 目录，对照 registry：
   • registry 有条目但 skill 目录不存在 → 删除条目
   • skill 目录存在但 registry 无条目 → 读取该 skill 的 SKILL.md frontmatter，新增条目
4. 确保 opencode-init 条目本身存在（类型: 基础设施）
5. 写回 registry.md

阶段 5：同步 opencode.json 配置

• 读取 opencode.json
• 确认 instructions 字段中包含所有必要的数据文件路径（changelog-headlines、deferred/registry、golden-rules、project-profile）
• 如有缺失或路径不正确，更新之

阶段 5.5：.gitignore 交互式生成

5.5.1 前置检测

检测项目根 .gitignore：
  不存在        → 进入 5.5.2 问卷
  已存在且非空  → Read 前 30 行展示给用户，询问：
                   [覆盖 / 追加到文件末尾 / 跳过本阶段]
  用户选"跳过"  → 本阶段结束，.init-done 里标记 gitignore_generated: false

5.5.2 问卷（一次性批量 AskQuestion 收集）

必问 3 项 + 可选 1 项：

编号	问题	类型	选项
Q1	项目主要技术栈	多选	Unity / Node.js / Python / Rust / Go / C# 非 Unity / Web 静态站点 / 其他 / 不确定（跳过语言段）
Q2	IDE 偏好	多选	OpenCode（预勾）/ VSCode / JetBrains 全家桶 / Visual Studio / Vim+Emacs
Q3	操作系统	多选	Windows / macOS / Linux（按探测到的当前 OS 预勾）
Q4（可选）	其他要忽略的路径	自由文本	用户可跳过

5.5.3 片段组装

按问卷选择拼装，片段内容见下方"模板内容 · .gitignore 片段库"。拼装顺序固定：

# === OpenCode（固定，所有项目都包含） ===
# === OS ===
# === IDE ===
# === Language / Framework ===
# === Custom ===

若 Q1 选"不确定" → 跳过 Language 段，其他段正常拼装（极简版仍可用）。

5.5.4 预览与确认

1. 把组装结果写到 .opencode/_gitignore-preview（临时文件）
2. 给用户完整展示（超过 60 行则折叠中段）
3. AskQuestion：[写入 .gitignore / 让我调整再确认 / 放弃本阶段]
4. "写入"→ move 到项目根 .gitignore（已存在时按 5.5.1 的选择做覆盖或追加），删除预览文件
5. "调整"→ 根据用户描述修改后重复步骤 2-3
6. "放弃"→ 删除预览文件，.init-done 标记 gitignore_generated: false

阶段 6：验证与报告

1. 重新递归扫描 .opencode/，再次分组
2. 【强制】验证所有 Skills 的 frontmatter：
   - 遍历 `.opencode/skills/*/SKILL.md`
   - 每个文件必须检查：第一行是否为 `---`、是否包含 `name:` 字段、frontmatter 是否正确闭合
   - 缺失 frontmatter 的 Skill 会无法被 opencode 注册（即使文件存在也不会出现在 available_skills 中）
   - 发现缺失 → 立即报告并修复（参考其他 Skill 的 frontmatter 格式）
3. 期望状态：
   - A 组：全部保留，文件内容未被动过
   - B 组：数据文件仅含模板内容
   - C 组：为空（或仅剩用户明确要求保留的文件）
   - 所有 Skill 的 frontmatter 完整
   - 项目根 .gitignore：按用户选择存在或被放弃（状态记到报告里）
   - project根 opencode.json：instructions 已正确配置
4. 给用户一份结构化报告，至少包含：
   - 删除的文件
   - 重置的文件
   - 新注册/移除的 registry 条目
   - .gitignore 的处理结果（新建/追加/覆盖/放弃）
   - Skill frontmatter 验证结果
   - 未处理的文件（如果有，逐条说明原因）

阶段 7：写入 .init-done sentinel

仅在阶段 6 验证全部通过后执行。任何前序阶段异常中断都不写入此文件，确保下次会话 AGENTS.md 能再次触发。

1. 按"模板内容 · .init-done"格式，填充实际值写入 .opencode/.init-done
2. 向用户输出收尾提示：
   > 初始化完成。建议现在执行：
   >   git add .opencode/ .gitignore
   >   git diff --cached -- .opencode/
   >   git commit -m "chore(opencode): initialize .opencode from template"
   >
   > ⚠️ .opencode/.init-done 必须 commit，否则团队其他成员 clone 后会被再次触发 init。

仅跑阶段 5.5 时（用户说"补 gitignore"）：

• 若 .init-done 存在 → 更新其中的 gitignore_generated: true 字段，保留其他字段
• 若 .init-done 不存在 → 提示用户"仓库尚未完整 init，只补 gitignore 不会写 sentinel。是否改为跑完整 init？"

---

规范清单（canonical）

声明：以下清单与 .opencode/canonical-manifest.json 保持同步。Agent 在阶段 1 必须读取 manifest.json， 不得凭本节的 Markdown 文本做文件分组。本节的文本版仅供人类阅读和 Skill 维护参考。

下列文件构成本 .opencode 模板的"主干"，初始化后必须都在、内容不被删改（数据文件除外）：

顶层

• AGENTS.md —— 项目规则文件（项目根目录）
• opencode.json —— OpenCode 配置文件
• .opencode/.init-done —— 阶段 7 写入；模板仓库自身不应包含此文件
• .opencode/.gitignore —— node_modules 忽略规则
• .opencode/package.json —— opencode 插件运行时依赖声明（@opencode-ai/plugin）
• .opencode/package-lock.json —— 依赖锁定文件，确保跨环境依赖版本一致

Skills（规范 Skill 目录白名单）

• .opencode/skills/opencode-init/
• .opencode/skills/deferred-decisions/
• .opencode/skills/dev-changelog/
• .opencode/skills/epee-orchestrator/（含 registry.md，见阶段 4）
• .opencode/skills/pitfall-journal/
• .opencode/skills/problem-distillery/
• .opencode/skills/profile-memory/
• .opencode/skills/spec-docs/
• .opencode/skills/game-design/
• .opencode/skills/skill-tester/

任何不在此白名单中的 skill 目录，在阶段 3 中一律删除（视为源项目的项目级 Skill）。

数据占位目录（保留目录，文件重置为模板内容）

• .opencode/data/changelog/{changelog-full.md, changelog-recent.md, changelog-headlines.md}
• .opencode/data/deferred/registry.md
• .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

阶段数据占位目录（保留目录，文件重置为模板内容）

• .opencode/phase/current.json
• .opencode/phase/data/design/state.json
• .opencode/phase/data/design/concept.md
• .opencode/phase/data/design/design-outline.md
• .opencode/phase/data/design/qa-quality-report.md
• .opencode/phase/data/design/reference-analysis/gdd-reverse.md
• .opencode/phase/data/design/reference-analysis/community-iteration.md

---

清理清单（cleanup list）

强制删除

路径	原因
.opencode/*.log、.opencode/**/*.log	调试日志遗留
.opencode/_init-backup/（如果是上一轮残留）	仅阶段 2 冲突备份用，运行前应不存在
.opencode/_gitignore-preview（如果是上一轮残留）	阶段 5.5 临时文件

重置为模板

见"模板内容"节。

---

模板内容

重置数据文件时使用以下内容。带 {{DATE}} 的占位符替换为当天日期（YYYY-MM-DD）。

changelog-full.md

# Dev Changelog — Full

完整的开发改动记录，按时间倒序排列。作为主动 RAG 的数据源，用户手动唤醒时读取。

## 记录

changelog-recent.md

# Dev Changelog — Recent

最近 ~10 次改动的摘要记录，按时间倒序排列。
当 Agent 检测到当前任务与近期改动相关时自动读取。

changelog-headlines.md

# Dev Changelog — Headlines

最近 ~50 次改动的一句话概要，按时间倒序排列。每次会话自动注入上下文。

deferred/registry.md

# Deferred Decisions Registry

## Active Items

（暂无延期方案）

---

## Completed / Cancelled Items

（暂无已完成或已废弃的方案）

pitfalls/pitfalls.md

# Pitfall Journal

开发过程中踩过的坑，按时间倒序排列。
Agent 进入 Debug mode 或遇到运行时错误时自动检索匹配。

---

distillery/problems.md

# Problem Distillery — Problems

反复出现的顽固问题追踪记录，按时间倒序排列。

<!-- 新条目追加在此行下方 -->

distillery/insights.md

# Problem Distillery — Insights

从已解决的顽固问题中蒸馏出的精炼方法论。

<!-- 新条目追加在此行下方 -->

---
last_distill_date: {{DATE}}

distillery/golden-rules.md

# Golden Rules

经过实践验证（权重 >= 5）的精炼认知，每次新会话自动注入。

<!-- 当条目达到权重阈值后由 Agent 自动写入 -->

profile/user-profile.md

# User Profile

## 审美与设计

## 技术偏好

## 做事风格

## 沟通偏好

## 产品理解

profile/user-profile-log.md

# User Profile Log

详细记录每次画像更新的完整上下文，按时间正序追加。

## 记录

profile/project-profile.md

# Project Profile

## 项目定位

## 技术栈与架构

## 设计约定

## 产品方向

profile/project-profile-log.md

# Project Profile Log

详细记录每次项目画像更新的完整上下文，按时间正序追加。

## 记录

spec-docs/state.json

{
  "last_review_date": null,
  "last_processed_changelog_id": null,
  "review_count": 0
}

phase/current.json

{
  "phase": "design",
  "switched_at": null,
  "previous_phase": null
}

phase/data/design/state.json

{
  "workflow_state": "WAITING_FOR_CONCEPT",
  "concept_summary": "",
  "reference_games": [],
  "in_progress": {
    "active": false,
    "operation": null,
    "started_at": null,
    "detail": null
  },
  "checkpoints": [],
  "sessions": [],
  "created_at": null,
  "updated_at": null
}

phase/data/design/concept.md

# 游戏概念

（设计阶段步骤 1 的用户原始概念记录）

phase/data/design/design-outline.md

# 游戏设计大纲

（设计阶段完成后由 game-design Skill 生成）

详见 `## 四、开发阶段交接` 章节供开发阶段 Agent 参考。

phase/data/design/qa-quality-report.md

# 问答质量评估报告

本文件记录设计工作流中每轮问答的质量评估结果。每次评估追加，不覆盖。

## 评估维度

- **劣质问题类型**：引导性 / 过于抽象 / 遗漏选项 / 不可回答 / 基于推测
- **问题原文**：保留用户质疑的原问题
- **用户反馈**：用户的具体质疑或自定义回答
- **优化方案**：改进后的提问方式
- **通用建议**：可跨项目复用的经验

---

## 质量报告

phase/data/design/reference-analysis/gdd-reverse.md

# GDD 逆向分析

（game-design Skill 步骤 3 sub-agent A 产物）

phase/data/design/reference-analysis/community-iteration.md

# 社群口碑与品类迭代分析

（game-design Skill 步骤 3 sub-agent B 产物）

.init-done

阶段 7 写入的 sentinel，YAML 格式，字段固定：

# .opencode/.init-done — opencode-init Skill 写入的初始化标记文件
# 本文件的存在表示本仓库已完成 .opencode 模板初始化
# 请务必 git commit 此文件，避免团队成员 clone 后被再次触发 init
initialized_at: {{ISO_DATETIME}}      # 如 2026-04-30T16:30:00+08:00
initialized_by: opencode-init
skill_version: 2
project_type: {{PROJECT_TYPE}}        # 阶段 5.5 问卷 Q1 结果；多选逗号分隔；"不确定"写 unknown
gitignore_generated: {{BOOL}}         # true / false

写入时机：

• 全流程跑完（阶段 6 验证通过）时由阶段 7 写入
• "补 gitignore" 单独跑阶段 5.5 时，若已存在则只更新 gitignore_generated 字段

---

模板内容 · .gitignore 片段库

阶段 5.5 按用户问卷选择拼接以下片段。每段前后各空一行，保证可读性。

固定段：OpenCode

# === OpenCode ===
# opencode-init 临时产物
.opencode/_init-backup/
.opencode/_gitignore-preview

OS 段（按问卷 Q3 多选拼接）

Windows

# === OS: Windows ===
Thumbs.db
Thumbs.db:encryptable
ehthumbs.db
ehthumbs_vista.db
Desktop.ini
$RECYCLE.BIN/
*.stackdump
*.lnk

macOS

# === OS: macOS ===
.DS_Store
.AppleDouble
.LSOverride
Icon
._*
.DocumentRevisions-V100
.fseventsd
.Spotlight-V100
.TemporaryItems
.Trashes
.VolumeIcon.icns
.com.apple.timemachine.donotpresent

Linux

# === OS: Linux ===
*~
.fuse_hidden*
.directory
.Trash-*
.nfs*

IDE 段（按问卷 Q2 多选拼接）

VSCode

# === IDE: VSCode ===
.vscode/*
!.vscode/settings.json
!.vscode/tasks.json
!.vscode/launch.json
!.vscode/extensions.json
!.vscode/*.code-snippets
.history/
*.vsix

JetBrains

# === IDE: JetBrains ===
.idea/
*.iml
*.ipr
*.iws
.idea_modules/
atlassian-ide-plugin.xml

Visual Studio

# === IDE: Visual Studio ===
.vs/
*.user
*.suo
*.userprefs
bin/
obj/
[Dd]ebug/
[Rr]elease/
x64/
x86/

Vim/Emacs

# === IDE: Vim / Emacs ===
*.swp
*.swo
*.swn
Session.vim
.netrwhist
*~
\#*\#
.\#*

OpenCode：固定段已覆盖，无需额外片段。

Language / Framework 段（按问卷 Q1 多选拼接）

Unity

# === Language: Unity ===
[Ll]ibrary/
[Tt]emp/
[Oo]bj/
[Bb]uild/
[Bb]uilds/
[Ll]ogs/
[Uu]ser[Ss]ettings/
[Mm]emoryCaptures/
[Rr]ecordings/
sysinfo.txt
*.apk
*.aab
*.unitypackage
*.app
*.csproj
*.unityproj
*.sln
*.suo
*.tmp
*.user
*.userprefs
*.pidb
*.booproj
*.svd
*.pdb
*.mdb
*.opendb
*.VC.db

Node.js

# === Language: Node.js ===
node_modules/
.npm/
.yarn/
.pnp.*
dist/
build/
out/
.next/
.nuxt/
.cache/
.parcel-cache/
coverage/
.env
.env.local
.env.*.local
npm-debug.log*
yarn-debug.log*
yarn-error.log*
pnpm-debug.log*
.turbo/

Python

# === Language: Python ===
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
build/
dist/
*.egg-info/
*.egg
.venv/
venv/
env/
.pytest_cache/
.mypy_cache/
.ruff_cache/
.coverage
.coverage.*
htmlcov/
.tox/
.nox/
.hypothesis/
.ipynb_checkpoints/

Rust

# === Language: Rust ===
target/
**/*.rs.bk
*.pdb
# Cargo.lock：lib crate 建议忽略，bin crate 建议提交，默认不忽略
# Cargo.lock

Go

# === Language: Go ===
bin/
vendor/
*.exe
*.exe~
*.dll
*.so
*.dylib
*.test
*.out
go.work

C# 非 Unity

# === Language: C# (non-Unity) ===
bin/
obj/
*.user
*.suo
*.pdb
*.cache
[Dd]ebug/
[Rr]elease/
x64/
x86/
[Bb]uild/
*.dll
*.pdb

Web 静态站点

# === Language: Web Static ===
node_modules/
dist/
build/
public/build/
.cache/
.tmp/
.sass-cache/
.parcel-cache/

其他：不拼接语言段，用户在 # === Custom === 段自行补充。

Custom 段（固定尾部）

# === Custom ===
# 在此段追加项目专属需要忽略的路径

若用户在问卷 Q4 填了自由文本，按行拆分后追加到 Custom 段下方。

---

冲突与边界情况处理

场景	处理
C 组某文件与 A 组重名	保留 A 组；C 组移到 .opencode/_init-backup/，告知用户自行 diff
C 组有 SKILL.md 且 skill 名与 A 组白名单同名	保留 A 组 skill；C 组整个 skill 目录移到 _init-backup/
数据文件（如 pitfalls.md）用户明确说"保留"	跳过该文件重置
扫描到 .opencode/_init-backup/（上轮残留）	警告用户并询问：删除 / 保留 / 重命名
git status 不能执行（不是 git 仓库）	警告但不阻塞，改为建议用户手动备份
.opencode/.init-done 已存在且用户触发了全流程	阶段 0 展示其元数据并要求二次确认
阶段 5.5 项目根已有 .gitignore 且用户选"追加"	把拼装结果追加到现有文件末尾（用 \n\n# --- 以下由 opencode-init 追加 ---\n 分隔）
阶段 5.5 中途异常或用户放弃	不写入 .gitignore，.init-done 的 gitignore_generated 记 false
阶段 7 写 .init-done 前前序阶段已 abort	不写入 sentinel，下次会话 AGENTS.md 会重新触发
用户说"补 gitignore" 但 .init-done 不存在	提醒"仓库尚未完整 init"，询问是否改为跑全流程

---

一次运行的最终状态（验收标准）

全流程（阶段 0 → 7）完成后 .opencode/ 应当满足：

1. 规范清单中列出的所有文件/目录都存在
2. 所有数据文件（changelog/deferred/pitfalls/distillery/profile）仅含模板内容
3. .opencode/skills/ 下仅有白名单中的 skill 目录
4. .opencode/skills/epee-orchestrator/registry.md 中只有：基础设施 + 个人级 skill 条目，且包含 opencode-init 条目
5. 不存在 *.log、_init-backup/、_gitignore-preview
6. .opencode/.init-done 已写入，字段完整且值有效
7. opencode.json 的 instructions 字段配置正确
8. 项目根 .gitignore 状态明确（存在且有内容 / 被用户显式放弃）
9. git status .opencode/ .gitignore 能让用户清楚看到所有改动

仅跑阶段 5.5（"补 gitignore"）完成后：

1. 项目根 .gitignore 存在或被显式放弃
2. 若 .init-done 已存在，其 gitignore_generated 字段被更新
3. 其他 .opencode/ 内容零改动

---

框架整合流程（Template Integration）

本清单是框架整合的唯一检核入口。当在实际项目中创建了新的跨项目级别能力，需要合并回本模板时，Agent 必须按本清单逐项执行，不得跳过任何一步。

触发关键词

整合到框架 / 合并到模板 / 加入框架白名单 / template integration / framework sync / 规模化这个 Skill / 沉淀到模板

执行流程

1. 识别整合类型：判断本次整合属于下方哪一（或几）类
2. 逐项执行该类的全部检核项：打勾即改，不可只记 "后续补充"
3. 交叉验证：执行完成后，用"框架截面自检"反向核对每项是否存在
4. 生成报告：列出每个检核项的完成状态

---

整合类型与检核清单

类型 1：新增基础设施 Skill

触发条件：在项目中创建了一个服务于 opencode 自身元系统的新 Skill（非项目业务 Skill）

#	检核项	操作
1.1	Skill 目录存在 SKILL.md 且含正确 YAML frontmatter	强制：第一行必须是 ---，必须含 name: 字段，必须正确闭合。缺失 frontmatter 会导致 opencode 无法注册该 Skill（"Skill not found"），即使文件存在、registry 有注册、AGENTS.md 有引用。
1.2	canonical-manifest.json → canonical_skills	首选更新目标：在 JSON 数组中追加新 Skill 目录路径
1.3	opencode-init 规范清单 → Skills 白名单	在 ### Skills（规范 Skill 目录白名单） 下新增条目（与 1.2 保持同步）
1.4	opencode-init 清理清单 → 阶段 3	检查：新 Skill 如有数据文件，需在 B 组重置列表新增条目
1.5	epee-orchestrator/registry.md	新增条目（格式见 registry.md 注释），类型标注 基础设施 或 个人级
1.6	AGENTS.md	检查：新 Skill 是否被 AGENTS.md 引用？若有，引用路径是否正确？
1.7	opencode.json → instructions	检查：新 Skill 是否有数据文件需要注入到会话上下文？若有，追加路径
1.8	Skill 自迭代日志	新 Skill 必须包含 ## 自迭代日志 章节（空白即可）

类型 2：新增数据文件

触发条件：新增或修改了 .opencode/data/ 下的数据文件（changelog/deferred/pitfalls/distillery/profile/spec-docs 等）

#	检核项	操作
2.1	canonical-manifest.json → template_data_files 或 template_phase_files	首选更新目标：在 JSON 对应数组中追加新数据文件路径。phase 阶段数据文件归入 template_phase_files，其余归入 template_data_files
2.2	opencode-init 规范清单 → 数据占位目录 / 阶段数据占位目录	在对应目录下新增路径（与 2.1 保持同步）
2.3	opencode-init 清理清单 → B 组重置列表	在阶段 3 的 B 组表格中新增一行
2.4	opencode-init → 模板内容	新增该文件的模板内容（最小化版本，含占位注释）
2.5	opencode.json → instructions	若该数据文件应注入会话上下文，追加到 instructions 数组
2.6	skill-tester/static-checks/run.py → MANIFEST_TO_INIT_SECTION	若新增了 manifest JSON 分组（非单文件），在 run.py 的映射表中新增条目。meta-check 会自动检测未映射的分组
2.7	所属 Skill 的 SKILL.md	若数据文件归属某个 Skill，该 Skill 应引用正确的文件路径

类型 3：新增运行时依赖

触发条件：新增或修改了 .opencode/package.json 中的 dependencies

#	检核项	操作
3.1	canonical-manifest.json → canonical_opencode_top	确认 .opencode/package.json + .opencode/package-lock.json 在 JSON 中
3.2	opencode-init 规范清单 → 顶层	确认 .opencode/package.json + .opencode/package-lock.json 在顶层 canonical 列表中（与 3.1 保持同步）
3.3	.opencode/.gitignore	确保 不 包含 package.json 和 package-lock.json（这些是基础设施文件，应被 git 跟踪）
3.4	npm install 后 package-lock.json 变更	提醒用户提交更新后的 package-lock.json
3.5	根目录 .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 必须运行此自检：逐一检查以下 "截面"，确认所有被引用的组件在对应位置都存在。

截面	检查方式
canonical-manifest.json VS canonical_skills	glob .opencode/skills/*/ → 不在 manifest 中且非项目级 → 警告
canonical-manifest.json VS template_data_files	glob .opencode/data/**/* → 不在 manifest 中 → 警告
canonical-manifest.json VS template_phase_files	glob .opencode/phase/**/*.md + .opencode/phase/*.json → 不在 manifest 中 → 警告
canonical-manifest.json VS disk	manifest 中的路径 → glob/read 验证文件存在
Skill frontmatter 完整性	遍历所有 SKILL.md → 验证第一行 ---、含 name: 字段、正确闭合
AGENTS.md 引用的 Skill	grep Skill 名 → 必须在 canonical-manifest.json → canonical_skills 中
AGENTS.md 引用的数据文件	grep 文件路径 → 必须在 canonical-manifest.json → template_data_files 或 template_phase_files 中
AGENTS.md 引用的 docs/ 文档	glob 检查文件存在
opencode.json → instructions 所列路径	read 逐条验证文件存在
opencode.json → instructions 所列路径	必须在 canonical-manifest.json 的 template_data_files 或 canonical_opencode_top 中
epee-orchestrator/registry.md 注册的 Skill	glob 检查对应 SKILL.md 存在
epee-orchestrator/registry.md 注册的 Skill	必须在 canonical-manifest.json → canonical_skills 中
.opencode/skills/ 下的 Skill 目录	若不在 epee-orchestrator/registry.md 中 → 缺失注册
.opencode/skills/ 下的 Skill 目录	若不在 canonical_skills 中且非项目级 → 警告
.opencode/data/ 下的数据文件	若不在 template_data_files 中 → 警告
.opencode/phase/ 下的数据文件	若不在 template_phase_files 中 → 警告
.opencode/data/ 下的数据文件	若需要注入上下文 → 检查是否在 opencode.json → instructions 中

整合自检执行规则

1. 先整合后自检：先完成所有类型检核项的修改，再跑截面自检
2. 自检发现缺口 → 回到对应类型的检核清单补充，不可手动修补绕过
3. 每项自检必须输出结果：✅ 通过 / ❌ 缺失：<具体描述> / ⚠️ 跳过：<原因>
4. 任何 ❌ 结果必须在最终报告前修复
5. 运行 Layer 1 静态检查：python .opencode/skills/skill-tester/static-checks/run.py，7 项检查必须全部通过。脚本验证 manifest↔init↔registry↔SKILL.md 之间的交叉引用一致性。meta-check（第0项）会自动检测 manifest 新增分组是否被覆盖——如有 FAIL，先在 run.py 的 MANIFEST_TO_INIT_SECTION 中补充映射再重跑。

---

自迭代日志

本节记录使用本 Skill 过程中发现的必要检查项。

已知必要检查

1. 阶段 2 的 C 组归位前必须先做 dry-run 展示 —— 批量移动文件是高破坏性操作，只要有一条分类错误就会污染 canonical 结构，必须让用户在列表上逐条过一遍再执行。

2. 重名冲突不许直接覆盖 —— C 组与 A 组重名时，A 组（模板版本）永远是 source of truth，冲突文件只能进 _init-backup/，让用户自行决定是否把差异合并回规范文件。

3. registry 重建时先读后写 —— 阶段 4 不要直接用硬编码模板覆盖 registry.md，必须先解析现有条目，只移除项目级条目、补齐缺失条目，避免丢失已有条目。

4. .init-done 是完成度契约 —— 只有阶段 6 验证通过后才能写入此文件。中途 abort 必须让 sentinel 缺失，这是保证下次会话能恢复触发的关键设计。

5. .gitignore 用户主导 —— 阶段 5.5 对语言栈/IDE/OS 的判断完全来自用户问卷，不要根据文件探测"智能推断"，因为新项目此时通常还是空白，推断不准反而会填错条目。