Goal Instruction Writer

English · 简体中文

Keep a long agent workflow tied to one outcome.

Preview the loop. Keep the next step clear. Finish with evidence.

An MIT-licensed skill for Codex that turns a broad request into a Goal with acceptance criteria, a bounded work loop, checkpoints, and clear stop conditions. Built from multi-day game development and software-delivery workflows.

Watch the 48-second recorded example · English case studies · Real usage and evidence · Where to share a skill

See one task finish

Inspect a recorded CLI task: original request, generated Goal, final code, 19 passing tests, and the actual check record. The maintainer's agent ran one focused suite and one final full suite, then stopped. Try your own task and share a report. We are looking for our first 3–5 independent reports; successful and unsuccessful attempts are welcome.

Start in two minutes

1. Install for Codex.

npx skills add wu736139669/goal-instruction-writer \
  --skill goal-instruction-writer -g -a codex -y

2. Paste this into a Codex chat in a repository.

Use $goal-instruction-writer in Preview mode.
Design a read-only Goal to audit local Markdown links in README.md and report
broken targets with proposed fixes. Limit the eventual audit to two passes.
Show the outcome, acceptance evidence, loop, checkpoint, and stop conditions.
Do not perform the audit or edit files yet.

The preview should make it clear which links are in scope, what evidence proves each finding, what the next step is, and when the audit will stop. Review it, then ask for the final Goal if the proposed loop fits your task.

Try three short examples · Other installation options · Preview, confirm, and execute

If this workflow helps you, star the repository to keep it handy and follow new examples.

What it helps with

Long agent tasks can lose their original scope, repeat broad checks, or leave the next turn without a usable handoff. goal-instruction-writer turns “keep improving until it feels right” into a Goal that can be reviewed, bounded, paused, and finished against observable criteria.

The host agent supplies execution, persistence, tools, and permissions. This skill supplies the instruction contract; it does not start an unattended runtime.

Built from long-running work

A concrete example is a multi-day Factory Town Idle Godot port. Project records cover analysis and architecture on October 13, playable systems on October 14, and a 0.49 local candidate with Mac and Android packages on October 17. The workflow carried forward production, construction, research, cross-town effects, save/load behavior, and a durable next step. Read the case study and delivery timeline.

The maintainer estimates a longest game-development workflow at more than 60 hours. The inspected records establish multi-day work and concrete stage deliveries; they do not measure uninterrupted agent compute time. At the case snapshot, the full recreation Goal was still active. The agent, engine, asset tools, and human decisions do the work; this skill supplies the instruction contract that keeps it connected.

The case library links each outcome to its evidence and provides short contracts to adapt. It identifies private-record audits, public contribution traces, and the limits of each recorded checkpoint.

What changes when you use it

• From a brief to a contract: agree on the observable result, allowed scope, evidence, and stop conditions before a long run starts.
• From repeated activity to a next step: each iteration names one criterion, the expected change, and the next durable cursor.
• From context loss to a checkpoint: the Goal Anchor and decision record let a later turn or another agent recover the intended outcome.
• From repeated release checks to valid evidence: run focused checks while editing, complete required broader checks at the right gate, and reuse results whose relevant inputs still match.
• From endless improvement to delivery: finish when the criteria and deliverable are satisfied; surface blockers and limits explicitly.

Use it for game development, feature delivery, migrations, research, or launch work that needs several iterations. A small one-shot task usually needs only a normal prompt. It does not add execution permissions or keep a host running by itself; continuation, tools, and context recovery come from your agent runtime.

The idea in one picture

flowchart TD
    A["Vague request<br/>Keep improving until it feels right"] --> B{"Preview first?"}
    B -->|Long / costly / uncertain| C["Loop Preview<br/>States · branches · evidence · stops"]
    B -->|Short / reversible| D["Draft Goal"]
    C --> E{"User confirms the loop"}
    E -->|Revise| C
    E -->|Confirm| D
    D --> F["Goal Anchor<br/>Outcome · criteria · scope · authority"]
    F --> G["One iteration<br/>Inspect → Select → Act → Verify"]
    G --> H{"Alignment check"}
    H -->|ON_TARGET| I["Record evidence and cursor"]
    I --> J{"Criteria still open?"}
    J -->|Yes| G
    J -->|No| K["GOAL COMPLETE"]
    H -->|SIDE_QUEST| L["Defer with a revisit condition"]
    L --> G
    H -->|DRIFTED| M["Pause and realign"]
    M --> N["GOAL REALIGNMENT REQUIRED"]
    G --> O{"Blocked / budgeted / owner-stopped?"}
    O -->|Blocked| P["GOAL BLOCKED"]
    O -->|Budget exhausted| Q["GOAL TIMEBOXED"]
    O -->|Cancelled or beyond authority| R["GOAL STOPPED"]

