Goal Prompt Builder

/goal Prompt Builder

This skill turns a fuzzy task description ("我想让 Codex 帮我重构鉴权") into a complete, audit-friendly /goal command that's ready to paste into Codex CLI 0.128+.

Why this skill exists

Codex 0.128 added /goal as a persistent objective with a runtime-injected audit prompt (continuation.md). The audit prompt forces the model to build a "prompt-to-artifact checklist" — but only if the user's goal text can be mapped to one. Vague goals produce vague checklists, which produce false completions. This skill exists to make sure every /goal you generate has the structure that lets the audit mechanism actually work.

The golden template (5 sections, in this order)

Every /goal Claude generates with this skill follows this structure exactly:

/goal <objective>.

[Optional: First action: read X, Y, Z and report counts. Wait for ack.]

Scope: <files / subsystem / feature area>.

Constraints:
  - <what not to change>
  - <compatibility / permission boundaries>
  - <project-specific rules from AGENTS.md / CLAUDE.md>

Done when:
  1. <verifiable artifact 1 — cite file or command>
  2. <verifiable artifact 2>
  ...

Stop if:
  - <mechanically detectable condition 1>
  - <mechanically detectable condition 2>
  ...

Use a token budget of <N> tokens for this goal.

Why this order: matches continuation.md's expected reading flow — objective first, then scope to bound the search, then constraints to prune options, then acceptance to define success, then stop-if as runtime guards.

Workflow

When this skill triggers, walk the user through these 6 steps. Step 0 (interaction mode) and Step 1 (project detection) happen automatically — Step 0 needs one user choice, Step 1 needs zero if filesystem is accessible. Don't skip steps unless the user explicitly says "I'll fill it in myself, just give me the template".

Step 0: Pick interaction mode

This skill supports three interaction modes. Ask once at the start:

你希望用哪种方式生成 /goal？

- A. 询问式 — 我一段一段问你（最稳，适合第一次写 /goal）

- B. 全描述式 — 你一句话描述需求，我拆解后只问你确认不确定的地方（最快，适合熟手）

- C. 混合式（默认） — 先选场景模板，再问 3-5 个关键问题（推荐）

Once chosen, follow the matching flow:

• A. 询问式 → Step 1 → Step 2 → Step 3a → 3b → 3c → 3d → 3e → Step 4 → Step 5 (each input gathered separately)
• B. 全描述式 → Step 1 → ask "用一段话描述你想做什么 / scope / 验收 / 不希望发生什么" → parse into 5 sections → Step 4 → ask user to confirm only the gaps → Step 5
• C. 混合式 → Step 1 → Step 2 → Step 3 (batched: ask all missing fields at once) → Step 4 → Step 5

Mode B is most powerful when the user has thought about the task. Mode A is safest when they haven't. Mode C is the default sweet spot.

If the user doesn't answer this question explicitly, default to mode C and proceed.

