helloagents 3.0.2-beta.1 → 3.0.7

package/skills/commands/prd/SKILL.md

@@ -6,13 +6,16 @@ policy:
 ---
 Trigger: ~prd [description]
 
-本 skill 自包含，不依赖再读取 `~design` 的 command skill。只有在本 skill 明确要求时，才继续读取对应的 hello-* 技能。
+执行 `~prd` 时，不读取 `~plan` 的 command skill；只有当前流程明确需要时，才继续读取对应的 hello-* 技能。
+执行 `~prd` 时，通用阶段边界按当前已加载 bootstrap 执行；本 skill 负责补充规格探索、PRD 落盘与执行衔接要求。
+`.helloagents/` 在本 skill 中表示逻辑项目空间：`STATE.md` 与 `.ralph-*.json` 保持项目本地；若 `project_store_mode=repo-shared`，知识库、`DESIGN.md` 与 `plans/` / `archive/` 按当前会话注入的项目知识/方案目录解析。
 
 ## 铁律
 - 在用户确认方案之前，禁止编写任何实现代码、创建任何文件、或执行任何实现操作。
 - 每个维度的选项必须体现当前前沿水准。若当前已加载 bootstrap 含审美/体验规则则遵循其要求；否则至少给出具体、可执行、非泛化的视觉特征，不确定时主动搜索查阅。
 - 用户说"跳过"某维度 → 跳过，不生成该文件。不强迫用户讨论不关心的维度。
 - 大项目检测：涉及多个独立子系统时，先帮用户分解为子项目，每个子项目走独立的 ~prd 循环。
+- 涉及 UI 时，`prd/03-ui-design.md` 负责沉淀本次产品/功能的 UI 决策；项目级稳定设计契约同步写入逻辑 `.helloagents/DESIGN.md`（实际路径按当前项目存储模式解析）
 
 ## PRD 维度清单
 
@@ -51,12 +54,11 @@ Trigger: ~prd [description]
 
 ## 流程
 
-### 1. 上下文收集（ORIENT）
+### 1. 上下文收集
 
 已有项目：
-- 读取 .helloagents/context.md 获取项目上下文和模块索引
-- 读取 .helloagents/guidelines.md 获取项目约定
-- 扫描相关代码文件理解现有架构
+- 按当前已加载 bootstrap 的“.helloagents/ 文件读取优先级”和“项目文件”规则恢复上下文；若当前消息显式继续既有链路，或会话刚经历恢复 / 压缩，先把 `.helloagents/STATE.md` 当恢复快照使用，再用当前用户消息、显式命令、活跃方案包 / PRD 与代码事实校正主线
+- 在进入维度探索前，至少确认 `.helloagents/context.md`、`.helloagents/guidelines.md`，并只扫描与当前产品范围直接相关的代码和配置
 
 全新项目（无 .helloagents/ 目录）：
 - 跳过，直接进入项目定位
@@ -94,30 +96,32 @@ c. AI 总结该维度的决策结果，进入下一个维度
 ### 4. 写入方案包
 
 将讨论结果写入本地项目：
-- 全新项目（无 .helloagents/ 目录）：先创建 .helloagents/ 和 STATE.md（按 templates/STATE.md 格式）。这是方案包写入的前置操作，不受 kb_create_mode 开关控制
-- 创建 .helloagents/plans/YYYYMMDDHHMM_{feature}/prd/
+- 按当前已加载 bootstrap 的 `.helloagents/` 与流程状态规则，确保最小项目状态已建立；这是方案包写入的前置操作，不受 kb_create_mode 开关控制
+- 创建逻辑 `.helloagents/plans/YYYYMMDDHHMM_{feature}/prd/`
 - 按 templates/plans/prd/ 的模板格式，仅写入用户未跳过的维度文件
-- 生成 tasks.md（每个任务包含具体文件路径、预期变更、验证方式；任务独立可验证；依赖顺序明确）
+- 生成 tasks.md（每个任务包含具体文件路径、预期变更、完成标准、验证方式；任务独立可验证；依赖顺序明确）
 - 生成 decisions.md（贯穿全程的决策日志）
