helloagents 3.0.2-beta.1 → 3.0.7

package/skills/commands/auto/SKILL.md

@@ -1,91 +1,57 @@
 ---
 name: ~auto
-description: ~design 的全自动版本 — AI 自主完成需求分析、方案设计和执行，流程与 ~design 一致（~auto 命令）
+description: 自动选路命令 — 根据任务自动选择 ~idea / ~plan / ~build / ~verify / ~prd 的组合路径（~auto 命令）
 policy:
   allow_implicit_invocation: false
 ---
 Trigger: ~auto <任务描述>
 
-~auto 是 ~design 的全自动版本。区别仅在于：需求分析和方案探索由 AI 自主决策（不确定的关键决策点仍向用户确认）。简单任务可跳过方案设计直接执行。
-
-本 skill 自包含，不依赖再读取 `~design` 的 command skill。只有在本 skill 明确要求时，才继续读取对应的 hello-* 技能。
+`~auto` 是自动选路命令。它根据任务类型、复杂度、风险等级与项目状态，自动在 `~idea`、`~plan`、`~build`、`~verify`、`~prd` 之间选择合适路径。
+`~auto` 只做选路。路径一旦确定，立即读取对应 command skill 并按其流程执行。
 
 ## 铁律
-- 在确认方案之前，禁止编写实现代码、创建实现文件或执行实现操作；仅当任务被判定为简单任务时，才可跳过方案设计直接进入执行
-- 需求分析阶段不读取实现类技能（hello-ui/hello-test/hello-verify 等），需求明确后再按需读取
-- 不因为 `~auto` 与 `~design` 相似，就额外读取 `~design` 的 SKILL.md
+- 不为了“自动化”而强行走重流程
+- 复杂度与风险不足以支撑更重路径时，优先选更轻但能保证质量的路线
+- `T3` 高风险或不可逆链路默认不直接进入 `~build`；优先先走 `~plan` 或 `~prd`，纯审查/纯验证请求才可先进入 `~verify`
+- 选路一旦确定，立即读取对应 command skill，避免重复探索
+- 选路不替代授权；涉及外部副作用或高风险不可逆操作时，仍遵守 bootstrap 的阻塞判定与确认规则
+- 优先消费当前上下文已注入的 ROUTE / TIER、当前工作流约束与项目状态；不要在 `~auto` 内另建一套关键词路由表
 
 ## 流程
 
-### 1. 上下文收集（ORIENT）
-
-已有项目：
-- 读取 .helloagents/context.md 获取项目上下文和模块索引
-- 读取 .helloagents/guidelines.md 获取项目约定
-- 扫描相关代码文件理解现有架构
-
-全新项目（无 .helloagents/ 目录）：
-- 跳过，直接进入需求分析
-
-### 2. 需求分析（CLARIFY，AI 自主判断）
-
-快速评估任务复杂度：
-1. 影响范围（单文件 vs 多文件）
-2. 是否涉及架构决策
-3. 复杂度信号：文件数 / 跨模块数 / 新增依赖 / 数据库变更
-
-简单任务（单文件修改/明确修复）→ 跳过方案设计，直接进入当前已加载 bootstrap 中定义的统一执行流程。
-
-复杂任务 → AI 自主分析三个方向（目的、约束、成功标准），不确定的关键决策点仍向用户确认。
-涉及视觉/交互/体验的决策：必须体现当前前沿设计水准。若当前已加载 bootstrap 含审美/体验规则则遵循其要求；否则至少给出具体、可执行、非泛化的视觉特征，不确定时主动搜索查阅最新设计案例和技术能力。
-
-大项目检测：如果任务涉及多个独立子系统，先分解为子项目，每个子项目走独立的设计→计划→实施循环。
-
-**假设模式**（已有代码库，优先使用）：
-- 基于代码证据自主判断目的、约束和成功标准
-- 不确定的关键决策点仍向用户确认
-
-**委托模式**（全新项目，对应 ~design 交互模式的自动化版本）：
-- 基于任务描述自主推断目的、约束和成功标准
-- 不确定的关键决策点仍向用户确认
-
-### 3. 方案探索（PLAN）
-
-基于需求分析结果，评估 2-3 个可行方案，自主选择最佳方案（与 ~design 一致，但由 AI 决策）。
-涉及 UI 的方案：此时读取 hello-ui SKILL.md 获取设计规范。
-
-### 4. 方案细化
+### 0. 当前工作流优先
 
-自主完成完整方案细化：
-- 架构与文件结构
-- 涉及 UI 时：按 hello-ui 的设计思维规范展开
-- 数据流与错误处理
-- 测试策略
+- 若当前上下文已注入“当前工作流提示”或“当前工作流约束”，优先服从其中的推荐下一命令 / 主路径
+- 默认原则：
+  - 活跃方案包不完整或缺少任务清单 → 先 `~plan`
+  - 活跃方案包仍在执行 → 先 `~build`，完成当前实现后再 `~verify`
+  - 活跃方案包已闭合 → 先 `~verify` 或收尾
+- 只有当用户明确要求换方向、重做方案，或现有方案已失效时，才偏离当前推荐重新规划
 
