helloagents 3.0.9-beta.1 → 3.0.10

package/skills/commands/plan/SKILL.md

@@ -1,20 +1,20 @@
 ---
 name: ~plan
-description: 结构化规划工作流 — 需求澄清、方案收敛、任务分解与方案包生成（~plan 命令）
+description: 结构化规划工作流 — 需求澄清、方案确认、任务分解与方案包生成（~plan 命令）
 policy:
   allow_implicit_invocation: false
 ---
 Trigger: ~plan [description]
 
-`~plan` 是实现前的主规划命令。它负责需求澄清、方案设计、任务拆解与方案落盘；直接显式执行 `~plan` 时，默认停在“形成可执行方案”，只有用户明确授权继续时才衔接执行。
-执行 `~plan` 时，通用阶段边界按当前已加载 bootstrap 执行；本 skill 负责补充 `~plan` 的需求澄清、方案收敛、方案包写入与执行衔接要求。
-`.helloagents/` 在本 skill 中统一按项目级存储路径理解：`STATE.md` 与 `.ralph-*.json` 保持项目本地；若当前上下文中的“当前项目存储”给出 `state_path`，本轮恢复快照统一读写该路径；若 `project_store_mode=repo-shared`，知识库、`DESIGN.md` 与 `plans/` / `archive/` 按当前上下文中已注入的项目知识/方案目录解析。
+`~plan` 是实现前的主规划命令。它负责需求澄清、方案设计、任务拆解与方案写入；直接显式执行 `~plan` 时，默认停在“形成可执行方案”，只有用户明确授权继续时才继续执行。
+执行 `~plan` 时，通用阶段边界按当前已加载 bootstrap 执行；本 skill 负责补充 `~plan` 的需求澄清、方案确认、方案包写入与继续执行要求。
+`.helloagents/` 在本 skill 中统一按项目级存储路径理解：状态文件只使用 `state_path`，`.ralph-*.json` 保持项目本地；若 `project_store_mode=repo-shared`，知识库、`DESIGN.md` 与 `plans/` / `archive/` 按当前上下文中已注入的项目知识/方案目录解析。
 
 ## 铁律
 - 在用户确认方案之前，禁止编写任何实现代码、创建任何实现文件、或执行任何实现操作
 - 需求澄清阶段不读取实现类技能（hello-ui / hello-test / hello-verify 等），需求明确后再按需读取
-- 方案必须收敛为可执行产物，不停留在泛化建议
-- 若当前链路来自 `~auto`，则“开始执行”视为已包含在 `~auto` 授权内；方案包落地后默认继续衔接执行，只有命中阻塞判定时才停下
+- 方案必须整理为可执行产物，不停留在泛化建议
+- 若当前任务来自 `~auto`，则“开始执行”视为已包含在 `~auto` 授权内；方案包写入后默认继续执行，只有命中阻塞判定时才停下
 - 涉及 UI 时，当前方案包中的 UI 决策优先于 `.helloagents/DESIGN.md`；`.helloagents/DESIGN.md`（按当前项目存储模式解析）优先于通用 UI 规则
 
 ## 流程
@@ -22,7 +22,7 @@ Trigger: ~plan [description]
 ### 1. 上下文收集与需求澄清准备
 
 已有项目：
-- 按当前已加载 bootstrap 的“.helloagents/ 文件读取优先级”和“项目文件”规则恢复上下文；若当前消息显式继续既有链路，或会话刚经历恢复 / 压缩，先把 `.helloagents/STATE.md` 当恢复快照使用（若当前项目存储给出 `state_path`，则优先读取该当前会话的 `STATE.md`），再用当前用户消息、显式命令、活跃方案包 / PRD 与代码事实校正主线
+- 按当前已加载 bootstrap 的“.helloagents/ 文件读取优先级”和“项目文件”规则恢复上下文；若当前消息明确要继续上次任务，或会话刚经历恢复 / 压缩，先读取 `state_path`，再用当前用户消息、显式命令、活跃方案包 / PRD 与代码事实确认当前任务
 - 在需求澄清前，至少确认 `.helloagents/context.md`、`.helloagents/guidelines.md`（按当前项目存储模式解析）；涉及 UI 时，如存在 `.helloagents/DESIGN.md`（按当前项目存储模式解析），一并读取现有设计契约
 - 只扫描与当前需求直接相关的代码文件，用于形成假设和识别约束
 
@@ -49,7 +49,7 @@ Trigger: ~plan [description]
 - 选项必须体现当前前沿水准
 - 每个选项都要有具体、可执行的视觉特征描述
 