-- 涉及 UI 的项目：生成或更新 .helloagents/DESIGN.md
-- 重写 .helloagents/STATE.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`）
+- 使用 `scripts/plan-contract.mjs write` 写 `contract.json`，不要只把验证路径留在 prose 里
+- 涉及 UI 的项目：生成或更新逻辑 `.helloagents/DESIGN.md`；若原文件不存在，先按模板建立最小设计契约，再同步已确认的稳定 UI 决策
+- 重写 `.helloagents/STATE.md`，其中“主线目标”写当前 PRD 链路真正要完成的产品 / 功能目标，不延续无关旧主线
 
 输出 PRD 完整度摘要：已覆盖 N/13 个维度，建议后续补充的维度（如有）。
 
 ### 5. 执行决策
 
 展示 PRD 摘要后，仅在是否进入执行仍构成阻塞决策时才询问用户：
-- 开始执行 → 重写 STATE.md（下一步设为第一个任务的具体动作）
+- 开始执行 → 重写 `STATE.md`（“主线目标”保持当前 PRD 目标，下一步设为第一个任务的具体动作）
 - 修改 PRD / 补充维度 → 回到对应维度继续讨论
-- 暂不执行，保留方案 → 重写 STATE.md（下一步设为“方案已确认；执行需用户明确启动”）
+- 暂不执行，保留方案 → 重写 `STATE.md`（“主线目标”保持当前 PRD 目标，下一步设为“方案已确认；执行需用户明确启动”）
 
-如果用户已对当前 PRD 或继续执行作出明确同意，视为执行授权成立，直接进入执行，不再追加确认环节。
+如果用户已对当前 PRD 或继续执行作出明确同意，视为执行授权成立，可直接进入执行，或按需先补一轮 `~plan` 收敛实现方案。
 
-### 6. 执行
+### 6. 执行衔接
 
 按 tasks.md 逐项完成，每项进入当前已加载 bootstrap 中定义的统一执行流程，完成后同步重写 STATE.md。
 任务状态标记仅写入 tasks.md、验收清单或验证结果；普通说明、方案解释、状态汇报不用 [√] / [-] / [ ]。
-所有任务完成后进入当前已加载 bootstrap 中定义的 VALIDATE 阶段。
+所有任务完成后进入当前已加载 bootstrap 中定义的 VERIFY / CONSOLIDATE 收尾阶段。
 可并行的任务标记后用子代理并行执行（不同子代理不改同一文件）。
 执行过程中遇到阻塞（依赖缺失、指令不清、验证反复失败）→ 立即停下询问用户，不猜测。
 执行过程中遇到高风险操作（删除文件/修改配置/数据库变更）→ 暂停确认。
@@ -133,6 +137,7 @@ plans/YYYYMMDDHHMM_{feature}/
 │   ├── 01-user-stories.md  # 仅用户未跳过的维度
 │   ├── 02-functional.md
 │   └── ...
+├── contract.json           # 机器可消费的验证 / 审查 contract
 ├── tasks.md                # 任务分解
 └── decisions.md            # 决策日志
 ```

package/skills/commands/verify/SKILL.md

@@ -1,21 +1,44 @@
 ---
 name: ~verify
-description: 运行项目的所有验证命令并报告结果（~verify 命令）
+description: 验证总入口 — 审查、lint、typecheck、test、build 与修复循环（~verify 命令）
 policy:
   allow_implicit_invocation: false
 ---
-Trigger: ~verify
+Trigger: ~verify [scope]
 
 ## 流程
 
-1. 按 hello-* 技能查找路径读取 hello-verify SKILL.md，并按其“验证命令来源”优先级检测命令
-2. 逐个运行所有检测到的命令
-3. 收集每个命令的输出和退出码
+0. 先对齐当前工作流状态：
+   - 若当前上下文已注入“当前工作流约束”或“当前建议下一命令”，先服从它
+   - 即使命令通过，也不能越过当前方案包边界：不完整方案包不能视为可信交付记录，未闭合方案包不能被整体报告为已完成
+   - 当推荐路径已进入 `~verify` / 收尾时，优先把本命令用于审查、验真和交付收尾
+   - 若当前存在活跃方案包，先读取 `requirements.md`、`plan.md`、`tasks.md`、`contract.json`，把它们当作本轮验证契约；不要只看命令结果
+   - 若 `contract.json` 声明 `advisor.required=true` 或 `ui.styleAdvisor.required=true`，则本轮还必须补齐 `.helloagents/.ralph-advisor.json`；advisor / style advisor 都是可选能力，不是默认常驻步骤
+   - 若 `contract.json` 声明 `ui.visualValidation.required=true`，则本轮还必须补齐 `.helloagents/.ralph-visual.json`；视觉验收优先用截图/浏览器工具，没有工具时才降级为结构化代码级自检
+1. 先决定验证分流：
+   - 若当前上下文已注入“验证分流”，先按该分流执行
+   - 用户显式使用 `~review` 时，即使当前轮没有注入分流，也按审查优先起步
+   - 若没有注入分流、也不是 `~review`，默认先做全量验证；执行中一旦发现高风险链路、关键权限/配置/迁移/发布边界或明显未覆盖的风险点，立即补做 `hello-review`
+2. 审查优先模式：
+   - 获取变更范围：无参数默认未提交变更；`staged` 代表暂存区；指定文件/目录则只审查对应范围
+   - 按 hello-* 技能查找路径读取 `hello-review` SKILL.md，执行逐文件审查
+   - 高风险链路除显式范围外，还要主动补查相关配置、迁移、权限、部署或安全边界文件，不能只盯住单个功能文件
+   - 审查结论确定后，立即调用 `scripts/review-state.mjs write` 写 `.helloagents/.ralph-review.json`；用结构化字段记录 `outcome`、`conclusion`、`findings`、`fileReferences`，不要让 gate 再从自然语言消息里猜结论
+3. 全量验证模式或审查后继续验证：
+   - 读取 `hello-verify` SKILL.md
+   - 按其“验证命令来源”优先级检测命令
+   - 逐个运行所有检测到的命令
+   - 收集每个命令的输出和退出码
+   - 对照当前 contract 逐项核对：requirements 是否覆盖、tasks 中每项“完成标准”是否满足、`plan.md` 中风险与设计约束是否被验证、`contract.json` 中声明的 `verifyMode` / reviewer / tester 关注边界是否已被覆盖
+   - 若 `advisor.required=true` 或 `ui.styleAdvisor.required=true`，在进入收尾前调用 `scripts/advisor-state.mjs write` 写 `.helloagents/.ralph-advisor.json`；记录触发原因、focus、consultedSources、结论与建议，禁止只在自然语言里留一段 advisor 意见
+   - 若 `ui.visualValidation.required=true`，在进入收尾前调用 `scripts/visual-state.mjs write` 写 `.helloagents/.ralph-visual.json`；记录 `reason`、`tooling`、`screensChecked`、`statesChecked`、`status`、`summary`、`findings` 与 `recommendations`
 4. 汇总报告：