-### 5. 写入方案包
+### 1. 选路
 
-复杂任务将确认的方案写入本地项目：
-- 全新项目（无 .helloagents/ 目录）：先创建 .helloagents/ 和 STATE.md（按 templates/STATE.md 格式）。这是方案包写入的前置操作，不受 kb_create_mode 开关控制
-- 创建 .helloagents/plans/YYYYMMDDHHMM_{feature}/
-- 按 templates/plans/ 的模板格式写入 requirements.md、design.md、tasks.md
-- 涉及 UI 的项目：生成或更新 .helloagents/DESIGN.md
-- 重写 .helloagents/STATE.md（正在做什么、关键上下文含需求摘要和方案决策、下一步设为第一个待执行任务）
+- 先按当前上下文里已注入的 ROUTE / TIER 语义约束判断，不依赖关键词命中做机械分流
+- 若当前轮没有足够的注入约束，再结合以下信号补足判断：影响范围、风险等级、是否需要 artifact、是否已有活跃方案包、用户是否只想先比较方向
+- 选路优先级：
+  - 纯探索 / 点子 / 方向比较 → `~idea`
+  - 明确要求验证 / 审查 / 跑检查 → `~verify`
+  - 0 到 1 / 产品级 / 多维规格 → `~prd`
+  - 多文件功能 / 架构变更 / 新项目规划 → `~plan`
+  - 明确修复 / 小范围实现 / 现有方案落地 → `~build`
 
-### 6. 执行决策
+### 2. 按 Tier 校正
 
-展示方案摘要后，仅在是否进入执行仍构成阻塞决策时才询问用户：
-- 开始执行 → 重写 STATE.md（下一步设为第一个任务的具体动作）
-- 修改方案 → 回到方案细化
-- 暂不执行，保留方案 → 重写 STATE.md（下一步设为“方案已确认；执行需用户明确启动”）
+- `T0` → 保持在 `~idea`，不创建项目文件
+- `T1` → 在 `~build` / `~verify` 间选择最短可交付路径
+- `T2` → 需要 artifact 或范围未完全收敛时优先 `~plan`
+- `T3` → 纯审查/验真走 `~verify`；其余默认 `~plan` 或 `~prd`，待方案与风险边界明确后再进入实现
 
-如果用户已对当前方案或继续执行作出明确同意，视为执行授权成立，直接进入执行，不再追加确认环节。
-简单任务跳过方案设计时，直接进入执行，无需额外确认。
+### 3. 读取对应命令并执行
 
-### 7. 执行
+- 选中 `idea` → 读取 `skills/commands/idea/SKILL.md`
+- 选中 `plan` → 读取 `skills/commands/plan/SKILL.md`
+- 选中 `build` → 读取 `skills/commands/build/SKILL.md`
+- 选中 `verify` → 读取 `skills/commands/verify/SKILL.md`
+- 选中 `prd` → 读取 `skills/commands/prd/SKILL.md`
 
-按 tasks.md 逐项完成，每项进入当前已加载 bootstrap 中定义的统一执行流程，完成后同步重写 STATE.md。
-任务状态标记仅写入 tasks.md、验收清单或验证结果；普通说明、方案解释、状态汇报不用 [√] / [-] / [ ]。
-所有任务完成后进入当前已加载 bootstrap 中定义的 VALIDATE 阶段。
-可并行的任务标记后用子代理并行执行（不同子代理不改同一文件）。
-执行过程中遇到阻塞（依赖缺失、指令不清、验证反复失败）→ 立即停下询问用户，不猜测。
-执行过程中遇到高风险操作（删除文件/修改配置/数据库变更）→ 暂停确认。
+不要额外读取未选中的 command skill。

