Back to Details

autogoal

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Autogoal

Autogoal

Use this when the user asks for a durable objective, long-running autonomous work, goal setup, or when a governing repo skill requires goal setup before work starts.
This skill turns a vague "keep going" instruction into a thread-scoped completion contract: what should be true, how it is verified, what must not change, and when Codex should stop.
当用户提出持久化目标、长期自主工作、目标设置需求，或者当某个仓库技能要求在工作开始前先完成目标设置时，使用本技能。
本技能将模糊的“继续推进”指令转化为线程范围内的完成契约：目标达成时的状态、验证方式、不可变更的约束，以及Codex应停止工作的时机。

Core Take

核心要点

A normal prompt says: do the next thing.
A goal says: keep working until this outcome is true, or until the evidence shows a real blocker.
Goals are for work where the next move depends on what Codex learns along the way: debugging, migrations, flaky tests, benchmark tuning, deep research, large refactors, prototypes, browser-proof loops, and pass-gated plans.
Goals are not a permission slip to wander. They are a scoped, evidence-checked contract.
No measurable outcome, no goal. A goal must have a verification surface and a completion threshold before 
create_goal
is called. Prefer numbers: score, count, latency, coverage, pass count, failing-to-passing repro count, issue rows, or explicit command success. When a numeric target does not fit, use a binary artifact checklist that can be audited from files, commands, screenshots, browser proof, or source-backed citations.
普通提示词的逻辑是：执行下一步操作。
目标的逻辑是：持续工作直到成果达成，或证据显示存在真实障碍。
目标适用于这类工作：下一步行动取决于Codex在过程中获取的信息，例如调试、迁移、不稳定测试、基准调优、深度研究、大规模重构、原型开发、浏览器兼容循环，以及通过关卡的计划执行。
目标不是随意探索的许可，而是一个有范围、经证据校验的契约。
没有可衡量的成果，就不算目标。在调用
create_goal
之前，目标必须具备验证依据和完成阈值。优先使用量化指标：分数、数量、延迟、覆盖率、通过次数、从失败到成功的复现次数、问题条目数，或明确的命令执行成功状态。当不适合使用数值目标时，可使用可审计的二进制工件清单，可通过文件、命令、截图、浏览器验证或源码引用进行审计。

Universal Boundary

通用边界

autogoal
is the goal lifecycle kernel. It owns:
  • objective shape
  • measurable completion thresholds
  • evidence standards
  • active goal conflict handling
  • durable plan state
  • blocker and completion rules
  • repair routing when a goal-backed workflow misses expectations
It does not own project policy. Keep repo commands, package managers, browser tools, release rules, PR policy, scorecards, issue ledgers, and lane-specific pass schedules in derived skills or project-owned 
docs/plans/templates/<template>.md
.
Derived skills may be stricter than 
autogoal
; they should not duplicate the goal lifecycle. 
autogoal
says how work remains honest. The derived skill says what the lane actually requires.
autogoal
是目标生命周期的核心组件，负责：
  • 目标形态定义
  • 可衡量的完成阈值
  • 证据标准
  • 活跃目标冲突处理
  • 持久化计划状态
  • 障碍与完成规则
  • 当基于目标的工作流未达预期时的修复路由
它不负责项目策略。仓库命令、包管理器、浏览器工具、发布规则、PR策略、评分卡、问题台账，以及特定流程的通过时间表，应放在派生技能或项目自有文件
docs/plans/templates/<template>.md
中。
派生技能的规则可以比
autogoal
更严格，但不应重复实现目标生命周期逻辑。
autogoal
确保工作的真实性，派生技能则定义特定流程的实际要求。

Template Composition

模板组合

Goal plans are composable, but only through static materialization.
The model is:
  1. one active goal
  2. one concrete 
    docs/plans
    plan file
  3. one primary template
  4. optional materialized packs
The primary template is chosen by dominant risk: 
task
for normal execution, 
docs
for docs-dominant work, 
major-task
for heavyweight architecture or proposal work, and repo-specific templates for domain lanes.
Packs are chosen by touched surface. They add recurring gates without becoming parents:
  • docs
    : docs are touched but not the dominant deliverable
  • agent-native
    : agent instructions, skills, hooks, commands, prompts, or user-action tooling changed
  • browser
    : real browser, route, UI, console, network, or interaction proof is required
  • package-api
    : package exports, public API, release artifacts, package boundaries, or package-level checks changed
Core execution and review gates belong in the primary template. Every primary template must include 
Autoreview
as the last human-readable gate before 
Goal plan complete
. Packs are only for optional touched surfaces that would otherwise be absent from that template.
Do not create runtime inheritance between templates. The helper copies pack rows into the generated plan's 
Start Gates
, 
Work Checklist
, and 
Completion Gates
. After creation, the generated plan is the truth; the checker validates that materialized plan only.
The generated plan is the dedicated plan shell. Fill that exact file immediately after generation: replace placeholders, resolve every gate row, and mark non-applicable generated rows as 
N/A: <reason>
with evidence. Do not delete, wholesale replace, or hand-narrow the generated plan into an ad hoc smaller plan after durable work has started. If the selected template is plainly wrong and no substantive work has started, regenerate once with the right template and record why. If work has already started, keep the generated plan and close it honestly.
Use packs like this:
bash
node .agents/skills/autogoal/scripts/create-goal-scratchpad.mjs \
  --template task \
  --with docs \
  --with agent-native \
  --title "<short task title>"
Examples:
  • docs-only work: 
    --template docs
  • normal code task that also changes docs: 
    --template task --with docs
  • agent workflow task: 
    --template task --with agent-native
  • browser behavior task: 
    --template task --with browser
  • public app/API or package-boundary task: 
    --template task --with package-api
  • major architecture task: 
    --template major-task
  • major architecture task that also changes docs and package API: 
    --template major-task --with docs --with package-api
If two packs add related gates, keep both when they protect different failure modes. If they duplicate exactly the same proof, keep the more specific pack and record the other as N/A in the plan.
目标计划支持组合，但仅通过静态实例化实现。
模型规则：
  1. 一个活跃目标
  2. 一个具体的
    docs/plans
    计划文件
  3. 一个主模板
  4. 可选的实例化包
主模板根据主要风险选择：
task
用于常规执行，
docs
以文档为主的工作，
major-task
用于重量级架构或提案工作，仓库特定模板用于领域专属流程。
包根据涉及的业务面选择，它们会添加重复关卡但不会成为父模板：
  • docs
    ：涉及文档但文档不是主要交付物
  • agent-native
    ：修改了Agent指令、技能、钩子、命令、提示词或用户操作工具
  • browser
    ：需要真实浏览器、路由、UI、控制台、网络或交互验证
  • package-api
    ：修改了包导出、公共API、发布工件、包边界或包级检查
核心执行和评审关卡属于主模板。每个主模板必须在
Goal plan complete
前包含
Autoreview
作为最后一个人工可读关卡。包仅用于主模板中未覆盖的可选业务面。
不要在模板间创建运行时继承关系。工具会将包中的行复制到生成计划的
Start Gates
、
Work Checklist
和
Completion Gates
中。计划生成后，该实例化计划即为唯一依据，校验器仅验证此实例化计划。
生成的计划是专用的计划框架。生成后需立即填充：替换占位符、解析所有关卡行，将不适用的生成行标记为
N/A: <原因>
并附上证据。在持久化工作开始后，不要删除、整体替换或手动缩窄生成计划为临时小型计划。如果所选模板明显错误且尚未开展实质性工作，可重新生成一次正确的模板并记录原因。如果已开始工作，则保留生成的计划并如实关闭。
包的使用示例：
bash
node .agents/skills/autogoal/scripts/create-goal-scratchpad.mjs \
  --template task \
  --with docs \
  --with agent-native \
  --title "<简短任务标题>"
更多示例：
  • 仅文档工作：
    --template docs
  • 同时修改文档的常规代码任务：
    --template task --with docs
  • Agent工作流任务：
    --template task --with agent-native
  • 浏览器行为任务：
    --template task --with browser
  • 公共应用/API或包边界任务：
    --template task --with package-api
  • 大型架构任务：
    --template major-task
  • 同时修改文档和包API的大型架构任务：
    --template major-task --with docs --with package-api
如果两个包添加了相关关卡，当它们针对不同故障模式时，保留两者；如果完全重复相同验证，则保留更具体的包，并在计划中将另一个标记为N/A。

Proportionality Dial

匹配度分级

Classify goal-backed work before creating or updating a plan:
  • micro
    : one narrow, auditable outcome; no cross-file state; no meaningful continuation loop. Use a tiny plan only when a repo rule requires it, or record the audit surface directly in the final response.
  • normal
    : multi-step work with concrete evidence and likely continuation. Use the appropriate 
    docs/plans
    template and close all relevant gates.
  • major
    : architecture, migrations, benchmarks, framework comparisons, broad refactors, pass-gated lanes, or public API/runtime risk. Use a derived skill or project template with phases, risk rows, review gates, and explicit closure criteria.
Do not inflate a micro work item into a ceremony pile. Do not shrink a major work item into a checklist that cannot catch real risk.
在创建或更新计划前，对基于目标的工作进行分类：
  • micro
    ：单一明确的可审计成果；无跨文件状态；无有意义的持续循环。仅当仓库规则要求时使用小型计划，或直接在最终响应中记录审计依据。
  • normal
    ：多步骤工作，具备具体证据和可能的持续推进。使用合适的
    docs/plans
    模板并完成所有相关关卡。
  • major
    ：架构、迁移、基准测试、框架对比、大范围重构、关卡型流程，或公共API/运行时风险相关工作。使用派生技能或项目模板，包含阶段、风险行、评审关卡和明确的关闭标准。