-   - ✅ 通过的命令
-   - ❌ 失败的命令 + 错误详情
+   - ✅ 通过的审查项 / 命令
+   - ❌ 失败的审查项 / 命令 + 错误详情
+   - 合同核对结论：哪些需求 / 任务完成标准已满足，哪些仍未满足
    - 修复建议
+   - 高风险链路额外说明：不能把“命令通过”直接等同于“风险已解除”；若仍存在未验证的风险边界、待授权操作或不可逆步骤，必须明确列出并停下
 
 ## 失败处理
-- 有失败 → 逐个修复，修复后重新运行验证
-- 全部通过 → 报告完成
+- 有失败 → 逐个修复，修复后重新运行对应审查或验证
+- 全部通过 → 进入当前已加载 bootstrap 的 CONSOLIDATE 收尾，再按交付边界报告完成

package/skills/commands/wiki/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: ~wiki
+description: 初始化或同步项目知识库（仅 `.helloagents/`，不写项目根载体）
+policy:
+  allow_implicit_invocation: false
+---
+Trigger: ~wiki
+
+`~wiki` 是用户显式命令，用于只创建、补全或同步项目知识库，不创建项目根 `AGENTS.md` / `CLAUDE.md` / `.gemini/GEMINI.md`，也不创建项目级 `skills/helloagents` symlink。适用于标准模式下希望保留项目目录为“非载体项目”，但仍希望当前项目拥有 `.helloagents/` 激活目录、`STATE.md` 和知识沉淀文件的场景。
+
+`~wiki` 是显式知识库命令，不受 `kb_create_mode` 限制。
+执行 `~wiki` 时，`.helloagents/` 目录结构、模板格式和 `STATE.md` 重写规则按当前已加载 bootstrap 执行；本命令只补充“只写知识库、不写项目根载体”的边界。
+`.helloagents/` 在本 skill 中表示逻辑项目空间：`STATE.md` 保持项目本地；若 `project_store_mode=repo-shared`，`context.md`、`guidelines.md`、`verify.yaml`、`CHANGELOG.md`、`DESIGN.md`、`modules/` 改按当前会话注入的项目知识目录写入。
+
+## 流程
+
+### 阶段 1：基础准备（必做）
+
+1. 创建 `.helloagents/` 目录 + `STATE.md`（按 templates/STATE.md 格式）；初始“主线目标”只写当前知识库初始化 / 同步目标，不把它写成长期项目总目标
+2. 追加 `.gitignore`（如果对应行不存在）：
+   ```
+   .helloagents/
+   ```
+3. 明确不执行以下操作：
+   - 不创建或更新项目根 `AGENTS.md`
+   - 不创建或更新项目根 `CLAUDE.md`
+   - 不创建或更新 `.gemini/GEMINI.md`
+   - 不创建项目级 `skills/helloagents` symlink
+
+### 阶段 2：知识库创建或补全（条件性）
+
+检查项目是否有实际代码文件（非空项目）：
+- 有代码文件 → 执行完整知识库创建/补全（下方流程）
+- 空项目 → 保留 `.helloagents/` 和 `STATE.md`，告知用户“项目为空，其余知识文件将在后续开发或首次编码任务中补全”
+
+知识库创建/补全流程（逻辑写入 `.helloagents/`；`project_store_mode=repo-shared` 时实际落在共享知识目录）：
+1. 按 templates/ 目录的模板格式，分析项目代码库后创建或补全：
+   - context.md — 按 templates/context.md 格式，填入项目概述、技术栈、架构、目录结构、模块链接
+   - guidelines.md — 按 templates/guidelines.md 格式，从现有代码推断编码约定
+   - verify.yaml — 验证命令（从 package.json/pyproject.toml 检测）
+   - CHANGELOG.md — 按 templates/CHANGELOG.md 格式创建或更新
+   - DESIGN.md — 如果项目包含 UI 代码，按 templates/DESIGN.md 格式提取或补全项目级设计契约（产品表面、设计 token、组件与模式、状态覆盖、无障碍要求、禁止事项等）
+2. 创建或补全 modules/ 目录，按 templates/modules/module.md 格式为主要模块生成文档
+3. 已存在的文件按模板格式增量更新，不自由改写结构；无新增信息时保持原样
+
+## verify.yaml 格式
+```yaml
+commands:
+  - npm run lint
+  - npm run test
+```
+
+## 幂等性
+重复执行 `~wiki` 是安全的：
+- `.helloagents/` 缺失时创建，已存在时复用
+- `STATE.md` 按当前任务状态重写，不追加历史；它只记录当前知识库链路的恢复快照，不承担项目主线的唯一记忆
+- 知识库文件缺失时补全，已存在时按模板增量更新
+- `.gitignore` 只追加缺失行
+- 永不写入项目根载体文件，也不创建项目级 `skills/helloagents` symlink

package/skills/hello-review/SKILL.md

@@ -27,6 +27,15 @@ description: 审查代码变更、检查 PR、review 代码质量，或用户要
 - 关注变更本身，不扩大审查范围到未修改的代码
 - 严重问题优先，建议性问题其次
 