package/skills/commands/build/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: ~build
+description: 执行实现工作流 — 基于当前需求或现有方案包完成实现、验证与状态同步（~build 命令）
+policy:
+  allow_implicit_invocation: false
+---
+Trigger: ~build [description]
+
+`~build` 是执行实现命令。它负责读取现有需求、方案包与项目上下文，完成实现、局部验证、修复循环，并把结果衔接到后续验证与收尾。
+执行 `~build` 时，通用阶段边界按当前已加载 bootstrap 执行；本 skill 负责补充实现前定位、实现约束，以及进入 `~verify` / 收尾前的实现边界。
+`.helloagents/` 在本 skill 中表示逻辑项目空间：`STATE.md` 与 `.ralph-*.json` 保持项目本地；若 `project_store_mode=repo-shared`，知识库、`DESIGN.md`、`verify.yaml` 与方案包按当前会话注入的项目知识/方案目录解析。
+
+## 铁律
+- 默认先定位上下文与范围，再修改代码
+- 已有方案包时，优先按方案包执行，不重复发明方案
+- 没有运行验证，不能报告完成
+- 遇到高风险或阻塞情况立即停下确认
+
+## 流程
+
+### 1. 恢复与定位
+
+- 优先按当前已加载 bootstrap 的“.helloagents/ 文件读取优先级”恢复当前链路；若当前消息显式继续既有链路，或会话刚经历恢复 / 压缩，先读取 `.helloagents/STATE.md` 作为恢复快照，再用当前用户消息、活跃方案包 / PRD 与代码事实校正主线
+- 若存在最近的活跃方案包，读取对应的：
+  - `requirements.md`
+  - `plan.md`
+  - `tasks.md`
+  - `contract.json`
+  - 实现时优先把 `tasks.md` 中每个任务的“完成标准”当作本轮 build contract，不要只按任务标题猜测范围
+  - `contract.json` 存在时，优先按其中的 `verifyMode`、`reviewerFocus`、`testerFocus` 理解后续验证边界
+- 若当前上下文已注入“当前工作流约束”或“当前建议下一命令”，先服从它；只有推荐仍为 `~build`，或用户明确提出新增实现范围时，才继续 `~build`
+- 其余项目知识库与相关代码文件，按 bootstrap 的项目上下文规则按需读取
+- 若任务涉及 UI，按以下优先级读取并遵循：当前活跃 `plan.md` / PRD 中的 UI 决策 > 逻辑 `.helloagents/DESIGN.md`（实际路径按当前项目存储模式解析） > `hello-ui` 通用规则
+- 若已激活项目且当前任务属于整页新建、设计系统改造、或跨多个组件的视觉重做，但逻辑 `.helloagents/DESIGN.md` 不存在，先按模板创建最小设计契约，再继续大规模实现
+
+如果 `.helloagents/` 不存在：
+- 按当前已加载 bootstrap 的 `.helloagents/` 与流程状态规则创建最小项目状态
+- 仅补足执行当前任务所需的最小状态，不自动展开完整知识库
+
+### 2. 需求与范围确认
+
+- 若用户提供的是明确执行任务，直接确认范围
+- 若当前活跃方案包已能覆盖需求，按方案执行
+- 若仍存在真实歧义，仅询问阻塞执行的关键决策
+
+### 3. 执行实现
+
+- 根据任务拆解逐步修改
+- 读取 PLAN 阶段所需的 hello-* 技能并遵循其规范
+- 编码任务遵循：
+  - 先补测试或最小验证手段，再写实现
+  - 每次编辑后主动跑确定性检查
+- 可并行任务通过子代理执行，但不同子代理不得改同一文件
+
+### 4. 验证与修复循环
+
+- 读取 `hello-verify` SKILL.md
+- 运行 lint / typecheck / test / build 等验证
+- 若失败，修复后重跑
+- 若涉及 review 场景，可按需读取 `hello-review`
+
+### 5. 交付衔接
+
+- 有方案包时，只同步本次实现直接影响的任务状态；未完成项保持打开
+- 当前实现已闭合、且需要进入交付或收尾时，转入 `~verify`
+- `STATE.md`、知识库、`CHANGELOG.md`、modules 文档与归档边界，按当前已加载 bootstrap 的 VERIFY / CONSOLIDATE 规则执行
+- 不在 `~build` 内把仍未闭合的方案包整体报告为已完成

package/skills/commands/clean/SKILL.md

@@ -6,16 +6,18 @@ policy:
 ---
 Trigger: ~clean
 
+执行 `~clean` 时，方案包归档、临时文件清理和 `STATE.md` 更新边界按当前已加载 bootstrap 执行；本命令只负责判定哪些方案包可以清理，以及输出清理摘要。
+`.helloagents/` 在本 skill 中表示逻辑项目空间：`STATE.md` 和临时运行态文件保持项目本地；若 `project_store_mode=repo-shared`，`plans/` 与 `archive/` 按当前会话注入的项目知识/方案目录解析。
+
 ## 流程
 