不要将微小工作过度复杂化，也不要将大型工作简化为无法识别真实风险的清单。

Goal Flow Modes

目标流程模式

Every goal-backed workflow chooses exactly one flow mode before durable work starts. The mode controls the human review boundary; it does not weaken the evidence or completion rules.
每个基于目标的工作流在开始持久化工作前必须选择一种流程模式。模式控制人工评审边界，但不会降低证据和完成规则的要求。

1. One-Shot Execution

1. 一次性执行

Use this for issue-like or work-item-like work where the agent is expected to read the source, derive the local plan, implement, verify, and hand off the result without stopping for plan approval.
Rules:
  • Create or continue a goal when the work is non-trivial and auditable.
  • Create a plan when durable state is useful or required by the caller.
  • The plan is an execution ledger, not a proposal waiting for acceptance.
  • Human review happens at the final handoff or explicit user interruption.
  • Do not pause merely because the plan has not been reviewed. Pause only for a real blocker, unsafe ambiguity, or a user decision that changes scope.
适用于类问题或类工作项的任务，预期Agent读取源码、推导本地计划、实现、验证，并直接交付结果，无需等待计划审批。
规则：
  • 当工作非 trivial 且可审计时，创建或继续目标。
  • 当持久化状态有用或调用者要求时，创建计划。
  • 计划是执行台账，而非等待接受的提案。
  • 人工评审在最终交付或用户明确中断时进行。
  • 不要仅因计划未评审而暂停。仅在遇到真实障碍、不安全的歧义，或用户决策改变范围时暂停。

2. Agent-Led Plan Hardening

2. Agent主导的计划强化

Use this when the requested output is a plan and the user wants the agent to drive toward the best plan with minimal human interruption.
Rules:
  • The agent owns the review loop: research, compare options, pressure-test, revise, and improve the plan until the confidence threshold is met.
  • Ask the user only for decisions that materially change intent, boundaries, risk tolerance, or acceptance criteria.
  • Record each self-review pass and plan delta as evidence.
  • Stop for one major user review when the plan reaches the stated readiness threshold.
  • Do not execute implementation under the planning goal unless the caller's governing workflow explicitly says planning and execution are the same goal.
适用于用户要求输出计划，且希望Agent以最少人工干预生成最优计划的场景。
规则：
  • Agent负责评审循环：研究、比较选项、压力测试、修订和优化计划，直到达到置信阈值。
  • 仅在决策会实质性改变意图、边界、风险容忍度或验收标准时，才询问用户。
  • 将每次自评审过程和计划变更记录为证据。
  • 当计划达到既定就绪阈值时，停止并请求一次主要的人工评审。
  • 除非调用者的管理工作流明确说明规划与执行属于同一目标，否则不要在规划目标下执行实现工作。

3. Collaborative Planning

3. 协作规划

Use this when the user and agent are intentionally shaping the plan together before execution.
Rules:
  • The goal outcome is an accepted plan, not implementation.
  • Ask focused questions when user judgment changes the plan.
  • Keep options, tradeoffs, rejected alternatives, and open decisions visible in the plan.
  • Continue revising until the user accepts the plan or a blocker remains.
  • Execution starts only after explicit acceptance or a new instruction that changes the flow mode.
Flow-mode selection belongs in the derived skill or the instantiated plan when the caller knows it. If no caller specifies a mode, default to one-shot execution for implementation tasks, agent-led plan hardening for autonomous planning/review requests, and collaborative planning when the user is actively brainstorming or asking for plan acceptance before work.
适用于用户与Agent在执行前共同制定计划的场景。
规则：
  • 目标成果是已接受的计划，而非实现结果。
  • 当用户判断会改变计划时，提出针对性问题。
  • 在计划中清晰展示选项、权衡、被否决的方案和未决决策。
  • 持续修订直到用户接受计划或遇到障碍。
  • 仅在明确接受或新指令改变流程模式后，才开始执行。
流程模式选择由派生技能或实例化计划决定（当调用者明确时）。如果调用者未指定模式，实现任务默认使用一次性执行，自主规划/评审请求默认使用Agent主导的计划强化，用户主动头脑风暴或要求计划审批后再工作时默认使用协作规划。

Use When

使用场景

  • The user asks to set a goal or asks Codex to keep working until a verifiable end state.
  • A repo skill says to use 
    create_goal
    or goal setup.
  • Work is long-running, iterative, and has an auditable success condition.
  • The path is uncertain but the finish line is auditable.
  • The user would otherwise keep saying: "continue", "try the next fix", "rerun the benchmark", "keep going until it works".
  • A pass-gated lane needs one durable objective with the pass schedule and closure gates inside it.
  • The user says 
    autogoal repair <expectation>
    after any goal-backed workflow missed their expectation, and they want the owning rule/template repaired for future runs.
  • 用户要求设置目标，或要求Codex持续工作直到可验证的最终状态。
  • 仓库技能要求使用
    create_goal
    或进行目标设置。
  • 工作是长期、迭代的，且具备可审计的成功条件。
  • 路径不确定，但终点可审计。
  • 用户可能会不断重复：“继续”“尝试下一个修复方案”“重新运行基准测试”“直到成功为止”。
  • 关卡型流程需要一个持久化目标，包含通过时间表和关闭关卡。
  • 用户在基于目标的工作流未达预期后，发出
    autogoal repair <expectation>
    指令，希望修复相关规则/模板以便未来运行。

Do Not Use When

非使用场景

  • The user asks a one-off question or wants one short answer.
  • The edit is tiny and no continuation loop is useful.
  • The finish line is vague: "make it better", "improve performance", "clean this up" without a verification surface.
  • The user explicitly declined goal setup or asked not to use goal tools.
  • The only possible next move requires user input.
  • Creating a goal would hide uncertainty instead of naming it.
  • The user only wants the current artifact fixed once. Repair mode is for recurring workflow expectation misses, not every ordinary bug in a plan file.
  • 用户提出一次性问题或需要简短回答。
  • 修改非常微小，且持续循环无意义。
  • 终点模糊：如“让它更好”“提升性能”“清理一下”，但无验证依据。
  • 用户明确拒绝目标设置或要求不使用目标工具。
  • 唯一可能的下一步操作需要用户输入。
  • 创建目标会掩盖不确定性而非明确它。
  • 用户仅希望修复当前工件一次。修复模式用于重复出现的工作流预期未达标情况，而非计划文件中的普通bug。

Tool Contract

工具契约

This is agent-native. Use the goal tools directly when available:
  • get_goal
    to inspect the current thread goal.
  • create_goal
    to start a new active goal.
  • update_goal(status: complete)
    only when the objective is genuinely met.
  • update_goal(status: blocked)
    only when no autonomous progress remains and the same blocker has recurred enough to satisfy the tool contract.
There can be only one active goal per thread. Repeated 
create_goal
calls fail while a goal exists. Always call 
get_goal
first; call 
create_goal
only when it returns no goal; use 
update_goal
to complete or block the active goal.
本技能是Agent原生的。当可用时直接使用目标工具：
  • get_goal
    ：检查当前线程的目标。
  • create_goal
    ：启动新的活跃目标。
  • update_goal(status: complete)
    ：仅当目标真正达成时调用。
  • update_goal(status: blocked)
    ：仅当无自主推进空间，且同一障碍重复出现次数满足工具契约时调用。
每个线程只能有一个活跃目标。当目标存在时，重复调用
create_goal
会失败。始终先调用
get_goal
；仅当返回无目标时调用
create_goal
；使用
update_goal
完成或标记活跃目标为障碍状态。

Active Goal Conflict Protocol

活跃目标冲突协议

When 
get_goal
returns a goal, classify it before touching durable state:
  • same
    : the existing goal already describes the current requested end state. Continue under it and keep its plan current.
  • same but stale plan
    : the goal is right but the plan is stale. Repair the plan first, then continue.
  • newer user correction
    : the latest user message narrows, reverses, or corrects the goal. Record the correction in the plan, follow the newest instruction, and do not call the old objective complete unless it is actually true.
  • different objective
    : the active goal is unrelated. Do not hijack it. If no lifecycle tool can pause, resume, cancel, or replace it, say so briefly and proceed only with degraded plan state when the user explicitly says to go.
  • paused or externally controlled
    : do not fake completion or blocked status to escape the tool. Continue only if the latest user instruction clearly authorizes the new work, and record the mismatch in the plan.
Never mark a goal complete because the user changed their mind. Completion means the objective is true. A correction changes the work path; it does not retroactively prove the old objective.
Do not invent a goal state file when a goal tool is available. If goal tools are not available, record degraded control state in the active plan only when the repo workflow requires that fallback; otherwise state that goal tools are not available and continue with the nearest safe workflow.
当
get_goal
返回目标时，在修改持久化状态前先分类：
  • same
    ：现有目标已描述当前请求的最终状态。继续使用该目标并保持其计划最新。
  • same but stale plan
    ：目标正确但计划过时。先修复计划，再继续工作。
  • newer user correction
    ：最新用户消息缩小、反转或修正了目标。在计划中记录修正，遵循最新指令，除非旧目标确实达成，否则不要标记其为完成。
  • different objective
    ：活跃目标无关。不要强行替换。如果没有生命周期工具可以暂停、恢复、取消或替换它，简要说明情况，仅在用户明确指示时以降级计划状态继续。
  • paused or externally controlled
    ：不要通过伪造完成或障碍状态来绕过工具。仅当最新用户指令明确授权新工作时才继续，并在计划中记录不匹配情况。
