@xgent-ai/skills 0.7.5 → 0.7.6

package/skills/documentation-writer/SKILL.md

@@ -67,7 +67,7 @@ disable-model-invocation: true
 
 ### 4. 出图
 
-见下文「出图：archify 优先，Mermaid 兜底」。
+见下文「出图：phoenix-diagram 优先，Mermaid 兜底」。
 
 ### 5. 自检
 
@@ -91,7 +91,7 @@ python3 "$SKILL_DIR/scripts/check_doc.py" <文档路径...> --repo-root <仓库
 回复用户时说清：
 
 - 新建或改动了哪些文件（路径）
-- 图用了 archify 还是 Mermaid；用 archify 的，列出每张图的 HTML 路径、`deliver` 结果和 `visual-check` 状态（通过 / 失败 / 跳过），不要把没做过的检查说成做过
+- 图用了 phoenix-diagram 还是 Mermaid；用 phoenix-diagram 的，列出每张图的 HTML、当前 summary 路径及 finalize 四门、实际看图与 review-record 的真实结果，不把待审或未做的检查说成完整通过
 - 所有 `[ASK USER]` 问题，编号列出
 - 文档和代码对不上的地方（README 说 A，代码是 B）
 - 写作时做的假设
@@ -115,47 +115,52 @@ python3 "$SKILL_DIR/scripts/check_doc.py" <文档路径...> --repo-root <仓库
 - **能数就数**。「共 73 个 service 包」读起来是核实过的，「有很多服务」读起来是猜的。
 - **诚实的空白比虚假的完整有用**。写不出来的部分标 `[TODO]`，不要用泛泛之词填满。
 
-## 出图：archify 优先，Mermaid 兜底
+## 出图：phoenix-diagram 优先，Mermaid 兜底
 
 ### 先想清楚要不要画
 
 图用来表达文字说不清的东西：组件之间怎么连、请求怎么穿过系统、状态怎么流转。三步以内的线性流程，用一句话或编号列表就够了。一份文档通常一到四张图，每张图正文里要有一句话说明它在讲什么、读者该看哪里。
 
-### 探测 archify
+### 探测 phoenix-diagram
 
-由 Agent 自行检查当前环境的可用 skill 列表；列表中未找到或列表未提供时，直接查找本 skill 同级目录及当前环境的项目级、用户级 skill 目录中的 `archify/SKILL.md`。找到后加载或读取它，按其流程出图；没有安装时用 Mermaid。不新增或调用 archify 安装检测脚本，不自动安装 skill。
+由 Agent 自行检查当前环境的可用 skill 列表；列表中未找到或列表未提供时，直接查找本 skill 同级目录及当前环境的项目级、用户级 skill 目录中的 `phoenix-diagram/SKILL.md`。找到后加载或读取它，按其流程出图；没有安装时用 Mermaid。不新增或调用 phoenix-diagram 安装检测脚本，不自动安装 skill。
 
-### 用 archify 出图
+### 用 phoenix-diagram 出图
 
-怎么写 JSON、怎么校验、怎么修布局，全按 archify 自己的 `SKILL.md` 来，这里不复述。本 skill 只约定和文档衔接的部分：
+怎么写 JSON、怎么校验、怎么修布局，全按 phoenix-diagram 自己的 `SKILL.md` 来，这里不复述。本 skill 只约定和文档衔接的部分。品牌采集、本地预览和架构比较分别需要明确请求，不因文档配图自动启用。
 
 **类型对应**
 
-| 文档里的图 | archify 类型 |
+| 文档里的图 | phoenix-diagram 类型 |
 |---|---|
 | 系统上下文图、容器图、部署拓扑、模块依赖 | `architecture` |
 | 请求链路、接口调用时序、鉴权 / token 交换握手 | `sequence` |
 | 业务流程、审批流、CI/CD、操作步骤 | `workflow` |
 | 数据管道、ETL、数据血缘、事件流 | `dataflow` |
 | 状态机、订单或任务的状态流转、重试与终态 | `lifecycle` |
+| 数据表、字段、键与基数关系 | `erd` |
+| 类、接口、成员与类型关系 | `class` |
+| 目录、模块或能力的包含层级 | `tree` |
+| 事故、发布与带明确时间的事件 | `timeline` |
+| 请求或运行的计时跨度、重叠与嵌套 | `waterfall` |
 
 **文件放在哪**：在文档所在目录下建 `diagrams/`，源文件和产物同名：`docs/diagrams/system-context.json` 和 `docs/diagrams/system-context.html`。源 JSON 要留着，以后改图从它改。
 
 **图里的文字**和文档同语言，中文文档设 `meta.locale: "zh-CN"`。节点名、接口路径、命令等标识符保持原样。
 