-1. 扫描 .helloagents/plans/ 下的方案包
-2. 判定完成状态：tasks.md 中所有任务已标记 [√]（该标记仅用于任务列表/验收清单）或 STATE.md "正在做什么"表明已完成
-3. 已完成的方案包 → 将整个 plans/{feature}/ 目录归档到 .helloagents/archive/YYYY-MM/
-4. 更新 .helloagents/archive/_index.md（按 templates/archive/_index.md 格式追加一行）
-5. 清理临时文件：.helloagents/loop-results.tsv、.helloagents/.ralph-breaker.json
-6. 重写 STATE.md（清空已归档的方案路径；这是强制更新，但不要求为仅执行 `~clean` 的场景首次创建）
+1. 扫描逻辑 `.helloagents/plans/` 下的方案包（`project_store_mode=repo-shared` 时按当前知识/方案目录解析）
+2. 判定完成状态：优先以 tasks.md 中所有任务已标记 [√] 为准；只有任务清单无法判断时，才把 `STATE.md` 中与当前方案一致的“主线目标”+“正在做什么”作为辅助信号，避免把旧恢复快照误当当前主线
+3. 已完成的方案包 → 按 bootstrap 的归档规则移入逻辑 `.helloagents/archive/YYYY-MM/`，并同步更新逻辑 `.helloagents/archive/_index.md`
+4. 清理 bootstrap 中定义的临时文件
+5. 按 bootstrap 的流程状态规则更新 `STATE.md`；若当前状态指向已归档方案包，则清空对应方案路径
 7. 输出清理摘要（归档了几个方案包、清理了哪些文件）
 
 ## 不删除
-流程状态：STATE.md、DESIGN.md
-知识沉淀：context.md、guidelines.md、verify.yaml、CHANGELOG.md、modules/
+- 除按流程状态规则必须重写的 `STATE.md` 外，不删除流程状态文件
+- 不删除知识沉淀文件或项目级设计契约

package/skills/commands/commit/SKILL.md

@@ -6,6 +6,8 @@ policy:
 ---
 Trigger: ~commit [message]
 
+执行 `~commit` 时，知识库同步与 `STATE.md` 更新边界按当前已加载 bootstrap 的 CONSOLIDATE / 流程状态规则执行；本命令只负责生成提交信息、读取提交归属配置并完成提交动作。
+
 ## 流程
 
 1. 检查 staged changes（git diff --staged）
@@ -13,14 +15,16 @@ Trigger: ~commit [message]
 3. 生成 conventional commit message（如未提供）
    - 格式: type(scope): description
    - type: feat|fix|refactor|docs|test|chore|style|perf
-4. 优先使用当前上下文中已注入的“当前用户设置”获取 `commit_attribution`；只有上下文不存在时才读取 `~/.helloagents/helloagents.json`：
+4. 先一次性解析本轮设置：优先使用当前上下文中已注入的“当前用户设置”；只有上下文不存在时才读取一次 `~/.helloagents/helloagents.json`
+5. 复用上一步已解析的设置获取 `commit_attribution`：
    - ""（空，默认）→ 不添加归属
    - 有内容（如 "Co-Authored-By: HelloAGENTS"）→ 添加该内容到 commit message
-5. 执行 git commit
+6. 执行 git commit
+7. 若项目已有 `.helloagents/STATE.md`，按 bootstrap 的“已有则更新”规则同步当前已提交状态
 
 ## 知识库同步
-提交后，优先使用当前上下文中已注入的“当前用户设置”获取 `kb_create_mode`；只有上下文不存在时才读取 `~/.helloagents/helloagents.json`：
+提交后，继续复用上方已解析的同一份设置获取 `kb_create_mode`，不要再次读取 `~/.helloagents/helloagents.json`：
 - 0 = 跳过
 - 1 = 编码任务自动同步（默认）
 - 2 = 始终同步
-同步内容（仅知识库文件，规则同当前已加载 bootstrap 的 VALIDATE 阶段中的知识库同步）。
+同步范围与更新格式按当前已加载 bootstrap 的 CONSOLIDATE 阶段执行。

package/skills/commands/help/SKILL.md

@@ -11,35 +11,43 @@ Trigger: ~help
 ### 可用命令
 | 命令 | 说明 |
 |------|------|
-| ~auto | 全自动执行：AI 自主分析需求、设计方案并执行 |
-| ~design | 深度设计：交互式需求挖掘 + 方案设计 + 方案包 |
+| ~idea | 轻量点子探索与方向比较 |
+| ~auto | 自动选路：在脑暴 / 规划 / 执行 / 验证 / PRD 间选择合适路径 |
+| ~plan | 结构化规划：需求澄清 + 方案收敛 + 方案包 |
+| ~build | 执行实现：按需求或方案包完成实现与验证 |
 | ~prd | 完整 PRD：头脑风暴式逐维度挖掘，生成现代产品需求文档 |
 | ~loop | 自主迭代优化：设定目标和指标，循环修改-验证-保留/回滚 |
-| ~init | 初始化项目知识库和配置 |
+| ~wiki | 仅创建/同步项目知识库（`.helloagents/`） |
+| ~init | 完整初始化项目：知识库 + 项目级载体配置 |
 | ~test | 为指定模块或最近变更编写完整测试 |