Why this exists

The three-layer contract

Long-running work also gets a Goal Anchor:

Goal Anchor: <one immutable outcome>
Success criteria: C1 <...>; C2 <...>; C3 <...>
Frozen scope: <invariants and forbidden side effects>
Allowed authority: <tools, files, systems, and approvals>
Current phase: <phase or milestone>

For feedback, adoption, pilot, launch, or validation Goals, define what counts as evidence before execution: an entry point, at least N non-author responses, or a named cohort. Add the feedback window and do not count author-only activity unless the Goal explicitly chooses it.

Goals also define a verification strategy: use focused checks during edits, complete required broader checks when the implementation is stable, and tie results to their relevant inputs and artifacts. Rerun checks when changes or new evidence invalidate them; report-only commits can reuse unrelated runtime results. Expensive checks get suitable bounds, and timed-out criteria stay open. Explicit acceptance and release requirements still apply.

Drift control in one picture

flowchart LR
    A["Goal Anchor"] --> B["Iteration record<br/>criterion · expected delta · scope reason"]
    B --> C["Act and verify"]
    C --> D{"Alignment"}
    D -->|ON_TARGET| E["Keep evidence<br/>choose the next cursor"]
    E --> B
    D -->|SIDE_QUEST| F["Defer<br/>add a revisit condition"]
    F --> B
    D -->|DRIFTED| G["Pause<br/>preserve the checkpoint"]
    G --> H["Re-anchor after an owner decision"]
    H --> B

Activity is not progress. An iteration counts only when it advances a named criterion and leaves evidence another agent can inspect.

Install

Recommended: open agent skills CLI

npx skills add wu736139669/goal-instruction-writer \
  --skill goal-instruction-writer -g -a codex -y

The command is verified against this repository and detects one skill: goal-instruction-writer.

OpenAI plugin package

The skills-only plugin ZIP packages the same instruction contract for OpenAI plugin upload. See the build and validation notes and privacy statement. Public directory review and publication are separate from this downloadable package.

Git clone fallback

SKILL_ROOT="${CODEX_HOME:-$HOME/.codex}"
git clone https://github.com/wu736139669/goal-instruction-writer.git \
  "$SKILL_ROOT/skills/goal-instruction-writer"

After installation, invoke it explicitly as $goal-instruction-writer, or let Codex discover it automatically for Goal-shaped requests.

30-second usage

1. Preview a long or uncertain task

Use $goal-instruction-writer in Preview mode.
Do not execute yet. Show the objective, loop steps, success and failure branches,
evidence, drift checks, and terminal conditions.

The preview should expose the loop before any external side effect:

Inspect baseline → choose one criterion → make one bounded change
→ verify evidence → classify ON_TARGET / SIDE_QUEST / DRIFTED
→ continue, defer, block, or realign

2. Confirm the loop

The loop is confirmed. Keep the current scope and terminal rules, then generate
the final Goal instruction.

3. Use the Goal during execution

Before each iteration, state the target criterion, expected evidence, and scope reason.
After each iteration, state the actual evidence, alignment label, remaining gap,
and next cursor.
For an external wait, save the pending criterion, next check time/event, and deadline.
Before the trigger, continue independent work or yield without another lookup.
On a later invocation, read the checkpoint and check limits before querying.
Waiting and due observations of "still pending" are not failed actionable attempts.
If two equivalent actionable attempts add neither acceptance progress nor new
relevant evidence, stop with:
GOAL REALIGNMENT REQUIRED.

For a short, reversible task, skip Preview and ask directly:

Use $goal-instruction-writer to draft the final Goal for this task.

Modes

A small before/after

Weak request

Fix the importer and keep trying until it works.

Reviewable Goal

