goal-crafter

Goal Crafter

Turn a vague task into a verifiable goal that an AI agent can run unattended.

Leading principle: A goal without a checkable completion criterion is just a wish. The agent must be able to answer "Am I done?" without asking a human.

Invocation modes

Choose the mode before following the process:

• Standalone mode: the user brings a vague task or directly asks for a goal. Run Phase 1 and clarify the task one question at a time.
• Compiled-handoff mode: approved planning evidence already supplies the answers. Do not interview the user again. Apply only this skill's verifiability rules and target-harness formatting. The evidence may come from a conversation, spec, issue, document, or another skill.

In compiled-handoff mode, if a required product decision or completion condition is genuinely absent from the sources, report that the source is not agent-ready and name the missing evidence. Do not reopen the planning interview from inside goal compilation.

Process

Phase 1 — Clarify the task

Run this phase only in standalone mode. In compiled-handoff mode, extract the five answers from the upstream evidence without asking questions.

Ask the user, one question at a time, in this shape (standalone interview only — keep compiled-handoff mode emoji-free):

❓ **QN** - **<short title>**
<body>

💡 <your recommended answer, when you have one>

Walk these five in order:

1. What exactly should the agent do? Get the task in one sentence. If it's vague ("优化代码", "改进 UI"), push for specifics.

2. Where does it run? Which project / repo / workspace? Is there a specific branch or file area?

3. What does DONE look like? This is the most important question. Push for observable, machine-checkable conditions:

   ❌ Vague (bad)	✅ Verifiable (good)
   "代码质量提高"	"tsc --noEmit 0 errors + eslint 0 warnings"
   "UI 更好看"	"页面在 375px / 768px / 1440px 三个断点下视觉一致，无溢出"
   "修复所有 bug"	"npm test 全部通过，且 git diff 只包含修复相关改动"
   "写好文档"	"README.md 包含安装/使用/API 三个章节，每个章节有代码示例"
   "性能优化"	"Lighthouse Performance 分数 ≥ 90，LCP < 2.5s"

4. Any constraints? Don't touch certain files? Must use specific tools? Budget limit? Time limit?

5. What agent / harness? Claude Code (/goal), Codex (Automations), Pi, or generic?

Phase 1 complete when you have answers to all 5 questions. If the user can't answer #3, help them brainstorm verifiable conditions — this is the most common failure point.

Phase 2 — Draft the goal

Write the goal in the target agent's format. Follow these rules:

The three shapes below are the formats this skill deliberately maintains for the harnesses it is most often pointed at. They are a snapshot, not a standard: when the target harness documents a different shape, follow the harness and treat the block here as the fallback. Any harness not listed uses the generic block.

For Claude Code /goal:

Goal: [one-line task description]

Completion criteria:
- [ ] [checkable condition 1]
- [ ] [checkable condition 2]
- [ ] [checkable condition 3]

Constraints:
- [file/area restrictions]
- [tool/approach restrictions]
- [budget/time limits]

For Codex Automations:

For Pi / generic:

Phase 3 — Verify the goal

Before presenting the final goal, self-check:

• Can an agent read the completion criteria and unambiguously decide "done" vs "not done"?
• Is every criterion observable without human judgment? (No "looks good", "feels right")
• Are the constraints specific enough to prevent scope creep?
• Is the context sufficient for the agent to start working without asking "where" or "how"?

If any check fails in standalone mode, go back to Phase 1 and ask the user to clarify that specific point. In compiled-handoff mode, report the source as not agent-ready and name the missing evidence instead of asking a new planning question.

Phase 4 — Deliver

In standalone mode, present the final goal and end with:

🎯 把这个 goal 粘贴到 [agent 名称] 里，它就会自己跑到完成。如果中途卡住，告诉我哪条完成标准没达到，我帮你调。

In compiled-handoff mode, the upstream skill owns the delivery wrapper. Return the goal in the requested harness format without adding this standalone closing line.

Examples

下面两个示例里的仓库名、目录结构和文件路径都是占位符，不代表任何真实项目的约定。真正产出的 goal 必须写目标仓库当前的真实路径，不要照抄这里的形状。

Example 1: Code review automation

User: "帮我写个 goal，自动审查 PR"

Clarified:

• Task: 审查当前分支相对于 main 的所有改动
• Where: 当前工作仓库
• Done: 输出一份审查报告，列出所有 P0/P1 问题，每个问题标注文件和行号
• Constraints: 只读，不改文件
• Agent: Claude Code

Output:

Example 2: UI redesign

User: "帮我写个 goal，重做这个页面"

Clarified:

• Task: 用 shadcn 组件库重做目标页面
• Done: 页面在 3 个断点下视觉一致，所有交互有 hover/focus/active 状态，通过 tsc 类型检查
• Constraints: 不改变现有 API 接口，使用项目已有的 Tailwind 配置
• Agent: Claude Code

Output:

Special Rules

• Never skip Phase 1 question #3 in standalone mode. If the user can't define "done", the goal will fail. Help them brainstorm.
• Never re-interview in compiled-handoff mode. Approved evidence already owns clarification and product decisions; missing evidence means the source is not agent-ready.
• One verifiable condition per checkbox. Don't combine multiple conditions into one line.
• Constraints are your friend. They prevent the agent from "optimizing" unrelated files or introducing breaking changes.
• If the task is too large for one goal, suggest breaking it into 2-3 smaller goals with clear handoffs.
• For research/analysis goals (no code changes), the completion criterion is "output a report with specific sections".