-| ~verify | 运行所有验证命令并报告结果 |
-| ~review | 代码审查 |
+| ~verify | 验证总入口：审查 + 运行验证命令 + 修复循环 |
 | ~commit | 规范化提交 + 知识库同步 |
 | ~clean | 清理临时文件和归档方案包 |
 | ~help | 显示此帮助 |
 
+兼容别名：
+- `~do` → 等同 `~build`
+- `~design` → 等同 `~plan`
+- `~review` → 等同 `~verify` 的审查优先模式
+
 ### 自动激活技能
-适用条件：以下技能仅在全局模式，或当前项目已通过 `~init` 激活后自动激活：
-排除条件：纯标准模式未激活项目不会自动触发。
+以下技能仅在全局模式或已激活项目中自动激活（例如执行过 `~wiki`、`~init`，或已处于项目级连续流程）。
+纯标准模式未激活项目不会自动触发这些深层技能；但涉及 UI 的任务仍受 UI 质量内核约束。
 
 编码时：hello-ui, hello-api, hello-data, hello-security, hello-errors, hello-perf, hello-arch, hello-test
 特定场景：hello-debug, hello-subagent, hello-write, hello-review
 完成时：hello-verify, hello-reflect
 
 ### 当前设置
-适用条件：优先使用当前上下文中已注入的“当前用户设置”显示；仅在上下文不存在该信息时，才尝试读取 `~/.helloagents/helloagents.json`。
-排除条件：如果当前 CLI 存在工作区限制导致家目录不可读，则明确说明“无法直接读取配置文件，以下按已注入设置或默认值展示”，不要改用无关工具或伪造已读取结果。
+优先使用当前上下文中已注入的“当前用户设置”显示；仅在上下文不存在该信息时，才尝试读取 `~/.helloagents/helloagents.json`。
+如果当前 CLI 存在工作区限制导致家目录不可读，则明确说明“无法直接读取配置文件，以下按已注入设置或默认值展示”，不要改用无关工具或伪造已读取结果。
 | 配置项 | 默认值 | 作用 | 适用 CLI |
 |--------|-------|------|---------|
 | output_language | "" | 空=跟随用户语言/填写则指定（如 zh-CN、en） | Claude Code + Gemini CLI + Codex CLI |
-| output_format | true | true=适用条件：仅主代理在流式结束后的最终收尾回复可使用 HelloAGENTS 格式；排除条件：所有流式/中间输出及所有子代理输出保持自然；false=自然输出 | Claude Code + Gemini CLI + Codex CLI |
+| output_format | true | true=仅主代理在最终收尾回复使用 HelloAGENTS 格式，所有流式/中间输出及子代理输出保持自然；false=自然输出 | Claude Code + Gemini CLI + Codex CLI |
 | notify_level | 0 | 0=关闭/1=桌面通知/2=声音/3=两者 | Claude Code + Gemini CLI + Codex CLI |
 | ralph_loop_enabled | true | 自动验证循环（任务完成时触发 lint/test/build） | Claude Code + Gemini CLI + Codex CLI |
 | guard_enabled | true | 阻断危险命令与写入后的安全扫描 | Claude Code + Gemini CLI + Codex CLI |
-| kb_create_mode | 1 | 0=关闭/1=编码自动/2=始终 | Claude Code + Gemini CLI + Codex CLI |
+| kb_create_mode | 1 | 0=关闭/1=已激活项目或全局模式中编码自动/2=已激活项目或全局模式中始终 | Claude Code + Gemini CLI + Codex CLI |
+| project_store_mode | "local" | "local"=知识库/方案包保留在项目本地 `.helloagents/`；"repo-shared"=本地 `.helloagents/` 仅保留激活/STATE/运行态，知识库与方案包改写到 `~/.helloagents/projects/<repo-key>/` | Claude Code + Gemini CLI + Codex CLI |
 | commit_attribution | "" | 空=不添加/填写内容则添加到 commit message | Claude Code + Gemini CLI + Codex CLI |