Objective: make fixtures/quoted_multiline.csv load into the existing record model
without truncation or row-count drift.

Loop: inspect the current failure → choose one parsing hypothesis → make one
focused change → run the focused test → record the diff and result → choose the
next unmet criterion.

Drift control: bind every iteration to one criterion, expected evidence, and
scope reason; put unrelated cleanup in the deferred list.

Termination: emit GOAL COMPLETE when all criteria pass; emit
GOAL BLOCKED: <reason> after two equivalent failures; emit
GOAL TIMEBOXED: <state> after the four-iteration limit.

Try it on a game-development task

Use $goal-instruction-writer to preview a Goal for a playable Godot game slice.
First show the outcome, scope, one iteration, evidence, and stop conditions.
Include a playable core loop, one coherent progression path, runtime playtest
evidence, save/load behavior, and a reproducible build handoff.
Keep the game concept and platform fixed. Park unrelated features.
Use focused checks during edits and the required broader checks at delivery.
Preserve the Goal Anchor and the next cursor across turns.
Do not execute the development task until I confirm the loop and ask you to run it.

After confirming the preview, ask for the ready-to-paste Goal, then run it in your agent's supported long-running workflow. A Goal is an instruction contract; the exact start, resume, and status commands depend on that host.

Runtime boundary

The skill designs and audits the instruction contract. Runtime access, permissions, tool availability, and approval for external side effects remain controlled by the host agent and the user.

For external gates, preserve the open criterion, evidence, next check time/event, and deadline or unblock condition. Continue independent work or yield until the trigger; waiting does not consume the actionable no-progress allowance. Actual queries and elapsed time still count toward host limits. See the scheduled-wait rules.

Active work and waiting

The skill supports continuation after time or event triggers through its Goal instructions. A single Goal can alternate between active iterations and waiting. Its outcome and acceptance criteria stay the same; the next action depends on what can usefully advance now.

This makes waiting a branch of the same Goal. A time or relevant notification can permit another check. Waiting and a due observation of "still pending" do not count as failed actionable attempts; actual queries, deadlines, and host budgets still apply.

The skill defines what to save, when another check is allowed, and how to resume. A host timer, relevant event, or authorized message can provide the next invocation with access to the saved checkpoint. The host supplies persistence and invocation, including any automatic delivery at the requested time. When automatic wake-up is unavailable, a later authorized invocation can resume the same workflow from its checkpoint. The documented waiting branch has not yet been validated by a live wait/resume test. See the waiting rules and English example.

Resources

• Skill entrypoint
• Three short prompts to try
• Goal contract and ready-to-paste skeleton
• Loop preview format and flow diagram
• Drift detection and recovery
• Coding, research, and open-source examples
• Launch kit with ready-to-post copy
• Independent Goal evaluation
• Real usage, recorded examples, and evidence limits
• Factory Town Idle: a multi-day Goal case study
• Skill distribution and submission guide
• Editable video source and provenance
• Contributing guide
• GitHub Discussions
• Chinese documentation

Contributing

Have a real use case, a confusing preview, or a better drift rule? Open a Discussion for a workflow question, or open an issue for a focused change. Small pull requests are welcome when they preserve the three-layer contract and include a clear reason or example.

Before opening a pull request, run:

npx --yes skills add . --list

The same packaging check runs automatically in GitHub Actions.

License

MIT. See LICENSE.

Goal Instruction Writer

Turn a vague request into a ready-to-run Goal instruction that an agent can execute without guessing what success, progress, or stopping means. Preserve the user's intent, language, authority boundaries, and requested scope. This skill designs and audits the instruction contract; runtime access, permissions, and external approvals still come from the host agent and user. Describe the checks while writing a Goal; execute the underlying task only when the user has also requested execution.

Read references/goal-contract.md when drafting or auditing a Goal. Read references/examples.md only when a worked example would clarify the requested task. For work that spans multiple phases, artifacts, or more than a few iterations, also read references/drift-control.md. For preview-first workflows, read references/loop-preview.md.

Choose the mode

• Draft: build a Goal from a rough request.
• Refine: preserve an existing Goal while closing missing objective, evidence, loop, or termination fields.
• Audit: identify ambiguity, unbounded repetition, unverifiable criteria, and unsafe or unauthorized transitions; propose the smallest fixes.
• Convert: turn a checklist, ticket, or project brief into a Goal without expanding its scope.
• Preview: show the concrete loop, branches, drift gates, and stop conditions before writing the final Goal. Do not emit an executable Goal or perform external work in this mode.

