goal-prep

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Goal Prep

Goal Prep

$goal-prep
(Codex) or
/goal-prep
(Claude Code) prepares a GoalBuddy board. It does not start execution automatically, but the board and harness-specific starter command must be shaped so the next run continues into safe execution by default.
GoalBuddy is for autonomous, long-running Codex or Claude Code work where the PM thread may need to discover the work, define tasks, sequence them, delegate them, execute them, verify them, and keep going without the human decomposing every step.
The loop is:
text
raw user intent -> intake compiler -> goal oracle -> local work surface -> one active task -> receipt -> proof loop -> repeat
GoalBuddy's core invariant is:
text
Intent -> Oracle -> Surface -> Loop -> Proof
No oracle, no serious goal. A goal oracle is the observable signal that tells the PM whether the original owner outcome is actually true yet. It may be a test suite, browser walkthrough, demo transcript, generated artifact, benchmark, source-backed answer, release check, or final human decision. Weak proof creates weak goals, so record the oracle before shaping tasks and keep testing against it until final completion.
$goal-prep
(Codex)或
/goal-prep
(Claude Code)用于准备 GoalBuddy 看板。它不会自动启动执行,但看板和特定运行环境的启动命令必须经过恰当配置,使下一次运行默认能够安全地进入执行阶段。
GoalBuddy 适用于自主式、长时间运行的 Codex 或 Claude Code 工作;PM 线程可能需要发现工作、定义任务、安排顺序、委派任务、执行任务、验证任务,并在无需人工拆解每个步骤的情况下持续推进。
循环如下:
text
raw user intent -> intake compiler -> goal oracle -> local work surface -> one active task -> receipt -> proof loop -> repeat
GoalBuddy 的核心不变量是:
text
Intent -> Oracle -> Surface -> Loop -> Proof
没有 goal oracle,就没有严肃的目标。goal oracle 是一种可观察信号,用于告诉 PM 原始负责人期望的结果是否已经真正实现。它可以是测试套件、浏览器演示流程、演示转录、生成的产物、基准测试、有来源支撑的答案、发布检查,或最终的人工决策。薄弱的 proof 会产生薄弱的目标,因此应先记录 goal oracle,再设计任务,并持续围绕它进行测试,直至最终完成。

Invocation Boundary

调用边界

There are two different modes:
  • $goal-prep
    or
    /goal-prep
    : prepare intake,
    goal.md
    ,
    state.yaml
    , and the starter execution commands, then stop.
  • Codex
    /goal Follow docs/goals/<slug>/goal.md.
    or Claude Code
    /goalbuddy Follow docs/goals/<slug>/goal.md.
    : execute the board, including Scout/Judge/Worker work.
This boundary is strict.
$goal-prep
is not a lightweight
/goal
; it is a board compiler.
This document is the prep-mode contract plus the shared board model. The execution contract lives in
references/goal-execution.md
next to this file; read it at the start of every Codex
/goal
or Claude Code
/goalbuddy
run. If it cannot be read, these execution invariants still hold:
state.yaml
is board truth; exactly one active task unless disjoint write scopes are proven; Scout and Judge tasks are read-only; Worker tasks write only inside
allowed_files
and run their
verify
commands; every completed, blocked, or escalated task gets a receipt; the goal completes only through a final Judge or PM audit that maps receipts and verification back to the original outcome (recording
full_outcome_complete: true
for continuous execution goals).
During a
$goal-prep
turn, do not perform the user's requested work, even if the work looks read-only, preparatory, or obviously useful. Do not refresh or load named skills, inspect implementation files, browse reference repos, research design inspiration, generate design plans, generate images/assets, run app-specific checks, or edit product files. Put those actions into Scout, Judge, Worker, or PM tasks for the later
/goal
run.
Allowed
$goal-prep
actions:
  • run the bundled GoalBuddy update checker and mention a newer version if one is available;
  • ask diagnostic intake questions and wait when required;
  • create or repair only
    docs/goals/<slug>/goal.md
    ,
    docs/goals/<slug>/state.yaml
    ,
    docs/goals/<slug>/notes/
    , and the generated
    .goalbuddy-board/
    visual board artifact;
  • create and open the built-in local GoalBuddy board surface for the goal unless the user opts out;
  • optionally run the GoalBuddy board checker against that
    state.yaml
    ;
  • verify GoalBuddy agent availability, if this can be done without touching implementation work, and record
    installed
    ,
    bundled_not_installed
    ,
    missing
    , or
    unknown
    truthfully;
  • print both exact execution commands: Codex
    /goal Follow docs/goals/<slug>/goal.md.
    and Claude Code
    /goalbuddy Follow docs/goals/<slug>/goal.md.
    ;
  • ask whether to start execution, refine the board, or stop.
If the prompt names another skill or tool, such as "use the taste skill", "refresh the taste skill", "look at this repo", "use browser", or "generate assets", record that requirement in the charter and seed tasks. Do not load that skill, browse that repo, or generate those assets during
$goal-prep
.
存在两种不同的模式:
  • $goal-prep
    或
    /goal-prep
    :准备 intake、
    goal.md
    、
    state.yaml
    和启动执行命令,然后停止。
  • Codex
    /goal Follow docs/goals/<slug>/goal.md.
    或 Claude Code
    /goalbuddy Follow docs/goals/<slug>/goal.md.
    :执行看板,包括 Scout/Judge/Worker 工作。