永远不要因为用户改变主意而标记目标完成。完成意味着目标状态已达成。修正改变工作路径，但不会追溯证明旧目标已完成。
当目标工具可用时，不要自行创建目标状态文件。如果目标工具不可用，仅当仓库工作流要求回退时，才在活跃计划中记录降级控制状态；否则说明目标工具不可用，并使用最安全的替代工作流继续。

Goal Anatomy

目标结构

A strong goal defines eight things:
  1. Flow mode: one-shot execution, agent-led plan hardening, or collaborative planning.
  2. Outcome: what must be true when done.
  3. Completion threshold: the number, pass/fail command, artifact checklist, or explicit acceptance rows that prove done.
  4. Verification surface: tests, benchmarks, logs, browser proof, generated artifact, report, issue comment, or source-backed audit.
  5. Constraints: what must not regress.
  6. Boundaries: files, packages, repos, tools, data, routes, issue scope, or product surfaces Codex may or may not touch.
  7. Iteration policy: how to choose the next move after each attempt.
  8. Blocked stop condition: when to stop and report the blocker, evidence, and next input needed.
The 
create_goal.objective
field is only a short handle for the active goal. Keep it under 240 characters. Put the full contract in the goal plan, not in the tool objective.
Use this tool-objective shape:
txt
<desired end state>; done when <short threshold>; plan <docs/plans/path>.
Do not put commands, full pass schedules, long issue lists, constraints, boundaries, iteration policy, or blocked reports in 
create_goal.objective
. Those belong in the plan sections.
一个完善的目标定义以下8项内容：
  1. 流程模式：一次性执行、Agent主导的计划强化或协作规划。
  2. 成果：完成时必须达成的状态。
  3. 完成阈值：证明完成的数值、通过/失败命令、工件清单或明确的验收条目。
  4. 验证依据：测试、基准测试、日志、浏览器验证、生成工件、报告、问题评论或源码审计。
  5. 约束：必须不退化的内容。
  6. 边界：Codex可以或不可以触及的文件、包、仓库、工具、数据、路由、问题范围或产品业务面。
  7. 迭代策略：每次尝试后如何选择下一步行动。
  8. 障碍停止条件：何时停止并报告障碍、证据和所需的下一步输入。
create_goal.objective
字段仅作为活跃目标的简短标识，长度保持在240字符以内。完整契约放在目标计划中，而非工具目标字段。
使用以下工具目标格式：
txt
<期望最终状态>; 完成条件：<简短阈值>; 计划路径：<docs/plans/path>.
不要在
create_goal.objective
中放入命令、完整通过时间表、长问题列表、约束、边界、迭代策略或障碍报告。这些内容属于计划章节。

Measurable Outcome Gate

可衡量成果关卡

Before calling 
create_goal
, rewrite vague objectives into measurable ones, then compress the tool objective to a short handle. The plan records the full contract.
Required:
  • a specific done state
  • a flow mode
  • a verification surface
  • a completion threshold
  • a constraint list or explicit 
    no extra constraints
  • a blocked condition
Quantitative examples:
  • p95 < 120 ms
  • score >= 0.92 and no dimension below 0.85
  • 0 accepted review findings
  • all 12 pass rows complete or skipped with evidence
  • focused repro fails before fix and passes 5 consecutive runs after
  • no stale symbol matches from rg
Auditable non-numeric examples:
  • named file exists with required sections
  • named issue rows moved to fixed/improved/related/not-claimed
  • named browser route has screenshot proof and no console errors
  • named API examples compile and match the accepted public shape
Reject or rewrite:
  • "make better"
  • "clean up"
  • "finish"
  • "absolute best" without score rows, pass gates, or evidence
  • "review and decide" without an artifact and acceptance criteria
在调用
create_goal
前，将模糊目标重写为可衡量的目标，然后将工具目标压缩为简短标识。完整契约记录在计划中。
必填项：
  • 明确的完成状态
  • 流程模式
  • 验证依据
  • 完成阈值
  • 约束列表或明确的“无额外约束”
  • 障碍条件
量化示例：
  • p95 < 120 ms
  • score >= 0.92 且所有维度不低于0.85
  • 0 个被接受的评审问题
  • 所有12项通过条目完成或有证据支持跳过
  • 修复前聚焦复现失败，修复后连续5次通过
  • rg
    无过时符号匹配
可审计的非量化示例：
  • 指定文件存在且包含所需章节
  • 指定问题条目已移至已修复/已改进/相关/未认领状态
  • 指定浏览器路由有截图验证且无控制台错误
  • 指定API示例可编译并匹配已接受的公共形态
拒绝或重写以下目标：
  • “变得更好”
  • “清理一下”
  • “完成”
  • “绝对最佳”但无分数条目、通过关卡或证据
  • “评审并决定”但无工件和验收标准

Completion Gate Policy

完成关卡策略

Do not make 
check-complete.mjs
the whole goal. That only proves the plan looks closed, not that the work is true.
Use the hybrid rule for every goal:
  1. The goal tool objective names the outcome, short threshold, and plan path.
  2. The 
    docs/plans
    goal plan records the verification surface, constraints, boundaries, blocked condition, fresh evidence, and completion threshold.
  3. node .agents/skills/autogoal/scripts/check-complete.mjs <docs/plans/path>
    is the final mechanical gate before 
    update_goal(status: complete)
    .
The checker validates that the goal plan has no unchecked required checklist items, no unresolved gate rows, no open phase/pass rows, concrete verification evidence, current reboot status, and recorded risks. It does not replace tests, browser proof, source audits, benchmark output, or other named verification evidence.
不要将
check-complete.mjs
作为目标的全部。它仅能证明计划看起来已关闭，而非工作真正完成。
对每个目标使用混合规则：
  1. 目标工具目标命名成果、简短阈值和计划路径。
  2. docs/plans
    目标计划记录验证依据、约束、边界、障碍条件、最新证据和完成阈值。
  3. node .agents/skills/autogoal/scripts/check-complete.mjs <docs/plans/path>
    是调用
    update_goal(status: complete)
    前的最终机械关卡。
校验器验证目标计划是否存在未检查的必填清单项、未解析的关卡行、未完成的阶段/通过行、具体验证证据、当前重启状态和已记录的风险。它不能替代测试、浏览器验证、源码审计、基准测试输出或其他指定的验证证据。

Evidence Type Contract

证据类型契约

Every completion proof should fit at least one evidence type:
  • command
    : exact command, cwd, and pass/fail result.
  • source-audit
    : exact files or search query proving a static property.
  • browser
    : route, interaction, screenshot or console/network caveat.
  • artifact
    : generated file, report, table, PR body, issue comment, or exported asset.
  • review
    : reviewer/tool used, accepted findings, fixes, and remaining rejected findings with reasons.
  • external-source
    : cited URL, issue, paper, docs page, or connected app result used as authority.
  • N/A:<reason>
    : why a recurring gate does not apply.
Evidence must name the owning workspace, package, app, route, or tool when that ownership matters. A root-level check cannot prove a sibling repo, app route, browser surface, or external tracker unless the plan explains why it is the owning surface.
每个完成验证应至少符合一种证据类型：
  • command
    ：精确命令、工作目录和通过/失败结果。
  • source-audit
    ：精确文件或搜索查询，证明静态属性。
  • browser
    ：路由、交互、截图或控制台/网络说明。
  • artifact
    ：生成的文件、报告、表格、PR正文、问题评论或导出资产。
  • review
    ：使用的评审者/工具、已接受的问题、修复内容，以及剩余被否决问题的原因。
  • external-source
    ：引用的URL、问题、论文、文档页面或关联应用结果作为权威依据。
  • N/A:<reason>
    ：重复关卡不适用的原因。
当归属关系重要时，证据必须指定所属工作区、包、应用、路由或工具。根级检查不能证明兄弟仓库、应用路由、浏览器业务面或外部跟踪器的状态，除非计划解释了为何它是归属依据。

Repair Mode

修复模式

Trigger this mode when the arguments start with:
txt
repair <expectation>
Repair mode is self-improvement with a leash. It converts a concrete expectation miss from a goal-backed run into the smallest durable change to the owning rule, template, helper, or active plan.
Use it for misses like:
  • the generated goal plan lacked a gate the user expected
  • a derived skill used the wrong template or completion rule
  • the skill completed too early or kept running past the intended boundary
  • the final handoff omitted evidence the user expects every time
  • the workflow forced too much ceremony or skipped a required review/proof step