-### 3. 方案收敛
+### 3. 方案确认
 
 基于已确认需求，给出 2-3 个可行方案：
 - 每个方案说明架构思路与关键取舍
@@ -81,12 +81,12 @@ Trigger: ~plan [description]
   - `tasks.md`
   - `contract.json`
 - 写 `contract.json` 时，至少落成以下字段：`verifyMode`、`reviewerFocus`、`testerFocus`；涉及 UI 时再写 `ui.required`、`ui.designContract` 与 `ui.sourcePriority`
-- 只有在 UI 方向确需前置收敛时，才额外写 `ui.styleAdvisor.required`、`ui.styleAdvisor.reason` 与 `ui.styleAdvisor.focus`；它复用 `.helloagents/.ralph-advisor.json`，不是默认常驻步骤
+- 只有在 UI 方向确需先明确时，才额外写 `ui.styleAdvisor.required`、`ui.styleAdvisor.reason` 与 `ui.styleAdvisor.focus`；它复用 `.helloagents/.ralph-advisor.json`，不是默认常驻步骤
 - 只有在 UI 验收确有收益时，才额外写 `ui.visualValidation.required`、`ui.visualValidation.reason`、`ui.visualValidation.screens` 与 `ui.visualValidation.states`；不要把视觉验收扩成所有 UI 任务的固定步骤
 - 只有在 `T3`、非 UI 的高风险审查或确需额外跨模型建议时，才写 `advisor.required`、`advisor.reason`、`advisor.focus` 与 `advisor.preferredSources`；不要把 advisor 变成默认常驻流程
 - 使用 `scripts/plan-contract.mjs write` 写 `contract.json`，不要让后续检查脚本再从 `plan.md` 的自然语言说明里猜验证主路径
 - 涉及 UI 的项目：生成或更新 `.helloagents/DESIGN.md`（按当前项目存储模式解析）；若原文件不存在，先按模板建立最小设计契约，再写入已确认的稳定设计决策
-- 重写当前会话的 `STATE.md`（优先取当前项目存储中的 `state_path`，未注入时回退 `.helloagents/STATE.md`），其中“主线目标”写当前规划链路真正要完成的目标，不把旧任务残留为当前主线
+- 重写 `state_path`，其中“主线目标”写本次规划要完成的目标，不保留其他任务的内容
 
 知识库完整创建与归档按当前已加载 bootstrap 的后续规则执行。
 
@@ -95,10 +95,10 @@ Trigger: ~plan [description]
 展示方案摘要后，仅在是否进入执行仍构成阻塞决策时才询问用户：
 - 开始执行 → 继续进入 `~build`
 - 修改方案 → 返回方案细化
-- 暂不执行，保留方案 → 更新 `STATE.md`；“主线目标”写当前已确认方案要解决的问题，下一步写为“方案已确认；执行需用户明确启动”
+- 暂不执行，保留方案 → 更新 `state_path`；“主线目标”写当前已确认方案要解决的问题，下一步写为“方案已确认；执行需用户明确启动”
 
-如果用户已明确表示继续执行，则视为授权成立，可直接衔接执行。
-如果当前链路来自 `~auto`，且方案包已足够支撑实现、也未命中阻塞判定，则默认直接进入 `~build`，不再追加一次“是否开始执行”的询问。
+如果用户已明确表示继续执行，则视为授权成立，可直接继续执行。
+如果当前任务来自 `~auto`，且方案包已足够支撑实现、也未命中阻塞判定，则默认直接进入 `~build`，不再追加一次“是否开始执行”的询问。
 
 ## 方案包要求
 

package/skills/commands/prd/SKILL.md

@@ -7,16 +7,16 @@ policy:
 Trigger: ~prd [description]
 
 执行 `~prd` 时，不读取 `~plan` 的 command skill；只有当前流程明确需要时，才继续读取对应的 hello-* 技能。