package/skills/commands/idea/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: ~idea
+description: 轻量点子探索与方向发散（~idea 命令）
+policy:
+  allow_implicit_invocation: false
+---
+Trigger: ~idea [description]
+
+`~idea` 是轻量探索命令，用于在不落盘、不进入执行、不激活完整项目流程的前提下，帮用户快速比较方向、生成点子、收敛方案。
+
+## 铁律
+- 只讨论，不编写实现代码，不创建项目文件，不执行实现操作
+- 不创建 `.helloagents/`
+- 不创建或更新 `.helloagents/STATE.md`、知识库文件、方案包或项目根载体
+- 不生成方案包
+- 不执行会改变工作区或外部状态的命令
+- 不默认使用子代理
+- 输出的重点是方向、差异、推荐理由与下一步可升级路径
+
+## 流程
+
+### 1. 快速理解问题
+
+- 理解用户当前要解决的目标、场景、限制与关注点
+- 若任务是已有项目中的连续工作，可按需读取少量相关上下文；不要为了脑暴而展开完整项目流程
+
+### 2. 生成备选方向
+
+- 提供 2-4 个可行方向
+- 每个方向都给出：
+  - 核心思路
+  - 适用场景
+  - 主要优点
+  - 主要代价或风险
+
+### 3. 给出推荐
+
+- 明确推荐一个最优方向
+- 解释推荐理由，不使用空泛形容词
+- 若涉及视觉/交互，选项必须具体到可执行特征
+
+### 4. 给出升级路径
+
+- 如果用户希望继续推进，实现层升级路径为：
+  - 想形成结构化方案 → `~plan`
+  - 想直接进入实现 → `~build`
+  - 需要重型产品规格 → `~prd`
+  - 想让 AI 自动选路径 → `~auto`
+- 如果用户在 `~idea` 过程中转而明确要求写文件、改代码、创建知识库或执行命令，不在 `~idea` 内偷偷落地；改为按最合适的升级路径继续
+
+## 输出要求
+
+- 允许发散，但必须收敛
+- 不做“点子堆砌”
+- 不把尚未决定的探索结果伪装成已确认方案

package/skills/commands/init/SKILL.md

@@ -7,12 +7,14 @@ policy:
 Trigger: ~init
 
 ~init 是用户显式命令，创建完整知识库，不受 kb_create_mode 限制。
+执行 `~init` 时，`.helloagents/` 目录结构、模板格式和 `STATE.md` 规则按当前已加载 bootstrap 执行；本命令额外负责项目根载体和项目级 `skills/helloagents` 链接。
+`.helloagents/` 在本 skill 中表示逻辑项目空间：项目本地 `.helloagents/` 继续承担激活目录与 `STATE.md`；若 `project_store_mode=repo-shared`，知识库、`DESIGN.md` 与方案包按当前会话注入的项目知识/方案目录写入。
 
 ## 流程
 
 ### 阶段 1：环境搭建（必做）
 
-1. 创建 `.helloagents/` 目录 + STATE.md（按 templates/STATE.md 格式，初始为空闲）
+1. 创建 `.helloagents/` 目录 + `STATE.md`（按 templates/STATE.md 格式，初始“主线目标”写当前初始化链路，初始状态为空闲）
 2. 定位插件根目录：优先读取当前会话中注入的“当前 HelloAGENTS 包根目录”；若上下文未提供，再根据当前已加载载体和规则反推，禁止猜测其他目录
 3. 创建 `skills/helloagents` symlink → `{插件根目录}/`
 4. 读取 `{插件根目录}/bootstrap.md`，用 `<!-- HELLOAGENTS_START -->` / `<!-- HELLOAGENTS_END -->` 标记包裹后写入：
@@ -35,13 +37,13 @@ Trigger: ~init
 - 有代码文件 → 执行完整知识库创建（下方流程）
 - 空项目 → 跳过，告知用户"项目为空，知识库将在后续开发中创建"
 
-知识库创建流程（与原 ~init 一致）：
+知识库创建流程（与原 ~init 一致；逻辑写入 `.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 格式提取设计系统
+   - DESIGN.md — 如果项目包含 UI 代码，按 templates/DESIGN.md 格式提取项目级设计契约（产品表面、设计 token、组件与模式、状态覆盖、无障碍要求、禁止事项等）
 2. 创建 modules/ 目录，按 templates/modules/module.md 格式为主要模块生成文档
 3. 不覆盖已存在的文件
 
@@ -55,6 +57,7 @@ commands:
 ## 幂等性
 重复执行 ~init 是安全的：
 - 已存在的 .helloagents/ 文件不覆盖
+- `STATE.md` 只作为当前初始化链路的恢复快照；后续进入其他主线任务时必须按新主线重写
 - symlink 刷新（删除旧的重建）
 - AGENTS.md/CLAUDE.md/GEMINI.md 中标记内容替换更新
 - .gitignore 只追加缺失行

package/skills/commands/loop/SKILL.md

@@ -19,12 +19,12 @@ Trigger: ~loop <目标描述> [--iterations N] [--metric "命令"] [--direction
 ## 初始化
 
 1. 确认 git 工作区干净（有未提交变更则先提醒用户处理）
-2. 确保 `.helloagents/` 目录和 `.helloagents/STATE.md` 存在；目录不存在时先创建，`STATE.md` 不存在时按 `templates/STATE.md` 创建。这是 `~loop` 的强制恢复快照，不受 `kb_create_mode` 控制
+2. 确保 `.helloagents/` 目录和 `.helloagents/STATE.md` 存在；目录不存在时先创建，`STATE.md` 不存在时按 `templates/STATE.md` 创建。这是 `~loop` 的强制恢复快照，不受 `kb_create_mode` 控制；“主线目标”固定写本次优化目标，避免被旧任务主线污染
 3. 运行指标命令获取基线值，记录到 results log
 4. 如有守卫命令，运行确认基线通过
 5. 创建 `.helloagents/loop-results.tsv`，并确保 .gitignore 包含该文件
 6. 根据优化目标标记可能需要的 hello-* 质量技能（如性能优化标记 hello-perf，UI 优化标记 hello-ui）
-7. 重写 `.helloagents/STATE.md`：记录当前优化目标、基线指标、守卫命令、下一步设为第一轮迭代的具体动作
+7. 重写 `.helloagents/STATE.md`：记录主线目标=当前优化目标、基线指标、守卫命令、下一步设为第一轮迭代的具体动作
 
 results log 格式：
 ```