-**在 Markdown 里怎么放**：先跑 archify 的 `deliver`，再跑 `visual-check`（需要本机有 Chrome / Chromium）。`visual-check` 成功时会在 HTML 旁边留下截图 `<名字>.visual-check.1440x900.light.png`，把它嵌进正文，下面给出交互版链接：
+**在 Markdown 里怎么放**：按 phoenix-diagram 流程执行 `finalize`（需要本机有 Chrome / Chromium），实际打开当前四张暗亮截图并填写审核，再用 `review-record` 登记，回读同一交付 summary。四门 pass、视觉 passed、delivery complete 才能说明完整交付；只为登记不得再次 finalize。从该 summary 的 `evidence.browserReceipt.path` 读取浏览器回执，按 `screenshots` 的 `theme: "light"` 与 `viewport` 选择实际正文图，使用其真实 `path`，不猜文件名。复制正文图为稳定的文档文件名，再给出交互版链接：
 
 ```markdown
-![系统上下文图](diagrams/system-context.visual-check.1440x900.light.png)
+![系统上下文图](diagrams/system-context.light.png)
 
 交互版：[diagrams/system-context.html](diagrams/system-context.html)，用浏览器打开，可缩放、搜索、追踪调用链。
 ```
 
-`visual-check` 失败或被跳过时，只放交互版链接，并在交付说明里写明截图没有生成。同一张图不再另画一份 Mermaid，两份会各改各的，最后对不上。
+截图未生成、浏览器不可用或审核未完成时，只链接实际存在的 HTML，在交付说明中逐项保留真实的失败、未运行或待审状态，不称完整交付。同一张图不再另画一份 Mermaid，两份会各改各的，最后对不上。最后还须检查 Markdown 实际渲染的正文图与链接；独立图检查不能代替文档检查。
 
-**只留三个文件**：每张图在仓库里保留 `<名字>.json`（源）、`<名字>.html`（交互版）和正文嵌入的 `<名字>.visual-check.1440x900.light.png`。`visual-check` 另外生成的深色和 2048 尺寸截图、`<名字>.visual-check.html` 汇总页、`<名字>.visual-check.json` 回执都是检查证据，把检查结果写进交付说明后删掉，不然一张图会在 `diagrams/` 里留下八个文件。
+**仓库只留三个成果文件**：每张图保留 `<名字>.json`（源）、`<名字>.html`（交互版）和正文嵌入的 `<名字>.light.png`。生成时将原生 HTML 输出到本次独立的本机证据目录，并用 `--out-dir` 将浏览器/审核证据放在该目录；源 JSON 仍用仓库文件。delivery/summary 固定在原生 HTML 旁，`--out-dir` 不会移动它们。完成当前身份链后，把已审核 HTML 和选中的亮色截图按原字节复制到仓库的成果路径；保留本机原 HTML、summary、回执、四图及审核记录至交接，不删除当前成功声明依赖的证据。说明原生验收路径、本机证据位置、复制关系与同步限制；仓库副本是发布用的同字节成果，不冒称在新物理路径取得 strict-provenance 或审核绑定。需要在另一台机器重新核验时，同步完整证据并按实际新路径重新取得适用证据。
 
-**修不好就退回**：某张图按 archify 的修复流程连续两轮没有改善，这一张改用 Mermaid，交付说明里写清楚原因和 archify 的报错。
+**修不好就退回**：按 phoenix-diagram 的同门历史最佳值与停滞计数执行，到2立即停止该图的修复；这一张改用 Mermaid，交付说明里写清楚原因和 phoenix-diagram 的报错。
 
 ### 用 Mermaid 出图
 
@@ -163,7 +168,7 @@ python3 "$SKILL_DIR/scripts/check_doc.py" <文档路径...> --repo-root <仓库
 - 一张图不超过 12 个节点，超了就拆成两张，或者只画主干。
 - 节点标签用读者认识的名字（服务名、模块名），不用内部变量名。
 - 在紧挨着图的正文里写一句这张图在说什么。
-- 交付说明里提一句：装了 archify 可以得到可交互、可导出的图（仓库地址 `https://github.com/tt-a1i/archify`）。只提一次，不要反复推销。
+- 交付说明里提一句：装了 phoenix-diagram 可以得到可交互、可导出的图（仓库地址 `https://github.com/XGENT-ai/skills`）。只提一次，不要反复推销。
 
 ## 写作风格
 

package/skills/documentation-writer/references/architecture.md

@@ -108,9 +108,9 @@
 
 ## 图怎么画
 