Step 1: Detect (don't ask) the project type

Auto-detection comes first. Only fall back to asking if detection fails.

Run this detection sequence:

1. Check the conversation context. Has the user already provided a repo URL, file path, or code snippet? Read those for hints first.

2. Probe the filesystem (if you have file tools and the user is in a project directory):

• package.json exists → Node / TypeScript
• pyproject.toml or requirements.txt or setup.py → Python
• *.xcodeproj/ or Package.swift → Swift / iOS
• Cargo.toml → Rust
• go.mod → Go
• astro.config.* / next.config.* / _config.yml / mkdocs.yml → Static / docs project

3. Fetch the repo if the user gave a URL (only if web tools available):

• GitHub URL → fetch the README + try to identify config files
• Read CLAUDE.md and AGENTS.md if they exist (these are gold for Constraints)

4. Fall back to asking only if all auto-detection failed:

我没法自动判断项目类型——这是 Node / Python / Swift / Go / Rust / 静态 / 其他？

When detection succeeds, announce what you found in one sentence so the user can correct you:

检测到这是一个 Swift / iOS 项目（找到 lingolearn.xcodeproj + CLAUDE.md）。

我会按 Swift 项目默认约束适配。如果不对，告诉我。

Then load the matching reference from references/project-types.md. Also load any `CLAUDE.md` / `AGENTS.md` found — these contain project-specific rules that override defaults.

Step 2: Pick a scenario template

Ask: 这个 goal 属于哪种类型？

Each option maps to a different default skeleton — see references/scenarios.md for the full templates.

Step 3: Gather the 5 inputs (in this order)

Ask only what's still missing. Don't ask all 5 at once — ask incrementally so the user can think.

3a. Objective (一句话)

• One sentence describing what changes by the end.
• If the user gives a verb-less noun phrase ("Cohere rerank support"), turn it into a verb phrase ("Add Cohere rerank support to retrieval pipeline").
• Reject vague verbs like "improve", "optimize", "clean up" — ask for the concrete change.

3b. Scope (改什么、不改什么)

• Which files / directories / subsystems are in play
• For brownfield projects: probe whether v1.x beta files or sensitive modules exist that should be off-limits

3c. Constraints (硬约束)

• Pull from AGENTS.md / CLAUDE.md if available
• Add project-type defaults from the loaded reference (e.g., for Swift: "do not modify project.pbxproj")
• Ask if there's a "MUST NOT modify" list

3d. Done when (验收清单)

• This is the most important section. Push back hard if items are vague.
• Each item must cite a file, command, test name, or measurable artifact.
• Replace "测试通过" → "<exact command> exits 0; paste summary"
• Replace "做完" → enumerate the deliverables
• Aim for 5-8 items; fewer than 3 is a red flag

3e. Stop if (停止条件)

• Each must be mechanically detectable
• Include project-type defaults (e.g., for Node: "needs npm install for new dep")
• Include a regression guard: "existing tests start failing — do not fix by editing tests"

Step 4: Predict audit-friendliness

Before showing the final command, internally score it (don't show the math, just the verdict):

• Acceptance count: 0 = bad, 1-2 = warn, 3-5 = good, 6-8 = excellent
• Vague verbs detected: "improve", "optimize", "全部", "彻底", "all", "everything" → flag
• Stop-if specificity: "if unclear" = bad, "if file X appears in git diff" = good
• Token budget present: missing = warn
• Mechanical verifiability: every Done-when item has a cite-able artifact = good

If score is below ~70%, don't ship the command yet. Instead, surface the weak spots and ask the user to refine. Be specific:

⚠ 我发现三处可以加强的地方：

1. Done when 第 2 条"测试覆盖" → 改成"测试名称 + 退出码"会更准

2. Stop if 缺少"现有测试 regression"兜底

3. Token 预算未指定，建议 80K（基于 scope 大小）

Step 5: Render and cite design choices

When all checks pass, render the final /goal in a code block (so it's copy-pasteable) and follow with a brief explanation of the key design choices — not a tutorial, just enough so the user knows why each choice was made.

Format:

/goal <full command here>

几个关键设计选择：

• 为什么 Done when 第 N 条这么写
• 为什么 Stop if 包含某条
• 为什么预算定这个数

Keep this explanation under 8 short lines. The user is here for the command, not a lecture.

Project type loading

When the project type is known, read the corresponding reference:

• Node / TypeScript → references/project-types.md (Node section)
• Python → references/project-types.md (Python section)
• Swift → references/project-types.md (Swift section)
• Go → references/project-types.md (Go section)
• Rust → references/project-types.md (Rust section)
• Static / docs → references/project-types.md (Static section)

Each section provides:

• Default test command with full flags
• Default build / type-check command
• Project-type-specific Stop-if bullets to include
• Common false-completion traps to guard against

Scenario templates

For the chosen scenario, read the corresponding skeleton:

• A. 重构 → references/scenarios.md § Refactor
• B. 新功能实现 → references/scenarios.md § Feature
• C. 批量补测试 / 修 bug → references/scenarios.md § Batch
• D. 代码考古 → references/scenarios.md § Archaeology
• E. UI / 行为 audit → references/scenarios.md § UI Audit
• F. 守门员 review → references/scenarios.md § Gatekeeper
• G. 自定义 → use bare 5-section template, no skeleton

Each scenario has its own emphasis — e.g., archaeology goals emphasize Constraints (禁区), feature goals emphasize "First action: read SPEC + report counts".

Worked examples

When the user's case is ambiguous about how to fill a section, consult references/examples.md. It contains 5 end-to-end transformations (vague request → final command) covering the most common patterns:

• Refactor (Node/TS) — cleanest baseline
• Feature with SDD spec (Swift) — most heavily constrained
• Vague request → push back instead of rendering — when not to render
• Archaeology (static / docs project) — read-only goals
• "Just give me the template" — when to skip the interview

Especially read example 3 for guidance on when to refuse rendering. Don't ship a goal you can't defend — surface the weak spots and ask for refinement first.

Hard rules (always follow)

These are non-negotiable. They come from continuation.md's actual behavior.

1. Never write Stop-if as "if unclear, stop" — that's not mechanically detectable. Ask the user to enumerate concrete conditions. 2. Never let "all / everything / 全部 / 彻底" through — flag and ask for a number or enumerable source. 3. Always include a token budget — missing budget = no soft stop = potential runaway. 4. Always include a "no test-rewriting" stop-if for any goal that touches tested code: "Existing tests start failing — this is a regression, do not 'fix' by editing tests." 5. For SDD-driven goals (scenario B), the first action is always "read X files and report counts" — bypasses @filename reference uncertainty and exposes loading failures early. 6. For brownfield projects, always ask about MUST NOT modify list — the absence of one is the #1 cause of scope creep.

Common failure modes to coach the user through

• "测试通过"做验收: too vague. Force into "exact command + exit code + paste summary".
• 没有 Stop if: goal is a one-way door. Add at least 3 mechanically detectable conditions.
• 预算 > 300K: too big to audit reliably. Suggest splitting into two goals.
• Scope = "整个仓库": too wide. Push for a specific directory or subsystem.
• "我之后再补 acceptance": this is the failure pattern. Refuse to render until at least 3 items exist.

What this skill does NOT do

• Does not run the /goal for the user — it only generates the text
• Does not validate the project state (no git status checks, no test runs)
• Does not handle Codex versions older than 0.128 — /goal doesn't exist there
• Does not generate prompts for /plan, /compact, or other Codex commands

Output format reminder

Final output is always: 1. A markdown code block containing the /goal command (so the user can copy) 2. A short bullet list of the key design choices (no more than 8 short lines) 3. Optional: a one-line "audit-friendliness verdict" (e.g., "审计友好度：优秀 · 7 项验收 · 0 风险标记")

That's it. No long lecture. The user is here for a command.

Worked Examples

End-to-end transformations: vague user input → final /goal command. Use these as reference when the user's case is ambiguous about how to fill a section.

Each example shows: 1. User's initial vague request 2. Skill's interview questions 3. User's answers 4. Final rendered /goal 5. Audit verdict

---

Example 1: Refactor (Node/TS project)

User's initial request

"Help me write a goal to refactor the auth middleware to support API key rotation"

Interview

• Skill: 这是 Node/TS 还是其他？项目里有 AGENTS.md 或 CLAUDE.md 吗？
• User: Node/TS, has AGENTS.md, follows conventional commits
• Skill: scope 涉及哪些文件？现有的 auth 测试在哪里？
• User: 只动 src/auth/middleware.ts 和 tests/auth/middleware.test.ts
• Skill: 具体的"after"状态是什么？需要支持哪些场景？
• User: 接受 current key 和 previous key（grace window 7 天），都过期才拒绝
• Skill: 公开 API 是否要保持不变？
• User: 是

Final /goal

/goal 重构 src/auth/middleware.ts，使其同时支持当前密钥与前一密钥（grace window 7 天）的鉴权。

Scope: 仅 src/auth/middleware.ts 与 tests/auth/middleware.test.ts。

Constraints:
  - 不修改 src/auth/index.ts 的公开导出签名。
  - 不修改 db schema、不修改 migrations/。
  - 不引入新的 npm 依赖。
  - commit message 遵循 conventional commits 格式（AGENTS.md 要求）。

Done when:
  1. src/auth/middleware.ts 同时接受 `Authorization: Bearer <current>` 
     和 `X-Auth-Previous: <rotated>` 两种 header。
  2. tests/auth/middleware.test.ts 包含 4 个新测试并全部通过：
     (a) 仅当前密钥；(b) 仅前一密钥（grace window 内）；
     (c) 仅前一密钥（grace window 已过）；(d) 双密钥都过期。
  3. `npm test -- tests/auth` 退出码 0；粘贴 test summary（应显示 ≥ 4 个新测试通过）。
  4. `npx tsc --noEmit` 退出码 0。
  5. CHANGELOG.md 在 "Unreleased" 段落新增条目描述行为变化。
  6. 最终 summary 列出所有修改文件 + 改动行数（应仅 3 个文件）。

Stop if:
  - 实现需要修改 db schema 或 migrations/。
  - 现有的 src/auth/* 测试任何一个开始失败（regression — 不要靠改测试解决）。
  - 需要新增 npm 依赖。
  - TypeScript strict 模式下出现新增的 `any` 类型（项目启用了 strict）。

Use a token budget of 80000 tokens for this goal.

审计友好度：优秀 · 6 项验收 · 0 风险标记

关键设计选择：

• Done when 第 2 项把"测试覆盖"翻译成 4 个具体可枚举的场景（current/grace 内/grace 外/双过期）
• Done when 第 3 项要求"粘贴 test summary"防止只看 exit code
• Stop if 第 2 条是 regression 兜底，明确禁止"改测试让自己通过"
• 80K 预算适合双文件改造 + 4 个测试

---

Example 2: Feature (SDD-driven, Swift project)

User's initial request

"我用 OpenSpec 提了个收藏夹智能排序的 change，现在想用 /goal 实现"

Interview

• Skill: 这是什么项目？SDD spec 路径在哪里？
• User: SwiftUI iOS 应用，spec 在 openspec/changes/add-favorites-smart-sort/
• Skill: Xcode 版本 + 测试框架？
• User: Xcode 26 beta, lingolearnTests 用 Swift Testing
• Skill: 项目有 CLAUDE.md / AGENTS.md 吗？有什么铁律？
• User: 有 CLAUDE.md。铁律：(1) 不改 pbxproj (2) MainActor isolation (3) 零第三方依赖 (4) 不联网

Final /goal

/goal 严格按照 openspec/changes/add-favorites-smart-sort/ 的全部规范实现。

First action: 先逐字读取以下文件，然后回报计数：
  - openspec/changes/add-favorites-smart-sort/proposal.md
  - openspec/changes/add-favorites-smart-sort/design.md
  - openspec/changes/add-favorites-smart-sort/tasks.md
  - openspec/changes/add-favorites-smart-sort/specs/favorites-sort/spec.md
  - CLAUDE.md
报告：tasks.md 中 task 数量、spec.md 中 SHALL 数量、CLAUDE.md 中 Iron Rules 数量。
等我确认后再开始实现。

Scope: design.md 中 "MUST NOT modify" 清单严格遵守；其他 .swift 文件可改。

Constraints:
  - CLAUDE.md 的 4 条铁律是非协商：
    (a) 不修改 lingolearn.xcodeproj/project.pbxproj；
    (b) 新类型默认 MainActor-isolated；
    (c) 不引入 Swift Package；
    (d) 不引入网络请求（隐私铁律：不联网）。
  - 单元测试用 Swift Testing（@Test / #expect），不用 XCTest。
  - 修改 @Model 需要 design.md 显式允许。

Done when:
  1. tasks.md 中每一项都打勾，每项注明对应的文件路径 + 关键修改点。
  2. spec.md 中每一条 SHALL 至少有一个通过的 Swift Testing 用例覆盖，
     注明测试文件名 + 测试函数名。
  3. spec.md 中每个 GIVEN/WHEN/THEN scenario 都有对应集成测试。
  4. 既有 11 个测试（SM2Tests 7 + SeedTests 3 + AppearanceTests 1）全部通过。
  5. `xcodebuild -project lingolearn.xcodeproj -scheme lingolearn 
     -destination 'platform=iOS Simulator,name=iPhone 17' build` 退出码 0。
  6. `xcodebuild ... test -only-testing:lingolearnTests` 退出码 0；
     粘贴 test summary（新增测试数应 ≥ spec.md 中 SHALL 数）。
  7. design.md 的 "MUST NOT modify" 清单中每个文件 git diff 输出为空。

Stop if:
  - tasks.md 中某项要求修改 design.md "MUST NOT modify" 清单中的文件。
  - spec.md 中两条 SHALL 互相冲突（升级，不要自行决定）。
  - 实现需要在 project.pbxproj 中手动注册新文件（违反 CLAUDE.md）。
  - 实现需要新增 Swift Package（违反零依赖）。
  - 实现需要任何网络请求（违反隐私铁律）。
  - 既有 11 个测试中任意一个失败（regression — 不要改测试）。
  - 需要 nonisolated 修饰符（先停下汇报为什么需要）。
  - iPhone 17 模拟器不可用（先 `xcrun simctl list devices available`，由我决定）。

Use a token budget of 130000 tokens for this goal.

审计友好度：优秀 · 7 项验收 · 8 项 stop-if · 0 风险标记

关键设计选择：

• First action 强制先读 5 个文件 + 报数——绕开 @filename 引用语法的不确定性
• CLAUDE.md 的 4 条铁律每一条同时进 Constraints（告诉模型别这么做）+ Stop if（如果发现必须这么做就停）
• Done when 第 6 项要求 paste test summary，防止 xcodebuild 输出过长模型只看末尾
• Stop if 第 8 条 iPhone 17 模拟器兜底是 Xcode beta 项目特有的——并非每台机器都装

---

Example 3: Vague request → push back instead of rendering

User's initial request

"我想让 Codex 把整个项目优化一下，跑得快一点"

Interview

• Skill: ⚠ 我看到几处需要先澄清的地方：
• "整个项目" 太宽——audit 期模型无法构建可枚举边界。具体哪个子系统？
• "优化" 是主观判断——audit 期模型无法验证。具体的可观测指标是什么？比如某个端点 p99 延迟、某个测试运行时长、内存占用？
• "跑得快一点" 没有数字——具体目标值是多少？比 baseline 提升多少 %？

请告诉我： 1. 哪个具体子系统 / 哪个具体场景？ 2. 你怎么测量"快"——什么命令、什么数字？ 3. 目标是从 X 提升到 Y 还是要 ≤ Z？

• User: 哦那这样：让搜索接口的 p95 latency 从 800ms 降到 400ms 以下，benchmark 用 scripts/bench.sh

• Skill: 这就好办多了。继续...

Lesson

对模糊请求不要直接 render —— 那样产出的 goal 必然 audit-hostile。Skill 的价值之一就是在写之前帮用户把愿望翻译成可验证的目标。

---

Example 4: Archaeology (Static / docs project)

User's initial request

"帮我让 Codex 摸清这个新接手的开源项目"

Interview

• Skill: 项目类型？什么语言？
• User: 一个 Astro 文档站点 + 一些 React component
• Skill: 你想要什么形式的产出？想识别哪类东西？
• User: 三份文档：架构图、调用链、文档没写但代码做了的事

Final /goal

/goal 摸清这个 Astro 文档站点的所有运作方式，输出三份文档；不修改任何源代码。

Scope: 只读 src/、components/、astro.config.* 与 README.md / CHANGELOG.md；
       可写文件仅限本 goal 创建的 3 份新 docs/*.md 文档。

Constraints:
  - 严格禁止修改任何 .astro / .tsx / .ts / .mdx 文件。
  - 不修改 astro.config.* 配置。
  - 不修改 public/ 资产。
  - 不运行 npm install / npm run build（这次只读，不验证）。
  - 引用代码必须用真实文件路径 + 行号，不要编造行号。
  - 重点指出"代码做了但 README 没写"的部分。

Done when:
  1. 新建 docs/ARCHITECTURE.md，包含：entry points、layout 文件、content 来源、
     主要 island components 列表、build pipeline 概述（mermaid 图，不超过 200 行）。
  2. 新建 docs/CALL_GRAPHS.md，包含 top 3 用户路径的渲染链：
     (a) 访问首页 → layout → content collection → render；
     (b) 访问博客列表 → 数据来源 → 分页 → 渲染；
     (c) 访问搜索页 → 客户端 island → 数据获取。
     每条链路 cite 文件:行号。
  3. 新建 docs/UNDOCUMENTED.md，列出至少 5 处"代码已实现但 README 未提及"的行为。
  4. 最终 summary 确认：本 goal 期间 git diff 仅显示 docs/ 下 3 个新文件，无其他改动。

Stop if:
  - 某个 .astro 文件无法解析（语法错误 / 编码问题）。
  - git status 显示任何 .astro / .tsx / .ts / .mdx / config 文件被修改（越界）。
  - 发现 README 与既有文档在同一事实上互相冲突（升级，让我决定）。

Use a token budget of 60000 tokens for this goal.

审计友好度：优秀 · 4 项验收 · 0 风险标记

关键设计选择：

• Constraints 列了具体扩展名（.astro / .tsx / .ts / .mdx）——比 "不改源码" 更精确
• Done when 第 1 项给出 mermaid 长度上限（200 行），防止图过大失去可读性
• Done when 第 4 项验证 git diff——把"没改代码"作为可机械检验的验收项
• 60K 预算偏低，因为不动代码的 goal 不需要长跑

---

Example 5: When user wants raw template (skip the interview)

User's initial request

"Just give me the 5-section template, I'll fill it in myself"

Skill response

/goal <objective>。

Scope: <files / subsystem>。

Constraints:
  - <hard rules>
  - <project-type defaults>

Done when:
  1. <verifiable artifact 1>
  2. <verifiable artifact 2>
  3. <verifiable artifact 3>

Stop if:
  - <mechanical condition 1>
  - <mechanical condition 2>
  - <mechanical condition 3>

Use a token budget of <N> tokens for this goal.

几个填空提示：

• Done when 至少 3 项，每项要 cite 一个文件 / 命令 / 测试
• Stop if 至少 3 项，每项要可机械检测
• 避免 "改进 / 优化 / 全部 / 彻底" 这类虚词
• Token budget：单文件 30-60K，子系统 80-120K，跨多文件 120-200K

如果你写完想让我 review，把它贴给我，我会指出 audit 友好度问题。

Project Type Defaults

This file is loaded by the goal-prompt-builder skill once the project type is known. Each section provides:

• Test command: full xcodebuild/npm/cargo invocation, no abbreviations
• Build / type-check command: same
• Default Stop-if bullets: what to add to every Stop-if for this project type
• False-completion traps: known ways the project type lets the model "pass" audit while still being broken
• AGENTS.md / CLAUDE.md probe questions: type-specific things to look for

Use the section matching the user's project type. Don't blend sections.

---

Node / TypeScript

Test command

npm test

or if more specific:

npm test -- <path-pattern>

For CI mode (no watch):

npm test -- --watchAll=false

Build / type-check

npx tsc --noEmit

or if there's a build script:

npm run build

Default Stop-if bullets

• package.json 中需要新增依赖（npm install would be required）
• node_modules/ 损坏，需要 rm -rf node_modules && npm ci 才能继续
• 现有测试开始失败（regression — 不要靠改测试 / 加 .skip 解决）
• TypeScript strict 模式下出现 any 类型新增（如 tsconfig 启用了 strict）

False-completion traps

• Jest 的 it.skip / describe.skip 被默认接受为"测试通过"——goal 应明确"skip 计数必须为 0"
• 如果项目用 jiti / esbuild-loader / ts-node 缓存：改 .ts 后跑测试前必须清缓存（rm -rf node_modules/.cache），否则跑的是旧版本
• monorepo 下 npm test 可能只跑当前 workspace，需要确认 --workspaces 是否生效

Probe questions for AGENTS.md / CLAUDE.md

• 是否锁定 Node 版本（engines field、.nvmrc）？
• 是否禁止某些 npm 包（lock file 里有 deny list）？
• 是否要求 commit message 遵循特定格式（conventional commits）？

---

Python

Test command

pytest -q

or for specific path:

pytest -q tests/<path>

or with coverage:

pytest -q --cov=<package> --cov-fail-under=80

Build / type-check

mypy <package>

or for ruff users:

ruff check . && ruff format --check .

Default Stop-if bullets

• 需要新增 requirements.txt / pyproject.toml 依赖（pip install would be required）
• 需要修改 Python 版本要求（python_requires）
• 现有测试开始失败（regression — 不要靠 @pytest.mark.skip 跳过）
• 引入会泄漏的全局状态（修改 module-level 变量）

False-completion traps

• pytest.mark.skip / pytest.mark.xfail 被默认计入"测试通过"——goal 应明确"skipped 计数必须为 0"
• 异步测试如果没装 pytest-asyncio 会被静默跳过——goal 应明确"async 测试实际执行计数 ≥ N"
• conftest.py 修改可能影响其他测试，但不会立刻报错——goal 应禁止改 conftest.py 除非显式需要

Probe questions

• 用什么 Python 版本管理（pyenv / conda / uv）？
• 是否有 pre-commit hooks 强制 lint / format？
• 是否区分 dev / prod dependencies？

---

Swift / iOS

Test command

xcodebuild -project <project>.xcodeproj -scheme <scheme> \
  -destination 'platform=iOS Simulator,name=iPhone 17' \
  test -only-testing:<TestTarget>

For Swift Package Manager projects:

swift test

Build

xcodebuild -project <project>.xcodeproj -scheme <scheme> \
  -destination 'platform=iOS Simulator,name=iPhone 17' build

Default Stop-if bullets

• 修改 <project>.xcodeproj/project.pbxproj（如果项目用 PBXFileSystemSynchronizedRootGroup，绝对禁止手动改）
• 引入新的 Swift Package（违反"零依赖"原则的项目）
• 需要 nonisolated 修饰符（如果项目设置了 SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor，先停下汇报为什么）
• iPhone 17 模拟器不可用（先 xcrun simctl list devices available，由用户决定换哪个 destination）
• 现有测试开始失败（regression — 不要改测试）

False-completion traps

• Swift Testing 的 @Test(.disabled()) 不计入失败但不再执行——goal 应明确"无 disabled 测试新增"
• XCTest 的 XCTSkip 同上
• iOS 测试有时因为模拟器启动失败"挂起"而不是失败——goal 应要求 paste 完整 test summary 而不是只看 exit code
• xcodebuild 的 stdout 极长，模型容易只看末尾——goal 应要求 cite 测试名而不是"all passed"

Probe questions

• Xcode beta 版本号是多少？
• 测试框架：Swift Testing（@Test）还是 XCTest（XCTestCase）？两个目录可能用不同的
• 是否启用 SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor？
• 是否禁止第三方依赖（README 常见铁律）？

---

Go

Test command

go test ./...

For specific package:

go test ./<pkg>/...

With race detector:

go test -race ./...

Build

go build ./...

Or for vet/lint:

go vet ./... && staticcheck ./...

Default Stop-if bullets

• 需要修改 go.mod 添加新依赖（go get would be required）
• go.sum 出现意外变动（除了添加同意的依赖）
• 现有测试开始失败（regression — 不要 t.Skip 解决）
• 数据竞争被引入（go test -race 检测到新的 race）

False-completion traps

• t.Skip 默认计入"通过"——goal 应明确"skipped 计数必须为 0"
• table-driven test 中某个 case 被注释掉看起来像通过——goal 应禁止"注释 test case 来让自己通过"
• _test.go 里的 helper 函数被改可能影响多个测试但不立刻报错

Probe questions

• Go 版本是多少（go.mod 第一行）？
• 是否要求 gofmt 干净？
• 是否使用 generics（Go 1.18+）？
• 是否有内部 packages（internal/）需要避免暴露？

---

Rust

Test command

cargo test --all-features

For specific crate in workspace:

cargo test -p <crate-name>

Build

cargo check --all-targets

Stricter:

cargo clippy --all-targets -- -D warnings

Default Stop-if bullets

• 需要修改 Cargo.toml 添加新依赖（cargo add would be required）
• Cargo.lock 出现意外变动
• 现有测试开始失败（regression — 不要 #[ignore] 解决）
• 引入 unsafe 块（如果项目政策禁止）
• clippy warnings 增加（如果项目用 -D warnings）

False-completion traps

• #[ignore] 标注会让测试跳过但仍计入 "test result: ok"——goal 应明确"ignored 计数必须为 0"
• cfg(test) 下的 mock 实现可能让测试通过但生产代码 broken——goal 应要求至少一个集成测试
• Cargo workspace 下 cargo test 不带 -p 会跑所有 crate，时间长

Probe questions

• Rust 版本（rust-toolchain.toml）？
• 是否 #![forbid(unsafe_code)]？
• 是否启用 nightly features？
• 是否有 no_std crate？

---

Static / 文档项目

Test / Build 命令

• 通常只有 markdown lint 或 link-check

markdownlint **/*.md

或：

npx markdown-link-check README.md

Default Stop-if bullets

• 修改任何 .svg / .png / .gif 资产（除非 goal 明确要求）
• 现有 markdown 渲染失败（如有 build pipeline）
• 引入 broken link
• frontmatter / metadata 字段被无意修改

False-completion traps

• 模型可能"修复"它认为是 typo 的术语，实际是项目刻意保留的拼法（如品牌名、缩写）
• markdown 表格的对齐改动会让 git diff 看起来很大但实际无内容变化——goal 应区分"内容变化"vs"格式化变化"
• 双语文档（README.md + README_CN.md）容易只改一个

Probe questions

• 是否有 style guide（措辞、术语表）？
• 是否双语？哪个是主？
• 是否用 mkdocs / docusaurus / vitepress 等 static site generator？

---

其他 / 未知

如果项目类型不在以上列表，至少问：

1. 怎么跑测试？（请给完整命令） 2. 怎么 build / type-check？（请给完整命令） 3. 项目最忌讳改什么文件？ 4. 是否有 AGENTS.md / CLAUDE.md / CONTRIBUTING.md 已经写了规则？

把这些答案直接塞进 Constraints 和 Stop-if，不要尝试推断。

Scenario Skeletons

Loaded by goal-prompt-builder after the user picks a scenario in Step 2. Each section provides a fillable skeleton plus the design rationale (so Claude knows why the skeleton looks the way it does, and can adapt intelligently when the user's actual case doesn't fit perfectly).

Use only the scenario the user picked. Don't blend.

---

§ Refactor (重构 — 单子系统改造)

When this fits

• Changes confined to 1-3 files or a single subsystem
• The change has a crisp "after" state (specific behavior change, specific test passing)
• Risk is contained — public API surface is preserved

Skeleton

/goal <重构动作>，<具体的 after 状态>。

Scope: <具体目录或文件 list>。

Constraints:
  - 不修改 <相邻但不相关的子系统>。
  - 公开 API（<具体导出文件>）签名保持不变。
  - <项目类型默认约束 — 从 references/project-types.md 取>
  - 不引入新依赖。

Done when:
  1. <文件 X> 实现了 <具体行为>。
  2. <测试文件 Y> 包含 N 个新用例并全部通过：(a) (b) (c)。
  3. <精确的测试命令> 退出码 0；粘贴 test summary。
  4. <build / type-check 命令> 退出码 0。
  5. CHANGELOG.md（如果存在）在 "Unreleased" 段落新增条目。
  6. 最终 summary 列出每个修改文件 + 改动行数。

Stop if:
  - 实现需要修改 <显式禁区>。
  - 现有测试开始失败（regression — 不要靠改测试解决）。
  - 需要新增依赖 / 升级语言版本。
  - <项目类型默认 stop-if>

Use a token budget of <60-100K> tokens for this goal.

Rationale

• Scope 必须先于 Constraints: scope 圈"动什么"，constraints 圈"不动什么"——前者是邀请，后者是边界
• Done when 5 项左右最稳: 少于 3 项 audit 抓不住，多于 8 项模型容易遗漏
• 测试命令必须完整: "测试通过" 是代理信号，"npx tsc --noEmit && npm test -- src/auth 退出码 0 + paste summary" 才是证据
• Stop if 第 1 条永远是"修改禁区": 这是最常见的越界路径

Token budget guidance

• 单文件 ≈ 30-60K
• 双文件 + 测试 ≈ 60-100K
• 跨 3+ 文件 ≈ 100-150K

---

§ Feature (新功能实现 — 已有 SDD spec)

When this fits

• 用户已经有 OpenSpec / SpecKit / 自写的 spec 文档
• Spec 用 SHALL / Acceptance / Scenarios 这种结构化形式
• 任务是"按 spec 实现"，不是"想清楚要什么"

Skeleton

/goal 严格按照 <spec 路径> 的全部规范实现。

First action: 先逐字读取以下文件，然后回报计数：
  - <spec 路径>/proposal.md
  - <spec 路径>/design.md
  - <spec 路径>/tasks.md
  - <spec 路径>/specs/<capability>/spec.md
  - AGENTS.md（如果存在）
报告：tasks.md 中 task 数量、spec.md 中 SHALL 数量、识别到的 AGENTS.md 关键约束条数。
等我确认后再开始实现。

Scope: design.md 中 "MUST NOT modify" 清单严格遵守；其他文件可改。

Constraints:
  - AGENTS.md 的所有 Iron Rules 是非协商约束。
  - <项目类型默认约束>
  - 不引入未在依赖清单中声明的新依赖。
  - 修改 @Model / data layer 需要 design.md 显式允许，否则禁止。

Done when:
  1. tasks.md 中每一项都打勾，每项注明对应的文件路径 + 关键修改点。
  2. spec.md 中每一条 SHALL 至少有一个通过的测试覆盖，注明测试文件 + 测试名称。
  3. spec.md 中每一个 GIVEN/WHEN/THEN scenario 都有对应的集成测试。
  4. <build 命令> 退出码 0，粘贴 build summary。
  5. <test 命令> 退出码 0，粘贴 test summary（新增测试数应 ≥ spec.md 中 SHALL 数）。
  6. design.md 的 "MUST NOT modify" 清单中每个文件 git diff 输出为空。
  7. README.md（如有要求）追加描述新增能力。

Stop if:
  - tasks.md 中某项要求修改 design.md "MUST NOT modify" 清单中的文件。
  - spec.md 中两条 SHALL 互相冲突（升级，不要自行决定优先级）。
  - 实现需要新增依赖。
  - 现有测试开始失败。
  - <项目类型默认 stop-if>

Use a token budget of <100-150K> tokens for this goal.

Rationale

• First action 是"先读 + 报数": 这一段是 SDD 模式的 killer 设计。绕开 @filename 引用语法是否被 Codex 解析的不确定性，强制模型在动手前显式回报它读到了多少内容。如果回报的数字对不上，立刻 /goal pause 排查，比让它跑半天才发现没读到 spec 安全得多
• Done when 第 1-3 项是"映射 1:1": SHALL → 测试 / Scenario → 集成测试 / task → 文件——这种 1:1 映射是 SDD + /goal 配合的核心价值
• Stop if 第 2 条"SHALL 冲突 → 升级": 这种冲突应该回到 spec 阶段解决，不应该让模型独断
• 预算偏高（100-150K）: SDD 实现通常涉及多文件 + 多测试，预算给足

Variant: 没有 SDD spec 的"新功能"

如果用户只有自然语言需求，没有 spec 文档，应该建议：

• 先用 OpenSpec 提案（/opsx:propose）生成 spec
• 再用本 skeleton

或者降级用 § Refactor 的 skeleton + 加大 scope。

---

§ Batch (批量任务 — 修 bug、补测试、批量重命名)

When this fits

• 任务是"做 N 件相似的事"
• N 是已知的或可枚举的
• 每件事的"完成"标准一致

Skeleton

/goal <批量动作> N 个 <对象>，<来自哪里 / 怎么枚举>。

Scope: <每件事的修改范围>。每件事一个 commit。

Constraints:
  - N 个对象必须来自 <可枚举来源>（如 GitHub issue tracker labels=bug+priority=high）。
  - 每件事的修改不能跨界（一个 commit 只动相关文件）。
  - 不合并、不关闭范围之外的其他对象。
  - <项目类型默认约束>
  - commit message 格式：<具体格式>。

Done when:
  1. N 个对象各自关联一个独立的 commit。
  2. 每件事在 <测试目录> 下有对应的 <测试 / 验证>，全部通过。
  3. <test 命令> 退出码 0，新增测试数 ≥ N。
  4. CHANGELOG.md 列出 N 条，每条附引用。
  5. 最终 summary 是一张表格，列出：对象号 / 一句话描述 / 修改文件 / 测试 / commit hash。

Stop if:
  - 某个对象在过程中状态变化（被关闭 / 被他人改动）。
  - 某件事需要破坏性变更（API 签名 / schema 变更）。
  - 现有的相关测试开始失败。
  - 某个对象实际不可复现 / 不存在。
  - 完成 N 件后 review 发现 < M 件实际正确（M 由用户定，通常 = N）。

Use a token budget of <100-150K> tokens for this goal.

Rationale

• N 必须是数字: "修一些 bug" 是愿望，"修 5 个 bug" 是循环。模型在续跑期会拿这个 N 当 audit checklist 的长度
• 可枚举来源: 强制让 N 的边界来自外部事实（issue tracker / 文件列表 / 测试覆盖报告），而不是模型主观判断
• commit 隔离: "一件事一个 commit" 让回滚边界明确，也是 audit 时的天然 checkpoint
• Stop if 第 5 条 "review 后 < M 件正确": 这是 batch 任务特有的兜底——避免"完成 5 件但有 3 件错了"的情况被宣告 done

---

§ Archaeology (代码考古 — 只研究不动手)

When this fits

• 接手陌生项目想摸清架构
• 想识别"代码做了但文档没写"的部分
• 想生成 onboarding 文档

Skeleton

/goal 摸清 <项目名> 的所有运作方式，输出 <N> 份文档；不修改任何源代码。

Scope: 只读 <源代码目录>；可写文件仅限本 goal 创建的 N 份新 .md 文档。

Constraints:
  - 严格禁止修改任何 <源代码目录> 下的现有文件。
  - 不修改 <资产文件，如 words.json / 配置文件>（这些是产品资产）。
  - 不运行任何会修改环境的命令（npm install / cargo build 等）。
  - 引用代码必须用真实文件路径 + 行号，不要编造。
  - 重点指出"代码做了但 README / docs 没写"的部分。

Done when:
  1. 新建 docs/ARCHITECTURE.md，包含：entry points、primary modules、外部依赖、数据流图（mermaid）。
  2. 新建 docs/CALL_GRAPHS.md，包含 top N 用户路径的调用链，每条 cite 文件:行号。
  3. 新建 docs/UNDOCUMENTED.md，列出 ≥ 5 处"代码已实现但 README 未提及"的行为。
  4. 最终 summary 确认：本 goal 期间 git diff 仅显示 docs/ 下 N 个新文件，无源码改动。

Stop if:
  - 某个文件需要外部工具才能解析（加密 / 二进制 / 专有格式）。
  - git status 显示任何源码文件被修改（越界，立即停止）。
  - 发现两份既有文档在同一事实上互相冲突（升级，让用户决定）。

Use a token budget of <50-80K> tokens for this goal.

Rationale

• Constraints 比 Scope 更长更严: 这种 goal 的核心价值是"不动代码"，禁区清单必须详尽
• "引用必须用真实路径 + 行号": 防止模型编造好看的报告。Done when 应该至少抽查 1 项 cite 是否真实（人工 review 时）
• Done when 最后一项验证 git diff: 把"没改代码"显式作为可机械检验的验收项
• 预算偏低（50-80K）: 不动代码的 goal 不需要长跑，主要消耗在 read 上

---

§ UI Audit (对照文档审实现)

When this fits

• 项目有 README / spec / 设计稿描述了"应该是什么样"
• 想 audit "实际实现"和"宣称行为"的差距
• 不修改代码，只生成报告

Skeleton

/goal 对照 <宣称来源> 描述的所有功能，audit <项目> 的实际实现，
       生成一份差距报告；不修改任何代码。

Scope: 只读 <UI 代码目录>、<宣称来源文件>；可写文件仅限本 goal 创建的 1 份 docs/<NAME>_AUDIT.md。

Constraints:
  - 不修改任何源代码。
  - 不启动 / 不运行（这次是静态 audit，运行验证留给后续）。
  - 不"宣称"功能存在或不存在——必须 cite 文件路径 + 行号。
  - 评估口径基于 <宣称来源> 的具体内容，不引入额外预期。

Done when:
  1. 新建 docs/<NAME>_AUDIT.md，包含 N 个段落（每个对应一个被 audit 的单元）。
  2. 每个段落有 4 个子段：(a) 宣称功能逐字摘录 (b) 实际实现位置 cite 行号 
     (c) 实现状态 ✅/⚠/❌ + 1 句理由 (d) 风险点（最多 5 条）。
  3. 文档末尾一张总览表：被审单元 × 状态计数。
  4. 文档末尾给出"如果只能改 1 处，建议先改哪里"+ 1 句理由。
  5. 最终 summary 确认：仅创建 docs/<NAME>_AUDIT.md，无其他 git diff。

Stop if:
  - 宣称的某项功能在源码中找不到任何相关文件（先列出搜索过的关键字，由用户决定是否真的缺失）。
  - 出现需要"运行才能判断"的 case（如动画行为、异步交互）—— 标 ⚠ 并说明"需要运行验证"，不要凭空给 ✅ 或 ❌。
  - git status 显示除报告之外的任何变化。

Use a token budget of <60-90K> tokens for this goal.

Rationale

• Done when 第 2 项把"输出格式"写死: 4 个子段是 audit 的具体证据靶子。如果让模型自由发挥结构，结果会五花八门
• Stop if "需要运行才能判断" → ⚠: 这是反 false-completion 的关键。强制模型主动承认"我没运行过"，而不是凭代码静态分析硬给结论
• 总览表 + "建议先改哪里": 这两个是 audit 报告的可消费性指标——没有它们，报告变成纯陈列

---

§ Gatekeeper (守门员 — 评估能否合并)

When this fits

• 有 N 个 PR / 分支需要 review
• 评估输出是判断而非代码
• 守门员模式：只 review 不修改

Skeleton

/goal 评估 <分支 / PR list> 是否可以合入 <目标分支>；不 push、不 merge、不修改代码。

Scope: 只读这 N 个 <分支 / PR>；可写文件仅限新建的 REVIEW_*.md。

Constraints:
  - 不执行 git push / merge / rebase。
  - 不修改任何 <被 review 项目的源码文件>。
  - 每个 <分支 / PR> 必须独立 review，不跨引用。
  - 评估必须基于实际 diff + 测试运行结果，不能仅凭 commit message 判断。

Done when:
  1. 为每个 <分支 / PR> 生成独立报告 REVIEW_<name>.md，包含：
     (a) diff 摘要：文件数 / 增删行数；
     (b) 每个修改文件的风险等级（low / medium / high）+ 1 句话理由；
     (c) 测试运行结果：cite 测试文件 + 退出码；
     (d) 缺失项清单（缺文档 / 缺迁移 / 缺 changelog 等），最多 5 条；
     (e) 最终判定：ready / needs-work / blocked，blocker 不超过 3 条。
  2. 每份报告末尾附"如果决定合并，建议的下一步操作"3 条以内。
  3. 最终 summary 是一张表格，对比 N 个 <分支 / PR> 的最终判定。

Stop if:
  - 某 <分支 / PR> diff 超过 2000 行（自动 review 范围之外，转人工）。
  - 某 <分支 / PR> 需要新依赖才能跑测试（可能引入未明示的依赖，需人工确认）。
  - 测试运行需要环境变量 / 凭据未在 .env.example 中声明。
  - <分支 / PR> 在 review 过程中被 force-push（diff 已变化）。

Use a token budget of <70-100K> tokens for this goal.

Rationale

• 每份报告独立: 跨 PR 引用会让 audit 失焦——一份报告对应一个判断
• "基于实际 diff + 测试结果，不能仅凭 commit message": 防止模型偷懒只读 commit message
• 判定限定为 3 个值: ready / needs-work / blocked。开放式判定（"看起来还行"）会让总览表失去意义
• Stop if 第 4 条"force-push": 长跑 review 期间 PR 可能变化，这是 batch / gatekeeper 类型特有的兜底

---

§ Custom (自定义)

如果用户的场景不在以上 6 种：

1. 不要硬塞进某个 skeleton 2. 用 SKILL.md 主体的"5 段式"裸模板 3. 多花一点时间问 Done when 和 Stop if——这两个是定制 goal 最容易出问题的地方 4. 至少 3 项 acceptance + 至少 3 项 stop-if，否则不要 render

通用裸模板（无场景特化）：

/goal <objective>。

Scope: <files / subsystem / area>。

Constraints:
  - <hard rules>
  - <项目类型默认约束>

Done when:
  1. <verifiable artifact>
  2. <verifiable artifact>
  3. <verifiable artifact>

Stop if:
  - <mechanical condition>
  - <mechanical condition>
  - <mechanical condition>

Use a token budget of <N> tokens for this goal.