helloagents 2.3.8 → 3.0.2-beta.1

package/skills/hello-subagent/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: hello-subagent
+description: 使用子代理执行任务、并行开发、分派工作时使用。确保子代理有清晰的上下文和验证标准。
+---
+
+子代理编排必须遵循以下规范。
+
+## 编码前
+先确定任务是否适合子代理（独立性高、边界清晰、可验证）。
+
+## 派遣规范
+- 每个子代理获得：tasks.md 中的对应任务 + 方案包中的相关约束（~design: requirements.md + design.md；~prd: prd/ 中的相关维度文件 + decisions.md）+ 验证命令
+- 新鲜上下文：不继承主会话历史，避免上下文污染
+- 提示开头标记 [子代理任务]，让子代理跳过 bootstrap 加载
+- 单一职责：一个子代理只做一件事
+- 只提取子代理需要的上下文，不把整个方案包全部塞给子代理
+
+## 协调规范
+- 使用子代理时，主代理作为控制器跟踪进度
+- 适用条件：主代理只有在本轮结束流式输出并最终收尾时才可使用 HelloAGENTS 外层输出格式。
+- 排除条件：团队协作中的进度与状态汇报都属于中间输出，不得包装 HelloAGENTS 外层输出格式。
+- 子代理完成后执行双阶段审查：
+  1. 需求符合性审查：变更是否符合方案包需求和 tasks.md 的要求？有无多做或少做？
+  2. 代码质量审查：运行验证命令，审查代码质量
+- 两阶段都通过后才继续下一个任务
+- 子代理报告 BLOCKED：评估阻塞原因，提供更多上下文后重试，或升级到更强模型，或拆分任务，不强制同一方式重试
+- 并行派遣时注意文件冲突（不同子代理不改同一文件）
+
+## 交付检查
+- [ ] 每个子代理有明确的任务边界和验收标准
+- [ ] 子代理输出已审查
+- [ ] 所有变更已通过验证

package/skills/hello-test/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: hello-test
+description: 编写测试、创建测试文件、实现测试覆盖、使用 Jest/Vitest/Mocha/pytest 等测试框架，或实践 TDD、修复失败测试时使用。
+---
+
+测试相关代码必须遵循以下规范。
+
+## 编码前
+先列出被测模块的关键行为和边界条件，设计测试用例，再写测试代码。
+
+## TDD 流程（强制）
+新功能和 Bug 修复必须遵循红-绿-重构循环：
+1. 红 — 写描述期望行为的测试，运行确认失败
+2. 绿 — 写最少的代码让测试通过
+3. 重构 — 清理代码，保持测试通过
+
+如果测试写完就直接通过了，说明测试没有验证新行为——重新审视测试。
+
+豁免场景（标记 [-] 说明原因即可）：
+- 纯 UI 样式调整（无逻辑变更）
+- 配置文件修改
+- 文档/注释变更
+- 快速原型探索（用户明确要求）
+
+除豁免场景外，没有先写测试 = 不能写实现代码。
+
+## 覆盖策略
+- 核心业务逻辑：单元测试必覆盖
+- API 端点：集成测试覆盖主要路径（成功 + 主要失败场景）
+- 关键用户流程：E2E 测试覆盖
+- Bug 修复：先写失败测试，再修复（红-绿验证）
+
+## 测试编写
+- 测试名描述行为：`should reject expired tokens`，不是 `test token`
+- AAA 模式：Arrange（准备）→ Act（执行）→ Assert（断言）
+- 每个测试独立，不依赖执行顺序
+- Mock 外部依赖（数据库/API/文件系统），不 mock 被测代码本身
+
+## 边界用例（必须覆盖）
+- 空值：null / undefined / 空字符串 / 空数组
+- 边界值：0、-1、MAX_INT、超长字符串
+- 错误路径：无效输入、网络超时、权限不足
+- 并发：竞态条件（如果适用）
+
+## 测试质量
+- 避免脆弱测试：不依赖时间、随机数、外部服务
+- 测试数据用 factory/fixture，不硬编码
+- 断言具体值，不只断言"不为空"
+- 一个测试验证一个行为
+
+## 交付检查
+- [ ] 核心逻辑有单元测试
+- [ ] 测试名描述行为
+- [ ] 覆盖了主要边界用例
+- [ ] 测试可独立运行