-执行 `~prd` 时，通用阶段边界按当前已加载 bootstrap 执行；本 skill 负责补充规格探索、PRD 落盘与执行衔接要求。
-`.helloagents/` 在本 skill 中统一按项目级存储路径理解：`STATE.md` 与 `.ralph-*.json` 保持项目本地；若当前上下文中的“当前项目存储”给出 `state_path`，本轮恢复快照统一读写该路径；若 `project_store_mode=repo-shared`，知识库、`DESIGN.md` 与 `plans/` / `archive/` 按当前上下文中已注入的项目知识/方案目录解析。
+执行 `~prd` 时，通用阶段边界按当前已加载 bootstrap 执行；本 skill 负责补充规格探索、PRD 写入与继续执行要求。
+`.helloagents/` 在本 skill 中统一按项目级存储路径理解：状态文件只使用 `state_path`，`.ralph-*.json` 保持项目本地；若 `project_store_mode=repo-shared`，知识库、`DESIGN.md` 与 `plans/` / `archive/` 按当前上下文中已注入的项目知识/方案目录解析。
 
 ## 铁律
 - 在用户确认方案之前，禁止编写任何实现代码、创建任何文件、或执行任何实现操作。
 - 每个维度的选项必须体现当前前沿水准。若当前已加载 bootstrap 含审美/体验规则则遵循其要求；否则至少给出具体、可执行、非泛化的视觉特征，不确定时主动搜索查阅。
 - 用户说"跳过"某维度 → 跳过，不生成该文件。不强迫用户讨论不关心的维度。
 - 大项目检测：涉及多个独立子系统时，先帮用户分解为子项目，每个子项目走独立的 ~prd 循环。
-- 若当前链路来自 `~auto`，则 PRD / 任务 / 契约落地后默认继续衔接后续执行；只有真实阻塞时才停在规格阶段。
-- 涉及 UI 时，`prd/03-ui-design.md` 负责沉淀本次产品/功能的 UI 决策；项目级稳定设计契约同步写入 `.helloagents/DESIGN.md`（按当前项目存储模式解析）
+- 若当前任务来自 `~auto`，则 PRD / 任务 / 契约写入后默认继续执行；只有真实阻塞时才停在规格阶段。
+- 涉及 UI 时，`prd/03-ui-design.md` 负责记录本次产品/功能的 UI 决策；项目级稳定设计契约同步写入 `.helloagents/DESIGN.md`（按当前项目存储模式解析）
 
 ## PRD 维度清单
 
@@ -58,7 +58,7 @@ Trigger: ~prd [description]
 ### 1. 上下文收集
 
 已有项目：
-- 按当前已加载 bootstrap 的“.helloagents/ 文件读取优先级”和“项目文件”规则恢复上下文；若当前消息显式继续既有链路，或会话刚经历恢复 / 压缩，先把 `.helloagents/STATE.md` 当恢复快照使用（若当前项目存储给出 `state_path`，则优先读取该当前会话的 `STATE.md`），再用当前用户消息、显式命令、活跃方案包 / PRD 与代码事实校正主线
+- 按当前已加载 bootstrap 的“.helloagents/ 文件读取优先级”和“项目文件”规则恢复上下文；若当前消息明确要继续上次任务，或会话刚经历恢复 / 压缩，先读取 `state_path`，再用当前用户消息、显式命令、活跃方案包 / PRD 与代码事实确认当前任务
 - 在进入维度探索前，至少确认 `.helloagents/context.md`、`.helloagents/guidelines.md`，并只扫描与当前产品范围直接相关的代码和配置
 
 全新项目（无 .helloagents/ 目录）：
@@ -102,26 +102,26 @@ c. AI 总结该维度的决策结果，进入下一个维度
 - 按 templates/plans/prd/ 的模板格式，仅写入用户未跳过的维度文件
 - 生成 tasks.md（每个任务包含具体文件路径、预期变更、完成标准、验证方式；任务独立可验证；依赖顺序明确）
 - 生成 decisions.md（贯穿全程的决策日志）
-- 生成 `contract.json`（至少包含 `verifyMode`、`reviewerFocus`、`testerFocus`；涉及 UI 时补 `ui.required`、`ui.designContract`、`ui.sourcePriority`；仅在确需前置审美收敛时再补 `ui.styleAdvisor.required`、`ui.styleAdvisor.reason`、`ui.styleAdvisor.focus`；仅在确需视觉验收时再补 `ui.visualValidation.required`、`ui.visualValidation.reason`、`ui.visualValidation.screens`、`ui.visualValidation.states`；仅在确需独立 advisor 时，再补 `advisor.required`、`advisor.reason`、`advisor.focus`、`advisor.preferredSources`）
+- 生成 `contract.json`（至少包含 `verifyMode`、`reviewerFocus`、`testerFocus`；涉及 UI 时补 `ui.required`、`ui.designContract`、`ui.sourcePriority`；仅在确需先明确审美方向时再补 `ui.styleAdvisor.required`、`ui.styleAdvisor.reason`、`ui.styleAdvisor.focus`；仅在确需视觉验收时再补 `ui.visualValidation.required`、`ui.visualValidation.reason`、`ui.visualValidation.screens`、`ui.visualValidation.states`；仅在确需独立 advisor 时，再补 `advisor.required`、`advisor.reason`、`advisor.focus`、`advisor.preferredSources`）
 - 使用 `scripts/plan-contract.mjs write` 写 `contract.json`，不要只把验证路径留在自然语言说明里
 - 涉及 UI 的项目：生成或更新 `.helloagents/DESIGN.md`（按当前项目存储模式解析）；若原文件不存在，先按模板建立最小设计契约，再同步已确认的稳定 UI 决策
