# Writing Goals

> Use when writing a bounded Codex completion contract, running unattended work, or decomposing a large objective into verifiable sub-goals.

- Skill: `iliaim/writing-goals` (Agent Skill, multi-file: 12 files)
- Install (CLI): `npx skillmds@latest add iliaim/writing-goals`
- Raw SKILL.md: https://api.skillmd.com/api/skills/iliaim/writing-goals/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: iliaim (https://skillmd.com/u/iliaim)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/iliaim/writing-goals

---


# Writing goals for Codex

Follow `shared/method.md` completely. It is the canonical method. Load its linked shared
references as the task requires; this adapter adds only Codex-native integration instructions.

## Invoke and trust

- Invoke as `$writing-goals`, select it from `/skills`, or allow its description to trigger it.
- Use the installed `assets/codex-continuation.sh` as the foreground host-native continuation
  non-interactive entrypoint for the sequential workflow in `shared/workflow.md`. It invokes
  `codex exec resume` only from protected authority and must run outside the maker sandbox.
- A trusted host, never the resumed child, may use the separately pinned
  `assets/core-state-advance.sh` to install a freshly checked, monotonic protected cursor.
- Skill frontmatter contains only `name` and `description`; UI and invocation metadata belong in
  `agents/openai.yaml`.
- Project hooks live in `.codex/hooks.json` or `.codex/config.toml`. Non-managed command hooks
  must be reviewed and trusted; `/hooks` shows their sources and trust state. A changed hook hash
  requires review again.
- Stop and PreToolUse hooks are cooperative backstops, not a security boundary or containment.
  Run unattended work in an OS-level sandbox (for example, a `sandbox-exec` profile where
  available) with only the intended writable source paths.
- Before presenting a non-trivial plan, invoke the separate read-only challenger and validate its
  exact-plan receipt with `assets/validate-review-packet.sh`; do not present a review packet while
  the challenge is missing, stale, non-independent, or red.

## Current Codex platform facts

- Stop hooks receive JSON on stdin and can run deterministic verification. A clean exit 0 with no
  block allows the turn to stop; the repository adapter is `assets/gate.codex.sh`.
- This adapter validates only `Bash` (including the documented unified execution payload) and
  `apply_patch`; do not infer coverage for any other tool or payload shape. A supported call can
  be denied using `permissionDecision:"deny"` or exit 2 with the reason on stderr.

## Native Codex goal

For a run that warrants a native Codex goal, bind one native Codex goal to the complete objective/run
only when `/goal` is available in the active Codex surface. Start it with `/goal <objective>`; use
`/goal` to inspect it and the goal progress controls above the composer to pause or resume the goal,
edit the goal text, or clear the goal. If `/goal` is unavailable, use `$writing-goals` and the
repository's custom continuation workflow instead. Native goal tracking is convenience state; the
protected host-owned workflow remains lifecycle authority for full-tier work.

Put a concise, user-legible completion contract in the native `objective` field:

If asked to set the goal yourself, inspect the current session, repository guidance, working tree,
tests, and exact verification surface first. If a material outcome, proof, preservation constraint,
boundary, iteration rule, or blocked stop remains ambiguous, restate the proposed understanding in
plain English and obtain the user's approval before setting the goal. Ask only for the unresolved
decision. When those material facts are clear from the request and investigation, do not ask again:
write the contract directly.

When monitoring a running goal, make each status check one concise sentence stating the current
activity, whether the run remains on track, and the next gate.

Use this shorthand only to compose the contract; retain every section below rather than merging
them into one sentence:

`/goal <desired end state> verified by <specific evidence> while preserving <constraints>. Use <allowed boundaries>. Between iterations, <evidence-led next action>. If blocked, <blocked report and unlock>.`