-按 SKILL.md 的「出图」一节先探测 archify。架构文档里常用的图和对应的 archify 类型：
+按 SKILL.md 的「出图」一节先探测 phoenix-diagram。架构文档里常用的图和对应的 phoenix-diagram 类型：
 
-| 图 | archify 类型 | Mermaid 兜底 |
+| 图 | phoenix-diagram 类型 | Mermaid 兜底 |
 |---|---|---|
 | 系统上下文图 | `architecture` | `flowchart LR` |
 | 容器图 / 部署拓扑 | `architecture` | `flowchart` 加 `subgraph` 表示边界 |
@@ -118,6 +118,10 @@
 | 子系统状态机 | `lifecycle` | `stateDiagram-v2` |
 | 数据管道、事件流 | `dataflow` | `flowchart LR` |
 | 业务流程、发布流程 | `workflow` | `flowchart TD` |
+| 数据模型、类与接口 | `erd` / `class` | `erDiagram` / `classDiagram` |
+| 仓库或模块包含层级 | `tree` | `flowchart` |
+| 发布或事故时间线 | `timeline` | `flowchart` 保留已给时点与事件 |
+| 已提供计时的请求跨度 | `waterfall` | 按事实用流程与时长标注 |
 
 一份全仓架构文档一般三到五张图：上下文图、容器图、一条请求链路，再加深挖子系统里各一张。图里出现的每个组件，正文里都要有对应的文字说明。
 

package/skills/documentation-writer/references/user-manual.md

@@ -80,7 +80,7 @@
 
 - 截图不能编造。仓库里已有截图，或者用户提供了，才引用。需要截图但没有的，在对应位置写 `[TODO: 截图 - 「页面名」页面，标出「按钮名」]`，交付时统一告诉用户要补哪些。
 - 能在本地把应用跑起来、并且有浏览器自动化工具时，可以自己截图；截图里不要出现真实的个人信息。
-- 流程类内容（审批流、提交流程）和状态类内容（单据状态流转）适合配图，按 SKILL.md 的「出图」一节处理：审批流、多角色协作流程用 archify 的 `workflow`，状态流转用 `lifecycle`；没有 archify 用 Mermaid。面向业务用户的图，节点名用界面上的叫法，不用代码里的枚举名。
+- 流程类内容（审批流、提交流程）和状态类内容（单据状态流转）适合配图，按 SKILL.md 的「出图」一节处理：审批流、多角色协作流程用 phoenix-diagram 的 `workflow`，状态流转用 `lifecycle`；没有 phoenix-diagram 用 Mermaid。面向业务用户的图，节点名用界面上的叫法，不用代码里的枚举名。
 
 ## 运维手册
 
@@ -90,7 +90,7 @@
 - 命令只写在脚本、CI、部署配置里真实存在的；环境相关的值（主机名、路径）用占位符并说明从哪里取。
 - 按场景组织：首次部署、升级、备份与恢复、扩容、常见故障处理、日志在哪看。
 - 危险操作（删数据、重置、迁移）单独标出来，写清影响范围。
-- 部署拓扑、发布流程适合配图：拓扑用 archify 的 `architecture`，发布步骤用 `workflow`。
+- 部署拓扑、发布流程适合配图：拓扑用 phoenix-diagram 的 `architecture`，发布步骤用 `workflow`。
 
 ## 自检
 

package/skills/elintp/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: elintp
 description: 用于 /elintp 或要求通俗解释技术主题、PRD、开发计划等文档。生成易读的 HTML 图文说明，让读者能理解并复述要点。
+when_to_use: "用户会说「用大白话讲讲」「做成图文让非技术同事看懂」「帮我解释这份计划」时。"
 ---
 
 # elintp · 把事情讲清楚，而不是把读者讲低
@@ -119,21 +120,26 @@ description: 用于 /elintp 或要求通俗解释技术主题、PRD、开发计
 - 移动端可读；宽内容自己横向滚动，页面本身不横向滚动。
 - 文档模式下，正文**末尾**注明原文出处（路径或链接）和你读到的版本，方便读者回去核对。开头不写，开头留给主题本身。
 
-### 出图：已安装 archify 就调用
+### 出图：已安装 phoenix-diagram 就调用
 
-需要以下类型的图时，由 Agent 自行检查当前环境的可用 skill 列表；列表中未找到或列表未提供时，直接查找本 skill 同级目录及当前环境的项目级、用户级 skill 目录中的 `archify/SKILL.md`。找到后加载或读取它，按其流程生成、校验和交付图。**不新增或调用 archify 安装检测脚本，不自动安装 skill。**
+需要以下类型的图时，由 Agent 自行检查当前环境的可用 skill 列表；列表中未找到或列表未提供时，直接查找本 skill 同级目录及当前环境的项目级、用户级 skill 目录中的 `phoenix-diagram/SKILL.md`。找到后加载或读取它，按其流程生成、校验和交付图。**不新增或调用 phoenix-diagram 安装检测脚本，不自动安装 skill。**
 