+## 输出要求
+
+- 审查结束时必须单独给出一行“审查结论：...”
+- 若发现阻塞问题，结论中明确写出存在问题，并在正文中为每个问题附文件定位
+- 若未发现阻塞问题，明确写“审查结论：未发现阻塞问题。”
+- 若当前项目已激活，且本轮审查结果需要进入 gate / closeout，审查结论确定后立即调用 `scripts/review-state.mjs write` 写 `.helloagents/.ralph-review.json`
+- `.ralph-review.json` 必须使用结构化字段记录：`outcome`（`clean` / `findings`）、`conclusion`、`findings`、`fileReferences`
+- 不要依赖“审查结论：...”这行让运行时再从自然语言里猜机器结论；这行只服务于人类阅读
+
 ## 交付检查
 - [ ] 每个文件都已审查
 - [ ] 严重问题都有修复建议

package/skills/hello-subagent/SKILL.md

@@ -4,12 +4,13 @@ description: 使用子代理执行任务、并行开发、分派工作时使用
 ---
 
 子代理编排必须遵循以下规范。
+`.helloagents/` 在本 skill 中表示逻辑项目空间：`STATE.md` 和 `.ralph-*.json` 保持项目本地；若 `project_store_mode=repo-shared`，方案包、`verify.yaml` 与 `DESIGN.md` 按当前会话注入的项目知识/方案目录解析。
 
 ## 编码前
 先确定任务是否适合子代理（独立性高、边界清晰、可验证）。
 
 ## 派遣规范
-- 每个子代理获得：tasks.md 中的对应任务 + 方案包中的相关约束（~design: requirements.md + design.md；~prd: prd/ 中的相关维度文件 + decisions.md）+ 验证命令
+- 每个子代理获得：tasks.md 中的对应任务 + 方案包中的相关约束（~plan: requirements.md + plan.md；~prd: prd/ 中的相关维度文件 + decisions.md）+ 验证命令；涉及 UI 时，再附逻辑 `.helloagents/DESIGN.md` 或其中相关片段
 - 新鲜上下文：不继承主会话历史，避免上下文污染
 - 提示开头标记 [子代理任务]，让子代理跳过 bootstrap 加载
 - 单一职责：一个子代理只做一件事
@@ -17,8 +18,8 @@ description: 使用子代理执行任务、并行开发、分派工作时使用
 
 ## 协调规范
 - 使用子代理时，主代理作为控制器跟踪进度
-- 适用条件：主代理只有在本轮结束流式输出并最终收尾时才可使用 HelloAGENTS 外层输出格式。
-- 排除条件：团队协作中的进度与状态汇报都属于中间输出，不得包装 HelloAGENTS 外层输出格式。
+- 主代理只有在本轮最终收尾时才可使用 HelloAGENTS 外层输出格式。
+- 团队协作中的进度与状态汇报都属于中间输出，不得包装 HelloAGENTS 外层输出格式。
 - 子代理完成后执行双阶段审查：
   1. 需求符合性审查：变更是否符合方案包需求和 tasks.md 的要求？有无多做或少做？
   2. 代码质量审查：运行验证命令，审查代码质量

package/skills/hello-ui/SKILL.md

@@ -1,14 +1,30 @@
 ---
 name: hello-ui
-description: 构建任何界面（Web/桌面/移动/游戏 UI）时使用。强制执行独特的、生产级的设计规范，杜绝泛化 AI 美学。
+description: 已进入显式 UI 工作流、已激活项目的视觉变更、设计系统改造或需要视觉验收时使用；在通用 UI 内核之上补充项目契约消费、设计系统映射与视觉验证。
 ---
 
-构建任何用户界面时，必须遵循以下设计规范。
+本 skill 不是 UI 质量的唯一来源。当前已加载 bootstrap 中的 UI 质量内核负责所有 UI 任务的基础水准；本 skill 在显式 UI 工作流和深度 UI 任务中，补充更强的契约执行、实现映射与视觉验收。
+`.helloagents/` 在本 skill 中表示逻辑项目空间：`.ralph-*.json` 等运行态证据保持项目本地；若 `project_store_mode=repo-shared`，`DESIGN.md` 与方案包按当前会话注入的项目知识/方案目录解析。
 
 ## 适用边界
-本技能在涉及视觉变更时激活：构建新 UI、修改现有 UI 样式、更换设计风格等。修复 bug、调整文案、改业务逻辑等不涉及视觉变更的任务，不激活本技能。在已有设计系统中工作时，保留已建立的模式、结构和视觉语言。
+已进入显式 UI 规划/实现/验证路径，或当前项目已激活且任务涉及整页新建、跨多个组件的视觉重做、设计系统改造、需要截图验收的界面任务时，读取本 skill。
+标准模式未激活项目中的普通 UI 请求，仍只受当前 bootstrap 的 UI 内核约束；修复 bug、调整文案、改业务逻辑等不涉及视觉变更的任务，不读取本 skill。在已有设计系统中工作时，保留已建立的模式、结构和视觉语言。
 
