helloagents 3.0.12 → 3.0.15-beta.1

package/skills/hello-debug/SKILL.md

@@ -7,6 +7,7 @@ description: 调试错误、修复 bug、排查失败测试、处理异常行为
 
 ## 编码前
 禁止未经根因分析直接修复。
+先建立可运行、可重复、可判断的反馈循环；没有反馈循环，不直接猜原因或改代码。
 
 ## Git 作为记忆
 每次调试前，先读取相关的 git 历史：
@@ -14,11 +15,19 @@ description: 调试错误、修复 bug、排查失败测试、处理异常行为
 - `git log --all --grep="revert"` 查看过去的失败回滚
 - 如果发现之前已经尝试并回滚过类似修复 → 不要重复同样的方向
 
+## 反馈循环优先
+
+反馈循环是调试入口，必须能证明“问题出现 / 问题消失”：
+- 优先写失败测试；不适合写测试时，用 HTTP 脚本、CLI 样例输入、浏览器脚本、请求 / 事件回放、最小验证脚本、差异对比或压力循环复现
+- 循环要尽量快、稳定、断言具体症状，不用“没有崩溃”代替正确性
+- 非确定性问题先提高复现率，记录触发次数、失败比例和关键条件
+- 实在无法建立循环时，停止并说明已尝试方式，向用户请求日志、录屏、请求记录、环境访问或授权加临时观测点
+
 ## 四阶段调试法
 
 ### 1. 定位
 - 完整读取错误信息（不截断、不猜测）
-- 稳定复现问题（确定触发条件）
+- 用反馈循环稳定复现问题（确定触发条件）
 - 反向追踪数据流（从错误点向上游追溯）
 
 ### 2. 分析
@@ -27,7 +36,8 @@ description: 调试错误、修复 bug、排查失败测试、处理异常行为
 - 识别所有隐含假设
 
 ### 3. 假设
-- 形成具体、可验证的假设
+- 形成 3-5 个按可能性排序的假设
+- 每个假设必须可证伪：写清“如果原因是 X，那么改变或观测 Y 会出现 Z”
 - 单变量测试（一次只改一个东西）
 - 记录每次尝试和结果
 
@@ -36,6 +46,11 @@ description: 调试错误、修复 bug、排查失败测试、处理异常行为
 - 实现最小修复（针对根因，不是症状）
 - 验证修复有效且无回归
 
+## 临时观测点
+- 临时日志必须带唯一前缀，如 `[DEBUG-a4f2]`
+- 禁止“到处打印再搜索”；每个观测点都要对应一个假设
+- 收尾前搜索前缀，删除所有临时日志、临时验证脚本和实验文件；确需保留时移动到明确的 debug 目录并说明原因
+
 ## 卡住升级机制
 
 连续修复失败时，按以下阶梯升级策略：
@@ -53,6 +68,8 @@ description: 调试错误、修复 bug、排查失败测试、处理异常行为
 
 ## 交付检查
 - [ ] 根因已识别并记录
-- [ ] 有失败测试复现 bug
+- [ ] 已建立能证明问题出现 / 消失的反馈循环
+- [ ] 有失败测试复现 bug，或已说明没有合适测试切入点并给出替代验证
 - [ ] 单一修复针对根因
+- [ ] 临时观测点和实验文件已清理
 - [ ] 无回归引入

package/skills/hello-review/SKILL.md

@@ -32,8 +32,8 @@ description: 审查代码变更、检查 PR、review 代码质量，或用户要
 - 审查结束时必须单独给出一行“审查结论：...”
 - 若发现阻塞问题，结论中明确写出存在问题，并在正文中为每个问题附文件定位
 - 若未发现阻塞问题，明确写“审查结论：未发现阻塞问题。”