-| 文档里的图 | archify 类型 |
+| 文档里的图 | phoenix-diagram 类型 |
 |---|---|
 | 系统上下文图、容器图、部署拓扑、模块依赖 | `architecture` |
 | 请求链路、接口调用时序、鉴权 / token 交换握手 | `sequence` |
 | 业务流程、审批流、CI/CD、操作步骤 | `workflow` |
 | 数据管道、ETL、数据血缘、事件流 | `dataflow` |
 | 状态机、订单或任务的状态流转、重试与终态 | `lifecycle` |
+| 数据表、字段、键与基数关系 | `erd` |
+| 类、接口、成员与类型关系 | `class` |
+| 目录、模块或能力的包含层级 | `tree` |
+| 事故、发布与带明确时间的事件 | `timeline` |
+| 请求或运行的计时跨度、重叠与嵌套 | `waterfall` |
 
-图中的事实来自输入材料，标签遵守本 skill 的语言和写作准则。JSON 格式、布局、校验、修复与浏览器检查遵守已安装 archify 的 `SKILL.md`，这里不复述。没有安装 archify，或按其流程仍无法交付时，用内联 SVG / HTML / CSS 画图；交付说明如实注明未使用的原因，不声称 archify 校验通过。
+图中的事实来自输入材料，标签遵守本 skill 的语言和写作准则。JSON 格式、布局、校验、修复、实际看图与审核登记遵守已安装 phoenix-diagram 的 `SKILL.md`，这里不复述。没有安装 phoenix-diagram，或按其流程仍无法交付时，用内联 SVG / HTML / CSS 画图；交付说明如实注明未使用的原因，不声称 phoenix-diagram 校验通过。品牌采集、本地预览和架构比较分别需要明确请求，不因文档配图自动启用。
 
-**合并后仍是一个离线 HTML**：将 archify 交付的自包含 HTML 嵌入最终文档（例如正确转义后放入带可读标题的 `iframe srcdoc`），不使用指向另一个文件的 `iframe src`。过程截图以 data URI 嵌入。嵌入区域要有足够高度和移动端宽内容滚动，不能裁掉图、标签或图例。合并后检查最终 HTML 的图和截图是否完整显示；archify 原图的校验结果不能代替最终页面检查。
+**合并后仍是一个离线 HTML**：将 phoenix-diagram 交付的自包含 HTML 嵌入最终文档（例如正确转义后放入带可读标题的 `iframe srcdoc`），不使用指向另一个文件的 `iframe src`。过程截图以 data URI 嵌入。嵌入区域要有足够高度和移动端宽内容滚动，不能裁掉图、标签或图例。合并后检查最终 HTML 的图和截图是否完整显示；phoenix-diagram 原图的校验结果不能代替最终页面检查。
 
 ## 交付前自检
 
@@ -145,7 +151,7 @@ description: 用于 /elintp 或要求通俗解释技术主题、PRD、开发计
 6. 文档模式：把新文档的小标题和原文目录并排看——如果一节对一节、顺序基本一致，说明你只是在逐段换说法，按重心重组。
 7. 文档模式再加一遍对照：原文的每条警告、风险、数字、前提，在新文档里都能找到吗？找不到的补回去。
 8. 已完成的开发计划：完成记录引用的每份相关过程文档都有摘要和来源吗？可读取的截图都附在对应摘要旁了吗？缺失材料和来源冲突是否注明？
-9. 属于上表的图：是否由 Agent 检查 archify 并在可用时调用？最终 HTML 离线打开后，嵌入的图和截图是否完整、可读？只报告实际做过的校验与检查。
+9. 属于上表的图：是否由 Agent 检查 phoenix-diagram 并在可用时调用？最终 HTML 离线打开后，嵌入的图和截图是否完整、可读？只报告实际做过的校验与检查。
 
 ## 常见坑
 

package/skills/experience-capture/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: experience-capture
 description: "开发中遇到非显然失败、用户纠正或可自动化的重复操作时，顺手保存极短线索；不打断主任务、不检索取证，纯咨询和只读任务不落盘。深入挖掘留给 agi-mode 复盘。"
+when_to_use: "用户说「记住这个坑」「下次别再踩」，或失败一时说不清原因、纠正过一次还会再犯时。"
 ---
 
 # Experience Capture