-## 设计思维（编码前必须完成）
+## 设计契约优先级
+进入 UI 相关的规划、实现、验证时，按以下顺序做设计决策：
+1. 当前活跃方案包 `plan.md` 或 PRD 中已确认的 UI 决策
+2. 逻辑 `.helloagents/DESIGN.md`（实际路径按当前项目存储模式解析）
+3. 本 skill 的通用规则
+缺少上层 artifact 时，才直接依赖下层规则；不得用通用审美覆盖已确认的项目契约。
+
+## 深层职责
+- 消费上游契约：把 `plan.md` / PRD / `DESIGN.md` 中已确认的 UI 决策视为强约束，而不是建议
+- 消费可选 UI contract：若 `contract.json` 启用 `ui.styleAdvisor`，复用 `.helloagents/.ralph-advisor.json` 留下设计方向复查证据；若启用 `ui.visualValidation`，用 `.helloagents/.ralph-visual.json` 留下视觉验收证据
+- 映射到代码结构：明确 token 放在哪里、组件边界如何划分、状态组件如何组织、动效与主题如何落地
+- 做视觉验收闭环：优先使用截图/浏览器工具做桌面与移动端检查；没有工具时也要完成结构化视觉自检
+- 回写稳定决策：只把跨 feature 稳定成立的设计系统规则同步回逻辑 `.helloagents/DESIGN.md`，不要把一次性页面细节全部写成项目级契约
+
+## 深层设计 brief（编码前必须落定）
 
 理解上下文，做出大胆且有意图的设计决策：
 
@@ -20,9 +36,18 @@ description: 构建任何界面（Web/桌面/移动/游戏 UI）时使用。强
 6. 约束定义：为当前项目定义具体约束（如最多几个区块、几种字体、几个强调色、首屏的 CTA 数量），约束释放创意。
 7. 真实内容：使用真实文案、产品信息、项目上下文，不使用 Lorem ipsum 或泛化占位符。真实内容帮助做出更贴合上下文的设计决策。
 
-已通过方案包确认设计方向的，按确认的方向执行。
-项目有 .helloagents/DESIGN.md 的，读取并遵循其中的设计系统（方案包中的设计决策优先于 DESIGN.md）。
-未经方案包且无 DESIGN.md 的任务，基于以上规则，结合任务需求和项目上下文，做出设计决策并执行。
+执行顺序要求：
+- 已激活项目且存在逻辑 `.helloagents/DESIGN.md` 时，进入真实 UI 任务先读取它，再展开方案或实现
+- 已通过方案包或 PRD 确认设计方向的，按确认方向执行，并以 `plan.md` / PRD 中的 UI 决策为最高优先级
+- 已激活项目且当前任务属于整页新建、设计系统改造、或跨多个组件的视觉重做，但逻辑 `.helloagents/DESIGN.md` 不存在时，先按 `templates/DESIGN.md` 创建最小设计契约（至少覆盖产品表面、设计 token、组件与模式、状态覆盖、无障碍要求、禁止事项），再继续大规模实现
+- 未经方案包且无 `DESIGN.md` 的任务，基于以上规则，结合任务需求和项目上下文做出设计决策并执行
+
+## 实现映射（进入编码前必须明确）
+- token 落点：颜色、字体、间距、圆角、阴影、动效参数分别落在哪个 token / theme 文件
+- 组件边界：哪些能力做成复用组件，哪些只保留在当前页面；避免把一次性布局抽成错误的“通用组件”
+- 状态矩阵：当前界面涉及的加载、空、错误、成功、禁用、危险态分别如何呈现
+- 主题与适配：深浅色、响应式断点或平台尺寸、安全区、最小窗口/最小视口如何处理
+- 验收证据：本轮需要检查的关键视口、关键状态和关键截图点是什么
 
 ## 结构性规则
 
@@ -169,6 +194,7 @@ Hero 区域：
 - [ ] 动效：至少 2-3 个有意图的动效，可中断，尊重减弱动效设置
 - [ ] 氛围：背景有纵深感
 - [ ] 记忆点：有一个让人记住的设计特征
+- [ ] 契约一致性：已确认的 `plan.md` / PRD / `DESIGN.md` 决策与实现一致；新增稳定设计决策已同步回 `DESIGN.md`
 - [ ] 状态覆盖：每个异步操作都有加载/成功/错误/空状态
 - [ ] 焦点管理：Tab 顺序合理，模态框焦点困住，关闭后焦点回到触发元素
 - [ ] 可访问性：对比度达标，辅助技术可用
@@ -192,6 +218,8 @@ Hero 区域：
 1. 截图渲染结果（桌面 + 移动端视口）
 2. 对照设计原则审查截图：构图是否完整？品牌感是否到位？配色是否一致？
 3. 发现问题 → 修复 → 再截图验证
-4. 确认截图与设计意图一致后才能报告完成
+4. 若当前 contract 要求 `ui.visualValidation.required=true`，调用 `scripts/visual-state.mjs write` 写 `.helloagents/.ralph-visual.json`，记录 `reason`、`tooling`、`screensChecked`、`statesChecked`、`status` 与 `summary`
+5. 确认截图与设计意图一致后才能报告完成
 
 无浏览器工具时，仔细审查生成的代码，确认样式、布局、动效的实现与设计意图一致。
+若当前 contract 要求 `ui.visualValidation.required=true`，仍需用结构化结论调用 `scripts/visual-state.mjs write` 写 `.helloagents/.ralph-visual.json`，并明确标记所用 tooling 与已检查的 screens / states。

package/skills/hello-verify/SKILL.md

@@ -4,6 +4,7 @@ description: 声称工作完成前、提交代码前、创建 PR 前、报告任
 ---
 
 声称完成之前，必须有验证证据。
+`.helloagents/` 在本 skill 中表示逻辑项目空间：`.ralph-review.json`、`.ralph-visual.json`、`.ralph-closeout.json` 等交付证据保持项目本地；若 `project_store_mode=repo-shared`，`verify.yaml`、方案包与 `DESIGN.md` 按当前会话注入的项目知识/方案目录解析。
 
 ## 铁律
 