此边界严格不可逾越。
$goal-prep
不是轻量版的
/goal
,而是看板编译器。
本文档是准备模式契约及共享看板模型。执行契约位于本文件旁的
references/goal-execution.md
;每次运行 Codex
/goal
或 Claude Code
/goalbuddy
时,都必须先阅读该文件。如果无法读取,以下执行不变量仍然有效:
state.yaml
是看板事实来源;除非能够证明写入范围互不重叠,否则只能有一个活跃任务;Scout 和 Judge 任务必须只读;Worker 只能写入
allowed_files
范围内并运行其
verify
命令;每个已完成、受阻或已升级的任务都必须产生 receipt;只有最终 Judge 或 PM 审计将 receipts 和验证结果映射回原始结果时,目标才算完成;对于持续执行目标,需记录
full_outcome_complete: true
。
在
$goal-prep
回合中,不要执行用户请求的工作,即使这些工作看起来是只读的、预备性的或明显有用。不要刷新或加载指定的 skill,不要检查实现文件、浏览参考仓库、研究设计灵感、生成设计方案、生成图像/素材、运行应用专用检查,也不要编辑产品文件。将这些操作放入后续
/goal
运行中的 Scout、Judge、Worker 或 PM 任务。
允许的
$goal-prep
操作:
  • 运行内置的 GoalBuddy 更新检查器;如果有新版本,则予以说明;
  • 询问诊断性 intake 问题,并在必要时等待用户回答;
  • 仅创建或修复
    docs/goals/<slug>/goal.md
    、
    docs/goals/<slug>/state.yaml
    、
    docs/goals/<slug>/notes/
    和生成的
    .goalbuddy-board/
    可视化看板产物;
  • 为目标创建并打开内置的本地 GoalBuddy 看板界面,除非用户选择退出;
  • 可以选择对该
    state.yaml
    运行 GoalBuddy 看板检查器;
  • 在不触及实施工作的情况下验证 GoalBuddy Agent 可用性,并如实记录
    installed
    、
    bundled_not_installed
    、
    missing
    或
    unknown
    ;
  • 打印两条准确的执行命令:Codex
    /goal Follow docs/goals/<slug>/goal.md.
    和 Claude Code
    /goalbuddy Follow docs/goals/<slug>/goal.md.
    ;
  • 询问用户是立即开始、细化看板,还是停止。
如果提示中提到其他 skill 或工具,例如“use the taste skill”“refresh the taste skill”“look at this repo”“use browser”或“generate assets”,应在 charter 中记录该要求并预置任务。在
$goal-prep
期间,不要加载该 skill、浏览该仓库或生成相关素材。

Update Check

更新检查

At the start of a
$goal-prep
turn, check whether GoalBuddy itself is stale. Run the bundled checker from the installed skill directory when available:
bash
node <skill-path>/scripts/check-update.mjs --json
If the checker reports
update_available: true
, tell the user once before continuing:
text
GoalBuddy <latest_version> is available. After this turn, update through the channel that installed GoalBuddy: `/plugin update goalbuddy@goalbuddy`, `npx goalbuddy@latest`, `npm i -g goalbuddy`, `pnpm update -g goalbuddy`, `bun update -g goalbuddy`, or `mise upgrade npm:goalbuddy`.
Do not block intake or board creation on update checking. If the checker is missing, cannot find npm, or network access fails, continue silently unless the user asked about updates.
在
$goal-prep
回合开始时,检查 GoalBuddy 本身是否已过期。如果可用,请从已安装的 skill 目录运行内置检查器:
bash
node <skill-path>/scripts/check-update.mjs --json
如果检查器报告
update_available: true
,请在继续之前告知用户一次:
text
GoalBuddy <latest_version> is available. After this turn, update through the channel that installed GoalBuddy: `/plugin update goalbuddy@goalbuddy`, `npx goalbuddy@latest`, `npm i -g goalbuddy`, `pnpm update -g goalbuddy`, `bun update -g goalbuddy`, or `mise upgrade npm:goalbuddy`.
不要因更新检查而阻塞 intake 或看板创建。如果检查器缺失、找不到 npm 或网络访问失败,则静默继续,除非用户要求检查更新。

Intake Compiler

Intake 编译器

Before creating, repairing, or running a board, privately translate the user's input into a Goal Intake. The input may be vague, specific, or detailed with an existing plan. Do not dump the intake to the user unless they ask for it.
Extract:
  • original request: the shortest faithful user wording;
  • interpreted outcome: what must become true;
  • input shape:
    vague | specific | existing_plan | recovery | audit
    ;
  • audience or beneficiary;
  • non-goals and hard constraints;
  • authority:
    requested | approved | inferred | needs_approval | blocked
    ;
  • proof type:
    test | demo | artifact | metric | review | source_backed_answer | decision
    ;
  • completion proof: the observable signal for full outcome completion;
  • goal oracle: the live check, walkthrough, artifact, metric, or decision that will keep pressure on the goal and prevent early completion;
  • likely misfire: how
    /goal
    could succeed at the wrong thing;
  • blind spots: important risks, choices, or success dimensions the user may not have named yet;
  • existing plan facts: user-provided steps, files, constraints, or sequencing that must be preserved but still validated.
Use the local GoalBuddy board as the default work surface for broad GoalBuddy runs. Ask only when the user has not already implied they want the default local surface, the goal is unusually quick/private, or board setup would materially distract from the requested prep:
text
Do you want the local GoalBuddy board for this goal?
Recommended options:
  1. Local live board (Recommended) - starts immediately, requires no credentials, and lets the user watch tasks populate inside Codex or Claude Code.
  2. No visual board - best for quick or private goals where the file board is enough.