package/skills/hello-ui/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: hello-ui
+description: 构建任何界面（Web/桌面/移动/游戏 UI）时使用。强制执行独特的、生产级的设计规范，杜绝泛化 AI 美学。
+---
+
+构建任何用户界面时，必须遵循以下设计规范。
+
+## 适用边界
+本技能在涉及视觉变更时激活：构建新 UI、修改现有 UI 样式、更换设计风格等。修复 bug、调整文案、改业务逻辑等不涉及视觉变更的任务，不激活本技能。在已有设计系统中工作时，保留已建立的模式、结构和视觉语言。
+
+## 设计思维（编码前必须完成）
+
+理解上下文，做出大胆且有意图的设计决策：
+
+1. 目的：这个界面解决什么问题？谁在用？什么场景？什么平台？
+2. 美学方向：选择一个鲜明的方向并坚持到底。不从固定列表中选，而是根据项目的受众、场景和情感目标，创造一个忠于上下文的独特风格。问自己：这个产品的用户期待什么情绪？什么视觉语言能传达这种情绪？
+3. 记忆点：用户看到这个设计会记住的一个特征是什么？
+4. 差异化：每次设计必须不同。在明暗主题、字体、美学方向间变换，不收敛到常见选择。
+5. 设计 token：尽早建立变量/token 体系——背景色/表面色/主色/弱化色/强调色 + 展示/标题/正文/说明文字的字体角色。Web 用 CSS 变量，桌面/移动端用平台对应的主题系统。
+6. 约束定义：为当前项目定义具体约束（如最多几个区块、几种字体、几个强调色、首屏的 CTA 数量），约束释放创意。
+7. 真实内容：使用真实文案、产品信息、项目上下文，不使用 Lorem ipsum 或泛化占位符。真实内容帮助做出更贴合上下文的设计决策。
+
+已通过方案包确认设计方向的，按确认的方向执行。
+项目有 .helloagents/DESIGN.md 的，读取并遵循其中的设计系统（方案包中的设计决策优先于 DESIGN.md）。
+未经方案包且无 DESIGN.md 的任务，基于以上规则，结合任务需求和项目上下文，做出设计决策并执行。
+
+## 结构性规则
+
+以下规则关于构图和信息架构，按页面类型适用。
+
+### 展示型页面（着陆页、营销页、产品展示页）
+
+第一屏构图：
+- 第一屏必须是一个完整构图，品牌/产品名必须是英雄级信号
+- 品牌测试：如果去掉导航栏后第一屏可以属于任何品牌，说明品牌感太弱
+
+Hero 区域：
+- Hero 图必须是边到边的主视觉平面或背景
+- Hero 预算：第一屏通常只放品牌、一个标题、一句支撑文案、一组 CTA、一张主图
+- 不在 hero 区域放次要内容，不在 hero 媒体上叠加浮动元素
+
+页面叙事：
+- Hero — 建立身份和承诺
+- 支撑图像 — 展示上下文或环境
+- 产品细节 — 解释产品/服务
+- 社会证明 — 建立可信度
+- 最终 CTA — 将兴趣转化为行动
+
+### 应用型页面（Dashboard、管理后台、工具型应用）
+
+- 信息密度优先：高效展示数据，合理利用空间
+- 清晰的导航层级：主导航/侧边栏/面包屑让用户始终知道自己在哪
+- 操作可发现性：关键操作显眼可达，次要操作收入菜单
+- 状态一目了然：用颜色/图标/徽章传达状态，减少用户认知负担
+
+### 通用规则（所有页面类型）
+
+- 卡片克制：默认不用卡片，卡片仅在作为交互容器时使用。去掉边框/阴影/背景/圆角后不影响理解的就不应该是卡片
+- 区块纪律：每个区块只做一件事，避免堆砌标签集群、统计条、图标行、多个竞争文本块
+- 真实视觉锚点：图像应展示产品、场所、氛围或上下文，装饰性渐变和抽象背景不算主视觉
+
+## 视觉执行
+
+### 字体
+选择有表现力、有目的的字体。展示字体与正文字体配对要有对比（衬线+无衬线，或粗+细）。避免默认字体栈。优先考虑可变字体（减少请求数、支持精细调节）和当前流行的高质量字体。
+
+### 配色
+选择清晰的视觉方向，用 token 体系建立一致性。大胆的主色 + 锐利的强调色，优于胆怯的均匀分配。暗色主题使用降低饱和度的色调变体，不是简单反转。优先使用感知均匀的色彩空间（如 OKLCH）生成和谐的色阶。
+
+### 布局
+有意识的空间运用。非对称、重叠、对角线流动、破格元素都是好工具。建立一致的间距系统，保持全局节奏。优先使用目标平台当前最新的布局能力实现响应式设计。
+
+### 动效
+用动效创造存在感和层次，不是噪音。一个精心编排的入场动画（带交错延迟）优于散落的微交互。时长参考：即时反馈 < 100ms，微交互 150-300ms，复杂过渡 ≤400ms。至少 2-3 个有意图的动效。动画必须可中断，不阻塞用户输入。支持减弱动效偏好设置。优先使用平台原生动画能力，复杂场景再引入动画库。
+
+### 氛围与纹理
+不依赖纯色背景。渐变网格、噪点纹理、几何图案、透明叠层、戏剧性阴影、颗粒覆盖——选择匹配整体美学的手法营造纵深感。
+
+## 实现标准
+
+### 可访问性（最高优先级，所有平台）
+- 颜色对比度 ≥ 4.5:1（正文），≥ 3:1（大文本）
+- 所有交互元素支持键盘/辅助技术操作
+- 不仅靠颜色传达信息（加图标或文字）
+- 支持系统级减弱动效设置
+- Web：语义化 HTML、aria-label、可见焦点环
+- 桌面/移动端：使用平台原生无障碍 API（VoiceOver/TalkBack/Narrator）
+
+### 响应与适配
+- Web：根据产品的主要使用场景确定首要目标视口（桌面端产品以桌面为主设计，移动端产品以移动为主设计），然后适配其他视口。优先使用组件级响应式而非仅依赖视口断点，确保所有目标视口都能正常使用
+- 桌面应用：支持窗口自由缩放，合理的最小窗口尺寸，内容自适应
+- 移动应用：适配不同屏幕尺寸，尊重安全区域（刘海/手势条），支持横竖屏
+- 通用：正文最小 16px/pt，触摸/点击目标 ≥ 44px/pt
+
+### 交互反馈
+- 加载状态：骨架屏 > spinner > 空白等待
+- 空状态、加载态、错误态都要有对应 UI
+- 移动端：合理使用触觉反馈（确认操作、重要动作）
+- 桌面端：支持常用键盘快捷键
+
+### 平台惯例
+- Web：优先平台原生动画能力（CSS 动画、原生过渡 API），复杂场景再引入动画库
+- iOS：遵循 HIG（底部 Tab Bar、滑动返回、Dynamic Type）
+- Android：遵循 Material Design（顶部 App Bar、涟漪反馈、预测性返回）
+- 桌面：遵循平台原生控件风格，除非品牌需要自定义
+- 游戏 UI：优先可读性和操作效率，HUD 不遮挡核心内容
+- 通用：查阅目标平台当前最新的设计指南和 API，不依赖旧版本知识
+
+### 表单
+- 每个输入框必须有可见 label
+- 错误信息紧挨字段显示
+- 失焦时验证
+- 提交时：按钮禁用 + 加载指示 + 成功/失败反馈
+- 长表单自动保存草稿，多步表单显示进度指示器
+- 破坏性操作使用语义危险色并与常规操作视觉分离
+
+### 图表与数据可视化
+- 图表类型匹配数据类型（趋势→折线、对比→柱状、占比→饼图/环形图）
+- 提供图例和交互 tooltip
+- 使用无障碍配色（不仅靠颜色区分数据，辅以图案或标签）
+- 大数据集使用虚拟滚动或聚合展示
+
+## 交互逻辑
+
+### 状态完整性
+每个异步操作必须覆盖四种状态：加载中、成功、错误、空数据。缺少任何一种都是交互缺陷。错误信息必须具体且可操作（说明原因 + 如何修复），不接受"出错了"这类泛化提示。
+
+### 焦点管理
+- 焦点永远不能消失或被意外困住
+- Tab/Shift+Tab 在控件间移动，方向键在复合控件内部导航
+- 模态框打开时焦点困在内部，关闭后焦点回到触发元素
+- 页面/路由切换后焦点移到主内容区域
+- 提交出错后焦点自动移到第一个错误字段
+
+### 模态框与对话框
+- 仅在需要中断用户流程时使用，不用于展示非关键信息
+- 必须支持 Escape 关闭，有明确的关闭/取消入口
+- 不嵌套模态框
+- 有未保存内容时关闭前确认
+
+### 导航
+- 用户始终知道自己在哪（高亮当前位置、面包屑、标题）
+- 返回行为可预测且一致，保留滚动位置和筛选状态
+- 主导航在深层页面仍可达
+- 破坏性操作（删除账号、登出）与常规导航项视觉和空间分离
+
+### 列表与数据
+- 分页适合比较/定位场景，无限滚动适合发现/浏览场景
+- 搜索框在内容密集型应用中必须显眼可达
+- 筛选器随查询上下文动态调整（禁用零结果的选项）
+- 可排序表格标注当前排序状态
+
+### 渐进式披露
+- 复杂功能分步展示，不一次性呈现所有选项
+- 高级设置折叠或收入二级入口
+- 引导新用户逐步发现功能，而非一次性展示全部
+
+## 复杂度匹配
+
+实现复杂度必须匹配美学愿景。大胆的设计需要丰富的代码，精致的设计需要克制和精确。优雅来自于执行愿景的质量，而非堆砌效果。根据上下文做出意外但合理的选择——展现真正的创造力。
+
+## 交付检查
+
+### 清单
+- [ ] 字体：有表现力，配对有对比
+- [ ] 配色：有凝聚力的色彩体系，token 一致
+- [ ] 构图：首屏完整，品牌感强（展示型页面）/ 信息层级清晰（应用型页面）
+- [ ] 结构：区块职责单一，整体有节奏
+- [ ] 动效：至少 2-3 个有意图的动效，可中断，尊重减弱动效设置
+- [ ] 氛围：背景有纵深感
+- [ ] 记忆点：有一个让人记住的设计特征
+- [ ] 状态覆盖：每个异步操作都有加载/成功/错误/空状态
+- [ ] 焦点管理：Tab 顺序合理，模态框焦点困住，关闭后焦点回到触发元素
+- [ ] 可访问性：对比度达标，辅助技术可用
+- [ ] 适配：目标平台上正常使用
+- [ ] 技术现代性：使用的技术方案符合当前已加载 bootstrap 的技术要求；若当前模式未加载质量下限章节，则至少满足技术选型原则且无过时依赖
+- [ ] 未使用当前已加载 bootstrap 明确禁止的过时模式；若当前模式未加载该章节，则至少避免紫色渐变默认配色、白底卡片堆砌、默认字体栈、emoji 图标等已列出的过时模式
+
+### 设计自评
+对以下维度各打 1-10 分，低于 8 分的维度必须迭代改进：
+- 字体表现力与配对质量
+- 配色凝聚力与品牌感
+- 构图与视觉层次
+- 动效意图性与流畅度
+- 整体氛围与记忆点
+- 技术现代性与性能表现
+
+3-5 轮迭代后仍低于 8 分的维度，记录原因并与用户讨论。
+
+### 视觉自检
+如果有浏览器工具可用（Playwright MCP 等）：
+1. 截图渲染结果（桌面 + 移动端视口）
+2. 对照设计原则审查截图：构图是否完整？品牌感是否到位？配色是否一致？
+3. 发现问题 → 修复 → 再截图验证
+4. 确认截图与设计意图一致后才能报告完成
+
+无浏览器工具时，仔细审查生成的代码，确认样式、布局、动效的实现与设计意图一致。