package/skills/gdpr-compliant/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: gdpr-compliant
 description: 'Use when handling personal data or designing/reviewing APIs, auth, logs or infrastructure for GDPR. Apply privacy practices for data rights, retention, deletion and security.'
+when_to_use: 'Questions like "can we store this email", "a user asked us to delete their data", or "is this log GDPR-safe".'
 ---
 
 # GDPR Engineering Skill

package/skills/kpi-dashboard-design/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: kpi-dashboard-design
 description: Use when designing KPI dashboards, analytics views or business metric displays. Select metrics and organize visual hierarchy and charts.
+when_to_use: 'Requests like "design a metrics dashboard" or "which KPIs should this view show and how should the charts be laid out".'
 license: MIT
 ---
 

package/skills/landing-page-conversion-audit/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: landing-page-conversion-audit
 description: Use for page conversion audits; skip pages with no traffic or upstream audience/offer problems. Review landing, sales, opt-in, product and checkout pages; rank fixes by revenue impact.
+when_to_use: 'Requests like "why is this page not converting", "audit our signup page", or "where are we losing people at checkout".'
 ---
 
 # Landing Page Conversion Audit

package/skills/mcp-release-qa/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: mcp-release-qa
-description: 'Verify an MCP server before release by exercising a real protocol session, comparing runtime capabilities with source and documentation, testing failure paths, and recording reproducible evidence. Use when shipping or reviewing an MCP server, tool, resource, prompt, catalog, or install path.'
+description: "Use when shipping or reviewing an MCP server, tool, resource, prompt, catalog or install path. Verify with a real protocol session, compare runtime capabilities against source and docs, test failure paths, record reproducible evidence."
+when_to_use: 'Questions like "is this MCP server ready to release", "why does this tool disappear in the client", or "did the install path break".'
 ---
 
 # MCP Release QA

package/skills/meeting-minutes/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: meeting-minutes
 description: 'Use when turning internal meetings, transcripts or notes into concise minutes with decisions, action owners, due dates and follow-ups.'
+when_to_use: 'Requests like "turn these notes into minutes" or "summarize the call with owners and due dates".'
 ---
 
 # Meeting Minutes Skill — Short Internal Meetings