-- 若当前项目已激活，且本轮审查结果需要进入后续交付检查或收尾，审查结论确定后立即调用 `scripts/review-state.mjs write` 写 `.helloagents/.ralph-review.json`
-- `.ralph-review.json` 必须使用结构化字段记录：`outcome`（`clean` / `findings`）、`conclusion`、`findings`、`fileReferences`
+- 若当前项目已激活，且本轮审查结果需要进入后续交付检查或收尾，审查结论确定后立即调用 `scripts/review-state.mjs write` 写当前会话 `artifacts/review.json`
+- `artifacts/review.json` 必须使用结构化字段记录：`outcome`（`clean` / `findings`）、`conclusion`、`findings`、`fileReferences`
 - 不要依赖“审查结论：...”这行让运行时再从自然语言里猜机器结论；这行只服务于人类阅读
 
 ## 交付检查

package/skills/hello-subagent/SKILL.md

@@ -4,7 +4,7 @@ description: 使用子代理执行任务、并行开发、分派工作时使用
 ---
 
 子代理编排必须遵循以下规范。
-`.helloagents/` 在本 skill 中统一按项目级存储路径理解：状态文件只使用 `state_path`，`.ralph-*.json` 保持项目本地；若 `project_store_mode=repo-shared`，方案包、`verify.yaml` 与 `DESIGN.md` 按当前上下文中已注入的项目知识/方案目录解析。
+`.helloagents/` 在本 skill 中统一按项目级存储路径理解：状态文件只使用 `state_path`；会话证据使用当前 `state_path` 所在目录下的 `artifacts/*.json`；若 `project_store_mode=repo-shared`，方案包、`verify.yaml` 与 `DESIGN.md` 按当前上下文中已注入的项目知识/方案目录解析。
 
 ## 编码前
 先确定任务是否适合子代理（独立性高、边界清晰、可验证）。
@@ -20,7 +20,7 @@ description: 使用子代理执行任务、并行开发、分派工作时使用
 - 使用子代理时，主代理作为控制器跟踪进度
 - 主代理只有在本轮最终收尾时才可使用 HelloAGENTS 外层输出格式。
 - 团队协作中的进度与状态汇报都属于中间输出，不得包装 HelloAGENTS 外层输出格式。
-- 子代理不得调用 `scripts/turn-state.mjs write` 代替主代理写完成态或等待态；turn-state 只由主代理在本轮最终收尾前写入
+- 子代理不得调用 `helloagents-turn-state write` 代替主代理写完成态或等待态；需要运行时状态信号时只由主代理写入
 - 子代理完成后执行双阶段审查：
   1. 需求符合性审查：变更是否符合方案包需求和 tasks.md 的要求？有无多做或少做？
   2. 代码质量审查：运行验证命令，审查代码质量

package/skills/hello-test/SKILL.md

@@ -6,7 +6,7 @@ description: 编写测试、创建测试文件、实现测试覆盖、使用 Jes
 测试相关代码必须遵循以下规范。
 
 ## 编码前
-先列出被测模块的关键行为和边界条件，设计测试用例，再写测试代码。
+先列出被测模块的公共接口、关键行为和边界条件，设计测试用例，再写测试代码。
 
 ## TDD 流程（强制）
 新功能和 Bug 修复必须遵循红-绿-重构循环：
@@ -15,6 +15,7 @@ description: 编写测试、创建测试文件、实现测试覆盖、使用 Jes
 3. 重构 — 清理代码，保持测试通过
 
 如果测试写完就直接通过了，说明测试没有验证新行为——重新审视测试。
+必须按垂直切片推进：一个行为 → 一个失败测试 → 最小实现 → 通过后再进入下一个行为。禁止先批量写完所有测试，再批量写实现。
 
 豁免场景（标记 [-] 说明原因即可）：
 - 纯 UI 样式调整（无逻辑变更）
@@ -31,10 +32,11 @@ description: 编写测试、创建测试文件、实现测试覆盖、使用 Jes
 - Bug 修复：先写失败测试，再修复（红-绿验证）
 
 ## 测试编写
