Goal Instruction Writer

English · 简体中文

Keep a long agent workflow tied to one outcome.

Preview the loop. Make progress inspectable. Finish with evidence.

Watch the full demo · Real usage and evidence · Where to share a skill

AI agents rarely fail because they did too little. More often, they work for a long time and quietly move away from the original outcome. goal-instruction-writer turns “keep improving until it feels right” into a Goal instruction that can be reviewed, bounded, paused, and finished cleanly.

It gives every long-running task an observable outcome, a bounded loop, evidence for meaningful progress, drift gates, and explicit terminal states.

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.

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 requestKeep improving until it feels right"] --> B{"Preview first?"}
    B -->|Long / costly / uncertain| C["Loop PreviewStates · branches · evidence · stops"]
    B -->|Short / reversible| D["Draft Goal"]
    C --> E{"User confirms the loop"}
    E -->|Revise| C
    E -->|Confirm| D
    D --> F["Goal AnchorOutcome · criteria · scope · authority"]
    F --> G["One iterationInspect → 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 PAUSED: 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: 
Success criteria: C1 ; C2 ; C3 
Frozen scope: 
Allowed authority: 
Current phase: 

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 recordcriterion · expected delta · scope reason"]
    B --> C["Act and verify"]
    C --> D{"Alignment"}
    D -->|ON_TARGET| E["Keep evidencechoose the next cursor"]
    E --> B
    D -->|SIDE_QUEST| F["Deferadd a revisit condition"]
    F --> B
    D -->|DRIFTED| G["Pausepreserve 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.

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.
If two equivalent iterations produce no new progress, stop with:
GOAL PAUSED: 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:  after two equivalent failures; emit
GOAL TIMEBOXED:  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 evidence and stop with the exact unblock needed. Waiting for a maintainer, owner, or missing dataset is not a reason to invent more work.

Resources

• Skill entrypoint
• 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.