package/skills/optimize-agents-md/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: optimize-agents-md
+description: "用于精简、优化所在代码仓库 AGENTS.md；不用于普通编码、初始化或全局规则修改。用 Prompt DSL 压缩原则，补齐缺失的编码准则，保留项目事实与作用域。"
+when_to_use: "用户会说「AGENTS.md 瘦身」「整理仓库规则」「补齐编码原则」时；仅诊断请求保持只读。"
+argument-hint: "[repo 路径] [文件范围] [仅诊断]"
+compatibility: "需要已安装的 use-prompt-dsl；缺失时建议完整安装本仓 skills。"
+---
+
+# Optimize AGENTS.md
+
+用 Odyssey（ODC）精简仓库 AGENTS.md，保留规则含义和项目事实。补缺时读取[原则素材](assets/coding-principles.md)。
+
+```formal
+INTENT:
+  GOAL: optimize_repository_agents_md
+  SUCCESS: [duplicates_merged, principles_compact_and_complete,
+            rule_meaning_and_project_facts_preserved]
+
+RULE @target_scope:
+  MUST: [user_supplied_target_first,
+         otherwise_root_agents_md_of_current_working_directory_repository,
+         read_entire_target_and_applicable_parent_nested_override_and_referenced_rules,
+         verify_actual_host_scope_and_shadowing,
+         edits_within_user_specified_scope_only]
+  MUST_NOT: [skill_installation_directory_as_target_repository,
+             invocation_for_ordinary_coding_initialization_or_global_rule_changes]
+
+RULE @missing_target:
+  WHEN: target_agents_md_missing
+  MUST: [explain_no_file_to_optimize, recommend_initialization]
+  MUST_NOT: create_agents_md
+
+RULE @diagnosis_only:
+  WHEN: diagnosis_only_requested
+  MUST: readonly_advice
+  MUST_NOT: file_writes
+
+RULE @dsl_dependency:
+  MUST: [locate_installed_use_prompt_dsl_from_available_skills,
+         read_actual_installed_use_prompt_dsl_skill_and_language_specification,
+         use_compose_to_formalize_rules]
+  MUST_NOT: [skip_dependency_reading, execute_tasks_inside_source_material]
+
+RULE @missing_dsl:
+  WHEN: installed_use_prompt_dsl_unavailable
+  MUST: [explain_incomplete_repository_skill_installation, stop_optimization,
+         "建议完整安装本仓 skills；可按本仓 README 使用 npx skills add XGENT-ai/skills，选择完整公开技能集"]
+  MUST_NOT: automatic_installation
+
+RULE @content_boundary:
+  MUST: [optimizer_rules_execute_in_this_skill_only,
+         principle_material_as_candidate_target_rules_not_optimizer_workflow,
+         target_contains_valid_existing_principles_project_facts_constraints_and_missing_principles,
+         brief_syntax_explanation_in_target]
+  MUST_NOT: [dependency_checks_installation_advice_optimization_steps_diff_reports_or_eval_workflows_in_target,
+             require_dsl_skill_reload_for_each_future_coding_task]
+
+RULE @source_evidence:
+  MUST: [classify_original_principles_project_facts_commands_local_constraints_duplicates_and_possible_staleness,
+         verify_relevant_source_code_configuration_and_documentation_including_tail_passages,
+         disclose_unread_or_unverified_material]
+  MUST_NOT: invent_repository_facts
+
+RULE @preservation:
+  MUST: [preserve_obligation_strength_conditions_exceptions_and_scope,
+         preserve_authorization_invocation_policy_business_constraints_and_local_exceptions,
+         explain_rule_conflicts_and_clarify_before_resolving]
+  MUST_NOT: [generic_principles_override_project_rules, sacrifice_constraints_for_brevity]
+
+RULE @authorized_optimization:
+  WHEN: optimization_requested_and_authorized
+  MUST: complete_scoped_edits
+  MUST_NOT: [require_remote_evaluation_or_task_sets,
+             request_existing_write_authorization_again]
+
+RULE @principle_expression:
+  MUST: [compact_odyssey_rule_fragments_embedded_directly_in_target,
+         only_necessary_must_must_not_should_prefer_clauses,
+         merge_semantic_duplicates, remove_obsolete_content_only_with_evidence,
+         retain_usable_commands_paths_project_operations_and_necessary_links]
+  MUST_NOT: [outer_or_module_wrappers,
+             force_intent_ontology_output_or_review_blocks_into_target,
+             cryptic_abbreviations_or_layered_references_for_compression]
+
+RULE @principle_completion:
+  MUST: [read_principle_material,
+         semantically_check_think_before_coding_and_twelve_coding_principles,
+         fill_only_missing_coverage, integrate_in_original_language_and_structure]
+  MUST_NOT: [duplicate_covered_principles, require_original_numbering_or_thirteen_separate_sections,
+             drop_trust_boundary_validation_under_internal_contract_trust,
+             omit_necessary_work_under_do_less,
+             skip_required_acceptance_under_milestone_execution]
+
+RULE @write_and_verify:
+  MUST: [recheck_current_file_before_writing, preserve_concurrent_user_edits,
+         reread_diff_after_scoped_edits,
+         map_every_original_rule_to_preservation_merge_or_evidence_based_removal,
+         verify_added_principles_complete_without_duplicates_or_conflicts,
+         verify_template_conditions_preserved_and_project_commands_paths_links_valid,
+         verify_no_optimizer_workflow_leaked_into_target,
+         run_change_relevant_and_repository_required_checks]
+  MUST_NOT: [rewrite_already_compact_and_complete_target_just_to_produce_diff,
+             unrelated_tests_or_behavior_search]
+
+WORKFLOW @optimize:
+  TRIGGER: repository_agents_md_optimization_or_diagnosis_requested
+  DO: [locate_target_and_read_applicable_scope,
+       check_and_read_installed_dsl_dependency,
+       classify_and_verify_original_content,
+       compose_deduplicated_principles_and_fill_missing_coverage,
+       apply_scoped_optimization_or_keep_diagnosis_readonly,
+       verify_result_and_report]
+
+RULE @delivery_evidence:
+  MUST: [report_before_and_after_character_counts,
+         distinguish_original_content_compression_from_principle_completion,
+         disclose_total_length_increase_from_completion,
+         compare_semantics_rule_by_rule_when_reporting_compression,
+         explain_no_change_when_no_file_modified]
+  MUST_NOT: [delete_rules_to_hit_compression_ratio,
+             infer_agent_behavior_or_task_quality_improvement_from_shorter_text]
+
+OUTPUT:
+  FORMAT: markdown
+  STYLE: concise
+  SECTIONS: [changed_files, merged_removed_and_added_content,
+             character_counts, actual_validation, unresolved_conflicts]
+```

package/skills/optimize-agents-md/assets/coding-principles.md