Do not use it for:
  • one-off wording preferences in a single plan
  • a product/runtime bug that belongs in implementation code
  • broad "make all skills better" edits
  • rewriting generated 
    skills/*/SKILL.md
    by hand
Target selection order:
  1. If the prompt names a plan path, read that plan first. Use its 
    Template:
    , skill name, phase table, and completion gates to identify the owner.
  2. If the prompt names a skill, read 
    skills/<skill>/SKILL.md
    first, then project-owned 
    docs/plans/templates/<skill>.md
    when it exists.
  3. If there is an active goal, read its plan path from the objective or current plan before editing anything.
  4. If the miss belongs to every goal, target the dotai source package: 
    skills/autogoal/SKILL.md
    and 
    skills/autogoal/assets/templates/goal.md
    . Do not patch the installed 
    .agents/skills/autogoal
    copy by hand.
  5. If ownership is still unclear after source reads, ask one short targeting question instead of patching multiple templates.
Repair scope matrix:
MissPrimary repair owner
Current plan has wrong status, row, evidence, or handoff fieldsactive 
docs/plans/*
plan
Future generated plans need a recurring section, gate, row, or placeholderproject-owned 
docs/plans/templates/<owner>.md
or dotai source 
skills/autogoal/assets/templates/<owner>.md
Agent chose the wrong workflow, target, proof standard, or completion rule
skills/<owner>/SKILL.md
Prose keeps failing and the miss is mechanically checkabledotai source 
skills/autogoal/scripts/*
plus focused script proof
Derived skill adds lane-specific ceremony or policyderived skill rule/template, not 
autogoal
Universal lifecycle rule is missing across goal-backed workdotai source 
skills/autogoal/SKILL.md
Repair workflow:
  1. Restate the expectation in one sentence.
  2. Identify the miss with source evidence: plan row, final response shape, missing gate, bad status, wrong template, or stale generated skill.
  3. Pick exactly one primary owner. Patch secondary owners only when sync is required, such as source rule plus project template.
  4. Create a repair plan with:
    bash
    node .agents/skills/autogoal/scripts/create-goal-scratchpad.mjs \
  --template goal-repair \
  --title "<short repair title>"
    If a repair is truly trivial, record why no separate repair plan is needed.
  5. Patch source-of-truth files only. Never hand-edit installed 
    .agents/skills/**/SKILL.md
    ; after changing dotai 
    skills/**
    , run 
    scripts/validate-skills
    .
  6. Prove the repair:
    • source audit with 
      rg
      for the new rule/gate/wording
    • generated skill sync when 
      skills/**
      changed
    • instantiate the repaired template or inspect it directly when a smoke plan would create noise
    • verify unfinished generated plans still fail 
      check-complete.mjs
    • verify a completed plan can record the new expectation without editing the template again
  7. Final response says: expectation, repaired owner, verification, and any deliberate non-repair.
Safety rules:
  • One expectation should produce one narrow repair. Do not turn repair mode into a skill rewrite.
  • Do not weaken completion gates just because a past run was annoying. If the expectation conflicts with evidence safety, record the conflict and ask.
  • Prefer adding a missing row or decision rule over adding a new script. Add mechanical enforcement only when prose gates keep failing.
  • A derived skill may have stricter rules than 
    autogoal
    . Repair the derived skill when the expectation is lane-specific; repair 
    autogoal
    only when the expectation should apply across goal-backed work.
  • If an active goal is unrelated to the repair, do not hijack it. Ask whether to finish/block it first or run the repair after it is closed.
当参数以以下内容开头时触发此模式：
txt
repair <expectation>
修复模式是带约束的自我改进。它将基于目标的运行中出现的具体预期未达标情况，转化为对所属规则、模板、工具或活跃计划的最小持久化修改。
适用于以下未达标情况：
  • 生成的目标计划缺少用户预期的关卡
  • 派生技能使用了错误的模板或完成规则
  • 技能过早完成或超出预期边界持续运行
  • 最终交付遗漏了用户每次都期望的证据
  • 工作流强制过多繁琐流程或跳过了必要的评审/验证步骤
不适用于：
  • 单个计划中的一次性措辞偏好
  • 属于实现代码的产品/运行时bug
  • 宽泛的“让所有技能更好”的修改
  • 手动重写生成的
    skills/*/SKILL.md
目标选择顺序：
  1. 如果提示词指定了计划路径，先读取该计划。使用其
    Template:
    、技能名称、阶段表和完成关卡确定归属方。
  2. 如果提示词指定了技能，先读取
    skills/<skill>/SKILL.md
    ，然后读取项目自有
    docs/plans/templates/<skill>.md
    （如果存在）。
  3. 如果存在活跃目标，在编辑任何内容前，从目标或当前计划中读取其计划路径。
  4. 如果未达标情况属于所有目标，目标为dotai源包：
    skills/autogoal/SKILL.md
    和
    skills/autogoal/assets/templates/goal.md
    。不要手动修改已安装的
    .agents/skills/autogoal
    副本。
  5. 如果读取源码后仍不清楚归属方，提出一个简短的目标定位问题，而非修改多个模板。