-- 重写当前会话的 `STATE.md`（优先取当前项目存储中的 `state_path`，未注入时回退 `.helloagents/STATE.md`），其中“主线目标”写当前 PRD 链路真正要完成的产品 / 功能目标，不延续无关旧主线
+- 重写 `state_path`，其中“主线目标”写本次 PRD 要完成的产品 / 功能目标，不保留其他任务的内容
 
 输出 PRD 完整度摘要：已覆盖 N/13 个维度，建议后续补充的维度（如有）。
 
 ### 5. 执行决策
 
 展示 PRD 摘要后，仅在是否进入执行仍构成阻塞决策时才询问用户：
-- 开始执行 → 重写 `STATE.md`（“主线目标”保持当前 PRD 目标，下一步设为第一个任务的具体动作）
+- 开始执行 → 重写 `state_path`（“主线目标”保持当前 PRD 目标，下一步设为第一个任务的具体动作）
 - 修改 PRD / 补充维度 → 回到对应维度继续讨论
-- 暂不执行，保留方案 → 重写 `STATE.md`（“主线目标”保持当前 PRD 目标，下一步设为“方案已确认；执行需用户明确启动”）
+- 暂不执行，保留方案 → 重写 `state_path`（“主线目标”保持当前 PRD 目标，下一步设为“方案已确认；执行需用户明确启动”）
 
-如果用户已对当前 PRD 或继续执行作出明确同意，视为执行授权成立，可直接进入执行，或按需先补一轮 `~plan` 收敛实现方案。
-如果当前链路来自 `~auto`，且 PRD 已收敛到可执行任务、也未命中阻塞判定，则默认继续进入 `~build`，必要时先补一轮轻量 `~plan`，不再额外询问一次“是否开始执行”。
+如果用户已对当前 PRD 或继续执行作出明确同意，视为执行授权成立，可直接进入执行，或按需先补一轮 `~plan` 明确实现方案。
+如果当前任务来自 `~auto`，且 PRD 已整理成可执行任务、也未命中阻塞判定，则默认继续进入 `~build`，必要时先补一轮轻量 `~plan`，不再额外询问一次“是否开始执行”。
 
-### 6. 执行衔接
+### 6. 继续执行
 
-按 tasks.md 逐项完成，每项进入当前已加载 bootstrap 中定义的统一执行流程，完成后同步重写 STATE.md。
+按 tasks.md 逐项完成，每项进入当前已加载 bootstrap 中定义的统一执行流程，完成后同步重写 `state_path`。
 任务状态标记仅写入 tasks.md、验收清单或验证结果；普通说明、方案解释、状态汇报不用 [√] / [-] / [ ]。
 所有任务完成后进入当前已加载 bootstrap 中定义的 VERIFY / CONSOLIDATE 收尾阶段。
 可并行的任务标记后用子代理并行执行（不同子代理不改同一文件）。

package/skills/commands/verify/SKILL.md

@@ -18,11 +18,11 @@ Trigger: ~verify [scope]
 1. 先决定验证分流：
    - 若当前上下文中已注入“验证分流”，先按该分流执行
    - 用户显式使用 `~review` 时，即使本轮没有注入分流，也按审查优先起步
-   - 若没有注入分流、也不是 `~review`，默认先做全量验证；执行中一旦发现高风险链路、关键权限/配置/迁移/发布边界或明显未覆盖的风险点，立即补做 `hello-review`
+   - 若没有注入分流、也不是 `~review`，默认先做全量验证；执行中一旦发现高风险流程、关键权限/配置/迁移/发布边界或明显未覆盖的风险点，立即补做 `hello-review`
 2. 审查优先模式：
    - 获取变更范围：无参数默认未提交变更；`staged` 代表暂存区；指定文件/目录则只审查对应范围
    - 按 hello-* 技能查找路径读取 `hello-review` SKILL.md，执行逐文件审查
-   - 高风险链路除显式范围外，还要主动补查相关配置、迁移、权限、部署或安全边界文件，不能只盯住单个功能文件
+   - 高风险流程除显式范围外，还要主动补查相关配置、迁移、权限、部署或安全边界文件，不能只盯住单个功能文件
    - 审查结论确定后，立即调用 `scripts/review-state.mjs write` 写 `.helloagents/.ralph-review.json`；用结构化字段记录 `outcome`、`conclusion`、`findings`、`fileReferences`，不要让后续检查脚本再从自然语言消息里猜结论
 3. 全量验证模式或审查后继续验证：
    - 读取 `hello-verify` SKILL.md