If the mode is not stated, infer it from the input. Ask only questions whose answers would change the objective, authority, acceptance evidence, or legal terminal state. Otherwise state assumptions and continue.

Preview before drafting

Use preview-first when the user asks to “先看循环”, “preview”, “先设计流程”, or similar. Also prefer it for multi-stage, costly, irreversible, or materially uncertain work. For a short, reversible task, a direct draft is enough.

The preview is a design checkpoint, not an approval to execute:

1. State the provisional outcome, baseline, and assumptions.
2. Show the loop as concrete state transitions, including the first work unit, success and failure branches, progress evidence, drift checks, phase gates, and legal stop states. Distinguish iteration checks from broader phase or delivery checks, including evidence reuse and bounds for expensive checks.
3. List the decisions that could change the loop or its scope. For feedback, adoption, pilot, launch, or validation work, include the evidence threshold, what counts, and the feedback window.
4. End with a clear handoff: wait for the user to confirm or revise the loop before generating the final Goal.

When the user confirms, carry the accepted preview into the final Goal without quietly changing its loop, scope, or terminal rules. If the user revises it, regenerate the preview or record the changed decision first. A preview response must not claim that the Goal is complete and must not perform external side effects merely because a loop was described.

Build the three-layer contract

1. Goal: define the outcome

Write one sentence with an observable end state. It should say what artifact, behavior, decision, or verified change will exist when the work is complete. Then make the contract concrete:

• Baseline: what exists now and which revision, source, or facts are authoritative.
• Scope: what may change and what is frozen.
• Acceptance criteria: observable checks tied to evidence, not activities such as “keep working” or “try harder.”
• Dependencies and authority: tools, access, owner decisions, and external gates the agent may or may not cross.
• Deliverable: the files, decision, report, or message that will be handed back.

For Goals about feedback, adoption, pilots, launches, or validation, define a feedback evidence threshold before drafting: what counts as feedback, whether an entry point is enough or at least N non-author responses are required, and the timebox or attempt window. Do not count author-only activity unless the user explicitly chooses that threshold.

Prefer one load-bearing outcome per Goal. Split unrelated outcomes into separate Goals. Replace vague verbs such as “improve,” “handle,” or “finish” with a measurable result.

Prevent drift in long-running work

For a long or multi-stage Goal, freeze a compact Goal Anchor before the first iteration: the one-sentence outcome, criterion IDs, frozen scope, and current phase. Treat it as an invariant. A new discovery may change the plan, but it must not silently change the outcome, acceptance criteria, or authority. An explicit owner decision creates a new Goal version or scope-change record.

At every iteration, record three links before acting:

1. Target criterion: which acceptance criterion this work advances.
2. Expected delta: what observable evidence should change if it works.
3. Scope reason: why this action is inside the frozen boundary now.

After verification, classify the result as:

• ON_TARGET: the named criterion moved or new relevant evidence supports a justified next step.
• SIDE_QUEST: useful but not required for this Goal; park it in a deferred list instead of expanding the loop.
• DRIFTED: the action changed the goal or scope without authorization, the next step cannot be justified from the Anchor, or the no-progress threshold is reached; stop and realign.

Run a phase gate every 3–5 iterations by default, at each milestone, and before an irreversible or high-cost action. Re-read the Anchor, compare the current state with the baseline, mark criteria open or verified, review deferred side quests, and choose one justified next action. Never rewrite criteria to make completed work appear on target.

2. Loop: define how progress is made

Use a bounded iteration with a visible progress signal:

1. Inspect the current state and the last durable cursor.
2. Select the smallest next work unit, name its target criterion, expected delta, and scope reason.
3. Act within the allowed scope and authority.
4. Verify the result against the relevant criterion using the verification strategy below; capture the evidence.
5. Classify the result as ON_TARGET, SIDE_QUEST, or DRIFTED and apply the corresponding drift rule.
6. Record the delta, remaining gap, decision, and next cursor before another iteration.