+- 测试通过公共接口验证外部可观察行为，不测试私有函数、内部调用顺序或实现形状
 - 测试名描述行为：`should reject expired tokens`，不是 `test token`
 - AAA 模式：Arrange（准备）→ Act（执行）→ Assert（断言）
 - 每个测试独立，不依赖执行顺序
-- Mock 外部依赖（数据库/API/文件系统），不 mock 被测代码本身
+- Mock 外部依赖（数据库/API/文件系统），不 mock 被测代码本身；如果必须 mock 内部协作者，先评估接口是否过浅或测试切入点是否错误
 
 ## 边界用例（必须覆盖）
 - 空值：null / undefined / 空字符串 / 空数组
@@ -47,8 +49,10 @@ description: 编写测试、创建测试文件、实现测试覆盖、使用 Jes
 - 测试数据用 factory/fixture，不硬编码
 - 断言具体值，不只断言"不为空"
 - 一个测试验证一个行为
+- 好测试应能承受内部重构；如果重命名内部函数就导致测试失败，说明测试耦合了实现
 
 ## 交付检查
+- [ ] 测试覆盖公共接口和外部行为，不锁定实现细节
 - [ ] 核心逻辑有单元测试
 - [ ] 测试名描述行为
 - [ ] 覆盖了主要边界用例

package/skills/hello-ui/SKILL.md

@@ -4,7 +4,7 @@ description: 已进入显式 UI 工作流、已激活项目的视觉变更、设
 ---
 
 本 skill 不是 UI 质量的唯一来源。当前已加载 bootstrap 中的 UI 质量基线负责所有 UI 任务的基础水准；本 skill 在显式 UI 工作流和复杂 UI 任务中，补充更明确的契约执行、实现映射与视觉验收。
-`.helloagents/` 在本 skill 中统一按项目级存储路径理解：`.ralph-*.json` 等运行态证据保持项目本地；若 `project_store_mode=repo-shared`，`DESIGN.md` 与方案包按当前上下文中已注入的项目知识/方案目录解析。
+`.helloagents/` 在本 skill 中统一按项目级存储路径理解：会话证据使用当前 `state_path` 所在目录下的 `artifacts/*.json`；若 `project_store_mode=repo-shared`，`DESIGN.md` 与方案包按当前上下文中已注入的项目知识/方案目录解析。
 
 ## 适用边界
 已进入显式 UI 规划/实现/验证路径，或当前项目已激活且任务涉及整页新建、跨多个组件的视觉重做、设计系统改造、需要截图验收的界面任务时，读取本 skill。
@@ -19,7 +19,7 @@ description: 已进入显式 UI 工作流、已激活项目的视觉变更、设
 
 ## 核心职责
 - 遵循上游契约：把 `plan.md` / PRD / `DESIGN.md` 中已确认的 UI 决策视为强约束，而不是建议
-- 处理可选 UI 契约：若 `contract.json` 启用 `ui.styleAdvisor`，复用 `.helloagents/.ralph-advisor.json` 记录设计方向复查证据；若启用 `ui.visualValidation`，用 `.helloagents/.ralph-visual.json` 记录视觉验收证据
+- 处理可选 UI 契约：若 `contract.json` 启用 `ui.styleAdvisor`，复用当前会话 `artifacts/advisor.json` 记录设计方向复查证据；若启用 `ui.visualValidation`，用当前会话 `artifacts/visual.json` 记录视觉验收证据
 - 映射到代码结构：明确 token 放在哪里、组件边界如何划分、状态组件如何组织、动效与主题如何实现
 - 做视觉验收闭环：优先使用截图/浏览器工具做桌面与移动端检查；没有工具时也要完成结构化视觉自检
 - 回写稳定决策：只把跨 feature 稳定成立的设计系统规则同步回 `.helloagents/DESIGN.md`（按当前项目存储模式解析），不要把一次性页面细节全部写成项目级契约
@@ -218,8 +218,8 @@ Hero 区域：
 1. 截图渲染结果（桌面 + 移动端视口）
 2. 对照设计原则审查截图：构图是否完整？品牌感是否到位？配色是否一致？
 3. 发现问题 → 修复 → 再截图验证