@@ -37,7 +37,7 @@ Trigger: ~verify [scope]
    - ❌ 失败的审查项 / 命令 + 错误详情
    - 合同核对结论：哪些需求 / 任务完成标准已满足，哪些仍未满足
    - 修复建议
-   - 高风险链路额外说明：不能把“命令通过”直接等同于“风险已解除”；若仍存在未验证的风险边界、待授权操作或不可逆步骤，必须明确列出并停下
+   - 高风险流程额外说明：不能把“命令通过”直接等同于“风险已解除”；若仍存在未验证的风险边界、待授权操作或不可逆步骤，必须明确列出并停下
 
 ## 失败处理
 - 有失败 → 逐个修复，修复后重新运行对应审查或验证

package/skills/commands/wiki/SKILL.md

@@ -9,14 +9,14 @@ Trigger: ~wiki
 `~wiki` 是用户显式命令，仅创建、补全或同步项目知识库。
 
 `~wiki` 是显式知识库命令，不受 `kb_create_mode` 限制。
-执行 `~wiki` 时，`.helloagents/` 目录结构、模板格式和 `STATE.md` 重写规则按当前已加载 bootstrap 执行；不写入项目级规则文件，也不创建项目级原生 skills 链接。
-`.helloagents/` 在本 skill 中统一按项目级存储路径理解：`STATE.md` 保持项目本地；若当前上下文中的“当前项目存储”给出 `state_path`，本轮恢复快照统一读写该路径；若 `project_store_mode=repo-shared`，`context.md`、`guidelines.md`、`verify.yaml`、`CHANGELOG.md`、`DESIGN.md`、`modules/` 改按当前上下文中已注入的项目知识目录写入。
+执行 `~wiki` 时，`.helloagents/` 目录结构、模板格式和状态文件重写规则按当前已加载 bootstrap 执行；不写入项目级规则文件，也不创建项目级原生 skills 链接。
+`.helloagents/` 在本 skill 中统一按项目级存储路径理解：状态文件只使用 `state_path`；若 `project_store_mode=repo-shared`，`context.md`、`guidelines.md`、`verify.yaml`、`CHANGELOG.md`、`DESIGN.md`、`modules/` 改按当前上下文中已注入的项目知识目录写入。
 
 ## 流程
 
 ### 阶段 1：基础准备（必做）
 
