auto-goal

name	auto-goal
version	1.3.0
description	文件化自动 Goal 执行技能，适用于任何仓库或工作区。用于用户要求 auto-goal、Goal 模式、带 goal 文件的 Codex/Claude 原生目标模式、文件维护目标、自修正目标、人机协作目标、子代理辅助执行、跨 Codex/Claude/其他 agent 互操作目标、HTN 递归分解、HGoal 风格执行、Ponytail 风格最小实现审查，或 SkillOpt 风格的目标与流程迭代优化。

Auto Goal

使用本技能时，将用户意图转换为一个文件化任务，并通过反复的子目标循环执行。goal.md 保持简洁、可人工实时编辑；循环细节、证据、子代理报告和错误路径放在配套文件中。

优先阅读

1. 首先遵循宿主仓库的基准要求，包括根目录或局部 agent 指令、工作流规则、安全规则、语言偏好、技术栈要求、构建/测试命令、依赖策略、目录约定和贡献约定。
2. 读取用户当前请求和用户提供的目标文件路径。
3. 如果用户提供了 goal.md，或当前任务目录已存在 goal.md，先读取它。
4. 只读取定义证据、约束和安全写入范围所需的任务相关项目文件。
5. 当当前循环会用到相关思想时，先检查本地副本或本地笔记中的 DietrichGebert/ponytail 和 microsoft/SkillOpt。如果本地副本缺失或可能过时，再在线学习上游仓库。
6. 如果多处指令冲突，先遵守系统/开发者/用户等更高优先级指令，再遵守最近的仓库指令。

仓库基准捕获

在创建或更新 goal.md 之前，识别并记录约束此 Goal 的宿主仓库基准。

最低基准字段：

• 面向用户回复和持久文档的语言偏好。
• 技术栈、框架、运行时、包管理器和版本约束。
• 与目标相关的构建、测试、lint、format、QA、发布或验证命令。
• 依赖策略：是否允许新增依赖，是否优先标准库、原生 API 或既有项目依赖。
• 目录和产物约定，包括生成任务文件和最终输出应放置的位置。
• 破坏性操作、密钥、外部服务、网络访问和生成资产的安全规则。
• 贡献风格：命名、格式、文档、提交/评审要求和既有代码模式。

把简洁的基准摘要写入 goal.md 的 约束 或 执行指导。详细命令证据、已发现文件和未解决问题写入当前循环文件或 references.md。

语言规则

语言偏好是硬约束，不是普通提示。

• 如果用户或仓库要求中文，则 goal.md、references.md、loops/、subagents/ 报告、最终报告、提示词和原生 Goal objective 默认使用中文。
• 如果用户或仓库要求其他语言，则所有持久目标文档和面向用户输出默认使用该语言。
• 只有在用户明确要求英文、双语或某个文件必须使用英文时，才允许偏离默认语言。
• 代码标识符、命令、路径、API 名称、错误消息、引用标题和第三方专有名词可以保持原文。
• 每个 goal.md 的 状态 必须包含 artifact_language，例如 zh-CN、en-US 或 bilingual-zh-en。
• artifact_language 必须同时约束原生 Goal objective。创建 Codex/Claude 原生 Goal 时，objective 应使用该语言，并明确要求每轮重读 goal.md。
• 如果发现既有目标文件语言与仓库或用户偏好不一致，先在 goal.md 中修正 artifact_language 和相关约束，再继续执行。

任务目录

• 如果用户提供文件路径，使用该路径。
• 如果用户提供目录，在该目录创建或复用 Auto Goal 任务文件。
• 如果用户提供 goal.md 路径，把它的父目录视为任务目录。
• 如果工作区或仓库明确指定 artifact 根目录，优先使用该目录。
• Auto Goal 的常态结构是 <artifact-root>/goal/<date-slug>/；也就是说 /goal/... 是挂在当前工作环境 artifact 根目录下的固定子结构。
• 如果仓库只指定 output、task-result 或 goal-result 目录，但没有指定 artifact 根目录，使用该目录下最接近 goal/<date-slug>/ 的等价结构。
• 如果仓库没有定义产物目录，本工作环境默认 artifact 根目录为 .artifact，因此使用 .artifact/goal/<date-slug>/。
• 如果已有任务目录在 .agents/artifact/goal/，继续复用该目录，不要为了默认值迁移活跃任务。
• 不要默认把任务状态放进规划/规范目录，除非仓库明确把这些目录指定为 Goal 任务状态的产物位置。
• 如果目标需要跨 agent 或跨会话持续存在，选择已提交或共享的项目路径，并说明它为什么持久。
• 如果目标是本地临时任务，放在仓库的 ignored/local runtime 区域；若没有，则放在 .auto-goal/ 等明确的本地目录。
• 不要把共享目标只存放在 ignored 或机器本地路径中。
• 不要假设任何特定仓库布局、任务系统或技能系统存在。