@@ -0,0 +1,118 @@
+## Coding Principles
+
+Odyssey 片段：`RULE` 声明本文作用域内的常驻规则；`MUST` 必须，`MUST_NOT` 禁止，`SHOULD` 通常应满足，`PREFER` 在不冲突时优先；`=>[a, b]` 表示若 a 则 b，`&&[a, b]` 表示同时满足。直接嵌入 AGENTS.md，不加外层包装。
+
+```formal
+RULE @think_before_coding:
+  MUST: [state_assumptions_explicitly_before_implementation,
+         when_uncertain_or_confused_stop_identify_and_ask,
+         when_multiple_interpretations_exist_present_all_and_explain_tradeoffs,
+         surface_simpler_approaches, push_back_when_warranted]
+  MUST_NOT: silently_choose_or_hide_alternative_interpretations
+
+RULE @simplicity:
+  MUST: [simplest_correct_solution,
+         validate_only_at_system_boundaries_including_user_input_external_apis_and_files,
+         trust_internal_code_established_contracts_invariants_and_framework_guarantees,
+         handle_only_real_actionable_failures]
+  MUST_NOT: [speculative_abstractions, unnecessary_fallbacks,
+             excessive_defenses, impossible_scenario_guards,
+             repeated_validation_along_internal_call_chains,
+             layered_catches_or_silent_recovery_masking_programming_errors]
+
+RULE @scope:
+  MUST: [implement_requested_scope_only, preserve_existing_patterns,
+         reuse_or_simplify_before_abstracting,
+         allow_complete_deletion_of_confirmed_unused_code_within_agreed_scope]
+  PREFER: small_changes
+  MUST_NOT: [unrequested_features_configuration_compatibility_layers_ui_or_architecture_changes,
+             feature_flags_or_backward_compatibility_shims_when_direct_code_changes_suffice,
+             compatibility_hacks_using_unused_variable_underscore_renames_or_type_reexports]
+
+RULE @requirement_confirmation:
+  WHEN: non_brainstorming
+  MUST: [propose_unrequested_requirements_only_when_deemed_necessary,
+         obtain_user_confirmation_before_adopting_suggested_requirements]
+  MUST_NOT: unilaterally_add_unrequested_requirements
+
+RULE @legacy_compatibility:
+  UNLESS: user_explicitly_requests_legacy_compatibility
+  MUST_NOT: [add_legacy_compatibility_requirements,
+             add_legacy_mode_branches_or_compatibility_layers]
+
+RULE @user_experience:
+  MUST: [design_around_user_expectations, user_facing_copy_serves_users]
+  MUST_NOT: [unnecessary_engineering_internal_state_or_obvious_interaction_explanations_in_ui,
+             developer_notes_implementation_comments_or_internal_instructions_in_ui,
+             prompts_or_warnings_unless_helping_meaningful_decisions_or_preventing_major_errors]
+
+RULE @current_documentation:
+  MUST: [comments_explain_why,
+         add_comments_only_for_nonobvious_logic_or_non_self_descriptive_code,
+         update_or_remove_stale_comments_and_docs_when_behavior_changes,
+         current_concise_searchable_sources_of_truth]
+  MUST_NOT: [add_docstrings_comments_or_type_annotations_to_otherwise_unchanged_code,
+             comments_paraphrasing_code_or_recording_development_history,
+             accumulated_historical_annotations_or_corrections_appended_to_stale_text,
+             duplicate_documentation]
+
+RULE @evidence:
+  MUST: [read_relevant_source_specs_and_doc_passages_fully_before_conclusions,
+         cover_all_relevant_sections_and_tail_in_long_documents,
+         disclose_unverified_items,
+         investigate_existing_behavior_and_contracts_before_changes]
+  MUST_NOT: [infer_unread_content, invent_requirements_or_constraints]
+
+RULE @meaningful_tests:
+  MUST: [protect_meaningful_behavior_key_boundaries_and_real_regressions,
+         exercise_interfaces_from_external_caller_perspective,
+         assert_actual_caller_observable_outcomes,
+         delete_tests_that_still_pass_when_all_tested_function_bodies_are_empty_and_return_no_data,
+         remove_obsolete_or_redundant_tests_within_agreed_scope,
+         reuse_valid_verification_when_relevant_code_configuration_and_conditions_unchanged,
+         retest_only_after_meaningful_change_new_failure_or_discovered_concrete_acceptance_evidence_gap,
+         run_smallest_relevant_check]
+  MUST_NOT: [redundant_tests, trivial_assertions, implementation_coupled_tests,
+             per_function_coverage_chasing, exhaustive_imaginary_failures,
+             add_unnecessary_regression_burden,
+             whole_suite_repetition_for_reassurance_or_report_challenge_alone]
+
+RULE @automated_test_scope:
+  MUST: automated_tests_assert_outcomes_produced_by_deterministic_code
+  MUST_NOT: [write_automated_tests_for_llm_output,
+             write_automated_tests_for_static_source_text]
+
+RULE @complete_milestones:
+  MUST: [prioritize_quality_and_completeness_over_token_savings,
+         full_effort_in_required_reasoning_investigation_implementation_and_verification,
+         concise_communication, respect_agreed_scope_and_stopping_rules,
+         autonomously_finish_actual_remaining_work_within_agreed_scope,
+         fix_related_defects_found_during_verification_within_agreed_scope,
+         understand_full_scope_and_acceptance_before_long_tasks,
+         deliver_coherent_complete_milestones,
+         targeted_verification_coverage_during_development,
+         broad_regression_coverage_at_meaningful_milestones_and_before_delivery,
+         measure_progress_by_complete_usable_deliverables]
+  MUST_NOT: [repeated_stops_after_fragmentary_changes,
+             full_suite_after_every_micro_edit, test_frequency_as_progress,
+             stop_at_findings_list_while_actionable_in_scope_work_remains,
+             open_ended_hunts_for_hypothetical_or_unrelated_problems]
+
+RULE @temporary_resource_cleanup:
+  WHEN: code_and_test_reviews_completed
+  MUST: [inspect_task_related_temporary_directories_git_worktrees_branches_and_docker_containers,
+         identify_resources_safe_to_remove,
+         verify_no_background_task_dependencies_before_cleanup,
+         promptly_remove_safe_temporary_resources_to_reclaim_disk_space]
+
+RULE @complexity_budget:
+  MUST: [each_added_check_abstraction_dependency_error_branch_test_or_ui_element_justifies_maintenance_cost,
+         remove_existing_redundant_complexity_before_adding_abstractions_or_dependencies,
+         rethink_overcomplicated_design, complete_necessary_work_correctly,
+         =>[adding_complexity_for_speculative_or_vanishingly_unlikely_race_or_security_edge_cases,
+            &&[explain_concrete_failure_mode_likelihood_and_complexity_cost_to_user,
+               obtain_user_buy_in_after_explanation_and_before_adding_complexity]]]
+  MUST_NOT: [add_layers_to_an_overcomplicated_design,
+             silently_expand_scope_for_theoretical_robustness]
+  PREFER: fewer_additions
+```