-4. 若当前契约要求 `ui.visualValidation.required=true`，调用 `scripts/visual-state.mjs write` 写 `.helloagents/.ralph-visual.json`，记录 `reason`、`tooling`、`screensChecked`、`statesChecked`、`status` 与 `summary`
+4. 若当前契约要求 `ui.visualValidation.required=true`，调用 `scripts/visual-state.mjs write` 写当前会话 `artifacts/visual.json`，记录 `reason`、`tooling`、`screensChecked`、`statesChecked`、`status` 与 `summary`
 5. 确认截图与设计意图一致后才能报告完成
 
 无浏览器工具时，仔细审查生成的代码，确认样式、布局、动效的实现与设计意图一致。
-若当前契约要求 `ui.visualValidation.required=true`，仍需用结构化结论调用 `scripts/visual-state.mjs write` 写 `.helloagents/.ralph-visual.json`，并明确标记所用 tooling 与已检查的 screens / states。
+若当前契约要求 `ui.visualValidation.required=true`，仍需用结构化结论调用 `scripts/visual-state.mjs write` 写当前会话 `artifacts/visual.json`，并明确标记所用 tooling 与已检查的 screens / states。

package/skills/hello-verify/SKILL.md

@@ -4,7 +4,7 @@ description: 声称工作完成前、提交代码前、创建 PR 前、报告任
 ---
 
 声称完成之前，必须有验证证据。
-`.helloagents/` 在本 skill 中统一按项目级存储路径理解：`.ralph-review.json`、`.ralph-visual.json`、`.ralph-closeout.json` 等交付证据保持项目本地；若 `project_store_mode=repo-shared`，`verify.yaml`、方案包与 `DESIGN.md` 按当前上下文中已注入的项目知识/方案目录解析。
+`.helloagents/` 在本 skill 中统一按项目级存储路径理解：交付证据写入当前 `state_path` 所在目录下的 `artifacts/*.json`；若 `project_store_mode=repo-shared`，`verify.yaml`、方案包与 `DESIGN.md` 按当前上下文中已注入的项目知识/方案目录解析。
 
 ## 铁律
 
@@ -59,6 +59,8 @@ description: 声称工作完成前、提交代码前、创建 PR 前、报告任
 - 修改代码后，先运行已有测试确认无回归
 - 如果新代码让指标改善但已有测试失败 → 修复回归（最多 2 次尝试），不修改已有测试
 - 已有测试是底线，不能为了新功能而降低底线
+- Bug 修复必须复跑最初的复现循环；如果没有自动化回归测试，必须记录替代验证和无法补测试的原因
+- 新增或修改测试时，确认测试验证公共接口和用户可观察行为，而不是实现细节
 
 ## 验证命令来源
 - 逻辑 `.helloagents/verify.yaml` 中的 commands（优先；`project_store_mode=repo-shared` 时按共享知识目录解析）