@@ -35,7 +35,8 @@ iteration	commit	metric	delta	guard	status	description
 
 ## 八阶段循环
 
-~loop 的八阶段循环是统一执行流程（ORIENT→CLARIFY→PLAN→EXECUTE→VALIDATE）在迭代优化场景下的特化形式。每轮迭代的 Modify 阶段遵循已标记的 hello-* 质量技能规范，Verify 阶段遵循 hello-verify 的验证规范。
+`~loop` 的八阶段循环是统一执行流程（ROUTE/TIER→SPEC→PLAN→BUILD→VERIFY→CONSOLIDATE）在迭代优化场景下的特化形式。每轮迭代的 Modify 阶段遵循已标记的 hello-* 质量技能规范，Verify 阶段遵循 hello-verify 的验证规范。
+执行 `~loop` 时，涉及公共阶段边界、阻塞判定与收尾要求的部分，仍按当前已加载 bootstrap 执行；本 skill 负责补充 loop 场景的迭代顺序与回滚规则。
 
 不要停止。不要询问是否继续。
 每轮迭代必须完整走完以下八个阶段：
@@ -76,7 +77,7 @@ iteration	commit	metric	delta	guard	status	description
 ### Phase 7: Log
 - 追加一行到 results log
 - status: baseline / keep / discard / crash / no-op
-- 重写 `.helloagents/STATE.md`：记录当前轮次、最近一次决策（keep / discard / crash）、当前最佳指标、下一步动作
+- 重写 `.helloagents/STATE.md`：保持主线目标=当前优化目标，并记录当前轮次、最近一次决策（keep / discard / crash）、当前最佳指标、下一步动作
 
 ### Phase 8: Repeat
 - 如果 iterations > 0 且 current_iteration >= max_iterations → 输出总结并停止
@@ -89,7 +90,7 @@ iteration	commit	metric	delta	guard	status	description
 - 总迭代次数 / 保留次数 / 丢弃次数
 - 最有效的 3 个改进
 - results log 路径
-- 重写 `.helloagents/STATE.md`：将“正在做什么”更新为已完成，保留最终结论摘要，清空阻塞项，并给出可立即执行的下一步（如继续优化、停止、切换目标）
+- 重写 `.helloagents/STATE.md`：将“主线目标”保留为本次优化目标，“正在做什么”更新为已完成，保留最终结论摘要，清空阻塞项，并给出可立即执行的下一步（如继续优化、停止、切换目标）
 
 ## 安全规则
 - 使用 `git revert`（保留历史）而非 `git reset --hard`（丢失历史）