使用这个结构：

<task-dir>/
  goal.md
  references.md
  loops/
    loop-001.md
  evidence/
  subagents/
  child-goals/

核心目标文件

goal.md 要足够短，方便用户实时检查和编辑。它是协作界面，不是完整日志。

使用 assets/template/goal.md 作为初始形状。有效的 goal.md 只包含顶部程序控制 frontmatter 和下面三个人工协作章节：

• 文件顶部 --- YAML frontmatter：包含机器可读状态字段，格式与 SKILL.md 元数据一致。
• 目标：详细、无歧义的基础目标和紧凑的完成证据。
• 约束：范围限制、排除项、安全规则、兼容需求、仓库语言偏好和技术要求。
• 执行指导：每轮如何拆分子目标、遵循仓库约定并验证。

程序控制字段必须放在文件顶部 YAML frontmatter 中，避免和正文说明混在一起。旧的 ## 状态 Markdown 表格或 YAML 代码块仍可读取和校验，但创建或实质更新时应迁移为顶部 frontmatter。必需状态键是 status、updated_at、artifact_language、execution_mode、native_goal_id、current_loop、next_sub_goal、last_verified_loop 和 references。

标准状态 frontmatter：

---
status: draft
updated_at: YYYY-MM-DD
artifact_language: zh-CN
execution_mode: simulated-file-goal
native_goal_id: null
current_loop: null
next_sub_goal: 等待用户确认目标文档
last_verified_loop: null
references: references.md
---

使用脚本辅助操作状态：

python .agents/skills/auto-goal/scripts/goal_state.py read <goal.md>
python .agents/skills/auto-goal/scripts/goal_state.py get <goal.md> status
python .agents/skills/auto-goal/scripts/goal_state.py set <goal.md> next_sub_goal "..." --in-place
python .agents/skills/auto-goal/scripts/goal_state.py migrate <goal.md> --in-place

脚本会把旧 ## 状态 表格或 YAML 状态迁移为顶部 frontmatter。不要用临时正则或手工字符串拼接改状态字段。

目标确认和 Grill-Me 澄清

生成或大幅改写 goal.md 后，必须邀请用户确认，然后才能进入执行循环，除非用户明确要求先执行且目标已经无歧义、低风险。

确认流程：

1. 写出 goal.md 草案，状态设为 draft，next_sub_goal 写成“等待用户确认目标文档”。
2. 向用户给出简短确认请求，要求重点检查基础目标、完成证据、约束、排除项、语言和验证方式。
3. 用户确认后，把 status 改为 active，设置第一个可执行 next_sub_goal，再进入原生 Goal 桥接或执行循环。
4. 如果用户修改 goal.md 或聊天中改变目标，重新读取并必要时回到确认流程。

遇到表述不清、边界不明或证据不可验证的目标时，使用 grill-me 思路逐分支澄清：

• 一次只问一个关键问题。
• 如果问题可通过阅读代码、README、任务文件或现有约束回答，先自己查证，不要问用户。
• 每个问题给出推荐答案和原因，方便用户快速确认或修正。
• 沿决策树推进：目标范围 → 非目标 → 成功证据 → 验证方式 → 约束/风险 → 优先级。
• 不要把用户未确认的推断写成事实；可以写入 references.md 的“待确认假设”。
• 如果用户不在线且合理默认足够安全，记录假设并继续低风险准备工作；高风险或会改变目标含义时等待确认。

工作流

1. 先把用户请求转换为详细、无歧义的目标表述，再执行：
   • 保留用户真实意图。
   • 把模糊词扩展为具体交付物、边界和成功标准。
   • 识别假设和未知项。
   • 当歧义会导致执行不安全、大概率走错、完成证据不可验证，或目标范围可能被错误缩小/扩大时，按 grill-me 思路一次问一个问题。
2. 捕获仓库基准，并决定它如何约束语言、技术、验证、目录、依赖和安全。
3. 决定 artifact_language。优先级为：用户明确要求 > 仓库语言规则 > 会话语言 > 任务内容自然语言；无法确定时使用当前对话语言。
4. 定位或创建 Auto Goal 任务目录。
5. 用 artifact_language 对应语言把明确化后的基础目标和简洁仓库基准写入 goal.md；需要时创建 references.md、loops/、evidence/ 和 subagents/。
6. 创建或实质修改后，运行 scripts/validate_goal_file.py <goal.md>。
7. 邀请用户确认 goal.md。确认前保持 status: draft，除非用户已明确授权跳过确认且目标无歧义、低风险。
8. 用户确认后，把状态更新为 active，再尝试桥接到宿主原生 Goal 模式；不可用时记录为文件模拟模式。
9. 每轮开始前必须重新读取 goal.md。用户可能在执行期间直接编辑它。
10. 如果循环会触及新模块、工具、语言、生成产物或外部系统，重新检查任务相关仓库基准文件。
11. 审查适用参考模式：
    • Ponytail：优先不做、复用平台能力、标准库、原生特性、已安装依赖，或实现满足证据的最小方案；不要削弱安全、验证、可访问性或数据丢失处理。
    • SkillOpt：把循环结果视为 rollout 证据；小步、有边界地编辑任务文件；只有当下一个验证门槛更好或能避免已知失败时，才接受方法变化。