@@ -60,7 +61,7 @@ description: 声称工作完成前、提交代码前、创建 PR 前、报告任
 - 已有测试是底线，不能为了新功能而降低底线
 
 ## 验证命令来源
-- .helloagents/verify.yaml 中的 commands（优先）
+- 逻辑 `.helloagents/verify.yaml` 中的 commands（优先；`project_store_mode=repo-shared` 时按共享知识目录解析）
 - package.json 中的 lint/test/typecheck 脚本
 - pyproject.toml 中的 ruff/mypy/pytest
 
@@ -72,6 +73,9 @@ description: 声称工作完成前、提交代码前、创建 PR 前、报告任
 2. 逐项确认每个检查项，标记 [√] 并附带证据（如：`src/api.ts:42` 使用了参数化查询）
 3. 不适用的项标记 [-] 并说明原因
 4. 有未通过项 → 修复 → 重新运行验证循环
+5. 若当前存在方案包并准备最终收尾，优先调用 `scripts/closeout-state.mjs write` 写 `.helloagents/.ralph-closeout.json`，记录 `requirementsCoverage` 与 `deliveryChecklist` 两项结论；两项都必须包含 `status`（`PASS` / `BLOCKED`）和 `summary`
+6. 若当前方案包要求 `review-first`，必须先确认 `.helloagents/.ralph-review.json` 已通过 `scripts/review-state.mjs write` 写成最新结构化证据；不要把审查自然语言消息直接当成交付证据
+7. 若 `contract.json` 中 `ui.visualValidation.required=true`，必须确认 `.helloagents/.ralph-visual.json` 已通过 `scripts/visual-state.mjs write` 写成最新结构化证据；若没有视觉 evidence，不得把本轮视为 UI 可交付
 
 ## 需求追踪验证
 
@@ -79,7 +83,11 @@ description: 声称工作完成前、提交代码前、创建 PR 前、报告任
 1. 逐条读取 requirements.md 的需求（核心目标、功能边界、质量要求）
 2. 确认每条需求都有对应的任务实现，没有被静默丢弃
 3. 确认非目标章节列出的内容确实没有被实现（防止范围蔓延）
-4. 发现遗漏 → 补充实现 → 重新验证
+4. 若 tasks.md 中定义了“完成标准”，逐项确认每个任务的完成标准确实成立，不能只因为代码存在或命令通过就视为完成
+5. 若存在 `contract.json`，逐项确认其中的 `verifyMode`、reviewer / tester 关注边界都已被本轮验证覆盖
+6. 若 `contract.json` 中 `advisor.required=true` 或 `ui.styleAdvisor.required=true`，额外确认 `.helloagents/.ralph-advisor.json` 已存在且结论为 clean；若没有 advisor artifact，不得把本轮视为可交付
+7. 若 `contract.json` 中 `ui.visualValidation.required=true`，额外确认 `.helloagents/.ralph-visual.json` 已存在、覆盖要求的关键 screens / states，且结论为 `PASS`；若没有 visual artifact，不得把本轮视为 UI 可交付
+8. 发现遗漏 → 补充实现 → 重新验证
 
 ## 反代理目标漂移 (APGD)
 

package/skills/helloagents/SKILL.md

@@ -5,8 +5,10 @@ description: 每次对话开始时使用 — 建立质量驱动工作流，通
 
 # HelloAGENTS
 
-适用条件：如果你是主代理并触发或读取任意 skill，只有在该条消息是本轮已经结束流式输出的最终收尾消息时，才按当前已加载 bootstrap 规则包装 HelloAGENTS 外层输出格式；任何 skill 若在当前轮明确要求输出停顿、确认或总结，对应消息也必须同时满足相同条件。
-排除条件：如果你是被派遣执行特定任务的子代理，跳过此 skill 的路由与流程要求，直接执行任务；基础安全、质量与失败处理规则仍持续生效，且无论是否触发或读取其他 skill，都不得包装 HelloAGENTS 外层输出格式。所有流式内容、进度或状态汇报、中间文本，以及任何仍将继续执行的文本，都不得触发外层格式。
+主代理触发或读取任意 skill 时，只有在该条消息是本轮最终收尾消息时，才按当前已加载 bootstrap 规则包装 HelloAGENTS 外层输出格式；任何 skill 若在当前轮明确要求输出停顿、确认或总结，对应消息也必须同时满足相同条件。
+子代理只豁免路由与收尾要求，直接执行任务；安全、质量、验证和失败处理规则仍持续生效，且不得包装 HelloAGENTS 外层输出格式。所有流式内容、进度或状态汇报、中间文本，以及任何仍将继续执行的文本，都不得触发外层格式。
+
+`.helloagents/` 在所有 skill 中都先视为逻辑项目空间：项目本地 `.helloagents/` 继续承担激活信号、`STATE.md` 与 `.ralph-*.json` 等运行态文件；若 `project_store_mode=repo-shared`，`context.md`、`guidelines.md`、`DESIGN.md`、`verify.yaml`、`modules/`、`plans/`、`archive/` 改按当前会话注入的“当前项目存储”/“项目知识/方案目录”解析，不要假定它们一定物理存在于工作树内。
 
 ## 三重质量保障
 
@@ -18,8 +20,12 @@ description: 每次对话开始时使用 — 建立质量驱动工作流，通
 违反规范 = 质量不合格，必须修复。
 
 ### 流程纪律（执行时）