package/skills/hello-verify/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: hello-verify
+description: 声称工作完成前、提交代码前、创建 PR 前、报告任务完成前使用。确保验证命令已运行并检查输出后才能声称成功。
+---
+
+声称完成之前，必须有验证证据。
+
+## 铁律
+
+没有运行验证命令 = 不能说"完成"、"通过"、"已修复"。
+没有看到验证输出 = 不能声称结果。
+
+## 验证循环（Ralph Loop）
+
+验证不是一次性操作，而是循环直到通过：
+
+```
+任务完成
+  ↓
+运行验证命令（lint/test/build/typecheck）
+  ↓
+全部通过？
+  ├─ 是 → 收集已激活技能的交付检查清单 → 逐项确认 → 报告完成
+  └─ 否 → 反思 → 修复 → 重新运行验证（回到循环开头）
+```
+
+这个循环没有上限。验证失败就修复，修复后再验证，直到全部通过。
+不允许在验证失败的状态下报告完成或询问用户是否跳过。
+
+## 反思（验证失败时必须执行）
+
+验证失败后，禁止跳过反思直接改代码。必须先回答：
+1. 失败的根本原因是什么？
+2. 之前的实现遗漏了什么？
+3. 修复方案是什么？会不会引入新问题？
+
+### 断路器
+连续 3 次以上验证失败 → 激活 hello-debug 的卡住升级机制。
+
+### 进展检测
+声称任务完成时，必须有实际文件变更。如果 git diff 为空（没有任何文件变更），不能声称完成了产出文件的任务。
+
+### 原子性自检
+提交前检查变更范围：
+- 如果单次变更涉及 >5 个文件 → 暂停，重新评估是否应该拆分为多个独立变更
+- 用一句话描述变更内容，如果需要用"和"连接不相关的操作 → 拆分为多次提交
+- 每次提交应该是一个原子操作：要么全部有意义，要么全部回滚
+
+### 代码体积检查
+变更涉及的文件必须符合当前已加载 bootstrap 的编码原则中的体积控制规则：
+- 文件/类 >300 行 → 评估是否需要拆分
+- 文件/类 >400 行 → 必须按职责拆分（例外：生成代码、大型测试夹具、迁移脚本、协议常量表）
+- 函数/方法 >40 行 → 评估是否需要拆分
+- 函数/方法 >60 行 → 必须拆分
+
+### 回归守卫
+优化或新增功能不能破坏已有测试：
+- 修改代码后，先运行已有测试确认无回归
+- 如果新代码让指标改善但已有测试失败 → 修复回归（最多 2 次尝试），不修改已有测试
+- 已有测试是底线，不能为了新功能而降低底线
+
+## 验证命令来源
+- .helloagents/verify.yaml 中的 commands（优先）
+- package.json 中的 lint/test/typecheck 脚本
+- pyproject.toml 中的 ruff/mypy/pytest
+
+## 交付检查清单门控
+
+验证命令全部通过后，还需要：
+这些标记只用于交付检查清单、验收记录和验证结果，不用于普通说明、方案解释或进度汇报。
+1. 收集所有已激活 hello-* 技能的交付检查清单
+2. 逐项确认每个检查项，标记 [√] 并附带证据（如：`src/api.ts:42` 使用了参数化查询）
+3. 不适用的项标记 [-] 并说明原因
+4. 有未通过项 → 修复 → 重新运行验证循环
+
+## 需求追踪验证
+
+如果有方案包（requirements.md），执行完成后必须交叉检查：
+1. 逐条读取 requirements.md 的需求（核心目标、功能边界、质量要求）
+2. 确认每条需求都有对应的任务实现，没有被静默丢弃
+3. 确认非目标章节列出的内容确实没有被实现（防止范围蔓延）
+4. 发现遗漏 → 补充实现 → 重新验证
+
+## 反代理目标漂移 (APGD)
+
+验证时必须区分真正目标和代理指标：
+- 真正目标：用户实际要解决的问题（功能正确、体验达标、需求满足）
+- 代理指标：测试通过、lint 干净、类型检查通过、diff 整洁
+
+代理指标全部通过 ≠ 真正目标达成。验证时必须回答：
+1. 用户的真正目标是什么？
+2. 代码是否真的实现了这个目标？（不是"测试说通过了"，而是"功能确实能用"）
+3. 是否存在测试通过但功能实际不工作的情况？（如：测试 mock 了关键依赖、测试只验证了 happy path）
+
+## 目标反向验证
+
+不要从"任务完成了吗"出发，而是从目标反向推导：
+1. 明确阶段目标（用户要什么结果？）
+2. 反向推导：要达成这个目标，哪些条件必须为真？
+3. 逐条验证每个条件，使用四级验证深度
+
+### 四级验证深度
+每个关键产出必须通过四级检查：
+1. 存在 — 文件/函数/组件确实存在
+2. 真实 — 包含真实实现（不是 stub、TODO、placeholder、空函数）
+3. 连接 — 被其他代码导入/调用/使用（不是孤立的死代码）
+4. 数据流 — 有真实数据流过（API 返回真实数据、UI 渲染真实内容、事件真实触发）
+
+未通过任何一级 → 视为未完成，必须修复。
+
+## 危险信号
+
+以下想法意味着你在合理化跳过验证：
+- "应该没问题了" → 运行验证
+- "我很有信心" → 信心 ≠ 证据
+- "linter 过了" → linter ≠ 测试 ≠ 构建
+- "代码改了应该修好了" → 运行验证确认
+- "就这一次跳过" → 没有例外
+- "问问用户要不要跳过" → 不允许，必须修复
+- "先写完再测" → 未经测试的代码是负债不是资产
+- "已经手动测过了" → 手动测试无记录、不可重复、不可回归
+- "太简单不需要测" → 简单代码在复杂系统中照样出错
+- "这次例外" → 每个例外都成为先例
+- "用户没要求测试" → 质量是底线不是选项
+
+## 五步证据链（每次声称完成前必须走完）
+
+1. 识别 — 确定哪个命令能证明你的声明
+2. 运行 — 完整执行该命令
+3. 阅读 — 审查完整输出和退出码
+4. 验证 — 确认输出确实支持你的声明
+5. 声明 — 附带证据报告结果