12. 根据基础目标和当前状态推导一个有边界的子目标。
13. 创建或更新 loops/loop-XXX.md，记录：
    • 正在处理的基础目标切片。
    • 子目标。
    • 本轮仓库基准检查。
    • 计划。
    • 执行记录。
    • 验证。
    • 结果。
    • 需要回写到 goal.md 或 references.md 的更新。
14. 如果子目标仍然太宽，按下面的 HTN 规则递归分解，不要假装它已经可执行。
15. 执行子目标；当子代理能提升隔离性、审查质量、探索能力或并行进度时，多使用子代理。
16. 验证子目标是否真正推进基础目标，并满足仓库基准。
17. 更新文件：
    • goal.md 保持简洁：状态、下一个子目标，以及变化后的约束或指导。
    • 错误路径、失败计划、有用模式和已接受子代理发现写入 references.md。
    • 详细循环轨迹写入 loops/。
    • 原始证据写入 evidence/。
18. 声称完成前必须满足：
    • goal.md 的 status 是 complete。
    • 基础目标完成证据有当前证明。
    • 最新循环验证通过。
    • 未解决的错误路径或失败计划已被修正，或被声明为外部/非必需。
    • 宿主仓库的完成、测试、安全和评审要求已满足。

原生 Goal 模式桥接

创建或定位 Auto Goal 任务目录后，尽力进入宿主 agent 的原生 Goal 模式。除非存在真实的原生 goal id、工具结果或宿主可见确认，否则不要假设桥接成功。

• Codex：如果可用原生 create_goal 能力，创建一个 Goal，目标是完成指定任务目录中的 Auto Goal。原生 objective 必须使用 artifact_language，提到 goal.md 路径，并要求每轮行动前重读 goal.md。把 execution_mode: native-codex-goal 和返回 id 或证据记录到 native_goal_id。
• Claude：如果宿主暴露原生 goal、plan、project 或 task 执行模式，按宿主规则激活。把 execution_mode: native-claude-goal 和可见 id 或证据记录到 native_goal_id。
• 其他 agent：如果没有原生 Goal 模式，用 goal.md、references.md、loops/、evidence/ 和 subagents/ 模拟 Goal 模式。记录 execution_mode: simulated-file-goal 和 native_goal_id: null。
• 如果原生 Goal 激活失败，把失败写入 references.md，继续以文件为事实来源，设置 execution_mode: simulated-file-goal。
• 除非用户明确要求重启或迁移，不要为同一个 Auto Goal 任务创建多个原生根 Goal。

HTN 递归分解

把 Auto Goal 当作轻量 HTN（Hierarchical Task Network）协议：每个基础目标分解为方法、子目标和可选的子 Auto Goal 任务。

• 把 goal.md 视为根任务节点。
• 把每个循环视为推进根任务的一种已选方法。
• 只有当一个子目标能在一个有边界的循环中完成并验证时，才把它视为可执行叶子。
• 如果子目标本身需要规划、循环、证据或用户编辑，在 child-goals/<child-slug>/ 下创建子 Auto Goal 任务。
• 每个子任务都有自己的 goal.md、references.md、loops/、evidence/、subagents/ 和可选 child-goals/。
• 委托给子任务的父循环必须记录：
  • 子任务路径。
  • 父级基础目标切片。
  • 子级基础目标。
  • 预期子级完成证据。
  • 子级完成后如何更新父级。
• 整合子结果前重新读取父级 goal.md；用户可能已修改父级目标。
• 子任务证据通过、且父循环验证它推进父级基础目标后，才能接受父级子目标。
• 如果用户明确要求 $hgoal，或目标需要递归多代理/隔离工作目录执行，使用 $hgoal；否则用嵌套 Auto Goal 任务目录模拟 HTN 递归。

外部参考审查

把这些项目当作实时参考，不要照搬成教条：

• DietrichGebert/ponytail：实现子目标前，检查最佳动作是否是不做、复用平台/标准库/原生/已安装能力，或实现满足证据的最小方案，同时保留安全关键处理。
• microsoft/SkillOpt：每轮之后，用成功或失败轨迹证据对 goal.md、references.md 和后续循环策略做有边界的小改；不要通过削弱证据让进度看起来更好。

参考查找规则：