-- 统一执行流程的五个阶段（ORIENT→CLARIFY→PLAN→EXECUTE→VALIDATE）不可跳过
-- ~design 的需求挖掘不可跳过，不可一个问题就出方案
+- 执行 command skill 时，公共阶段边界以当前已加载 bootstrap 为准；command skill 只补充该命令的专属动作和边界
+- 统一执行流程的六个阶段（ROUTE/TIER→SPEC→PLAN→BUILD→VERIFY→CONSOLIDATE）不可跳过
+- 所有 UI 任务先受当前 bootstrap 的 UI 质量内核约束；已激活项目或显式 UI 工作流中的设计约束优先级固定为：当前 `plan.md` / PRD UI 决策 → 逻辑 `.helloagents/DESIGN.md`（实际路径按当前项目存储模式解析） → `hello-ui` 深层规则
+- 方案包存在 `contract.json` 时，验证分流、reviewer / tester 关注边界、可选 style advisor / visual validation 与交付门控优先按它执行，不再从自然语言总结里回推
+- 因阻塞判定而必须等待用户输入时，遵循当前 bootstrap 的等待输入规则，不得把等待输入包装成完成态
+- ~plan 的需求澄清与方案收敛不可跳过，不可一个问题就出方案
 - ~prd 的维度探索不可跳过，每个激活维度必须经过讨论或用户明确跳过
 - ~auto 的复杂度判断不可省略
 - hello-verify 的验证铁律：没有运行验证 = 不能说完成