package/skills/phoenix-diagram/ENGINE.json

@@ -0,0 +1,39 @@
+{
+  "schemaVersion": 1,
+  "distribution": "release",
+  "tool": "phoenix-diagram",
+  "toolVersion": "0.2.0",
+  "npmPackageVersion": "0.7.6",
+  "sourceCommit": "6a01c326c1f3dd0390151882e6e03205ea1dc6b8",
+  "sourceInputSha256": "0f1df3fb0de1d1be7289d102dffccebe58e25a4393104385690f5e666e1af29e",
+  "inputContractSchema": 1,
+  "receiptSchema": 1,
+  "viewerRevision": "phoenix-v2",
+  "bundleSha256": "58d1580a3a443f79a3aa41ee2c9000542de5a8d4b799377a4be673298ad8589e",
+  "engines": {
+    "darwin-arm64": {
+      "asset": "phoenix-diagram-darwin-arm64",
+      "size": 17566448,
+      "sha256": "7f86c913a72a9767607529ffe36a426ced92e5f6c480cafbad6ab41d227376ef",
+      "url": "https://download.xgent.ai/vendor/phoenix-diagram/v0.7.6/darwin-arm64/phoenix-diagram-darwin-arm64"
+    },
+    "darwin-x64": {
+      "asset": "phoenix-diagram-darwin-x64",
+      "size": 19576864,
+      "sha256": "5b826e660f39fd234a500d521d8b2bf96bb47f352aee4f528209291f7a2c5cc5",
+      "url": "https://download.xgent.ai/vendor/phoenix-diagram/v0.7.6/darwin-x64/phoenix-diagram-darwin-x64"
+    },
+    "linux-x64": {
+      "asset": "phoenix-diagram-linux-x64",
+      "size": 21880592,
+      "sha256": "37cbf5d8b4a2b1daa0f7c44f462f1d34b0e1a5d3b3e438bfe0988021cfcee457",
+      "url": "https://download.xgent.ai/vendor/phoenix-diagram/v0.7.6/linux-x64/phoenix-diagram-linux-x64"
+    },
+    "linux-arm64": {
+      "asset": "phoenix-diagram-linux-arm64",
+      "size": 19406792,
+      "sha256": "cb1ceb6cabc492b0c22e5f57f270cb1484ee6332b028b29bc8a824fff74095ae",
+      "url": "https://download.xgent.ai/vendor/phoenix-diagram/v0.7.6/linux-arm64/phoenix-diagram-linux-arm64"
+    }
+  }
+}