• 优先使用本地已检出仓库、本地文档或先前笔记，前提是它们存在且足够新。
• 如果本地参考缺失、不完整或可能过时，在线检查链接的上游仓库。
• 将影响执行的参考经验写入 references.md，包括来源、日期，以及它如何改变下一子目标。

协作循环

把 goal.md 当作用户和 AI 的实时协作界面。

• 把用户对 goal.md 的编辑视为一等指令，但仍受更高优先级系统和仓库规则约束。
• 每轮开始以及任何已知用户编辑后，都重新读取 goal.md。
• 当用户改变语言、目标模块、输出目录、技术或验证期望时，重新读取相关仓库指令。
• goal.md 保持简洁；历史和大块细节放在 references.md、loops/、evidence/ 和 subagents/。
• 如果聊天和 goal.md 冲突，先在 goal.md 中调和冲突，再继续。
• 重要决策优先更新到任务文件，不只留在聊天里。
• 每次修改都要小到用户能检查和继续编辑。

自修正规则

agent 可以在执行时编辑任务文件，但编辑必须保守且可审计。

无需额外确认即可执行：

• 澄清模糊措辞但不改变用户意图。
• 添加缺失证据门槛。
• 把宽泛计划项拆成更小行动。
• 在证据失败后标记某路径为错误方向。
• 添加失败检查后的延续任务。
• 记录新发现的约束。
• 在循环结束时用 goal_state.py 更新顶部 frontmatter 状态。

需要用户明确确认：

• 缩小或替换根目标。
• 删除用户写入的要求。
• 把外部审批、凭据、发布或破坏性操作标记为完成。
• 改变安全边界或写入范围。
• 执行破坏性文件系统变更。

当前计划错误时，不要原样反复重试。更新 references.md 和当前循环，写明：

1. 失败证据。
2. 失败类别，例如 bad-goal、bad-plan、bad-evidence、missing-prerequisite、external-blocker 或 wrong-direction。
3. 改变后的方法或延续任务。
4. 下一验证门槛；如果会改变下一子目标，也反映到 goal.md 状态中。

HGoal 经验

• 根目标保持不变，直到证据证明完成。
• 规划和审查是下一循环的证据，不是完成本身。
• 宽目标要使用具体门槛和完成审计。
• 把状态保存在聊天之外，方便新 agent 接手。
• 当目标足够宽时，使用隔离子任务、独立进程证据或递归 HGoal。
• 每轮都应把基础目标分解为子目标，执行、验证，然后才更新根状态。
• 当一个子目标仍然太大时，允许并鼓励 HTN 分解；创建子 Auto Goal 任务，不要把一个循环塞爆。
• 如果用户明确要求 $hgoal，或目标需要递归多代理执行，使用 $hgoal，并让本技能保持为人类可编辑的 goal 文件层。

子代理使用

当子代理能提升隔离性、审查质量、探索能力或并行进度时，多使用子代理。

• 适合子代理的任务包括独立研究、代码审查、测试设计、替代方案生成、bug 复现、有边界子任务实现，以及根据当前 goal 文件验证。
• 给每个子代理提供当前 goal.md 路径、相关 loop 文件、分配的子目标、允许写入范围、期望证据，以及 subagents/ 下的报告路径。
• 要求子代理用任务文件术语回报：改了什么、哪些证据通过、仍不确定什么，以及是否需要修正 goal.md 或 references.md。
• 不要让子代理输出静默覆盖 goal。只把已接受发现整合进 goal.md、references.md 或当前循环。
• 如果子代理工具不可用，手动保留同样边界：分离子目标、证据和报告。

SkillOpt 启发式优化

像优化一个可编辑技能一样优化任务文件：

• 把失败视为 rollout 证据，而不是尴尬。
• 只编辑最小且有用的目标或方法片段。
• 优先添加示例、门槛和反模式，少写空泛指令。
• 错误路径、失败计划和已接受方法写入 references.md。
• 只有当 goal.md 修改能改善下一执行周期或避免已知失败时，才接受它。
• 不要通过削弱证据、缩窄目标或隐藏未解决工作来优化。

互操作契约

对非 Codex agent：

• goal.md 加最新循环和 references.md 必须包含足够上下文，使其无需聊天记录即可恢复。
• 尽量使用仓库相对路径。
• 避免依赖隐藏 Codex 状态、MCP 专属状态或只存在于记忆里的结论。
• 使用显式字段，不使用工具专属状态名。
• 如果存在工具专属产物，用 Markdown 摘要并链接到路径。

脚本和资产

• assets/template/goal.md：创建 goal.md 时复制或改写。
• assets/template/references.md：创建 references.md 时复制或改写。
• assets/template/loop.md：创建每个循环文件时复制或改写。
• scripts/validate_goal_file.py：机械 Markdown 结构校验器；它不判断目标是否正确。