package/skills/hello-write/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: hello-write
+description: 撰写文档、README、技术方案、分析报告、用户指南，或任何需要专业文本产出的任务时使用。
+---
+
+文本产出必须遵循以下规范。
+
+## 编码前
+先确定：受众是谁？目的是什么？读者读完应该能做什么？
+
+## 结构
+- 金字塔原则：结论先行，细节递进
+- 每段一个核心观点
+- 使用标题层级建立清晰导航
+- 长文档提供目录或摘要
+
+## 表达
+- 主动语态优于被动语态
+- 短句优于长句（中文 ≤40 字/句，英文 ≤25 词/句）
+- 技术术语首次出现时解释
+- 避免模糊词（"一些"、"可能"、"大概"）→ 用具体数据
+
+## 格式
+- 代码块标注语言
+- 表格对齐、列表层级清晰
+- 关键信息加粗或用 callout 突出
+- 中英文之间加空格
+
+## 交付检查
+- [ ] 结构清晰，有层级导航
+- [ ] 无模糊表达，关键数据具体
+- [ ] 格式规范，排版专业
+- [ ] 受众适配（技术深度匹配读者水平）

package/skills/helloagents/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: helloagents
+description: 每次对话开始时使用 — 建立质量驱动工作流，通过技能标准、流程纪律和检查清单三重保障确保交付质量
+---
+
+# HelloAGENTS
+
+适用条件：如果你是主代理并触发或读取任意 skill，只有在该条消息是本轮已经结束流式输出的最终收尾消息时，才按当前已加载 bootstrap 规则包装 HelloAGENTS 外层输出格式；任何 skill 若在当前轮明确要求输出停顿、确认或总结，对应消息也必须同时满足相同条件。
+排除条件：如果你是被派遣执行特定任务的子代理，跳过此 skill 的路由与流程要求，直接执行任务；基础安全、质量与失败处理规则仍持续生效，且无论是否触发或读取其他 skill，都不得包装 HelloAGENTS 外层输出格式。所有流式内容、进度或状态汇报、中间文本，以及任何仍将继续执行的文本，都不得触发外层格式。
+
+## 三重质量保障
+
+以下三重机制是强制性的，没有例外，不可跳过，不可简化。
+
+### 质量标准
+每个 hello-* 技能的规范是强制性的，不是建议。
+技能被激活时，其中的每一条规范都必须遵守。
+违反规范 = 质量不合格，必须修复。
+
+### 流程纪律（执行时）
+- 统一执行流程的五个阶段（ORIENT→CLARIFY→PLAN→EXECUTE→VALIDATE）不可跳过
+- ~design 的需求挖掘不可跳过，不可一个问题就出方案
+- ~prd 的维度探索不可跳过，每个激活维度必须经过讨论或用户明确跳过
+- ~auto 的复杂度判断不可省略
+- hello-verify 的验证铁律：没有运行验证 = 不能说完成
+
+### 检查清单门控（完成时）
+任务完成后，必须执行以下门控流程（详见 hello-verify）：
+1. 运行验证命令（lint/test/build）→ 循环直到通过
+2. 收集所有已激活技能的交付检查清单
+3. 逐项验证。仅在交付检查清单、验收记录和验证结果中使用 [√] / [-] 标记，并附带证据；普通说明、方案解释、状态汇报不用这些标记
+4. 有未通过项 → 修复后重新检查
+5. 全部通过 → 才能报告完成
+
+未经门控就报告完成 = 违反 HelloAGENTS 核心规则。
+
+## 技能加载规则（渐进式披露）
+
+技能分三层加载，严格按需，不提前读取：
+
+Layer 1 — 元数据（启动时已知，不需要读取文件）：
+仅凭下方列表中的名称和描述判断技能是否可能相关。
+
+Layer 2 — 完整技能（进入对应阶段时读取 SKILL.md）：
+当任务进入某个阶段且该阶段需要某技能的规范时，才读取该技能的 SKILL.md。
+
+Layer 3 — 资源文件（技能内引用时读取）：
+技能 SKILL.md 中引用的 templates/、modules/*.md 等文件，仅在技能明确要求时读取。
+
+禁止行为：
+- 禁止在 ORIENT/CLARIFY 阶段读取实现类技能（hello-ui/hello-test/hello-verify 等）
+- 禁止因为"可能用到"就提前读取技能文件——等到真正需要时再读
+- 同一轮内对同一配置文件、模块、SKILL、模板只读取一次，后续直接复用已得结论，不重复探测或重复读取同一路径
+- 若项目已初始化，项目根 AGENTS.md / CLAUDE.md / .gemini/GEMINI.md 已由宿主自动加载，无需再次读取；仅按需读取具体 SKILL.md，不扫描整个 `skills/helloagents/` 目录
+- ~command 命令只读取对应的 command SKILL.md，不连带读取其他技能
+
+## 技能查找路径
+
+读取其他技能时，按以下路径查找，找到即停，不自行猜测或遍历其他路径。
+
+### hello-* 技能
+1. `{CWD}/skills/helloagents/skills/{技能名}/SKILL.md`
+2. 当前已加载 HelloAGENTS 包根目录下的 `skills/{技能名}/SKILL.md`
+
+### ~command 命令技能
+1. `{CWD}/skills/helloagents/skills/commands/{name}/SKILL.md`
+2. 当前已加载 HelloAGENTS 包根目录下的 `skills/commands/{name}/SKILL.md`
+命中路径后立即停止，不要再探测另一路径，也不要重复读取同一命令 skill。
+
+## 技能索引（仅元数据）
+
+### 编码时（EXECUTE 阶段按需读取）
+- hello-ui — 构建 UI/页面/组件时
+- hello-api — 构建/修改 API 时
+- hello-data — 数据库/迁移/事务时
+- hello-security — 涉及认证/密钥/权限时
+- hello-errors — 错误处理/日志/重试时
+- hello-perf — 性能优化/查询/缓存时
+- hello-arch — 重构/架构决策时
+- hello-test — 编写测试时（TDD：EXECUTE 开始时读取）
+
+### 特定场景（触发时读取）
+- hello-debug — 调试错误/修复 bug/排查失败时
+- hello-subagent — 使用子代理执行任务时
+- hello-write — 撰写文档/报告/方案等非编码文本时
+- hello-review — 审查代码/检查变更时
+
+### 完成时（VALIDATE 阶段读取）
+- hello-verify — 声称完成前（必定读取）
+- hello-reflect — 符合触发条件时（详见 hello-reflect SKILL.md）
+
+## 命令路由
+
+用户使用 `~command` 时，只读取对应的 command skill，路径按上方“~command 命令技能”规则查找：
+- `~auto`
+- `~design`
+- `~prd`
+- `~loop`
+- `~init`
+- `~test`
+- `~verify`
+- `~review`
+- `~commit`
+- `~clean`
+- `~help`
+
+只有当对应 command skill 明确要求再读取 hello-* 技能时，才按上方“hello-* 技能”规则继续读取。

package/templates/CHANGELOG.md

@@ -0,0 +1,5 @@
+# 变更日志
+
+## [0.1.0] - YYYY-MM-DD
+### 新增
+- **[项目]**: 初始化

package/templates/DESIGN.md

@@ -0,0 +1,19 @@
+# {项目名} 设计系统
+
+## 美学方向
+[整体视觉风格和情感基调]
+
+## 设计 token
+[变量体系：背景色、表面色、主色、强调色、语义色、字体角色]
+
+## 布局策略
+[各视口的布局方式、网格系统、响应式策略]
+
+## 记忆点
+[用户会记住的一个标志性设计特征]
+
+## 动效策略
+[入场动画、交互反馈、状态过渡；尊重 prefers-reduced-motion]
+
+## 约束定义
+[字体数量、强调色数量、核心区块数量、CTA 数量等具体上限]

package/templates/STATE.md

@@ -0,0 +1,19 @@
+# 恢复快照
+
+## 正在做什么
+[一句话：当前任务 + 当前正在执行的具体步骤，无任务时写"空闲"]
+
+## 关键上下文
+[恢复工作必需的最小信息集——已做的关键决策、已修改的文件和变更摘要、当前依赖的假设。无则留空]
+
+## 下一步
+[具体到可以立即执行的下一个动作，包含文件路径。无则留空]
+
+## 阻塞项
+（无）
+
+## 方案
+[plans/{feature}/ 目录路径，无方案包则留空]
+
+## 已标记技能
+[hello-* 列表，无则留空]

package/templates/archive/_index.md

@@ -0,0 +1,4 @@
+# 方案归档索引
+
+| 日期 | 方案 | 摘要 |
+|------|------|------|

package/templates/context.md

@@ -0,0 +1,19 @@
+# 项目上下文
+
+## 概述
+[项目做什么、解决什么问题、给谁用]
+
+## 技术栈
+[语言、框架、构建工具、测试框架、主要依赖]
+
+## 架构
+[核心模块、依赖关系、数据流向]
+
+## 目录结构
+[关键目录和文件的作用说明]
+
+## 模块文档
+[链接到 modules/ 下的各模块文档]
+
+## 最近变更
+见 [CHANGELOG.md](CHANGELOG.md)

package/templates/guidelines.md

@@ -0,0 +1,15 @@
+# 项目约定
+
+<!-- 只记录从代码看不出来的约定。AI 能从代码推断的风格不需要写在这里。 -->
+
+## 编码风格
+[非显而易见的约定——从现有代码无法推断的规则]
+
+## 命名规范
+[变量/函数/文件/目录的命名风格——仅记录特殊约定]
+
+## Git 工作流
+[分支命名、commit 格式、PR 流程]
+
+## 测试
+[测试框架、测试文件位置、覆盖要求]

package/templates/modules/module.md

@@ -0,0 +1,13 @@
+# 模块: {名称}
+
+## 用途
+[这个模块做什么]
+
+## 关键文件
+[主要源文件及其职责]
+
+## 依赖
+[依赖哪些其他模块]
+
+## 经验
+[调试发现、架构决策、踩坑记录——增量追加，不重写]