```text
Objective: <one complete parent outcome>
Read first: <exact repository files, issue, specification, or decision record>

## Outcome
Given: <material starting condition>
When: <completed user action or state transition>
Then: <one measurable end state; not “improve”, “better”, or “works correctly”>
Positive scenario: <representative successful path and expected result>
Negative scenario: <invalid, rejected, or failure path and safe expected result>
Edge case: <boundary, empty, extreme, compatibility, or concurrent case and expected result; `not applicable` needs an evidence-based reason>

## Verification surface
Evidence: <exact test, benchmark, report, artifact, command output, or source material>
Given: <the evidence surface proves this outcome rather than a proxy>
When: <a fresh check observes the result>
Then: Automated proof: `<exact command>` exits 0 and reports <pass signal>; Manual proof: <specific expected observation>, when automation cannot establish the criterion.
Positive scenario: <normal evidence input and exact passing signal>
Negative scenario: <broken, invalid, or missing condition and exact failing/safe signal>
Edge case: <threshold, partial-evidence, or flaky-risk case and proof handling; `not applicable` needs an evidence-based reason>

## Constraints
Constraints: <what must not regress, including unrelated refactors, dependencies, interfaces, or data>
Preserve: <each behavior, compatibility promise, security property, or regression check>
Given: <the named preservation requirements are the baseline>
When: <Codex performs authorized work>
Then: <each requirement remains true, with its material evidence>
Positive scenario: <expected preservation observation after the intended change>
Negative scenario: <prohibited regression and the detecting check/observation>
Edge case: <version, migration, permission, performance, or compatibility boundary and preserved result; `not applicable` needs an evidence-based reason>

## Boundaries
Allowed: <included paths, tools, data, repositories, and external resources; repository-local is the default>
Forbidden: <excluded paths, external systems, credentials, data, repositories, or actions>
Given: <the allowed resources are sufficient for the approved goal>
When: <Codex investigates, changes, or verifies>
Then: <only Allowed resources are used; request approval before widening the boundary>
Positive scenario: <normal in-bound operation and allowed resource>
Negative scenario: <prohibited resource/action and required refusal or escalation>
Edge case: <generated file, transitive tool, credential-adjacent input, or shared resource handling; `not applicable` needs an evidence-based reason>

## Iteration policy
Given: <an attempt has produced evidence or a failed check>
When: <selecting the next action>
Then: <record hypothesis/action, change, and result; choose the next lowest-risk, highest-evidence action; never retry blindly>
Positive scenario: <new evidence identifies a safe next experiment>
Negative scenario: <same failure without a new diagnosis: stop/reassess, do not retry>
Edge case: <conflicting, incomplete, noisy, or non-reproducible evidence and disambiguating action; `not applicable` needs an evidence-based reason>

## Blocked stop condition
Given: <no defensible path remains under the approved evidence, scope, resources, or enforced limit>
When: <the blocked condition is established>
Then: <do not claim success; report attempted paths, evidence gathered, blocker, and the specific input, access, or decision that unlocks progress>
Positive scenario: <an unavailable required surface remains after all approved in-bound paths are exhausted, so provide the complete blocked handoff>
Negative scenario: <a defensible next investigation remains, so continue rather than declare the goal blocked>
Edge case: <budget limit, partial proof, unavailable verifier, or reversible workaround and correct incomplete/escalation result; `not applicable` needs an evidence-based reason>

Document: <focused documentation to update, or not applicable with a reason>
Details (optional): `<stable workspace-relative path to the persisted contract or frozen plan>`
Checkpoint: <one sentence with current phase, exact evidence observed, next gate, and blocker/decision>
Stop when: <Outcome, Verification surface, Constraints, Boundaries, and Iteration policy Then results plus every required proof pass>, OR <the Blocked stop condition is evidenced and its complete non-success handoff is reported>
```

Outcome, Verification surface, Constraints, Boundaries, and Iteration policy `Then` criteria are
cumulative and parent-level. The Blocked stop condition is mutually exclusive: it never contributes
to native completion, but governs the complete non-success handoff when its trigger is evidenced.
Each section also names distinct positive, negative, and edge scenarios; `not applicable` is permitted
only with an evidence-based reason. Native completion requires evidence for all success criteria; it
does not mean implementation began, a subset passes, or child slices are complete. For a full plan,
derive these criteria from the frozen `objective_acceptance`. State concrete outputs, access decisions, files, responses, or other observable
signals; never use vague criteria such as “works correctly.” `Details` is navigation only: it may
explain a criterion, but never replace one, redefine scope, or become lifecycle authority. Keep implementation steps,
alternatives, per-slice checks, and lifecycle receipts in the contract or protected plan rather
than the native goal. Do not create a native goal for a direct one-shot edit with no useful
verification boundary.

Use literal paths and commands. Do not delete, skip, weaken, narrow, or rewrite tests or other
verification surfaces to make the goal pass; do not refactor unrelated code or add dependencies.
Do not create a new ADR or decision record without human approval. If a product decision, absolute
target, irreversible/external action, new dependency/ADR, or objective change is required, pause
and ask before proceeding.

A child handoff can never complete the parent; native completion is rejected while the parent rollup is incomplete.

For coordinated or multi-turn work, the native `Checkpoint` sentence is only a summary. Persist
the checkpoint's phase, evidence, next gate, and blocker in the `Details` target or frozen
contract before reporting it; the native goal remains navigation and completion evidence, not the
durable lifecycle authority.

If the host exposes an enforceable budget and it is reached, the goal is incomplete—not success and
not a resolved blocker. Stop substantive work and report the progress, evidence, blocker, and next
useful step. Do not invent a budget or present a time/cost estimate as an enforced limit.

For `research_design`, keep the persisted contract's research evidence ledger: one claim per row,
its exact source or evidence surface, support status (`confirmed`, `approximate`, `support-only`,
or `blocked`), and remaining uncertainty. Do not elevate approximate or support-only evidence to
confirmation.

Sources: [Codex slash commands](https://learn.chatgpt.com/docs/reference/slash-commands),
[Codex goals](https://learn.chatgpt.com/use-cases/follow-goals), and
[Codex hooks documentation](https://learn.chatgpt.com/docs/hooks).