State the iteration limit that fits the task: a timebox, tool or token budget, maximum attempts, or a finite work-unit list. Add a no-op rule: do not repeat the same action without new information; after a repeated failure, change the hypothesis or stop with the blocker. The loop must be able to explain why the next iteration is different from the previous one.

For external dependencies, record the unmet criterion, next check time or relevant notification, and deadline. Before that trigger, continue independent work or yield with the checkpoint preserved. Waiting and a due check that confirms the dependency is still pending do not count as failed actionable attempts toward the default two-equivalent-no-progress threshold. Actual tool calls and elapsed time still count against host limits. See scheduled waits for polling, resumption, and deadline rules.

Verification strategy

Include a short verification strategy in the Goal. Preserve explicit user and repository acceptance requirements while controlling when checks run:

• Iteration checks: choose the smallest checks sufficient for the affected behavior. Broaden for change impact, new failures, unresolved uncertainty, or a required gate.
• Phase and delivery checks: once the relevant implementation is stable, complete the remaining required regression, build, integration, and artifact checks. A phase gate reviews current evidence; it does not automatically repeat the entire validation and delivery pipeline.
• Evidence reuse: tie results to the checked source or artifact, relevant inputs, dependencies, and environment. Carry forward results while those conditions remain valid. Documentation or receipt changes do not invalidate unrelated runtime checks. Distinguish reused evidence from newly run checks.
• Rerun reason: before repeating a check, name the change or new evidence that invalidates its result and select the affected checks. A source or artifact change invalidates dependent evidence, including consumer checks when the consumed artifact changes.
• Cost and completion: give expensive checks suitable command timeouts or attempt bounds. A timeout leaves its criterion unverified; report the gap. Finish when all criteria have valid evidence and delivery is complete; further checking needs a concrete unresolved concern or invalidated result.

3. Termination: define legal endings

Make the terminal states explicit and mutually understandable:

• Complete: every acceptance criterion is verified and the deliverable is available.
• Blocked: a named, verifiable dependency, missing authority, or owner decision prevents the next meaningful action and cannot be resolved without new input or permission; report the attempts made, the dependency, and the exact unblock condition.
• Paused: the owner explicitly asks to pause; preserve the cursor and do not resume without authorization.
• Timeboxed/Budgeted: the limit is reached before completion; report the verified progress, remaining gap, and the safest next action.
• Stopped: the owner cancels the work or an action would exceed the granted authority; do not silently continue.
• Realignment required: a drift check fails; stop the current loop, preserve the checkpoint, and resume only after the next action is re-anchored. Use GOAL REALIGNMENT REQUIRED when a local terminal label is needed.

Blocked is a claim about the world, not a way to end a hard turn. It qualifies only when all three hold: the dependency is named and verifiable, the agent cannot resolve it without new input or permission, and the report states what would unblock it. Difficulty, slowness, uncertainty, an ambiguous requirement, a failure a different approach could resolve, and a preference the agent could ask about are not blockers. Change approach, ask one scoped question, or realign instead. If another criterion is still actionable, keep working it and record the blocked criterion separately. A blocked claim that turns out to be false is a defect in the report, not a neutral stop.

Do not use “continue until satisfied,” “try indefinitely,” or a success claim based only on effort. If the task has a local convention for terminal strings, preserve it; otherwise give each state a short, exact label and require the final response to include it. A goal or acceptance criterion cannot be changed just because the current work became difficult or interesting.

Produce the answer

Return the result in the user's language. Unless they request another format, use this order:

1. Design notes: one short paragraph explaining the objective, loop, and termination and drift-control choices; list assumptions or high-value open questions.
2. Loop preview: in Preview mode, show the state transitions, branches, evidence, drift gates, terminal states, and unresolved decisions; stop there and wait for confirmation.
3. Ready-to-paste Goal: in Draft, Refine, or Convert mode, include the full instruction in a fenced block with Objective, Goal anchor, Baseline and scope, Acceptance criteria, Feedback evidence when applicable, Verification strategy, Execution loop, Drift control, Limits and no-op rule, Termination, and Reporting sections.
4. Audit notes: if refining or auditing, name each remaining ambiguity and the smallest change that resolves it.

The ready-to-paste block must be executable as an instruction, not a discussion of how one might write an instruction. Keep acceptance checks and terminal states concrete enough that a later reviewer can decide them from evidence.