@@ -73,10 +75,11 @@ 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` 写成最新结构化证据；若没有视觉验收证据，不得把本轮视为 UI 可交付
-8. 准备以本轮最终收尾消息报告完成时，先调用 `scripts/turn-state.mjs write` 写 `kind=complete`、`role=main`；若因阻塞判定等待输入或因前置条件缺失而停下，写 `kind=waiting` 或 `kind=blocked`，并同时写 `reasonCategory` 与 `reason`，不要让运行时从自然语言消息里猜状态
+5. 若当前存在方案包并准备最终收尾，优先调用 `scripts/closeout-state.mjs write` 写当前会话 `artifacts/closeout.json`，记录 `requirementsCoverage` 与 `deliveryChecklist` 两项结论；两项都必须包含 `status`（`PASS` / `BLOCKED`）和 `summary`
+6. 若当前方案包要求 `review-first`，必须先确认当前会话 `artifacts/review.json` 已通过 `scripts/review-state.mjs write` 写成最新结构化证据；不要把审查自然语言消息直接当成交付证据
+7. 若 `contract.json` 中 `ui.visualValidation.required=true`，必须确认当前会话 `artifacts/visual.json` 已通过 `scripts/visual-state.mjs write` 写成最新结构化证据；若没有视觉验收证据，不得把本轮视为 UI 可交付
+8. 本地版本检查点：非只读任务完成验证且产生工作区变更时，最终收尾前自动执行本地提交。先检查 `git status --short`；若不是 git 仓库或无变更则跳过。若发现 `.env`、密钥、凭据、明显不应提交的大文件或二进制产物，停止提交并说明风险；否则执行 `git add -A`，使用当前回复语言生成简洁 conventional commit message 后执行 `git commit`。不自动远程 `git push`，除非用户明确要求
+9. 若本轮需要运行时识别验证收尾状态，优先调用 `helloagents-turn-state write --kind complete --role main`；若因阻塞判定等待输入或因前置条件缺失而停下，写 `kind=waiting` 或 `kind=blocked`，并同时写 `reasonCategory` 与 `reason`；显式 `~auto` / `~loop` 下还要写 `blocker.target`、`blocker.evidence`、`blocker.requiredAction`，不要让运行时从自然语言消息里猜状态
 
 ## 需求追踪验证
 
@@ -86,8 +89,8 @@ description: 声称工作完成前、提交代码前、创建 PR 前、报告任
 3. 确认非目标章节列出的内容确实没有被实现（防止范围蔓延）
 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 证据，不得把本轮视为可交付
-7. 若 `contract.json` 中 `ui.visualValidation.required=true`，额外确认 `.helloagents/.ralph-visual.json` 已存在、覆盖要求的关键 screens / states，且结论为 `PASS`；若没有视觉验收证据，不得把本轮视为 UI 可交付
+6. 若 `contract.json` 中 `advisor.required=true` 或 `ui.styleAdvisor.required=true`，额外确认当前会话 `artifacts/advisor.json` 已存在且结论为 clean；若没有 advisor 证据，不得把本轮视为可交付
+7. 若 `contract.json` 中 `ui.visualValidation.required=true`，额外确认当前会话 `artifacts/visual.json` 已存在、覆盖要求的关键 screens / states，且结论为 `PASS`；若没有视觉验收证据，不得把本轮视为 UI 可交付
 8. 发现遗漏 → 补充实现 → 重新验证
 
 ## 目标偏移检查

package/skills/helloagents/SKILL.md

@@ -1,19 +1,19 @@
 ---
 name: helloagents
-description: 每次对话开始时使用 — 建立质量驱动工作流，通过技能标准、流程纪律和检查清单三重保障确保交付质量
+description: 按任务类型适用 — 建立质量驱动工作流，通过技能标准、流程纪律和检查清单保障交付质量
 ---
 
 # HelloAGENTS
 
 主代理触发或读取任意 skill 时，只有在该条消息是本轮最终收尾消息时，才按当前已加载 bootstrap 规则包装 HelloAGENTS 外层输出格式；任何 skill 若在本轮明确要求输出停顿、确认或总结，对应消息也必须同时满足相同条件。
 子代理只豁免路由与收尾要求，直接执行任务；安全、质量、验证和失败处理规则仍持续生效，且不得包装 HelloAGENTS 外层输出格式。所有流式内容、进度或状态汇报、中间文本，以及任何仍将继续执行的文本，都不得触发外层格式。
-主代理在本轮最终收尾前，如要报告“已完成 / 等待输入 / 本轮阻塞”，必须先调用 `scripts/turn-state.mjs write` 写机器可读的 turn-state；不要让运行时再从自然语言或图标反推状态。若写 `kind=waiting` 或 `kind=blocked`，还必须同时写 `reasonCategory` 与 `reason`。子代理不得写 turn-state。
+只有运行时必须识别本轮“完成 / 等待输入 / 阻塞”时，主代理才写 turn-state；普通问候、普通问答、T0 只读分析和一次性解释不调用。必须调用场景：显式 `~auto` / `~loop`、非只读任务完成验证并进入收尾、需要 delivery gate / Ralph Loop / closeout evidence、需要等待或阻塞且运行时必须识别状态、已进入项目连续流程或方案包闭环。首选 `helloagents-turn-state write --kind complete --role main`；等待或阻塞时写 `kind=waiting` / `kind=blocked`，并同时写 `reasonCategory` 与 `reason`。显式 `~auto` / `~loop` 下，还必须写入 `blocker.target`、`blocker.evidence`、`blocker.requiredAction`。不要查找、读取或拼接 `turn-state.mjs` 源码路径。子代理不得写 turn-state。
 
-`.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/` 按当前上下文中已注入的“当前项目存储”/“项目知识/方案目录”解析，不要假定这些文件一定实际位于当前工作树中。
+`.helloagents/` 在所有 skill 中都统一按项目级存储路径理解：项目本地 `.helloagents/` 继续承担激活信号和会话运行态；状态文件只使用 `state_path`（实际位于 `sessions/{branch}/{session-or-default}/STATE.md`）；会话证据使用当前 `state_path` 所在目录下的 `artifacts/*.json`；若 `project_store_mode=repo-shared`，`context.md`、`guidelines.md`、`DESIGN.md`、`verify.yaml`、`modules/`、`plans/`、`archive/` 按当前上下文中已注入的“当前项目存储”/“项目知识/方案目录”解析，不要假定这些文件一定实际位于当前工作树中。
 
 ## 三重质量保障
 
-以下三重机制是强制性的，没有例外，不可跳过，不可简化。
+以下三重机制按任务类型适用；一旦当前任务进入对应阶段，对应机制就是强制要求，不可跳过或弱化。普通问候、普通问答、T0 只读分析和一次性解释不进入完整实现、验证或收尾流程。
 
 ### 质量标准
 每个 hello-* 技能的规范是强制性的，不是建议。
@@ -22,7 +22,7 @@ description: 每次对话开始时使用 — 建立质量驱动工作流，通
 
 ### 流程纪律（执行时）
 - 执行 command skill 时，公共阶段边界以当前已加载 bootstrap 为准；command skill 只补充该命令的专属动作和边界
-- 统一执行流程的六个阶段（ROUTE/TIER→SPEC→PLAN→BUILD→VERIFY→CONSOLIDATE）不可跳过
+- 统一执行流程的六个阶段（ROUTE/TIER→SPEC→PLAN→BUILD→VERIFY→CONSOLIDATE）按当前 Delivery Tier 和实际任务推进；未进入的阶段不强行补齐，已进入的阶段不可跳过
 - 所有 UI 任务先受当前 bootstrap 的 UI 质量基线约束；已激活项目或显式 UI 工作流中的设计约束优先级固定为：当前 `plan.md` / PRD UI 决策 → `.helloagents/DESIGN.md`（按当前项目存储模式解析） → `hello-ui` 深层规则
 - 方案包存在 `contract.json` 时，验证分流、reviewer / tester 关注边界、可选 style advisor / visual validation 与交付检查优先按它执行，不再从自然语言总结里回推
 - 因阻塞判定而必须等待用户输入时，遵循当前 bootstrap 的等待输入规则，不得把等待输入包装成完成态
@@ -64,15 +64,20 @@ Layer 3 — 资源文件（技能内引用时读取）：
 
 读取其他技能时，按以下路径查找，找到即停，不自行猜测或遍历其他路径。
 
-路径定义：`{HELLOAGENTS_READ_ROOT}` = 本轮已确定的 HelloAGENTS 读取根目录
+路径定义：`{HELLOAGENTS_READ_ROOT}` = 本轮已确定的 HelloAGENTS 读取根目录，统一用于读取 `skills/` 与 `templates/`
 先确定当前技能根目录：
 - 优先使用当前上下文中已注入的“本轮 HelloAGENTS 读取根目录”
-- 若当前上下文未注入，则将当前宿主 home 目录下的 `helloagents/` 链接作为 `{HELLOAGENTS_READ_ROOT}`
+- 若当前上下文未注入，则使用稳定运行根目录 `~/.helloagents/helloagents`
+- 宿主固定链接（Codex `~/.codex/helloagents`、Claude `~/.claude/helloagents`、Gemini `~/.gemini/helloagents`）只作为兼容别名，不作为优先探测路径
+- 仍无法确定时，明确说明缺少 HelloAGENTS 读取根目录；不要递归扫描 `$HOME`、`Downloads`、项目目录或旧版本目录
 - 已激活项目或全局模式下，技能是否需要使用由当前已加载 AGENTS 规则决定；不要因此额外探测项目目录里的 HelloAGENTS skills 路径
 
 ### hello-* 技能
 读取 `{HELLOAGENTS_READ_ROOT}/skills/{技能名}/SKILL.md`
 
+### 包内脚本
+优先使用稳定命令入口；需要写收尾状态时优先调用 `helloagents-turn-state write --kind complete --role main`，不要拼接 `turn-state.mjs` 路径。
+
 ### ~command 命令技能
 若当前上下文已解析出具体命令技能文件路径，直接使用它；否则读取 `{HELLOAGENTS_READ_ROOT}/skills/commands/{name}/SKILL.md`
 确定路径后立即停止，不要重复读取同一命令 skill。

package/templates/context.md

@@ -9,6 +9,12 @@
 ## 架构
 [核心模块、依赖关系、数据流向]
 
+## 领域语言
+[只记录本项目特有概念，不记录通用编程术语]
+- **标准术语**：定义（一句话）；避免用语：别名/易混词
+- **关系**：术语 A 与术语 B 的关系、数量约束或生命周期关系
+- **已消除歧义**：曾经混用的词 → 当前统一含义
+
 ## 目录结构
 [关键目录和文件的作用说明]
 

package/templates/plans/plan.md

@@ -6,6 +6,9 @@
 ## 架构与实现策略
 [关键决策及理由]
 
+## 领域语言
+[涉及项目特有概念时填写：标准术语、避免用语、关键关系；无则标记不适用]
+
 ## 完成定义
 [功能完成时必须为真的条件、关键验收点、验证主路径（test-first / review-first）、reviewer / tester 关注边界]
 

package/templates/plans/tasks.md

@@ -1,10 +1,15 @@
 # {项目/功能名称} — 任务分解
 
+## 拆分原则
+- 默认按端到端垂直切片拆分：每个任务交付一个可验证行为，而不是单独交付某一层。
+- `AFK` 表示代理可独立完成；`HITL` 表示需要用户决策、外部凭据、人工视觉确认或手动验收。
+- 厚任务必须继续拆小；横向前置任务只在确有技术依赖时保留。
+
 ## 任务列表
 [按执行顺序排列，每个任务独立可验证]
-- [ ] 任务1：描述（涉及文件：path/to/file.ts；完成标准：功能行为或验收结果；验证方式：npm run test -- feature）
-- [ ] 任务2：描述（涉及文件：...；完成标准：...；验证方式：...）
-- [ ] 任务3：描述（涉及文件：...；完成标准：...；验证方式：...）
+- [ ] 任务1（AFK/HITL）：端到端行为描述（依赖：无；涉及文件：path/to/file.ts；预期变更：...；完成标准：功能行为或验收结果；验证方式：npm run test -- feature）
+- [ ] 任务2（AFK/HITL）：端到端行为描述（依赖：任务1；涉及文件：...；预期变更：...；完成标准：...；验证方式：...）
+- [ ] 任务3（AFK/HITL）：端到端行为描述（依赖：...；涉及文件：...；预期变更：...；完成标准：...；验证方式：...）
 
 ## 进度
 [执行过程中更新]