If the user chooses the local live board, create the goal directory,
notes/
, and an initial minimal
state.yaml
as soon as the slug is known, then run
node <skill-path>/surfaces/local-goal-board/scripts/local-goal-board.mjs --goal docs/goals/<slug>
and open the printed local URL in the AI coding agent's in-app browser (the Codex in-app Browser, the Claude Code preview, or the user's regular browser). The default local hub is
http://goalbuddy.localhost:41737/
, and board URLs normally look like
http://goalbuddy.localhost:41737/<slug>/
. In short: start the local board before filling the task list so the board pops up right away and cards populate live as
state.yaml
changes. Include the printed board URL in the final prep response as an actual clickable Markdown link, for example
[Open GoalBuddy board](http://goalbuddy.localhost:41737/<slug>/)
. Do not put the board URL only in a code block, quote, HTML comment, or prose that the UI cannot click.
If
http://goalbuddy.localhost:41737/<slug>/
returns 404, do not assume the existing process is stale and do not stop it. First check
http://127.0.0.1:41737/api/boards
. If that endpoint returns board JSON, the port is the shared multi-board hub; rerun
node <skill-path>/surfaces/local-goal-board/scripts/local-goal-board.mjs --goal <absolute-goal-path>
if needed so the new goal registers on the same port. Only stop a specific process on 41737 when
/api/boards
is missing, returns 404, or otherwise proves the listener is not a current GoalBuddy multi-board hub.
If the user wants an external board, GitHub sync, Slack digest, Linear handoff, or any other custom integration, do not install a GoalBuddy catalog item. Treat it as normal implementation work: create a concrete task that designs and verifies that integration inside the target repo or asks the operator for the required credentials and scope.
Ask before board creation when the request is vague, strategic, improvement-oriented, or open-ended and the user has not explicitly said to use defaults. Ask one guided question at a time with 2-3 options and a recommended default, then wait. Continue the diagnostic intake until the user's answers are sufficient to choose the board shape. Do not create or repair
docs/goals/<slug>/
until the diagnostic intake is complete or the user explicitly accepts defaults.
For vague or strategic goals, one answer is rarely enough. After each answer, reflect what it implies, name one likely blind spot, and ask the next material question. The goal is to help the user discover what they mean, not merely collect a form value.
Proceed with labeled assumptions and seed a safe board only when at least one is true:
  • the user provides a specific outcome and enough completion proof to choose the first phase;
  • the user provides an existing plan or concrete artifact to validate;
  • the request is clearly recovery or audit with a target path, error, failing command, or stale board;
  • the user says to proceed, use defaults, or prepare the board now.
If a missing answer materially changes outcome, authority, scope, risk, owner, completion proof, or board-handling choice, ask even if the user provided details.
Examples:
  • Vague input: start with Scout, then Judge, bounded Worker, final audit.
  • Specific input with incomplete evidence: start with Scout or Judge before Worker.
  • Existing plan: preserve the plan as facts, start with PM or Judge plan validation, then queue bounded Worker slices from the validated plan.
  • Recovery: start with Scout evidence mapping or Judge triage before writes.
  • Audit: keep the board read-only unless the user approves follow-up execution.
The intake compiler is an internal strut for
/goal
: it exists to make the first board correct, not to create process theater.
在创建、修复或运行看板之前,先私下将用户输入转译为 Goal Intake。输入可能是模糊的、具体的,或带有现有计划的详细信息。除非用户要求查看,否则不要转储 intake。
提取以下信息:
  • 原始请求:最简短且忠实于用户原意的表述;
  • 解释后的结果:必须变成怎样的状态;
  • 输入形态:
    vague | specific | existing_plan | recovery | audit
    ;
  • 受众或受益者;
  • 非目标与硬性约束;
  • 授权状态:
    requested | approved | inferred | needs_approval | blocked
    ;
  • proof 类型:
    test | demo | artifact | metric | review | source_backed_answer | decision
    ;
  • 完成 proof:表明完整结果已实现的可观察信号;
  • goal oracle:持续推动目标并防止过早完成的实时检查、演示流程、产物、指标或决策;
  • 可能的误跑:
    /goal
    可能以正确的方式完成错误目标的方式;
  • 盲点:用户可能尚未提及的重要风险、选择或成功维度;
  • 现有计划事实:用户提供且必须保留,但仍需验证的步骤、文件、约束或执行顺序。
对于广泛的 GoalBuddy 运行,默认使用本地 GoalBuddy 看板作为工作界面。仅当用户尚未表明希望采用默认本地界面、目标异常简短或私密,或者看板设置会明显干扰所请求的准备工作时,才进行询问:
text
Do you want the local GoalBuddy board for this goal?
推荐选项:
  1. 本地实时看板(推荐)——可立即启动,无需凭据,并允许用户在 Codex 或 Claude Code 中观察任务逐步填充。
  2. 无可视化看板——适用于简短或私密的目标,此时文件看板已经足够。
如果用户选择本地实时看板,请在 slug 确定后立即创建目标目录、
notes/
和初始的最小
state.yaml
,然后运行
node <skill-path>/surfaces/local-goal-board/scripts/local-goal-board.mjs --goal docs/goals/<slug>
,并在 AI coding agent 的应用内浏览器中打开打印出的本地 URL(Codex 应用内 Browser、Claude Code 预览或用户的常规浏览器)。默认本地中心地址为
http://goalbuddy.localhost:41737/
,看板 URL 通常形如
http://goalbuddy.localhost:41737/<slug>/
。简而言之,应在填充任务列表之前启动本地看板,让看板立即显示,并随着
state.yaml
的变化实时填充卡片。在最终准备响应中,应将打印出的看板 URL 作为实际可点击的 Markdown 链接包含在内,例如
[Open GoalBuddy board](http://goalbuddy.localhost:41737/<slug>/)
。不要仅将看板 URL 放在代码块、引号、HTML 注释或 UI 无法点击的文本中。
如果
http://goalbuddy.localhost:41737/<slug>/
返回 404,不要假定现有进程已经过期,也不要停止它。首先检查
http://127.0.0.1:41737/api/boards
。如果该端点返回看板 JSON,则该端口是共享的多看板中心;如有必要,使用
node <skill-path>/surfaces/local-goal-board/scripts/local-goal-board.mjs --goal <absolute-goal-path>
重新运行,以便在同一端口注册新目标。只有在
/api/boards
缺失、返回 404,或其他证据证明 41737 上的监听器并非当前的 GoalBuddy 多看板中心时,才可停止 41737 上的特定进程。
如果用户需要外部看板、GitHub 同步、Slack 摘要、Linear 交接或任何其他自定义集成,不要安装 GoalBuddy 目录项。将其视为常规实施工作:在目标仓库中创建一个具体任务,用于设计和验证该集成,或者要求运维人员提供必要的凭据和权限范围。
当请求模糊、战略性、改进导向或开放式,且用户尚未明确表示要使用默认值时,在创建看板之前进行询问。每次只提出一个有引导性的问题,提供 2–3 个选项和一个推荐默认值,然后等待回答。继续进行诊断性 intake,直到用户的回答足以确定看板形态。除非诊断性 intake 已完成,或用户明确接受默认值,否则不要创建或修复
docs/goals/<slug>/
。
对于模糊或战略性的目标,一个回答通常远远不够。每次回答后,应反映其含义,指出一个可能的盲点,并提出下一个实质性问题。目标是帮助用户发现自己的真实意图,而不仅仅是收集表单值。
仅在至少满足以下一项条件时,才能带着明确标注的假设继续并预置安全看板:
  • 用户提供了具体结果以及足够的完成 proof,可以据此选择第一阶段;
  • 用户提供了现有计划或需要验证的具体产物;
  • 请求明确属于恢复或审计,并提供了目标路径、错误、失败命令或过期看板;
  • 用户表示继续、使用默认值或立即准备看板。
如果缺失的回答会实质性地改变结果、授权、范围、风险、负责人、完成 proof 或看板处理方式,即使用户已提供其他细节,也应继续询问。
示例:
  • 模糊输入:以 Scout 开始,然后是 Judge、有边界的 Worker 和最终审计。
  • 具体但证据不足的输入:在 Worker 之前先执行 Scout 或 Judge。
  • 现有计划:将计划作为事实保留,以 PM 或 Judge 验证计划作为首个活跃任务,仅在计划经过证据、风险、允许文件、验证和停止条件检查后,才排入 Worker 工作切片。
  • 恢复:在写入之前先执行 Scout 证据映射或 Judge 分诊。
  • 审计:除非用户批准后续执行,否则保持看板只读。
Intake 编译器是
/goal
的内部支撑结构:它的作用是确保第一版看板正确,而不是制造流程仪式。

Guided Intake Surface

引导式 Intake 界面

For interactive vague or improvement-oriented input, run a diagnostic intake. Show only the current turn of the diagnostic, not the private intake:
markdown
I read this as: [one-sentence interpreted outcome].

One possible blind spot: [a risk, unstated choice, or success dimension the user may not have named].

[One material question?]

1. [Recommended direction] (Recommended) - [when it wins]
2. [Second direction] - [when it wins]
3. [Third direction, only if genuinely useful] - [when it wins]

My default would be [option] because [short reason].
Stop after each question. Do not create files, repair an existing board, run checks, or print
/goal
until the diagnostic intake is complete. Do not dump the private intake.
Minimum diagnostic ladder for vague, strategic, or improvement-oriented goals:
  1. Goal surface: use the local live board by default, or ask "Do you want the local GoalBuddy board for this goal?" when board handling is unresolved.
  2. Intent target: what kind of improvement or outcome matters most?
  3. Success proof: what evidence would convince the user this worked?
  4. Scope and non-goals: what should remain untouched or explicitly out of scope?
  5. Goal handling: reuse an existing goal, create a fresh goal, or inspect first?
Ask these one at a time. Skip a step only when the user's words already answer it clearly. After the user answers one step, do not assume the remaining steps; ask the next unresolved material question.
For "make GoalBuddy better", a good first question is which improvement target matters most: intake clarity, board/execution reliability, completion proof/eval coverage, or user experience during long-running goals. A good second question asks what proof would convince the user it improved. A good third question asks whether to reuse an existing goal, create a fresh goal, or inspect first.
对于交互式、模糊或改进导向的输入,运行诊断性 intake。只展示诊断的当前轮次,不要展示私有 intake:
markdown
I read this as: [one-sentence interpreted outcome].

One possible blind spot: [a risk, unstated choice, or success dimension the user may not have named].

[One material question?]

1. [Recommended direction] (Recommended) - [when it wins]
2. [Second direction] - [when it wins]
3. [Third direction, only if genuinely useful] - [when it wins]

My default would be [option] because [short reason].
每个问题之后都要停止。不要创建文件、修复现有看板、运行检查或打印
/goal
,直至诊断性 intake 完成。不要转储私有 intake。
对于模糊、战略性或改进导向的目标,最低诊断阶梯如下:
  1. 目标界面:默认使用本地实时看板;如果看板处理方式尚未确定,则询问“是否要为此目标使用本地 GoalBuddy 看板?”
  2. 意图目标:哪类改进或结果最重要?
  3. 成功 proof:什么证据能让用户相信它已生效?
  4. 范围与非目标:哪些内容应保持不变或明确排除在范围之外?
  5. 目标处理方式:复用现有目标、创建全新目标,还是先进行检查?
这些问题应逐个提出。只有当用户原话已经清楚回答某一步时,才可跳过该步。用户回答某一步后,不要假定其余步骤也已明确;应继续提出下一个尚未解决的实质性问题。
对于“让 GoalBuddy 变得更好”,一个好的首问是:最需要改进的目标是什么——intake 清晰度、看板/执行可靠性、完成 proof/eval 覆盖范围,还是长时间运行目标期间的用户体验。好的第二个问题应询问什么 proof 能让用户相信改进已经生效。好的第三个问题应询问是复用现有目标、创建全新目标,还是先进行检查。

What
$goal-prep
Does

$goal-prep
的作用

When invoked directly, run intake first. For vague, strategic, improvement-oriented, or open-ended input, run the diagnostic intake and stop before creating or repairing the board until enough material answers are known. For sufficiently clear, planned, recovery, audit, or explicitly-defaulted input, prepare or repair the board and stop for user choice.
Do:
  • check for a newer GoalBuddy version once at the start and mention it without blocking;
  • clarify or infer the goal title and slug;
  • run the Intake Compiler;
  • ask diagnostic intake questions when clarity would materially improve the board;
  • classify the goal as
    specific
    ,
    open_ended
    ,
    existing_plan
    ,
    recovery
    , or
    audit
    ;
  • scan environment reality before seeding: existing worktrees, branches, or goal directories matching the slug, so the first task starts from what exists instead of assuming a fresh workspace;
  • inventory the repo's verify-style scripts once and record which are gate suites for this goal versus pre-existing red repo-health suites, so the oracle is honest about what this goal owns;
  • create or repair
    docs/goals/<slug>/
    ;
  • create
    goal.md
    ,
    state.yaml
    , and
    notes/
    ;
  • start the local board immediately and open it in the AI coding agent's in-app browser (Codex in-app Browser, Claude Code preview, or the user's regular browser) before filling the task list, unless the user opts out;
  • seed a role-tagged task board that matches the input shape;
  • make the first active task safe;
  • verify Scout, Worker, and Judge agent availability or record an explicit truthful state;
  • print the exact Codex command
    /goal Follow docs/goals/<slug>/goal.md.
    and Claude Code command
    /goalbuddy Follow docs/goals/<slug>/goal.md.
    ;
  • ask whether to start now, refine
    goal.md
    , or stop.
Do not:
  • start
    /goal
    automatically;
  • use, refresh, inspect, or load named skills requested by the goal; schedule that as
    /goal
    work instead;
  • browse links, inspect reference repos, read implementation files, generate design plans, generate images, or create assets for the requested outcome;
  • create or repair a board from vague/open-ended input before diagnostic intake is complete;
  • create
    evidence.jsonl
    ,
    units/
    , or
    artifacts/
    for new v2 goals;
  • edit implementation files before the board exists;
  • invent implementation tasks from vibes when the intake requires Scout, Judge, or plan validation first;
  • discard a user-provided plan; preserve it as facts and validate it before execution;
  • treat
    goal.md
    as board truth when it conflicts with
    state.yaml
    .
直接调用时,先运行 intake。对于模糊、战略性、改进导向或开放式输入,运行诊断性 intake,并在掌握足够的实质性答案之前停止,不要创建或修复看板。对于足够清晰、已有计划、恢复、审计或明确采用默认值的输入,准备或修复看板,然后停止以供用户选择。
执行以下操作:
  • 在开始时检查一次是否有更新的 GoalBuddy 版本,并予以说明,但不阻塞流程;
  • 明确或推断目标标题和 slug;
  • 运行 Intake 编译器;
  • 当进一步明确能够实质性改善看板时,提出诊断性 intake 问题;
  • 将目标分类为
    specific
    、
    open_ended
    、
    existing_plan
    、
    recovery
    或
    audit
    ;
  • 预置任务前核查实际环境:查找与 slug 匹配的现有 worktree、分支或目标目录,使首个任务基于现有成果,而不是假定处于全新工作区;
  • 一次性清点仓库中的 verify 类脚本,并记录哪些是本目标的门禁测试套件,哪些是原本就失败的仓库健康检查套件,以确保 oracle 准确反映本目标所负责的范围;
  • 创建或修复
    docs/goals/<slug>/
    ;
  • 创建
    goal.md
    、
    state.yaml
    和
    notes/
    ;
  • 除非用户选择退出,否则立即启动本地看板,并在填充任务列表前在 AI coding agent 的应用内浏览器中打开它(Codex 应用内 Browser、Claude Code 预览或用户的常规浏览器);
  • 预置与输入形态匹配的带角色标签任务看板;
  • 确保首个活跃任务安全;
  • 验证 Scout、Worker 和 Judge Agent 是否可用,或如实记录明确状态;
  • 打印准确的 Codex 命令
    /goal Follow docs/goals/<slug>/goal.md.
    和 Claude Code 命令
    /goalbuddy Follow docs/goals/<slug>/goal.md.
    ;
  • 询问用户是立即开始、细化
    goal.md
    ,还是停止。
不要执行以下操作:
  • 自动启动
    /goal
    ;
  • 使用、刷新、检查或加载目标所请求的指定 skill;应将这些操作安排为后续
    /goal
    工作;
  • 浏览链接、检查参考仓库、读取实现文件、生成设计方案、生成图像或为目标结果创建素材;
  • 在诊断性 intake 完成前,根据模糊或开放式输入创建或修复看板;
  • 为新的 v2 目标创建
    evidence.jsonl
    、
    units/
    或
    artifacts/
    ;
  • 在看板存在之前编辑实现文件;
  • 当 intake 要求先执行 Scout、Judge 或计划验证时,凭感觉臆造实施任务;
  • 丢弃用户提供的计划;应将其作为事实保留,并在执行前进行验证;
  • 当
    goal.md
    与
    state.yaml
    冲突时,将
    goal.md
    视为看板事实来源。

Slice Sizing Policy

切片规模策略

A good task is the largest safe useful slice.
Small is not the goal. Useful is the goal.
Safe does not mean small. Safe means bounded, explicit, verified, and reversible.
A good Worker task usually produces a working screen, a working API path, a working data pipeline step, a working backend vertical slice, a real bug fix, or a milestone review. A bad Worker task is one more tiny helper, projection function, contract file, read-only proof, or doc note unless that tiny task is truly blocking progress.
Judge specs the largest safe useful next slice and the PM activates it. Worker completes the whole assigned slice. Judge reviews the whole slice.
After two tiny tasks in a row, PM or Judge should reorient the board. If a demo milestone is complete, the next task should move toward the next real milestone.
Tiny tasks are allowed when the failure is isolated, the risk is high, the scope is unknown, or the tiny task unlocks a larger slice. Tiny tasks are bad when they keep happening, do not change behavior, only add wrappers/contracts/proof files, or avoid the real milestone.
一个好的任务应完成最大且安全、有用的工作切片。
小并不等于目标。有用才是目标。
安全并不意味着小。安全意味着边界明确、范围显式、经过验证且可以回退。
一个好的 Worker 任务通常会产出一个可工作的界面、一条可工作的 API 路径、一个可工作的数据管道步骤、一个可工作的后端垂直切片、一个真实的 bug 修复或一次里程碑审查。一个糟糕的 Worker 任务只是再增加一个微小的辅助函数、投影函数、契约文件、只读 proof 或文档说明,除非这个微小任务确实阻塞了进展。
Judge 负责确定下一个最大且安全、有用的工作切片,由 PM 激活该切片。Worker 完成被分配的全部切片,Judge 则审查整个切片。
如果连续出现两个微小任务,PM 或 Judge 应重新调整看板方向。如果演示里程碑已经完成,下一个任务应转向下一个真正的里程碑。
当故障范围孤立、风险较高、范围尚不明确,或微小任务能够解锁更大的切片时,允许安排微小任务。当微小任务不断出现、不改变行为、只增加包装层/契约/proof 文件或始终回避真正的里程碑时,它们就是糟糕的任务。

When To Use

何时使用

Use this skill for goals that are broad, multi-hour, ambiguous, high-risk, already planned, already stale, already red, or likely to need Scout/Judge/Worker delegation.
For a one-change task, do not create a GoalBuddy board.
If the user explicitly invokes
$goal-prep
on a one-change task anyway, ask one guided question offering the direct change without a board (Recommended) or a minimal board. If the user has already said to proceed or use defaults, prepare the smallest valid board and note the tradeoff in the prep response.
Scout and Judge tasks may identify optional publishing, reporting, integration, plugin, or channel opportunities as improvement candidates. Treat those as normal board tasks with concrete implementation plans.
state.yaml
remains board truth.
对于范围广、耗时数小时、含义模糊、风险高、已有计划、已经停滞、已经失败,或可能需要 Scout/Judge/Worker 委派的目标,使用此 skill。
对于只涉及一项变更的任务,不要创建 GoalBuddy 看板。
如果用户仍明确调用
$goal-prep
来处理一项变更任务,应提出一个有引导性的问题,让用户选择直接修改而不使用看板(推荐)或使用最小看板。如果用户已经表示继续或使用默认值,则准备最小有效看板,并在准备响应中说明这种取舍。
Scout 和 Judge 任务可能会发现可选的发布、报告、集成、插件或渠道机会,将其作为改进候选项。这些都应作为正常的看板任务处理,并附带具体实施计划。
state.yaml
仍然是看板事实来源。

The Four Primitives

四种基本元素

  1. Charter:
    goal.md
    says what the current tranche is trying to accomplish and what constraints matter.
  2. Board:
    state.yaml
    is the rolling task list and machine truth.
  3. Task: exactly one active task may be worked at a time.
  4. Receipt: every completed, blocked, or escalated task leaves a compact durable result on the task card.
Agents are not a separate primitive. They are the assignee type on a task.
  1. Charter(章程):
    goal.md
    说明当前批次试图实现什么,以及哪些约束至关重要。
  2. Board(看板):
    state.yaml
    是滚动任务列表和机器事实来源。
  3. Task(任务):同一时间只能处理一个活跃任务。
  4. Receipt(回执):每个已完成、受阻或已升级的任务,都会在任务卡片上留下紧凑且持久化的结果。
Agent 不是独立的 basic primitive,而是任务的 assignee 类型。

Control Files

控制文件

For a v2 goal, create only:
text
docs/goals/<slug>/
  goal.md
  state.yaml
  notes/
The goal root may contain only
goal.md
,
state.yaml
,
notes/
, optional depth-1
subgoals/
child boards, and generated
.goalbuddy-board/
files when the local visual board is enabled.
Most results live inline as task receipts in
state.yaml
. Only create
notes/<task-id>-<slug>.md
when Scout, Judge, or PM output is too large to fit on the task card.
Always start
state.yaml
from
templates/state.yaml
. The template carries required top-level keys (
version: 2
,
rules
,
oracle
,
visual_board
) that hand-written boards routinely miss, and the tooling rejects boards without them.
Use:
  • templates/goal.md
  • templates/state.yaml
  • templates/note.md
对于 v2 目标,仅创建:
text
docs/goals/<slug>/
  goal.md
  state.yaml
  notes/
目标根目录只能包含
goal.md
、
state.yaml
、
notes/
、可选的一级
subgoals/
子看板,以及启用本地可视化看板时生成的
.goalbuddy-board/
文件。
大多数结果以内联 receipt 的形式保存在
state.yaml
中。只有当 Scout、Judge 或 PM 的输出过大、无法放入任务卡片时,才创建
notes/<task-id>-<slug>.md
。
始终从
templates/state.yaml
创建
state.yaml
。该模板包含手写看板经常遗漏的必需顶层键(
version: 2
、
rules
、
oracle
、
visual_board
),工具会拒绝缺少这些键的看板。
使用:
  • templates/goal.md
  • templates/state.yaml
  • templates/note.md

Charter

Charter

The charter answers:
text
What did the user originally ask for?
What are we trying to improve?
What input shape did the intake identify?
What is the goal oracle?
What constraints are non-negotiable?
Is this goal specific, open-ended, existing-plan, recovery, or audit?
What likely misfire must the PM avoid?
What counts as enough for the current tranche?
Avoid forever goals. A broad goal should define an execution tranche, for example:
text
Discover the highest-leverage local improvements, complete successive safe verified work packages, review only at risk or phase boundaries, and keep advancing until the full outcome is complete.
Charter 回答以下问题:
text
What did the user originally ask for?
What are we trying to improve?
What input shape did the intake identify?
What is the goal oracle?
What constraints are non-negotiable?
Is this goal specific, open-ended, existing-plan, recovery, or audit?
What likely misfire must the PM avoid?
What counts as enough for the current tranche?
避免无期限目标。广泛目标应定义一个执行批次,例如:
text
Discover the highest-leverage local improvements, complete successive safe verified work packages, review only at risk or phase boundaries, and keep advancing until the full outcome is complete.

Board

Board

state.yaml
is the board and machine truth. A task card has:
yaml
id: T001
type: scout | judge | worker | pm
assignee: Scout | Judge | Worker | PM
status: queued | active | blocked | done
objective: "<one sentence>"
inputs: []
constraints: []
expected_output: []
receipt: null
Worker tasks additionally require:
yaml
allowed_files: []
verify: []
stop_if: []
Task ids must match the
T###
shape (for example
T001
,
T999
). The bundled checker rejects other formats such as
T001b
; a sibling or follow-up task gets the next free number.
The PM owns the board. Scout, Judge, and Worker return receipts; they do not select the next active task or mark the goal complete. Receipt shapes and all other runtime rules live in
references/goal-execution.md
.
state.yaml
是看板和机器事实来源。任务卡片具有以下结构:
yaml
id: T001
type: scout | judge | worker | pm
assignee: Scout | Judge | Worker | PM
status: queued | active | blocked | done
objective: "<one sentence>"
inputs: []
constraints: []
expected_output: []
receipt: null
Worker 任务还需要:
yaml
allowed_files: []
verify: []
stop_if: []
任务 ID 必须符合
T###
格式,例如
T001
、
T999
。内置检查器会拒绝
T001b
等其他格式;同级或后续任务应使用下一个可用编号。
PM 负责看板。Scout、Judge 和 Worker 返回 receipts;它们不能选择下一个活跃任务,也不能将目标标记为完成。Receipt 结构及其他所有运行时规则均位于
references/goal-execution.md
。

Seed Boards

预置看板

If the goal is vague, the first active task is Scout, but the seeded board should still lead toward execution. Queue Judge selection, a bounded Worker slot, and a final audit.
If the user provides an existing plan, do not ignore it and do not execute it blindly. Preserve the plan in
goal.intake.existing_plan_facts
, make the first active task PM or Judge validation, and queue Worker slices only after the plan is checked for evidence, risk, allowed files, verification, and stop conditions.
Example open-ended seed:
yaml
tasks:
  - id: T001
    type: scout
    assignee: Scout
    status: active
    objective: "Map repo health and identify improvement candidates."
    receipt: null
  - id: T002
    type: scout
    assignee: Scout
    status: queued
    objective: "Find verification commands, flaky tests, stale docs, dependency risks, and easy safety wins."
    receipt: null
  - id: T003
    type: judge
    assignee: Judge
    status: queued
    objective: "Choose the first safe implementation task by impact, confidence, reversibility, and verification strength."
    expected_output:
      - "Decision"
      - "Exact Worker objective"
      - "allowed_files"
      - "verify"
      - "stop_if"
    receipt: null
  - id: T004
    type: worker
    assignee: Worker
    status: queued
    objective: "Execute the first safe implementation task selected by Judge."
    allowed_files: []
    verify: []
    stop_if:
      - "Need files outside allowed_files."
      - "Behavior is ambiguous."
      - "Verification fails twice."
    receipt: null
  - id: T999
    type: judge
    assignee: Judge
    status: queued
    objective: "Audit whether the implemented slice satisfies the original user outcome for this tranche."
    receipt: null
If the goal is specific but evidence is incomplete, start with Scout. If risk or priority is unclear, queue Judge before Worker. If evidence is adequate and implementation is bounded, the first active task may be Worker.
If the goal is audit, keep the active task read-only. Queue execution only if the user asks for fixes or approves follow-up implementation.
如果目标模糊,首个活跃任务应为 Scout,但预置看板仍应指向执行。排入 Judge 选择任务、有边界的 Worker 任务位和最终审计。
如果用户提供了现有计划,不要忽略它,也不要盲目执行。将计划保存在
goal.intake.existing_plan_facts
中,把首个活跃任务设为 PM 或 Judge 验证,并且仅在计划的证据、风险、允许文件、验证和停止条件均已检查后,才排入 Worker 切片。
开放式目标的预置示例:
yaml
tasks:
  - id: T001
    type: scout
    assignee: Scout
    status: active
    objective: "Map repo health and identify improvement candidates."
    receipt: null
  - id: T002
    type: scout
    assignee: Scout
    status: queued
    objective: "Find verification commands, flaky tests, stale docs, dependency risks, and easy safety wins."
    receipt: null
  - id: T003
    type: judge
    assignee: Judge
    status: queued
    objective: "Choose the first safe implementation task by impact, confidence, reversibility, and verification strength."
    expected_output:
      - "Decision"
      - "Exact Worker objective"
      - "allowed_files"
      - "verify"
      - "stop_if"
    receipt: null
  - id: T004
    type: worker
    assignee: Worker
    status: queued
    objective: "Execute the first safe implementation task selected by Judge."
    allowed_files: []
    verify: []
    stop_if:
      - "Need files outside allowed_files."
      - "Behavior is ambiguous."
      - "Verification fails twice."
    receipt: null
  - id: T999
    type: judge
    assignee: Judge
    status: queued
    objective: "Audit whether the implemented slice satisfies the original user outcome for this tranche."
    receipt: null
如果目标具体但证据不完整,则以 Scout 开始。如果风险或优先级不明确,则在 Worker 之前安排 Judge。如果证据充分且实施范围有界,首个活跃任务可以是 Worker。
如果目标是审计,则保持活跃任务只读。只有用户要求修复或批准后续实施时,才排入执行任务。

Agents

Agents

Scout, Worker, and Judge templates are bundled with GoalBuddy as Codex
goal_*.toml
files and Claude Code
goal-*.md
files. They may also be installed as user or project agent configs, but a board must not claim
installed
unless the preparer verified the matching agent files.
Use these
state.yaml
values:
StateMeaningNext action
installed
Matching Scout/Worker/Judge agent configs were found in the expected user or project agent location.Continue.
bundled_not_installed
A bundled Codex
goal_*.toml
or Claude Code
goal-*.md
template exists, but no matching installed agent config was verified.
/goal
can proceed through PM fallback. If dedicated agents are required before
/goal
, run the GoalBuddy CLI through the user's install channel with
agents
.
missing
Neither an installed config nor the bundled template was verified.
/goal
can proceed through PM fallback. If dedicated agents are required before
/goal
, run the GoalBuddy CLI through the user's install channel with
install
.
unknown
Agent availability could not be checked.
/goal
must attempt the exact harness-specific GoalBuddy agent once. Use PM fallback only after the harness reports that exact agent unavailable or returns an error. To check before
/goal
, run the GoalBuddy CLI through the user's install channel with
doctor
.
Non-
installed
states are warnings, not false failures, because the main
/goal
PM can perform Scout/Judge/Worker-shaped tasks directly when dedicated agents are unavailable.
AgentThinking levelWrite accessUse for
Scoutlownotargeted source/spec/repo evidence mapping
Workermediumyes, boundedone coherent bounded useful slice
Judgehighnophase/risk/final review, ambiguity, scope, completion skepticism
A task's
assignee
determines the agent. The task card is the order. The receipt is the return format.
Only the main
/goal
PM may choose the active task, update the board, mark tasks done, or mark the goal complete. The PM thinking policy and the execution quality commands (including the subagent dispatch rules) live in
references/goal-execution.md
.
Scout、Worker 和 Judge 模板作为 Codex
goal_*.toml
文件和 Claude Code
goal-*.md
文件与 GoalBuddy 一同提供。它们也可以作为用户级或项目级 Agent 配置安装,但除非准备者已验证匹配的 Agent 文件,否则看板不能声明为
installed
。
使用以下
state.yaml
值:
状态含义后续操作
installed
在预期的用户级或项目级 Agent 位置找到了匹配的 Scout/Worker/Judge Agent 配置。继续执行。
bundled_not_installed
存在内置的 Codex
goal_*.toml
或 Claude Code
goal-*.md
模板,但未验证到匹配的已安装 Agent 配置。
/goal
可以通过 PM fallback 继续。如果在
/goal
之前必须使用专用 Agent,请通过用户的安装渠道运行带
agents
参数的 GoalBuddy CLI。
missing
既未验证到已安装配置,也未验证到内置模板。
/goal
可以通过 PM fallback 继续。如果在
/goal
之前必须使用专用 Agent,请通过用户的安装渠道运行带
install
参数的 GoalBuddy CLI。
unknown
无法检查 Agent 可用性。
/goal
必须尝试一次特定运行环境的精确 GoalBuddy Agent。只有当该运行环境明确报告此 Agent 不可用或返回错误后,才能使用 PM fallback。要在
/goal
之前检查,请通过用户的安装渠道运行带
doctor
参数的 GoalBuddy CLI。
非
installed
状态只是警告,并非失败,因为主
/goal
PM 在专用 Agent 不可用时,可以直接执行 Scout/Judge/Worker 形态的任务。
Agent思考级别写入权限用途
Scoutlow否有针对性地映射源码、规格和仓库证据
Workermedium是,有边界完成一个连贯、有边界且有用的切片
Judgehigh否阶段/风险/最终审查,以及处理歧义、范围和完成状态审慎性判断
任务的
assignee
决定使用哪个 Agent。任务卡片是命令载体,receipt 是返回格式。
只有主
/goal
PM 可以选择活跃任务、更新看板、将任务标记为完成,或将目标标记为完成。PM 思考策略和执行质量命令(包括 subagent 调度规则)位于
references/goal-execution.md
。

Default Execution Shape

默认执行形态

text
Codex:      /goal Follow docs/goals/<slug>/goal.md.
Claude Code: /goalbuddy Follow docs/goals/<slug>/goal.md.
When that command runs, the PM follows
references/goal-execution.md
.
text
Codex:      /goal Follow docs/goals/<slug>/goal.md.
Claude Code: /goalbuddy Follow docs/goals/<slug>/goal.md.
运行该命令时,PM 应遵循
references/goal-execution.md
。