package/skills/commands/plan/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: ~plan
+description: 结构化规划工作流 — 需求澄清、方案收敛、任务分解与方案包生成（~plan 命令）
+policy:
+  allow_implicit_invocation: false
+---
+Trigger: ~plan [description]
+
+`~plan` 是实现前的主规划命令。它负责需求澄清、方案设计、任务拆解与方案落盘；默认停在“形成可执行方案”，只有用户明确授权继续时才衔接执行。
+执行 `~plan` 时，通用阶段边界按当前已加载 bootstrap 执行；本 skill 负责补充 `~plan` 的需求澄清、方案收敛、方案包写入与执行衔接要求。
+`.helloagents/` 在本 skill 中表示逻辑项目空间：`STATE.md` 与 `.ralph-*.json` 保持项目本地；若 `project_store_mode=repo-shared`，知识库、`DESIGN.md` 与 `plans/` / `archive/` 按当前会话注入的项目知识/方案目录解析。
+
+## 铁律
+- 在用户确认方案之前，禁止编写任何实现代码、创建任何实现文件、或执行任何实现操作
+- 需求澄清阶段不读取实现类技能（hello-ui / hello-test / hello-verify 等），需求明确后再按需读取
+- 方案必须收敛为可执行 artifact，不停留在泛化建议
+- 涉及 UI 时，当前方案包中的 UI 决策优先于逻辑 `.helloagents/DESIGN.md`；逻辑 `.helloagents/DESIGN.md`（实际路径按当前项目存储模式解析）优先于通用 UI 规则
+
+## 流程
+
+### 1. 上下文收集与需求澄清准备
+
+已有项目：
+- 按当前已加载 bootstrap 的“.helloagents/ 文件读取优先级”和“项目文件”规则恢复上下文；若当前消息显式继续既有链路，或会话刚经历恢复 / 压缩，先把 `.helloagents/STATE.md` 当恢复快照使用，再用当前用户消息、显式命令、活跃方案包 / PRD 与代码事实校正主线
+- 在需求澄清前，至少确认逻辑 `.helloagents/context.md`、逻辑 `.helloagents/guidelines.md`；涉及 UI 时，如存在逻辑 `.helloagents/DESIGN.md`，一并读取现有设计契约
+- 只扫描与当前需求直接相关的代码文件，用于形成假设和识别约束
+
+全新项目（无 `.helloagents/` 目录）：
+- 跳过项目级上下文读取，直接进入需求澄清
+
+### 2. 需求澄清
+
+目标：通过自然对话明确目的、约束、成功标准与验收边界。
+
+根据项目类型选择模式：
+
+**假设模式**（已有代码库，优先使用）：
+- 先读取 5-15 个相关文件，基于代码证据形成假设
+- 用 2-4 轮确认关键假设
+- 低置信度假设必须明确询问
+
+**交互模式**（全新项目或信息不足）：
+- 每次只问一个问题，优先使用选择题
+- 只确认真正影响执行路径的关键决策
+- 每个问题给出推荐选项和理由
+
+涉及视觉/交互/体验的问题时：
+- 选项必须体现当前前沿水准
+- 每个选项都要有具体、可执行的视觉特征描述
+
+### 3. 方案收敛
+
+基于已确认需求，给出 2-3 个可行方案：
+- 每个方案说明架构思路与关键取舍
+- 标注推荐方案及理由
+- 让用户选择或修正
+
+涉及 UI 的方案：
+- 读取 `hello-ui` SKILL.md
+- 将视觉、交互、设计系统要求纳入方案
+- 区分“本次 feature 的 UI 决策”和“项目级稳定设计契约”：前者写入 `plan.md`，后者同步到逻辑 `.helloagents/DESIGN.md`
+
+### 4. 方案细化
+
+用户确认方向后，一次性输出完整可执行方案：
+- 架构与文件结构
+- 完成定义（功能完成时必须为真的条件、关键验收点、验证主路径= `test-first` 或 `review-first`、reviewer / tester 各自要验证什么）
+- 数据流与错误处理
+- 验证策略
+- 涉及 UI 时的设计方向、状态覆盖与 `DESIGN.md` 更新点
+
+### 5. 写入方案包
+
+将确认的方案写入本地项目：
+- 按当前已加载 bootstrap 的 `.helloagents/` 与流程状态规则，确保最小项目状态已建立
+- 创建逻辑 `.helloagents/plans/YYYYMMDDHHMM_{feature}/`
+- 按模板写入：
+  - `requirements.md`
+  - `plan.md`
+  - `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.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`，不要让 gate / validator 再从 `plan.md` prose 里猜验证主路径
+- 涉及 UI 的项目：生成或更新逻辑 `.helloagents/DESIGN.md`；若原文件不存在，先按模板建立最小设计契约，再写入已确认的稳定设计决策
+- 重写 `.helloagents/STATE.md`，其中“主线目标”写当前规划链路真正要完成的目标，不把旧任务残留为当前主线
+
+知识库完整创建与归档按当前已加载 bootstrap 的后续规则执行。
+
+### 6. 执行决策
+
+展示方案摘要后，仅在是否进入执行仍构成阻塞决策时才询问用户：
+- 开始执行 → 继续进入 `~build`
+- 修改方案 → 返回方案细化
+- 暂不执行，保留方案 → 更新 `STATE.md`；“主线目标”写当前已确认方案要解决的问题，下一步写为“方案已确认；执行需用户明确启动”
+
+如果用户已明确表示继续执行，则视为授权成立，可直接衔接执行。
+
+## 方案包要求
+
+方案包中的 `tasks.md` 必须满足：
+- 每个任务是一个原子操作
+- 明确文件路径、预期变更、完成标准与验证方式
+- 任务之间依赖关系清晰
+- 任务可独立验证
+
+方案包中的 `contract.json` 必须满足：
+- `verifyMode` 只能是 `test-first` 或 `review-first`
+- `testerFocus` 必填
+- `review-first` 时 `reviewerFocus` 必填
+- 涉及 UI 时显式写出 UI 契约来源优先级
+- 若启用 `ui.styleAdvisor`，必须写清触发原因与 focus
+- 若启用 `ui.visualValidation`，必须写清触发原因，以及至少一组关键 screens 或 states
+- 仅在明确需要独立 advisor 时，才填写 advisor 区块；填写后必须写清触发原因、focus 与优先来源