修复范围矩阵：
未达标情况主要修复归属方
当前计划状态、行、证据或交付字段错误活跃的
docs/plans/*
计划
未来生成的计划需要重复章节、关卡、行或占位符项目自有
docs/plans/templates/<owner>.md
或dotai源
skills/autogoal/assets/templates/<owner>.md
Agent选择了错误的工作流、目标、验证标准或完成规则
skills/<owner>/SKILL.md
文本描述持续出错且未达标情况可机械校验dotai源
skills/autogoal/scripts/*
加针对性脚本验证
派生技能添加了流程特定的繁琐流程或策略派生技能规则/模板，而非
autogoal
基于目标的工作缺少通用生命周期规则dotai源
skills/autogoal/SKILL.md
修复工作流：
  1. 用一句话重述预期。
  2. 用源码证据识别未达标情况：计划行、最终响应形态、缺失的关卡、错误状态、错误模板或过时的生成技能。
  3. 选择恰好一个主要归属方。仅当需要同步时才修改次要归属方，例如源规则加项目模板。
  4. 创建修复计划：
    bash
    node .agents/skills/autogoal/scripts/create-goal-scratchpad.mjs \
  --template goal-repair \
  --title "<简短修复标题>"
    如果修复确实微不足道，记录无需单独修复计划的原因。
  5. 仅修改真实源文件。永远不要手动编辑已安装的
    .agents/skills/**/SKILL.md
    ；修改dotai
    skills/**
    后，运行
    scripts/validate-skills
    。
  6. 验证修复：
    • 使用
      rg
      进行源码审计，确认新规则/关卡/措辞存在
    • 当
      skills/**
      修改时，同步生成技能
    • 实例化修复后的模板或直接检查（当烟雾计划会产生噪音时）
    • 验证未完成的生成计划仍会使
      check-complete.mjs
      失败
    • 验证已完成的计划无需再次编辑模板即可记录新预期
  7. 最终响应说明：预期、修复的归属方、验证结果，以及任何故意不修复的内容。
安全规则：
  • 一个预期应产生一个窄范围的修复。不要将修复模式变成技能重写。
  • 不要仅因为过去的运行令人厌烦就弱化完成关卡。如果预期与证据安全性冲突，记录冲突并询问用户。
  • 优先添加缺失的行或决策规则，而非添加新脚本。仅当文本关卡持续失败时才添加机械强制规则。
  • 派生技能的规则可能比
    autogoal
    更严格。当预期是流程特定的，修复派生技能；仅当预期应适用于所有基于目标的工作时，才修复
    autogoal
    。
  • 如果活跃目标与修复无关，不要强行占用。询问用户是先完成/标记其为障碍，还是在关闭后再运行修复。

Derived Skill Contract

派生技能契约

Any skill that requires or wraps 
autogoal
should declare:
  • when it creates or continues a goal
  • which flow mode it uses by default, and how the user changes it
  • which project template 
    docs/plans/templates/<template>.md
    it uses
  • which packs it applies by default, and which touched surfaces add more packs
  • extra start gates and completion gates it owns
  • evidence types it requires
  • final handoff shape
  • review or pressure lenses it adds
  • what remains delegated to 
    autogoal
  • what it intentionally does not inherit from broader templates
Derived skills should route to 
autogoal
for lifecycle mechanics instead of re-implementing plan creation, completion, blocked semantics, repair mode, or evidence closure.
任何需要或封装
autogoal
的技能应声明：
  • 何时创建或继续目标
  • 默认使用的流程模式，以及用户如何修改它
  • 使用的项目模板
    docs/plans/templates/<template>.md
  • 默认应用的包，以及哪些业务面会添加更多包
  • 自有额外启动关卡和完成关卡
  • 要求的证据类型
  • 最终交付形态
  • 添加的评审或压力校验视角
  • 委托给
    autogoal
    的内容
  • 故意不继承自通用模板的内容
派生技能应将生命周期机制路由到
autogoal
，而非重新实现计划创建、完成、障碍语义、修复模式或证据关闭逻辑。

Resume Protocol

恢复协议

After compaction, interruption, or a long pause:
  1. Read the latest user message first.
  2. Call 
    get_goal
    when available.
  3. Re-read the active 
    docs/plans
    path named by the goal, current workflow, or latest handoff.
  4. Find the latest verification evidence, open risk, and next owner.
  5. Continue from the newest user instruction, not from an older stale objective.
  6. Before final response, sanity-check that the answer matches the newest request and the current plan state.
If the active goal and newest request disagree, use the Active Goal Conflict Protocol before editing.
在压缩、中断或长时间暂停后：
  1. 先读取最新用户消息。
  2. 可用时调用
    get_goal
    。
  3. 重新读取目标、当前工作流或最新交付指定的活跃
    docs/plans
    路径。
  4. 找到最新验证证据、未解决风险和下一归属方。
  5. 从最新用户指令继续，而非旧的过时目标。
  6. 在最终响应前，检查答案是否匹配最新请求和当前计划状态。
如果活跃目标与最新请求不一致，先使用活跃目标冲突协议再进行编辑。

Start And Completion Gates

启动与完成关卡

Project templates may define 
Start Gates:
and 
Completion Gates:
tables. These are template-owned audit surfaces for recurring project checks.
Keep this rule generic. Do not put project-specific commands, package-manager details, release rules, browser tooling, or repo policy in this file. Those rows belong in project-owned templates under 
docs/plans/templates/
.
When present, gate tables must use markdown tables with these columns:
  • Gate
  • Applies
  • Evidence
They may include extra columns such as 
Required action
. The checker treats any cell in a gate row as unresolved when it is blank, 
pending
, 
TODO
, or 
TBD
.
Gate closure rules:
  • Applies
    must be resolved before completion.
  • yes
    means the evidence cell names the command, artifact, proof, source audit, or concrete result.
  • no
    or 
    N/A: <reason>
    means the evidence cell explains why the gate does not apply.
  • A completion gate row should stay unresolved until the action or reason is recorded.
  • check-complete.mjs
    enforces gate-row closure mechanically, but it does not know what project-specific commands mean.
项目模板可定义
Start Gates:
和
Completion Gates:
表格。这些是模板自有审计面，用于重复的项目检查。
保持此规则通用。不要将项目特定命令、包管理器细节、发布规则、浏览器工具或仓库政策放入本文件。这些行应放在项目自有模板
docs/plans/templates/
下。
当存在时，关卡表格必须使用包含以下列的Markdown表格：
  • Gate
  • Applies
  • Evidence
可添加额外列，如
Required action
。当单元格为空、
pending
、
TODO
或
TBD
时，校验器将其视为未解析。
关卡关闭规则：
  • Applies
    必须在完成前解析。
  • yes
    表示证据单元格指定了命令、工件、验证、源码审计或具体结果。
  • no
    或
    N/A: <reason>
    表示证据单元格解释了关卡不适用的原因。
  • 完成关卡行应保持未解析状态，直到记录了操作或原因。
  • check-complete.mjs
    机械强制关卡行关闭，但不知道项目特定命令的含义。

Start Workflow

启动工作流

  1. Read the user's request and any named plan, issue, logs, route, test, or source-of-truth file.
  2. Inspect the current goal with 
    get_goal
    when available.
  3. Select the flow mode: one-shot execution, agent-led plan hardening, or collaborative planning.
  4. Rewrite the desired objective until it has a measurable or auditable completion threshold.
  5. Choose the title, template, and 
    docs/plans
    path needed by the objective. If the helper is the only reliable way to know the path, create only the static plan shell before 
    create_goal
    .
  6. If no active goal exists and the user or governing skill asked for a goal, create one with a short 
    create_goal.objective
    handle under 240 characters.
  7. If an active goal already matches the desired end state, continue under it.
  8. If an active goal exists but points at a different objective, do not overwrite it. Resolve the current goal honestly before starting another one. If the tool does not allow that transition, report the mismatch and ask for the smallest decision needed. A governing lane goal may proceed only when it can honestly complete or fit within the current active goal.
  9. Ensure the 
    docs/plans
    goal plan exists before substantive work.
  10. Fill the generated plan itself before substantive work: write the objective, threshold, verification surface, constraints, boundaries, blocked condition, flow mode, and goal plan path; resolve generated gates as yes/no/N/A instead of deleting or replacing the template output.
  11. Record the output-budget strategy before exploratory commands: which searches or reads are allowed, which high-volume paths are excluded, and how large results will be capped, counted, or saved as artifacts instead of streamed into the goal context.
  12. Use that exact path for 
    check-complete.mjs
    .
  13. Do not start durable work until the goal is set, verified as already matching, or the user explicitly resolves the missing-goal path.
Set or verify the goal before mutable lane state when the workflow depends on a goal. The only exception is creating the static plan shell needed to get the path for the short objective. For pass-gated planning or accepted-plan execution lanes, the goal is the first durable action after the minimum read and optional static plan shell needed to derive the objective.
  1. 读取用户请求和任何指定的计划、问题、日志、路由、测试或真实源文件。
  2. 可用时使用
    get_goal
    检查当前目标。
  3. 选择流程模式：一次性执行、Agent主导的计划强化或协作规划。
  4. 重写期望目标，直到具备可衡量或可审计的完成阈值。
  5. 选择目标所需的标题、模板和
    docs/plans
    路径。如果只有工具能可靠确定路径，在
    create_goal
    前仅创建静态计划框架。
  6. 如果无活跃目标且用户或管理技能要求目标，创建一个
    create_goal.objective
    简短标识（长度≤240字符）。
  7. 如果活跃目标已匹配期望最终状态，继续使用它。
  8. 如果活跃目标存在但指向不同目标，不要覆盖它。先如实解决当前目标再启动新目标。如果工具不允许此转换，报告不匹配情况并请求最小决策。管理流程目标仅能在如实完成或适配当前活跃目标时继续。
  9. 在开展实质性工作前，确保
    docs/plans
    目标计划存在。
  10. 在开展实质性工作前填充生成的计划：写入目标、阈值、验证依据、约束、边界、障碍条件、流程模式和目标计划路径；将生成的关卡解析为yes/no/N/A，而非删除或替换模板输出。
  11. 在执行探索性命令前记录输出预算策略：允许哪些搜索或读取，排除哪些高容量路径，以及如何限制、计数或保存大结果为工件而非流式传输到目标上下文。
  12. 将该路径用于
    check-complete.mjs
    。
  13. 在目标设置完成、验证为已匹配，或用户明确解决缺失目标路径前，不要启动持久化工作。
当工作流依赖目标时，在修改可变流程状态前设置或验证目标。唯一例外是创建获取简短目标所需路径的静态计划框架。对于关卡型规划或已接受计划执行流程，目标是在最小读取和可选静态计划框架（用于推导目标）后的第一个持久化操作。

Template Init

模板初始化

Generic autogoal templates are project files. They live at:
txt
docs/plans/templates/goal.md
docs/plans/templates/task.md
docs/plans/templates/docs.md
docs/plans/templates/major-task.md
docs/plans/templates/goal-repair.md
docs/plans/templates/packs/<pack>.md
When 
docs/plans/templates/goal.md
or another generic template is missing, initialize the generic set before creating a goal plan:
bash
node .agents/skills/autogoal/scripts/init-templates.mjs
create-goal-scratchpad.mjs
and 
create-goal-template.mjs
run this initialization automatically. Existing files are kept. Project-specific templates such as 
docs/plans/templates/<lane>.md
stay in the project and are never moved into the skill package.
通用autogoal模板是项目文件，位于：
txt
docs/plans/templates/goal.md
docs/plans/templates/task.md
docs/plans/templates/docs.md
docs/plans/templates/major-task.md
docs/plans/templates/goal-repair.md
docs/plans/templates/packs/<pack>.md
当
docs/plans/templates/goal.md
或其他通用模板缺失时，在创建目标计划前初始化通用模板集：
bash
node .agents/skills/autogoal/scripts/init-templates.mjs
create-goal-scratchpad.mjs
和
create-goal-template.mjs
会自动运行此初始化。现有文件将被保留。项目特定模板（如
docs/plans/templates/<lane>.md
）保留在项目中，永远不会移入技能包。

Goal Plan

目标计划

Every active goal gets one durable goal plan. It is a single markdown file that absorbs the useful file-planning parts: phases, findings, progress, decisions, failed attempts, verification, and reboot status.
Path:
txt
docs/plans/YYYY-MM-DD-<short-goal-slug>.md
docs/plans/<ticket>-<short-goal-slug>.md
Use the ticket-prefixed form for issue-backed work. Do not create 
task_plan.md
, 
findings.md
, 
progress.md
, 
.planning/**
, 
docs/goals/**
, 
.tmp/goals/**
, or hook state for goal work. Hooks are overkill. The active goal plus the 
docs/plans
file are the durable state.
Create the goal plan with the source-owned helper whenever available:
bash
node .agents/skills/autogoal/scripts/create-goal-scratchpad.mjs \
  --title "<short title>" \
  --template "<primary template name or path>" \
  --with "<optional pack name>"
The helper writes 
docs/plans/YYYY-MM-DD-<slug>.md
or 
docs/plans/<ticket>-<slug>.md
from a project-owned template or built-in autogoal template. The helper lives under 
.agents/skills/autogoal/
because it is generic rule tooling; generated 
SKILL.md
files are not edited by hand.
Do not pass objective, threshold, verification, constraints, boundaries, or blocked condition through CLI flags. The CLI only creates the static plan shell. After creation, edit the generated 
docs/plans
file and write the active goal objective, completion threshold, verification surface, constraints, boundaries, blocked condition, and remaining goal-specific rows into the file.
Editing the generated file means filling and resolving that materialized shell, not replacing it with a hand-made mini-plan. Keep generated sections and rows unless the row is truly irrelevant, then mark it complete with 
N/A: <reason>
. If a template choice is wrong before work starts, regenerate with the correct template and record the replacement. If any durable work has already started, do not swap the plan out from under the work; close the generated plan with honest evidence, N/A rows, or a blocker.
The default project template is generic:
txt
docs/plans/templates/goal.md
Project or skill-specific templates live beside it:
txt
docs/plans/templates/<template>.md
Reusable packs live under:
txt
docs/plans/templates/packs/<pack>.md
Use templates by passing the primary template name. Add packs for touched surfaces:
bash
node .agents/skills/autogoal/scripts/create-goal-scratchpad.mjs \
  --template "<template-name>" \
  --with "<pack-name>" \
  --title "<short title>" \
  ...
Repeat 
--with
for multiple packs, or pass a comma-separated list. The helper records 
Primary template:
and 
Applied packs:
in the generated plan and copies pack rows into the plan's existing gate/checklist sections.
docs/plans/templates
holds reusable project templates. Generic templates are seeded there by 
init-templates.mjs
; non-generic templates stay there as project-owned workflow policy. Direct files under 
docs/plans
are instantiated runtime goal plans. Do not store goal templates or active goal state under 
docs/goals
.
Create a new project-owned template by copying the generic template:
bash
node .agents/skills/autogoal/scripts/create-goal-template.mjs \
  --skill "<skill-name>"
Then edit the new 
docs/plans/templates/<skill-name>.md
to add that skill or project lane's mandatory sections, checklist rows, phase schedule, evidence rows, and closure gates. Keep the generic goal template project-agnostic.
Template creation is not skill creation. Do not generate skill folders, aliases, execution handoffs, hook state, or compatibility bridges from this workflow. A project template is just a reusable static shell for a future 
docs/plans/*
goal plan. The agent fills the real objective, threshold, verification surface, constraints, boundaries, and blocked condition inside the instantiated plan.
Before creating or updating a project template, define these inputs:
  • template name and owning skill or project lane
  • primary-template role and which packs should usually compose with it
  • display name and purpose
  • recurring failure mode the template prevents
  • use cases and non-use cases
  • allowed edit boundaries for plans created from it
  • required read-first sources and optional read-when-relevant sources
  • evidence sources and final verification surface
  • measurable score, count, pass/fail command, or artifact checklist threshold
  • required plan sections
  • required checklist rows, including skill analysis and final goal-plan check
  • phase or pass table, or an explicit reason the template needs no phases
  • completion gates and score caps when score is used
  • review or pressure lenses that must run before closeout
  • handoff, final response, and risk rows
  • blocked condition and what input would unblock it
If an input cannot be inferred from current project context, add a placeholder inside the template and label it as a generation gap. Ask the user only when the missing answer changes the template's purpose, safety model, or boundaries.
Template quality bar:
  • The template must be self-contained enough to create a useful goal plan from scratch. Do not require a sibling template to understand it.
  • Sibling templates may be used for sync review, not as hidden dependencies.
  • Packs may provide recurring touched-surface rows, but only after the helper materializes them into the generated plan. Do not rely on hidden pack state.
  • Domain facts must be placeholders or instructions unless live source proves them. Do not invent current-state, before/after, API, product, or workflow facts.
  • No template may let a goal finish from polished prose, score alone, or a completed phase table without fresh evidence.
  • Every primary template must include an 
    Autoreview
    completion gate before the final 
    Goal plan complete
    check.
  • Every required checklist item must map to evidence, an explicit N/A reason, or a blocker.
  • Every required section is either present in the template or omitted with a recorded reason.
  • Project templates that cover implementation work should include compact gates for review target selection, workspace-authority verification, specialized agent/tooling review when those surfaces change, and a high-risk note for public API, runtime, package-boundary, browser, agent-action, or command contract changes. Do not copy a major planning lane's scorecard, issue ledger, or full pass schedule into generic execution templates.
  • The template should prefer concrete commands, file paths, issue rows, browser routes, screenshots, benchmark names, or source-audit rows over vague "review" wording.
  • The generated plan remains the runtime truth. Do not put active goal state in 
    docs/plans/templates
    .
Template sync review:
  • Instantiate the template once with 
    create-goal-scratchpad.mjs
    or inspect the copied file directly when a smoke plan would create noise.
  • Verify the expected headings, checklist rows, phase/pass rows, completion gates, and blocker rows are present.
  • Verify a blank or unfinished instantiated plan fails 
    check-complete.mjs
    .
  • Verify a completed plan can record the named evidence without editing the template itself.
  • After editing dotai 
    skills/autogoal/SKILL.md
    , run 
    scripts/validate-skills
    .
Create the plan before substantive edits. Update it after every meaningful decision, finding, tradeoff, failed attempt, review fix, verification run, or scope change. Re-read it before major decisions and after compaction or interruption.
Check the goal plan before completion:
bash
node .agents/skills/autogoal/scripts/check-complete.mjs docs/plans/<goal-plan>.md
This is the final mechanical gate, not a substitute for the named verification surface.
The goal-plan checklist is mandatory. Its first required item is skill analysis. Do not call 
update_goal(status: complete)
while any required checklist item remains unchecked. If an item does not apply, check it and add 
N/A: <reason>
.
Required goal-plan sections:
md
undefined
每个活跃目标对应一个持久化目标计划。它是一个Markdown文件，包含有用的计划相关内容：阶段、发现、进度、决策、失败尝试、验证和重启状态。
路径：
txt
docs/plans/YYYY-MM-DD-<short-goal-slug>.md
docs/plans/<ticket>-<short-goal-slug>.md
基于问题的工作使用工单前缀格式。不要创建
task_plan.md
、
findings.md
、
progress.md
、
.planning/**
、
docs/goals/**
、
.tmp/goals/**
或目标工作的钩子状态。钩子过于冗余。活跃目标加
docs/plans
文件即为持久化状态。
当可用时，使用源自有工具创建目标计划：
bash
node .agents/skills/autogoal/scripts/create-goal-scratchpad.mjs \
  --title "<简短标题>" \
  --template "<主模板名称或路径>" \
  --with "<可选包名称>"
工具从项目自有模板或内置autogoal模板生成
docs/plans/YYYY-MM-DD-<slug>.md
或
docs/plans/<ticket>-<slug>.md
。工具位于
.agents/skills/autogoal/
下，因为它是通用规则工具；生成的
SKILL.md
文件不手动编辑。
不要通过CLI标志传递目标、阈值、验证、约束、边界或障碍条件。CLI仅创建静态计划框架。生成后，编辑
docs/plans
文件，写入活跃目标的目标、完成阈值、验证依据、约束、边界、障碍条件和其他目标特定行。
编辑生成文件意味着填充和解析该实例化框架，而非替换为手动制作的小型计划。保留生成的章节和行，除非该行确实无关，然后标记为完成并添加
N/A: <原因>
。如果在工作开始前发现模板选择错误，重新生成正确模板并记录替换情况。如果已开展持久化工作，不要更换计划；如实关闭生成的计划，附上证据、N/A行或障碍标记。
默认项目模板是通用的：
txt
docs/plans/templates/goal.md
项目或技能特定模板与其放在一起：
txt
docs/plans/templates/<template>.md
可复用包位于：
txt
docs/plans/templates/packs/<pack>.md
通过传递主模板名称使用模板。为涉及的业务面添加包：
bash
node .agents/skills/autogoal/scripts/create-goal-scratchpad.mjs \
  --template "<template-name>" \
  --with "<pack-name>" \
  --title "<简短标题>" \
  ...
重复
--with
添加多个包，或传递逗号分隔的列表。工具会在生成的计划中记录
Primary template:
和
Applied packs:
，并将包中的行复制到计划的现有关卡/清单章节。
docs/plans/templates
存放可复用项目模板。通用模板由
init-templates.mjs
初始化；非通用模板作为项目自有工作流政策保留在此。
docs/plans
下的直接文件是实例化的运行时目标计划。不要将目标模板或活跃目标状态存放在
docs/goals
下。
通过复制通用模板创建新的项目自有模板：
bash
node .agents/skills/autogoal/scripts/create-goal-template.mjs \
  --skill "<skill-name>"
然后编辑新的
docs/plans/templates/<skill-name>.md
，添加该技能或项目流程的必填章节、清单行、阶段时间表、证据行和关闭关卡。保持通用目标模板与项目无关。
模板创建不是技能创建。不要从此工作流生成技能文件夹、别名、执行交付、钩子状态或兼容桥接。项目模板只是未来
docs/plans/*
目标计划的可复用静态框架。Agent会在实例化计划中填充真实的目标、阈值、验证依据、约束、边界和障碍条件。
在创建或更新项目模板前，定义以下输入：
  • 模板名称和所属技能或项目流程
  • 主模板角色和通常与之组合的包
  • 显示名称和用途
  • 模板预防的重复故障模式
  • 使用场景和非使用场景
  • 从该模板创建的计划允许的编辑边界
  • 必填优先读取源和可选相关读取源
  • 证据源和最终验证依据
  • 可衡量的分数、数量、通过/失败命令或工件清单阈值
  • 必填计划章节
  • 必填清单行，包括技能分析和最终目标计划检查
  • 阶段或通过表，或模板无需阶段的明确原因
  • 完成关卡和使用分数时的分数上限
  • 关闭前必须运行的评审或压力校验视角
  • 交付、最终响应和风险行
  • 障碍条件和解除障碍所需的输入
如果无法从当前项目上下文推断输入，在模板中添加占位符并标记为生成缺口。仅当缺失答案会改变模板的用途、安全模型或边界时，才询问用户。
模板质量标准：
  • 模板必须足够独立，可从零开始创建有用的目标计划。无需依赖兄弟模板即可理解。
  • 兄弟模板可用于同步评审，但不能作为隐藏依赖。
  • 包可提供重复业务面行，但仅在工具将其实例化到生成计划后。不要依赖隐藏包状态。
  • 领域事实必须是占位符或指令，除非有实时源证明。不要编造当前状态、前后对比、API、产品或工作流事实。
  • 任何模板都不能仅通过优美的文本、分数或完成的阶段表就让目标完成，必须有最新证据。
  • 每个主模板必须在最终
    Goal plan complete
    检查前包含
    Autoreview
    完成关卡。
  • 每个必填清单项必须对应证据、明确的N/A原因或障碍。
  • 每个必填章节要么存在于模板中，要么记录原因后省略。
  • 覆盖实现工作的项目模板应包含紧凑关卡，用于评审目标选择、工作区权限验证、业务面变更时的专用Agent/工具评审，以及公共API、运行时、包边界、浏览器、Agent操作或命令契约变更的高风险提示。不要将大型规划流程的评分卡、问题台账或完整通过时间表复制到通用执行模板中。
  • 模板应优先使用具体命令、文件路径、问题条目、浏览器路由、截图、基准测试名称或源码审计行，而非模糊的“评审”措辞。
  • 生成的计划是运行时唯一依据。不要将活跃目标状态存放在
    docs/plans/templates
    中。
模板同步评审：
  • 使用
    create-goal-scratchpad.mjs
    实例化模板一次，或直接检查复制的文件（当烟雾计划会产生噪音时）。
  • 验证预期的标题、清单行、阶段/通过行、完成关卡和障碍行是否存在。
  • 验证空白或未完成的实例化计划会使
    check-complete.mjs
    失败。
  • 验证已完成的计划无需编辑模板即可记录指定证据。
  • 修改dotai
    skills/autogoal/SKILL.md
    后，运行
    scripts/validate-skills
    。
在实质性编辑前创建计划。在每个有意义的决策、发现、权衡、失败尝试、评审修复、验证运行或范围变更后更新计划。在重大决策前、压缩或中断后重新读取计划。
完成前检查目标计划：
bash
node .agents/skills/autogoal/scripts/check-complete.mjs docs/plans/<goal-plan>.md
这是最终机械关卡，不能替代指定的验证依据。
目标计划清单是必填项，其第一个必填项是技能分析。当任何必填清单项未检查时，不要调用
update_goal(status: complete)
。如果某项不适用，检查它并添加
N/A: <原因>
。
必填目标计划章节：
md
undefined

<Goal title>

<目标标题>

Objective: <short create_goal objective, under 240 characters>
Flow mode: <one-shot execution | agent-led plan hardening | collaborative planning>
Goal plan: <docs/plans/path>
Primary template: <docs/plans/templates/name.md>
Applied packs:
  • <pack or none>
Completion threshold:
  • <quantitative or auditable done row>
Verification surface:
  • <tests/artifacts/browser proof/source audit>
Constraints:
  • <must preserve / must not touch>
Boundaries:
  • <allowed files/packages/tools>
Output budget strategy:
  • <how command/search output will be scoped, capped, counted, or artifacted>
Blocked condition:
  • <condition that stops autonomous work>
Start Gates: | Gate | Applies | Evidence |
Work Checklist:
  • Actual work item or pass-specific requirement with evidence.
  • ...
Completion Gates: | Gate | Applies | Required action | Evidence |
Phase / pass table: | Phase | Status | Evidence | Next |
Findings:
  • <research, source reads, browser/visual findings as data>
Timeline:
  • <timestamp> <action/evidence>
Decisions and tradeoffs:
  • <decision> -> <reason> -> <risk>
Review fixes:
  • <finding> -> <accepted/rejected> -> <change or reason>
Error attempts: | Error / failed attempt | Count | Next different move | Resolution |
Verification evidence:
  • <command/artifact> -> <result>
Reboot status: | Where am I? | Where am I going? | What is the goal? | What learned? | What done? |
Open risks:
  • <risk or none> 

Before `update_goal(status: complete)`, the goal plan must include the final
verification evidence, checked checklist, current reboot status, and any
remaining risks.
Objective: <简短的create_goal目标，≤240字符>
Flow mode: <one-shot execution | agent-led plan hardening | collaborative planning>
Goal plan: <docs/plans/path>
Primary template: <docs/plans/templates/name.md>
Applied packs:
  • <包名称或无>
Completion threshold:
  • <量化或可审计的完成条目>
Verification surface:
  • <测试/工件/浏览器验证/源码审计>
Constraints:
  • <必须保留/不得触及>
Boundaries:
  • <允许的文件/包/工具>
Output budget strategy:
  • <命令/搜索输出的范围限制、上限、计数或工件化方式>
Blocked condition:
  • <停止自主工作的条件>
Start Gates: | Gate | Applies | Evidence |
Work Checklist:
  • 实际工作项或特定通过要求，附证据。
  • ...
Completion Gates: | Gate | Applies | Required action | Evidence |
Phase / pass table: | Phase | Status | Evidence | Next |
Findings:
  • <研究、源码读取、浏览器/视觉发现等数据>
Timeline:
  • <时间戳> <操作/证据>
Decisions and tradeoffs:
  • <决策> -> <原因> -> <风险>
Review fixes:
  • <发现> -> <接受/拒绝> -> <变更或原因>
Error attempts: | Error / failed attempt | Count | Next different move | Resolution |
Verification evidence:
  • <命令/工件> -> <结果>
Reboot status: | Where am I? | Where am I going? | What is the goal? | What learned? | What done? |
Open risks:
  • <风险或无>

在调用`update_goal(status: complete)`前，目标计划必须包含最终验证证据、已检查的清单、当前重启状态和任何剩余风险。

Good Goal Handles

优质目标标识示例

Performance:
txt
Reduce checkout p95; done when p95 < 120 ms and checks pass; plan docs/plans/YYYY-MM-DD-checkout-latency.md.
Bug hunt:
txt
Fix flaky checkout test; done when repro passes 5 consecutive runs; plan docs/plans/YYYY-MM-DD-checkout-flake.md.
Research:
txt
Reproduce target paper evidence; done when every headline claim has a status row; plan docs/plans/YYYY-MM-DD-paper-repro.md.
Pass-gated planning:
txt
Close layout plan; done when score >= 0.92 and closure gates pass; plan docs/plans/YYYY-MM-DD-layout-plan.md.
性能优化：
txt
Reduce checkout p95; done when p95 < 120 ms and checks pass; plan docs/plans/YYYY-MM-DD-checkout-latency.md.
Bug修复：
txt
Fix flaky checkout test; done when repro passes 5 consecutive runs; plan docs/plans/YYYY-MM-DD-checkout-flake.md.
研究：
txt
Reproduce target paper evidence; done when every headline claim has a status row; plan docs/plans/YYYY-MM-DD-paper-repro.md.
关卡型规划：
txt
Close layout plan; done when score >= 0.92 and closure gates pass; plan docs/plans/YYYY-MM-DD-layout-plan.md.

Weak Goal Examples

劣质目标示例

txt
Improve performance
Make this better
Refactor the editor
Run all passes
Finish the project
These are weak because they lack a measurable outcome, verification surface, or scope boundary.
txt
Improve performance
Make this better
Refactor the editor
Run all passes
Finish the project
这些目标劣质的原因是缺少可衡量的成果、验证依据或范围边界。

Pass-Gated Goals

关卡型目标

For pass-gated lanes, prefer one lane goal when the goal tool can persist across turns. Put the pass schedule in the plan, keep the goal objective short, run one pass per activation, and complete the goal only when closure gates prove no pass remains runnable.
Use this when a workflow has scheduled passes such as current-state read, issue discovery, intent boundary, research refresh, steelman, revision, verification sweep, or closure.
Rules:
  • The goal objective should describe only the lane outcome, short completion threshold, and plan path.
  • The plan should describe the full pass schedule, one-pass-per-activation policy, proof gates, and closure condition.
  • Complete the current pass in the plan or progress ledger, not by closing the goal.
  • Complete the goal only when every required pass is complete or intentionally skipped with evidence.
  • Do not use separate per-pass goals; keep scheduled passes as rows in the active plan.
  • Keep pass status in the plan or progress ledger; keep goal status tied to the whole lane.
Progress fields for pass-gated lanes:
md
current_pass: current-state-read
current_pass_status: in_progress
next_pass: related-issue-discovery
goal_status: active
Allowed 
goal_status
values:
  • active
  • complete
  • blocked
对于关卡型流程，当目标工具可跨轮次持久化时，优先使用单个流程目标。将通过时间表放入计划，保持目标标识简短，每次激活运行一个通过步骤，仅当关闭关卡证明无剩余可运行通过步骤时才完成目标。
适用于包含预定通过步骤的工作流，如当前状态读取、问题发现、意图边界、研究更新、强化验证、修订、验证扫描或关闭。
规则：
  • 目标标识仅描述流程成果、简短完成阈值和计划路径。
  • 计划描述完整通过时间表、每次激活一个通过步骤的策略、验证关卡和关闭条件。
  • 在计划或进度台账中完成当前通过步骤，而非关闭目标。
  • 仅当所有必填通过步骤完成或有证据支持故意跳过时，才完成目标。
  • 不要使用单独的每个通过步骤目标；将预定通过步骤作为活跃计划中的行。
  • 将通过步骤状态存放在计划或进度台账中；目标状态与整个流程绑定。
关卡型流程的进度字段：
md
current_pass: current-state-read
current_pass_status: in_progress
next_pass: related-issue-discovery
goal_status: active
允许的
goal_status
值：
  • active
  • complete
  • blocked

Completion Rules

完成规则

Mark a goal complete only when:
  • the outcome in the goal is actually achieved
  • the completion threshold is met exactly
  • the verification surface named by the goal was checked
  • the 
    docs/plans
    goal plan is updated with final verification
  • every required goal-plan checklist item is checked or marked N/A with reason
  • node .agents/skills/autogoal/scripts/check-complete.mjs <docs/plans/path>
    passes after the final evidence is recorded
  • constraints and boundaries were respected, or deviations were explicitly accepted
  • required artifacts were created or updated
  • no required owner remains runnable
  • the final response reports the evidence, not just confidence
Do not mark complete because:
  • tests passed but the goal also required review, browser proof, docs, or a report
  • the budget is nearly exhausted
  • the current slice is done but later slices remain
  • a plan was written but execution or proof remains
  • the user says "nice" without accepting open risks
When calling 
update_goal(status: complete)
, include the tool's final token/time usage in the user-facing closeout when the tool returns it.
仅当满足以下所有条件时，才标记目标完成：
  • 目标中的成果实际达成
  • 完成阈值完全满足
  • 检查了目标指定的验证依据
  • docs/plans
    目标计划已更新最终验证内容
  • 所有必填目标计划清单项已检查或标记为N/A并附原因
  • 记录最终证据后，
    node .agents/skills/autogoal/scripts/check-complete.mjs <docs/plans/path>
    通过
  • 约束和边界得到遵守，或偏差已被明确接受
  • 必填工件已创建或更新
  • 无剩余必填归属方可运行
  • 最终响应报告证据，而非仅报告置信度
不要因以下情况标记完成：
  • 测试通过，但目标还要求评审、浏览器验证、文档或报告
  • 预算即将耗尽
  • 当前部分完成，但后续部分仍未完成
  • 已编写计划，但执行或验证仍未完成
  • 用户说“不错”但未接受未解决风险
调用
update_goal(status: complete)
时，如果工具返回最终令牌/时间使用情况，在面向用户的关闭报告中包含该信息。

Blocked Rules

障碍规则

Blocked is terminal for the goal, not a normal checkpoint.
Use blocked only when:
  • no autonomous next move remains
  • missing evidence, access, tooling, data, or a user decision prevents progress
  • repeated attempts show the same blocker, and the tool's blocked threshold is satisfied
Do not mark blocked when:
  • more investigation is possible
  • a different test, smaller repro, or narrower source read is available
  • the work is merely hard, slow, or broad
  • a review pass found issues that can be fixed
  • a gate failed and the failing owner is obvious
Blocked report shape:
md
Goal blocked.
Attempted:

- ...
  Evidence:
- ...
  Blocker:
- ...
  Needed to continue:
- ...
障碍状态是目标的终结状态，而非常规检查点。
仅当满足以下条件时使用障碍状态：
  • 无自主下一步行动
  • 缺失证据、权限、工具、数据或用户决策阻碍了进展
  • 重复尝试出现相同障碍，且满足工具的障碍阈值
不要因以下情况标记障碍：
  • 仍可进行更多调查
  • 可使用不同测试、更小的复现或更窄的源码读取
  • 工作只是困难、缓慢或范围广
  • 评审通过步骤发现了可修复的问题
  • 关卡失败且失败归属方明确
障碍报告格式：
md
Goal blocked.
Attempted:

- ...
  Evidence:
- ...
  Blocker:
- ...
  Needed to continue:
- ...

Budget Handling

预算处理

Budget exhaustion is not success.
预算耗尽不等于成功。

Output Budget Discipline

输出预算规范

Goal token budgets are real work budgets, not decorative counters. A goal run that burns its budget on tool output has failed the workflow even when no app code was touched.
Oversized goal objectives are budget failures too. If the tool objective starts to read like a plan, stop and move that detail into 
docs/plans
.
Before running exploratory commands inside an active goal:
  • Prefer narrow reads over broad scans: exact files, focused 
    rg -n
    patterns, targeted globs, and short 
    sed -n
    ranges.
  • Treat 
    tmp/**
    , logs, binaries, generated output, build artifacts, 
    node_modules
    , 
    .next
    , 
    .turbo
    , and coverage folders as excluded by default. Include them only when they are the named source of truth.
  • Set explicit tool output caps for commands likely to return more than a screenful. Keep ordinary source reads around a few thousand tokens, and justify any larger cap in the plan.
  • For broad audits, first ask for counts, filenames, or top matches (
    rg --count
    , 
    rg --files-with-matches
    , 
    --max-count
    , 
    wc
    , 
    head
    ) before printing matching lines.
  • If a result may be large but still matters, write it to a local artifact and inspect slices from that artifact. Do not stream the full result into the conversation.
  • Never run unbounded 
    rg
    across the whole repo plus large generated trees, logs, or binary outputs during a budgeted goal. Split the search by owner or exclude the noisy trees first.
  • After any accidental large output, stop broad exploration immediately, record the miss in the error-attempts row, and continue only with constrained commands.
If the system stops or warns because a goal budget is reached:
  • stop substantive work
  • summarize current evidence and remaining owners
  • name the next useful action
  • do not call the goal complete unless the original objective is already proven
目标令牌预算是真实的工作预算，而非装饰性计数器。即使未修改应用代码，消耗预算在工具输出上的目标运行也属于工作流失败。
过大的目标标识也是预算失败。如果工具标识开始像计划，停止并将细节移至
docs/plans
。
在活跃目标中运行探索性命令前：
  • 优先窄范围读取而非宽范围扫描：精确文件、聚焦的
    rg -n
    模式、目标通配符和短
    sed -n
    范围。
  • 默认排除
    tmp/**
    、日志、二进制文件、生成输出、构建工件、
    node_modules
    、
    .next
    、
    .turbo
    和覆盖率文件夹。仅当它们是指定的真实源时才包含。
  • 为可能返回超过一屏内容的命令设置明确的工具输出上限。普通源码读取保持在几千令牌左右，任何更大的上限都需在计划中说明理由。
  • 对于宽范围审计，先请求计数、文件名或顶部匹配结果（
    rg --count
    、
    rg --files-with-matches
    、
    --max-count
    、
    wc
    、
    head
    ），再打印匹配行。
  • 如果结果可能很大但仍重要，写入本地工件并检查该工件的切片。不要将完整结果流式传输到对话中。
  • 在预算目标中，永远不要在整个仓库加大规模生成树、日志或二进制输出上运行无限制的
    rg
    。按归属方拆分搜索或先排除噪音树。
  • 意外产生大输出后，立即停止宽范围探索，在错误尝试行中记录未达标情况，仅使用受限命令继续。
如果系统因目标预算耗尽而停止或警告：
  • 停止实质性工作
  • 总结当前证据和剩余归属方
  • 指定下一个有用的操作
  • 除非原始目标已证明达成，否则不要标记目标完成

Lifecycle Boundaries

生命周期边界

Do not use 
update_goal
for lifecycle transitions outside its contract.
The model may complete or block a goal only through 
update_goal
when the tool contract is satisfied. Other lifecycle transitions are user/system-owned. If the user asks for a lifecycle transition and no direct tool is available, state that the current runtime does not expose that control instead of faking it with completion or blocked status.
不要将
update_goal
用于其契约外的生命周期转换。
仅当满足工具契约时，模型才可通过
update_goal
完成或标记目标为障碍状态。其他生命周期转换由用户/系统负责。如果用户要求生命周期转换但无直接工具可用，说明当前运行时未暴露该控制，而非通过完成或障碍状态伪造。

Status Updates During Goals

目标执行中的状态更新

Keep status short and evidence-based:
  • current checkpoint
  • what changed
  • what was verified
  • what remains
  • whether blocked
  • next concrete action
Avoid vague updates like "making progress" or "continuing investigation". If status gets vague, tighten the goal or checkpoint.
保持状态简短且基于证据：
  • 当前检查点
  • 变更内容
  • 已验证内容
  • 剩余工作
  • 是否处于障碍状态
  • 下一个具体操作
避免模糊更新，如“正在推进”或“继续调查”。如果状态变得模糊，收紧目标或检查点。

Research Goals

研究目标

Research goals need stricter epistemic accounting.
Final reports should separate:
  • confirmed findings
  • approximate reconstructions
  • proxy/support-only evidence
  • blocked exact claims
  • remaining uncertainty
Do not flatten "approximate support" into "reproduced" or "fixed". A good research goal lets Codex keep working through uncertainty while preventing overclaiming.
研究目标需要更严格的认知记录。
最终报告应区分：
  • 已确认的发现
  • 近似重构结果
  • 仅支持性证据
  • 无法验证的明确声明
  • 剩余不确定性
不要将“近似支持”简化为“已复现”或“已修复”。优质研究目标允许Codex在不确定性中持续工作，同时防止过度声明。

Closeout Template

关闭模板

Use this shape when closing a goal:
md
Goal complete.
Evidence:

- <command/artifact/source>
  What changed:
- <short list>
  Constraints preserved:
- <short list>
  Residual risk:
- <only if real>
  Usage:
- <tool-reported tokens/time, when available>
For blocked:
md
Goal blocked.
Evidence:

- <what was tried>
  Blocker:
- <why no autonomous progress remains>
  Needed next:
- <specific user/tool/input>
关闭目标时使用以下格式：
md
Goal complete.
Evidence:

- <命令/工件/源>
  What changed:
- <简短列表>
  Constraints preserved:
- <简短列表>
  Residual risk:
- <仅当存在真实风险>
  Usage:
- <工具报告的令牌/时间，当可用时>
障碍状态关闭格式：
md
Goal blocked.
Evidence:

- <尝试内容>
  Blocker:
- <无自主进展的原因>
  Needed next:
- <具体用户/工具/输入>