Goal Prompt Crafter
Refine vague requests into
measurable completion condition statements that autonomous execution agents or evaluators can use to determine achievement. The universal core is
completion condition design. The same condition statement can be reused as input for environments with
commands (such as Claude Code), or as stop conditions, Definitions of Done, or review criteria for autonomous loops in environments without such commands. Target examples: Claude Code, Codex CLI, Stop hook, external orchestrators.
When to Use
- When users want to create commands, done criteria, Definitions of Done, or stop conditions
- When users want to safely define tasks that should run autonomously until completion
- When users want to convert task descriptions into binary-verifiable completion conditions (such as passing tests, zero lint errors, successful builds, file generation, or issue resolution)
- When designing stop conditions for autonomous loops (loop/cron/Stop hook/external orchestrator)
Not for
- One-off tasks that finish in a single turn (no need to create condition statements)
- Refining requirements specifications themselves (this falls under requirement-focused skills like prompt-optimizer)
Target Adapters (3 Types of Output Destinations)
The same completion condition statement can be adapted based on the entity responsible for determining achievement. By default, condition statements are constructed assuming the most conservative output-only evaluator (if it works for this type, it will work for the other two).
1. Output-only evaluator — Evaluator only observes agent output
Claude Code's
is a representative example. The evaluator (a lightweight model equivalent to Haiku by default) only observes the agent's
output text and does not execute shell commands itself.
- Set with
/goal <condition statement>
- Condition statements have a maximum length of 4000 characters. Use alone to display status, to remove the goal, and re-specify to replace it
- Verification results must appear in the output to be judged. If setting a condition like "tests pass", the condition statement must explicitly require the agent to execute the verification command and output the command, exit code, and summary
- Reference: https://code.claude.com/docs/en/goal.md
2. Tool-capable evaluator / orchestrator — Can directly inspect shell/CI/workspace
External orchestrators or autonomous loops where the evaluator itself can execute commands. The
actual execution results of verification commands can be used for judgment (no requirement to transcribe them to output). The statement can be reused as input for environments with
commands, or as stop conditions, Definitions of Done, or review criteria for autonomous loops in environments without such commands.
3. Human-reviewed loop — Humans confirm achievement
Condition statements are used as review criteria. If humans can observe the results, output-only constraints can be relaxed, but binary-verifiability must always be maintained.
Workflow
Step 1: Input Validation (5-Point Check)
Check the user's request against the following points, and only ask for missing items in Step 2. If all items are complete, proceed directly to Step 3.
- Is it a single measurable goal? — Can it be binary-verified, such as "tests pass" or "zero lint errors"? If multiple goals are mixed, split them or explicitly combine with "and"
- Is the verification method specific? — Which command's exit code/output indicates achievement?
- Are there scope constraints? — Files that cannot be modified, behaviors that cannot be changed
- Is there a stop limit? — Maximum number of turns or time limit (to prevent infinite loops)
- Is it observable by the evaluator? — Assuming the default output-only evaluator, does it include conditions that don't appear in output (e.g., human approval, external system status)? This constraint can only be relaxed if using a tool-capable/human-reviewed adapter (see Target Adapters)
Step 2: Gathering Missing Information
Only ask about missing dimensions. Don't re-ask if all items are complete.
- Use the question UI if available (e.g., Claude Code's AskUserQuestion). Fall back to plain text questions in environments without it
- In contexts where the user is absent/unresponsive (e.g., recursive use during autonomous execution), fill in missing dimensions with conservative assumptions and explicitly state these assumptions alongside the condition statement
Dimensions to ask and common options:
| Dimension | Example Question | Common Answers |
|---|
| Verification Method | What needs to be executed to confirm achievement? | Test command exits with 0 / 0 lint errors / Successful build / Existence of specific file |
| Scope Constraints | What should not be modified? | Do not rewrite existing tests / Public API unchanged / Specific directory immutable |
| Stop Limit | After how many turns/minutes should it stop? | Equivalent to |
| Partial Achievement | Are all items required, or can some be excluded? | Exclude flaky tests / Allow skipping known failures |
Step 3: Assemble Deliverables (Completion Condition + Execution Brief)
Deliverables consist of two parts. The completion condition statement is the measurable condition observed by the evaluator, and the execution brief is the work instruction passed to the autonomous loop (including sub-agent delegation guidelines).
3-1: Completion Condition Statement (Part passed to )
[Verifiable Goal: Execute <verification command> to achieve <expected result>]
[Invariant Constraint: Do not modify <items that cannot be touched>]
[Upper Limit: Stop after <N> turns if not achieved]
- For output-only evaluators (default), phrase the verification command to require the agent to execute and output it (so the evaluator can judge from the output). For tool-capable adapters, this transcription is not required since the evaluator can directly judge execution results
- Keep it within the 4000-character limit. Move lengthy background explanations to the execution brief instead of including them in the condition statement
- Sub-agent delegation is a "method of work" and should not be included in the condition statement (the evaluator observes achievement status, not the means used)
3-2: Execution Brief (Work prompt passed to autonomous loop)
When running autonomous multi-turn tasks naively, the main context fills up with investigation and verification output, leading to performance degradation in later loops. The brief must include sub-agent delegation guidelines:
## Task
<What to do (place background and design instructions here; do not include in condition statement)>
## Sub-agent Delegation Guidelines (Required Section)
- Delegate broad research, grep operations, and multi-file reading to research sub-agents, and only receive conclusions (do not accumulate file dumps in the main context)
- Fan out independent parallel work to multiple sub-agents
- Delegate verification tasks like test execution and reviews to sub-agents, and only receive summaries
- The main loop focuses solely on "integrating delegated conclusions to decide the next step"
## Scope Constraints
<Items that cannot be modified, behaviors that cannot be changed>
- Do not delete or omit delegation guidelines (without them, execution regresses to naive single-context operation)
- Adjust the terminology for delegate targets to match the environment (subagent/task tool/worker agent/parallel agent/reviewer agent, etc.)
- Only if the target agent lacks delegation functionality, explicitly state this and replace the guidelines with: "Avoid long file dumps; compress research results into short summaries before proceeding in the main loop"
Step 4: Self-Check (Anti-pattern Matching)
Compare the generated condition statement against the following; if any apply, return to Step 3 to revise:
- Ambiguous terms: "improve" / "clean up" — Cannot be binary-verified
- Implicit multiple goals: "Fix tests and organize documentation" — Combine with "and" or split into separate goals
- Unobservable conditions: "When review is approved" / "When deployment stabilizes" — Evaluator can only see agent output
- Missing verification command: Only writing "tests pass" without requiring execution
- Self-referential loophole: "Report when achieved" — Conditions that count achievement solely based on reports are invalid
- No upper limit: No safeguard against infinite loops for unachievable goals
Step 5: Output (Save as MD File + Message Prompt)
In environments where writing to the file system is possible,
always save deliverables as an MD file (do not stop at just message output). Condition statements and briefs tend to be long, and volatile messages alone are insufficient for later reuse like pasting into
or using in other sessions. Since target development agents (Claude Code/Codex CLI, etc.) are all file-capable, saving as a file is the default.
Only in environments where writing is not possible, output the same structure (
/
/
) in a message, formatted so the user can save it themselves.
- Save as MD file (required in writable environments):
- Save to the user-specified path. If no path is specified, use in the working directory (slug generated from the goal). Can also use scratchpad if available
- File structure: (Step 3-1 statement) → (Step 3-2) → if any were made in Step 2
- After saving, report the file path to the user
- Also present in message:
- Claude Code: Show
/goal <condition statement>
- Other agents: Return the condition statement as "Completion Condition (Definition of Done)", along with a note on its use as stop criteria for autonomous loops, task definition, or review standards
- If assumptions were made in Step 2, explicitly list them immediately after the condition statement
Good / Bad Examples
The following "good/bad" examples compare
completion condition statements passed to
. Actual deliverables include the execution brief (with sub-agent delegation guidelines) and are saved as MD files.
Sample Complete Deliverable (MD File to Save)
markdown
# Completion Condition
Execute `uv run pytest tests/unit` and ensure all tests pass, and `uv run ruff check src/` returns 0 errors. Do not modify existing tests under `tests/`. Stop after 15 turns if not achieved.
# Execution Brief
## Task
Fix failing unit tests. If caused by implementation bugs, correct the production code.
## Sub-agent Delegation Guidelines
- Delegate investigation of failure causes (grep relevant modules, read related files) to research sub-agents and only receive conclusions
- Delegate post-fix verification (pytest/ruff execution) to test execution sub-agents and receive summaries
- The main loop focuses solely on integrating delegation results to determine the next fix target
## Scope Constraints
- Do not rewrite existing tests under `tests/`
- Do not change public import paths
Test Fix Scenario
# Good
/goal Execute `uv run pytest tests/unit` and ensure all tests pass, and `uv run ruff check src/` returns 0 errors. Do not modify existing tests under `tests/`. Stop after 15 turns if not achieved.
# Bad
/goal Fix the tests nicely # Unmeasurable, no verification command, no upper limit
Refactoring Scenario
# Good
/goal Split `src/big_module.py` into 3 or more modules, ensure each file has ≤300 lines, and `uv run pytest` maintains the same number of passes as before splitting. Do not change public import paths. Stop after 20 turns.
# Bad
/goal Cleanly split the code # "Cleanly" is unjudgeable
Backlog Resolution Scenario
# Good
/goal Ensure the number of open issues labeled "quick-fix" (from `gh issue list --label quick-fix --state open`) is 0. For each issue, create a fix commit that includes the issue number in the commit message. Do not push to main. Stop after 30 turns or when all issues have been addressed.
# Bad
/goal Fix all issues # No definition of "fix", no safety constraints
Constraints & Notes
- specifications (version, character limit, evaluation model) may change due to updates to Claude Code. If behavior differs from this description, prioritize the official documentation (URL in Target Adapters). Constraints like the 4000-character limit and output-only requirements are specific to the output-only evaluator adapter and do not apply to tool-capable/human-reviewed adapters
- Condition statements are for achievement judgment only. Work procedures, background, design instructions, and sub-agent delegation guidelines belong in the execution brief and should not be mixed into the condition statement
- In writable environments, always save deliverables (completion condition + execution brief) as an MD file and report the path. In non-writable environments, output the same structure in a message
- For goals involving destructive operations (push/deploy/delete), always include safety boundaries in the invariant constraints (e.g., "Do not push to main")