@@ -48,10 +54,9 @@ Layer 3 — 资源文件（技能内引用时读取）：
 技能 SKILL.md 中引用的 templates/、modules/*.md 等文件，仅在技能明确要求时读取。
 
 禁止行为：
-- 禁止在 ORIENT/CLARIFY 阶段读取实现类技能（hello-ui/hello-test/hello-verify 等）
+- 禁止在 ROUTE / TIER / SPEC 阶段读取实现类技能（hello-ui/hello-test/hello-verify 等）
 - 禁止因为"可能用到"就提前读取技能文件——等到真正需要时再读
 - 同一轮内对同一配置文件、模块、SKILL、模板只读取一次，后续直接复用已得结论，不重复探测或重复读取同一路径
-- 若项目已初始化，项目根 AGENTS.md / CLAUDE.md / .gemini/GEMINI.md 已由宿主自动加载，无需再次读取；仅按需读取具体 SKILL.md，不扫描整个 `skills/helloagents/` 目录
 - ~command 命令只读取对应的 command SKILL.md，不连带读取其他技能
 
 ## 技能查找路径
@@ -65,19 +70,19 @@ Layer 3 — 资源文件（技能内引用时读取）：
 ### ~command 命令技能
 1. `{CWD}/skills/helloagents/skills/commands/{name}/SKILL.md`
 2. 当前已加载 HelloAGENTS 包根目录下的 `skills/commands/{name}/SKILL.md`
-命中路径后立即停止，不要再探测另一路径，也不要重复读取同一命令 skill。
+命中路径后立即停止，不要重复读取同一命令 skill。
 
 ## 技能索引（仅元数据）
 
-### 编码时（EXECUTE 阶段按需读取）
-- hello-ui — 构建 UI/页面/组件时
+### 编码时（BUILD 阶段按需读取）
+- hello-ui — 深层 UI 规划/实现/验收时
 - hello-api — 构建/修改 API 时
 - hello-data — 数据库/迁移/事务时
 - hello-security — 涉及认证/密钥/权限时
 - hello-errors — 错误处理/日志/重试时
 - hello-perf — 性能优化/查询/缓存时
 - hello-arch — 重构/架构决策时
-- hello-test — 编写测试时（TDD：EXECUTE 开始时读取）
+- hello-test — 编写测试时（TDD：BUILD 开始时读取）
 
 ### 特定场景（触发时读取）
 - hello-debug — 调试错误/修复 bug/排查失败时
@@ -85,7 +90,7 @@ Layer 3 — 资源文件（技能内引用时读取）：
 - hello-write — 撰写文档/报告/方案等非编码文本时
 - hello-review — 审查代码/检查变更时
 
-### 完成时（VALIDATE 阶段读取）
+### 完成时（VERIFY / CONSOLIDATE 阶段读取）
 - hello-verify — 声称完成前（必定读取）
 - hello-reflect — 符合触发条件时（详见 hello-reflect SKILL.md）
 
@@ -93,15 +98,21 @@ Layer 3 — 资源文件（技能内引用时读取）：
 
 用户使用 `~command` 时，只读取对应的 command skill，路径按上方“~command 命令技能”规则查找：
 - `~auto`
-- `~design`
+- `~idea`
+- `~plan`
+- `~build`
 - `~prd`
 - `~loop`
 - `~init`
 - `~test`
 - `~verify`
-- `~review`
 - `~commit`
 - `~clean`
 - `~help`
 
+兼容别名：
+- `~do` → 直接按 `~build` 的 command skill 路径读取并执行
+- `~design` → 直接按 `~plan` 的 command skill 路径读取并执行
+- `~review` → 直接按 `~verify` 的 command skill 路径读取并执行
+
 只有当对应 command skill 明确要求再读取 hello-* 技能时，才按上方“hello-* 技能”规则继续读取。

package/templates/DESIGN.md

@@ -1,19 +1,40 @@
 # {项目名} 设计系统
 
+## 产品表面
+[当前产品包含哪些核心界面类型：营销页 / 应用壳 / 设置页 / 数据密集页 / 编辑器 / 对话流程；说明各自的角色与优先级]
+
 ## 美学方向
-[整体视觉风格和情感基调]
+[整体视觉风格、情绪目标、品牌气质；说明为什么这种方向适合当前产品和用户]
 
 ## 设计 token
-[变量体系：背景色、表面色、主色、强调色、语义色、字体角色]
+[变量体系：背景/表面/边框/文本/主色/强调色/语义色/阴影/圆角/间距/字体角色；注明平台实现方式]
 
 ## 布局策略
-[各视口的布局方式、网格系统、响应式策略]
+[主次导航、网格与间距系统、响应式原则、信息密度策略]
+
+## 组件与模式
+[核心组件清单、交互模式、何时使用/禁止使用；包括按钮、表单、卡片、表格、对话框、导航等]
+
+## 状态覆盖
+[加载/空/错误/成功/禁用/危险态的统一表现；异步流程的反馈节奏]
 
 ## 记忆点
 [用户会记住的一个标志性设计特征]
 
 ## 动效策略
-[入场动画、交互反馈、状态过渡；尊重 prefers-reduced-motion]
+[入场、过渡、反馈、层级切换；尊重 prefers-reduced-motion / 平台减弱动效]
+
+## 无障碍要求
+[对比度、键盘与辅助技术、焦点环、可点击区域、语义要求]
+
+## 内容语气
+[文案风格、空状态语气、错误提示风格、按钮动词规范]
+
+## 禁止事项
+[明确禁止的配色、组件滥用、布局模式、动效误用、品牌冲突做法]
 
 ## 约束定义
 [字体数量、强调色数量、核心区块数量、CTA 数量等具体上限]
+
+## 实现备注
+[设计契约如何映射到代码：token 文件、组件层、主题切换、截图验证、需要同步的目录]

package/templates/STATE.md

@@ -1,5 +1,8 @@
 # 恢复快照
 
+## 主线目标
+[一句话：当前连续任务真正要完成什么；若当前消息已切换新主线，必须改写或留空]
+
 ## 正在做什么
 [一句话：当前任务 + 当前正在执行的具体步骤，无任务时写"空闲"]
 

package/templates/plans/contract.json

@@ -0,0 +1,48 @@
+{
+  "version": 1,
+  "source": "{~plan | ~prd}",
+  "originCommand": "{plan | prd}",
+  "verifyMode": "{test-first | review-first}",
+  "reviewerFocus": [
+    "{仅 review-first 必填：reviewer 需要重点检查的边界}"
+  ],
+  "testerFocus": [
+    "{tester 需要重点验证的边界}"
+  ],
+  "ui": {
+    "required": false,
+    "designContract": false,
+    "sourcePriority": [
+      "{涉及 UI 时填写：plan.md / prd/03-ui-design.md}",
+      "{涉及 UI 时填写：.helloagents/DESIGN.md}",
+      "{涉及 UI 时填写：hello-ui}"
+    ],
+    "styleAdvisor": {
+      "required": false,
+      "reason": "{仅在 UI 方向尚未稳定、需要前置审美收敛时填写：为什么需要独立 style advisor}",
+      "focus": [
+        "{仅 ui.styleAdvisor.required=true 时填写：需要独立复查的设计方向、记忆点或视觉风险}"
+      ]
+    },
+    "visualValidation": {
+      "required": false,
+      "reason": "{仅在 UI 验收、整页重做、发布前视觉收尾等场景填写：为什么需要独立视觉验收}",
+      "screens": [
+        "{仅 ui.visualValidation.required=true 时填写：需要检查的关键视口或页面}"
+      ],
+      "states": [
+        "{仅 ui.visualValidation.required=true 时填写：需要检查的关键状态}"
+      ]
+    }
+  },
+  "advisor": {
+    "required": false,
+    "reason": "{仅在 T3 / UI / 高风险链路确有收益时填写：为什么需要独立 advisor}",
+    "focus": [
+      "{仅 advisor.required=true 时填写：advisor 需要独立复查的边界}"
+    ],
+    "preferredSources": [
+      "{仅 advisor.required=true 时填写：claude | codex | gemini}"
+    ]
+  }
+}

package/templates/plans/plan.md

@@ -0,0 +1,23 @@
+# {项目/功能名称} — 实施规划
+
+## 目标与范围
+[本次要解决的问题、范围边界、验收目标]
+
+## 架构与实现策略
+[关键决策及理由]
+
+## 完成定义
+[功能完成时必须为真的条件、关键验收点、验证主路径（test-first / review-first）、reviewer / tester 关注边界]
+
+## 文件结构
+[涉及的文件和目录规划]
+
+## UI / 设计约束
+[涉及 UI 时填写：设计方向、状态覆盖、与 DESIGN.md 的关系、需要新增或更新的设计系统约束]
+
+## 风险与验证
+[主要风险、验证方式、回退点]
+
+## 决策记录
+[规划过程中的关键决策，供回溯]
+- [YYYY-MM-DD] 决策内容及理由

package/templates/plans/tasks.md

@@ -2,9 +2,9 @@
 
 ## 任务列表
 [按执行顺序排列，每个任务独立可验证]
-- [ ] 任务1：描述（涉及文件、验证方式）
-- [ ] 任务2：描述
-- [ ] 任务3：描述
+- [ ] 任务1：描述（涉及文件：path/to/file.ts；完成标准：功能行为或验收结果；验证方式：npm run test -- feature）
+- [ ] 任务2：描述（涉及文件：...；完成标准：...；验证方式：...）
+- [ ] 任务3：描述（涉及文件：...；完成标准：...；验证方式：...）
 
 ## 进度
 [执行过程中更新]