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>.

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, Codex goals, and Codex hooks documentation.