-1. 创建 `.helloagents/` 目录 + 当前 `STATE.md`（优先取当前项目存储中的 `state_path`，未注入时回退 `.helloagents/STATE.md`；按 templates/STATE.md 格式）；初始“主线目标”只写当前知识库初始化 / 同步目标，不把它写成长期项目总目标
+1. 创建 `.helloagents/` 目录 + `state_path`（按 templates/STATE.md 格式）；初始“主线目标”只写当前知识库初始化 / 同步目标，不把它写成长期项目总目标
 2. 追加 `.gitignore`（如果对应行不存在）：
    ```
    .helloagents/
@@ -29,7 +29,7 @@ Trigger: ~wiki
 
 检查项目是否有实际代码文件（非空项目）：
 - 有代码文件 → 执行完整知识库创建/补全（下方流程）
-- 空项目 → 保留 `.helloagents/` 和 `STATE.md`，告知用户“项目为空，其余知识文件将在后续开发或首次编码任务中补全”
+- 空项目 → 保留 `.helloagents/` 和 `state_path`，告知用户“项目为空，其余知识文件将在后续开发或首次编码任务中补全”
 
 知识库创建/补全流程（统一写入 `.helloagents/` 对应的项目级存储路径；`project_store_mode=repo-shared` 时实际落在共享知识目录）：
 1. 按 templates/ 目录的模板格式，分析项目代码库后创建或补全：
@@ -51,7 +51,7 @@ commands:
 ## 幂等性
 重复执行 `~wiki` 是安全的：
 - `.helloagents/` 缺失时创建，已存在时复用
-- `STATE.md` 按当前任务状态重写，不追加历史；它只记录当前知识库链路的恢复快照，不承担项目主线的唯一记忆
+- `state_path` 按当前任务状态重写，不追加历史；它只记录当前知识库任务，不承担项目的长期记忆
 - 知识库文件缺失时补全，已存在时按模板增量更新
 - `.gitignore` 只追加缺失行
 - 永不写入项目级规则文件，也不创建任何项目级原生 skills 链接

package/skills/hello-subagent/SKILL.md

@@ -4,7 +4,7 @@ description: 使用子代理执行任务、并行开发、分派工作时使用
 ---
 
 子代理编排必须遵循以下规范。
-`.helloagents/` 在本 skill 中统一按项目级存储路径理解：`STATE.md` 和 `.ralph-*.json` 保持项目本地；若 `project_store_mode=repo-shared`，方案包、`verify.yaml` 与 `DESIGN.md` 按当前上下文中已注入的项目知识/方案目录解析。
+`.helloagents/` 在本 skill 中统一按项目级存储路径理解：状态文件只使用 `state_path`，`.ralph-*.json` 保持项目本地；若 `project_store_mode=repo-shared`，方案包、`verify.yaml` 与 `DESIGN.md` 按当前上下文中已注入的项目知识/方案目录解析。
 
 ## 编码前
 先确定任务是否适合子代理（独立性高、边界清晰、可验证）。

package/skills/hello-ui/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: hello-ui
-description: 已进入显式 UI 工作流、已激活项目的视觉变更、设计系统改造或需要视觉验收时使用；在通用 UI 基线之上补充项目契约消费、设计系统映射与视觉验证。
+description: 已进入显式 UI 工作流、已激活项目的视觉变更、设计系统改造或需要视觉验收时使用；在通用 UI 基线之上补充项目契约执行、设计系统映射与视觉验证。
 ---
 
-本 skill 不是 UI 质量的唯一来源。当前已加载 bootstrap 中的 UI 质量基线负责所有 UI 任务的基础水准；本 skill 在显式 UI 工作流和深度 UI 任务中，补充更强的契约执行、实现映射与视觉验收。
+本 skill 不是 UI 质量的唯一来源。当前已加载 bootstrap 中的 UI 质量基线负责所有 UI 任务的基础水准；本 skill 在显式 UI 工作流和复杂 UI 任务中，补充更明确的契约执行、实现映射与视觉验收。
 `.helloagents/` 在本 skill 中统一按项目级存储路径理解：`.ralph-*.json` 等运行态证据保持项目本地；若 `project_store_mode=repo-shared`，`DESIGN.md` 与方案包按当前上下文中已注入的项目知识/方案目录解析。
 
 ## 适用边界
@@ -17,24 +17,24 @@ description: 已进入显式 UI 工作流、已激活项目的视觉变更、设
 3. 本 skill 的通用规则
 缺少上层产物时，才直接依赖下层规则；不得用通用审美覆盖已确认的项目契约。
 
-## 深层职责
-- 消费上游契约：把 `plan.md` / PRD / `DESIGN.md` 中已确认的 UI 决策视为强约束，而不是建议
-- 消费可选 UI 契约：若 `contract.json` 启用 `ui.styleAdvisor`，复用 `.helloagents/.ralph-advisor.json` 留下设计方向复查证据；若启用 `ui.visualValidation`，用 `.helloagents/.ralph-visual.json` 留下视觉验收证据
-- 映射到代码结构：明确 token 放在哪里、组件边界如何划分、状态组件如何组织、动效与主题如何落地
+## 核心职责
+- 遵循上游契约：把 `plan.md` / PRD / `DESIGN.md` 中已确认的 UI 决策视为强约束，而不是建议
+- 处理可选 UI 契约：若 `contract.json` 启用 `ui.styleAdvisor`，复用 `.helloagents/.ralph-advisor.json` 记录设计方向复查证据；若启用 `ui.visualValidation`，用 `.helloagents/.ralph-visual.json` 记录视觉验收证据
+- 映射到代码结构：明确 token 放在哪里、组件边界如何划分、状态组件如何组织、动效与主题如何实现
 - 做视觉验收闭环：优先使用截图/浏览器工具做桌面与移动端检查；没有工具时也要完成结构化视觉自检
 - 回写稳定决策：只把跨 feature 稳定成立的设计系统规则同步回 `.helloagents/DESIGN.md`（按当前项目存储模式解析），不要把一次性页面细节全部写成项目级契约
 
-## 深层设计 brief（编码前必须落定）
+## 设计简报（编码前必须明确）
 
-理解上下文，做出大胆且有意图的设计决策：
+先理解上下文，再做出大胆且有意图的设计决策：
 
 1. 目的：这个界面解决什么问题？谁在用？什么场景？什么平台？
-2. 美学方向：选择一个鲜明的方向并坚持到底。不从固定列表中选，而是根据项目的受众、场景和情感目标，创造一个忠于上下文的独特风格。问自己：这个产品的用户期待什么情绪？什么视觉语言能传达这种情绪？
+2. 美学方向：选择一个鲜明的方向并坚持到底。不套用固定风格标签，而是根据项目的受众、场景和情感目标，创造一个忠于上下文的独特风格。先问清楚：这个产品的用户期待什么情绪？什么视觉语言能传达这种情绪？
 3. 记忆点：用户看到这个设计会记住的一个特征是什么？
 4. 差异化：当任务明确要求探索，或缺少现成设计约束时，主动避免滑入常见默认风格；差异化必须服务产品语义、品牌边界与可用性，不为变化而变化。
 5. 设计 token：尽早建立变量/token 体系——背景色/表面色/主色/弱化色/强调色 + 展示/标题/正文/说明文字的字体角色。Web 用 CSS 变量，桌面/移动端用平台对应的主题系统。
-6. 约束定义：为当前项目定义具体约束（如最多几个区块、几种字体、几个强调色、首屏的 CTA 数量），约束释放创意。
-7. 真实内容：使用真实文案、产品信息、项目上下文，不使用 Lorem ipsum 或泛化占位符。真实内容帮助做出更贴合上下文的设计决策。
+6. 约束定义：为当前项目定义具体约束（如最多几个区块、几种字体、几个强调色、首屏的 CTA 数量），用约束帮助释放创意。
+7. 真实内容：使用真实文案、产品信息、项目上下文，不使用 Lorem ipsum 或泛化占位符。真实内容更容易帮助做出更贴合上下文的设计决策。
 
 执行顺序要求：
 - 已激活项目且存在 `.helloagents/DESIGN.md`（按当前项目存储模式解析）时，进入真实 UI 任务先读取它，再展开方案或实现
@@ -56,7 +56,7 @@ description: 已进入显式 UI 工作流、已激活项目的视觉变更、设
 ### 展示型页面（着陆页、营销页、产品展示页）
 
 第一屏构图：
-- 第一屏必须是一个完整构图，品牌/产品名必须是英雄级信号
+- 第一屏必须是一个完整构图，品牌/产品名必须是最明显的识别点
 - 品牌测试：如果去掉导航栏后第一屏可以属于任何品牌，说明品牌感太弱
 
 Hero 区域：
@@ -82,7 +82,7 @@ Hero 区域：
 
 - 卡片克制：默认不用卡片，卡片仅在作为交互容器时使用。去掉边框/阴影/背景/圆角后不影响理解的就不应该是卡片
 - 区块纪律：每个区块只做一件事，避免堆砌标签集群、统计条、图标行、多个竞争文本块
-- 真实视觉锚点：图像应展示产品、场所、氛围或上下文，装饰性渐变和抽象背景不算主视觉
+- 真实视觉重点：图像应展示产品、场所、氛围或上下文，装饰性渐变和抽象背景不算主视觉
 
 ## 视觉执行
 
@@ -182,7 +182,7 @@ Hero 区域：
 
 ## 复杂度匹配
 
-实现复杂度必须匹配美学愿景。大胆的设计需要丰富的代码，精致的设计需要克制和精确。优雅来自于执行愿景的质量，而非堆砌效果。根据上下文做出意外但合理的选择——展现真正的创造力。
+实现复杂度必须匹配设计目标。需要强表现力的界面，可以用更丰富的实现；需要克制的界面，就保持简洁和精确。不要为了效果堆效果，也不要为了求稳把设计做平，而是根据上下文做出意外但合理的选择——展现真正的创造力。
 
 ## 交付检查
 

package/skills/hello-verify/SKILL.md

@@ -11,7 +11,7 @@ description: 声称工作完成前、提交代码前、创建 PR 前、报告任
 没有运行验证命令 = 不能说"完成"、"通过"、"已修复"。
 没有看到验证输出 = 不能声称结果。
 
-## 验证循环（Ralph Loop）
+## 验证循环
 
 验证不是一次性操作，而是循环直到通过：
 
@@ -90,7 +90,7 @@ description: 声称工作完成前、提交代码前、创建 PR 前、报告任
 7. 若 `contract.json` 中 `ui.visualValidation.required=true`，额外确认 `.helloagents/.ralph-visual.json` 已存在、覆盖要求的关键 screens / states，且结论为 `PASS`；若没有视觉验收证据，不得把本轮视为 UI 可交付
 8. 发现遗漏 → 补充实现 → 重新验证
 
-## 反代理目标漂移 (APGD)
+## 目标偏移检查
 
 验证时必须区分真正目标和代理指标：
 - 真正目标：用户实际要解决的问题（功能正确、体验达标、需求满足）

package/skills/helloagents/SKILL.md

@@ -9,7 +9,7 @@ description: 每次对话开始时使用 — 建立质量驱动工作流，通
 子代理只豁免路由与收尾要求，直接执行任务；安全、质量、验证和失败处理规则仍持续生效，且不得包装 HelloAGENTS 外层输出格式。所有流式内容、进度或状态汇报、中间文本，以及任何仍将继续执行的文本，都不得触发外层格式。
 主代理在本轮最终收尾前，如要报告“已完成 / 等待输入 / 本轮阻塞”，必须先调用 `scripts/turn-state.mjs write` 写机器可读的 turn-state；不要让运行时再从自然语言或图标反推状态。子代理不得写 turn-state。
 
-`.helloagents/` 在所有 skill 中都统一按项目级存储路径理解：项目本地 `.helloagents/` 继续承担激活信号、`STATE.md` 与 `.ralph-*.json` 等运行态文件；若当前上下文中的“当前项目存储”给出 `state_path`，本轮读写恢复快照一律使用该路径（可能是会话级 `sessions/{branch}/{session}/STATE.md`），不要强行回写旧的 `.helloagents/STATE.md`；若 `project_store_mode=repo-shared`，`context.md`、`guidelines.md`、`DESIGN.md`、`verify.yaml`、`modules/`、`plans/`、`archive/` 改按当前上下文中已注入的“当前项目存储”/“项目知识/方案目录”解析，不要假定这些文件一定实际位于当前工作树中。
+`.helloagents/` 在所有 skill 中都统一按项目级存储路径理解：项目本地 `.helloagents/` 继续承担激活信号与 `.ralph-*.json` 等运行态文件；状态文件只使用 `state_path`（实际位于 `sessions/{branch}/{session-or-default}/STATE.md`）；若 `project_store_mode=repo-shared`，`context.md`、`guidelines.md`、`DESIGN.md`、`verify.yaml`、`modules/`、`plans/`、`archive/` 按当前上下文中已注入的“当前项目存储”/“项目知识/方案目录”解析，不要假定这些文件一定实际位于当前工作树中。
 
 ## 三重质量保障
 
@@ -26,7 +26,7 @@ description: 每次对话开始时使用 — 建立质量驱动工作流，通
 - 所有 UI 任务先受当前 bootstrap 的 UI 质量基线约束；已激活项目或显式 UI 工作流中的设计约束优先级固定为：当前 `plan.md` / PRD UI 决策 → `.helloagents/DESIGN.md`（按当前项目存储模式解析） → `hello-ui` 深层规则
 - 方案包存在 `contract.json` 时，验证分流、reviewer / tester 关注边界、可选 style advisor / visual validation 与交付检查优先按它执行，不再从自然语言总结里回推
 - 因阻塞判定而必须等待用户输入时，遵循当前 bootstrap 的等待输入规则，不得把等待输入包装成完成态
-- ~plan 的需求澄清与方案收敛不可跳过，不可一个问题就出方案
+- ~plan 的需求澄清与方案确认不可跳过，不可一个问题就出方案
 - ~prd 的维度探索不可跳过，每个激活维度必须经过讨论或用户明确跳过
 - ~auto 的复杂度判断不可省略
 - hello-verify 的验证铁律：没有运行验证 = 不能说完成
@@ -108,6 +108,7 @@ Layer 3 — 资源文件（技能内引用时读取）：
 - `~build`
 - `~prd`
 - `~loop`
+- `~wiki`
 - `~init`
 - `~test`
 - `~verify`

package/templates/plans/contract.json

@@ -19,7 +19,7 @@
     ],
     "styleAdvisor": {
       "required": false,
-      "reason": "{仅在 UI 方向尚未稳定、需要前置审美收敛时填写：为什么需要独立 style advisor}",
+      "reason": "{仅在 UI 方向尚未稳定、需要先明确审美方向时填写：为什么需要独立 style advisor}",
       "focus": [
         "{仅 ui.styleAdvisor.required=true 时填写：需要独立复查的设计方向、记忆点或视觉风险}"
       ]
@@ -37,7 +37,7 @@
   },
   "advisor": {
     "required": false,
-    "reason": "{仅在 T3 / UI / 高风险链路确有收益时填写：为什么需要独立 advisor}",
+    "reason": "{仅在 T3 / UI / 高风险流程确有收益时填写：为什么需要独立 advisor}",
     "focus": [
       "{仅 advisor.required=true 时填写：advisor 需要独立复查的边界}"
     ],