Goalopt

Goalopt

Purpose

Use this skill to convert a rough objective into a checkable Codex goal. Preserve the five-field contract behavior of the Hermes original, while using Codex-native goal tools.

1. Optimize the rough objective into a five-line completion contract.
2. Fall back to a bare but structured contract if the optimizer is unavailable.
3. Set the result through the native goal mechanism.

In Codex, the native mechanism is create_goal, get_goal, and update_goal. Do not create NexusOS DISPATCH.md tasks, do not invoke auto-run, and do not require a remote quality-gate unless the user explicitly asks for NexusOS/Hermes dispatch.

Source

This is a Codex port of the Hermes plugin:

• Hermes plugin source: ${HERMES_HOME}/plugins/goalopt/__init__.py
• Hermes plugin metadata: ${HERMES_HOME}/plugins/goalopt/plugin.yaml
• Hermes behavior: PromptForge optimizer -> contract parser -> GoalManager.set(...)

The older NexusOS/Claude adapter at ~/.claude/skills/goalopt/SKILL.md is provenance only. It relies on DISPATCH.md, auto-run, and quality-gate, none of which belong in this native Codex workflow.

Dependencies

Required:

• Native Codex goal tools: get_goal, create_goal, and update_goal.

Optional:

• PromptForge optimizer wrapper at ${NEXUS_HOME:-$HOME/.nexus}/lib/opt-memapo-wrapper.py. It is not installed on this Mac as of 2026-07-10, so direct contract drafting is the normal local path unless an executor has independently verified that the wrapper is available.
• python3 for the optional optimizer wrapper and packaging validation examples.
• Remote optimizer access through explicitly configured NEXUS_REMOTE_USER, NEXUS_REMOTE_HOST, and REMOTE_NEXUS_HOME. Do not assume defaults for exportable use.
• timeout or gtimeout for a hard optimizer wall clock. If neither exists, skip the optimizer and draft the fallback contract directly.

Fallback:

• If any optimizer dependency is unavailable, fails, returns empty output, or returns malformed output, draft the five-line contract directly from the raw objective and proceed.

Contract Shape

Produce exactly this shape before creating a goal:

<one-sentence outcome - the end state that must be true, not an action verb>
verify: <exact command, test, artifact, or observable result that proves it>
constraints: <what must not change or regress while working toward the outcome>
boundaries: <exact files, directories, tools, systems, or business scope in bounds>
stop when: <the condition where Codex should pause and ask instead of guessing>

The verify: line should be binary whenever possible: tests pass, a named file exists, a query returns zero rows, a report has been written, a health check passes, or a specific manual readback has been delivered.

Workflow

1. Normalize the user objective by trimming whitespace. If it is empty, explain the usage: /goalopt <rough objective>.
2. Build the structuring prompt below. Use the optional PromptForge wrapper only when it is present and its interface has been verified; otherwise draft the contract directly.
3. Validate the optimizer output. It must have all five fields and no extra preamble.
4. If optimizer output is missing, invalid, or times out, draft the same five-line contract directly from the raw objective. Do not block on optimizer failure.
5. Check for an active native Codex goal with get_goal.
6. If an unfinished goal already exists, report it and do not replace it. Ask Pafi to finish or explicitly redirect the active goal in the conversation.
7. If no unfinished goal exists, call create_goal with a single objective string containing the outcome plus the four labeled contract fields.
8. Start working on the goal immediately unless the user only asked to prepare or review it.

Optional Optimizer

Optional local optimizer path:

${NEXUS_HOME:-$HOME/.nexus}/lib/opt-memapo-wrapper.py

Use this call pattern only after confirming that the installed wrapper accepts --input and --output. Do not install or repair the wrapper as part of /goalopt; its absence must take the direct-contract fallback path.

Concrete local call pattern:

opt_wrapper="${NEXUS_HOME:-$HOME/.nexus}/lib/opt-memapo-wrapper.py"
prompt_file="$(mktemp)"
output_file="$(mktemp)"
trap 'rm -f "$prompt_file" "$output_file"' EXIT
chmod 600 "$prompt_file" "$output_file"
printf '%s\n' "$structuring_prompt" > "$prompt_file"
optimizer_status=1

if [ -f "$opt_wrapper" ]; then
  if command -v timeout >/dev/null 2>&1; then
    timeout 30 python3 "$opt_wrapper" --input "$prompt_file" --output "$output_file" && optimizer_status=0
  elif command -v gtimeout >/dev/null 2>&1; then
    gtimeout 30 python3 "$opt_wrapper" --input "$prompt_file" --output "$output_file" && optimizer_status=0
  else
    echo "No timeout command available; use fallback contract instead of optimizer."
  fi
fi

if [ "$optimizer_status" -eq 0 ]; then
  contract_text="$(cat "$output_file")"
fi

If the local wrapper is not available, the remote optimizer is optional. Prefer the fallback contract unless all remote settings are explicitly present and the remote call can preserve this interface:

input: the structuring prompt over stdin or a chmod 600 temporary file
configuration: NEXUS_REMOTE_USER, NEXUS_REMOTE_HOST, and REMOTE_NEXUS_HOME from the local environment
validation: NEXUS_REMOTE_USER and NEXUS_REMOTE_HOST are non-empty host/user identifiers; REMOTE_NEXUS_HOME is an absolute path
ssh: BatchMode=yes and ConnectTimeout=10
outer wall clock: timeout 30 or gtimeout 30 before ssh starts
remote runtime: chmod 600 temporary input/output files, wrapper subprocess timeout=30
output: only the contract text on stdout
failure mode: nonzero exit, timeout, missing dependency, empty output, or malformed output -> fallback contract

Do not embed complex nested SSH/Python shell snippets in this skill. If a concrete remote runner is needed, put it in scripts/, test it, and keep SKILL.md limited to the interface above. Do not use an unbounded remote shell pattern such as:

ssh "$NEXUS_REMOTE_USER@$NEXUS_REMOTE_HOST" \
  'set -e
   prompt_file="$(mktemp)"
   output_file="$(mktemp)"
   python3 "$REMOTE_NEXUS_HOME/lib/opt-memapo-wrapper.py" --input "$prompt_file" --output "$output_file"'

Pass user text through temporary files or stdin. Never interpolate the raw objective into a shell command. Use a timeout of 30 seconds for the optimizer path, matching Hermes. If the optimizer fails, use the fallback contract.

Structuring prompt:

Rewrite the objective below as a precise completion contract with EXACTLY this format - one sentence per line, no preamble, no extra lines:

<one-sentence outcome - the end state that must be TRUE, not an action verb>
verify: <exact command / test / artifact that proves it - must be binary, machine-checkable when possible>
constraints: <what must NOT change or regress while working toward the outcome>
boundaries: <exact files / dirs / tools / systems in scope - nothing outside this>
stop when: <the condition where the loop should pause and ask, instead of guessing>

Objective: {objective}

Native Codex Goal Format

When calling create_goal, use this objective format:

<outcome sentence>

Completion contract:
verify: ...
constraints: ...
boundaries: ...
stop when: ...

Pass a token budget only if Pafi explicitly provided one. Otherwise omit token_budget.

Example tool-call shape:

create_goal({
  "objective": "<outcome sentence>\n\nCompletion contract:\nverify: ...\nconstraints: ...\nboundaries: ...\nstop when: ..."
})

Validation

Before create_goal, confirm:

• The outcome is not empty.
• verify:, constraints:, boundaries:, and stop when: are present exactly once.
• The verify: line describes concrete evidence, not a vague intention.
• Boundaries are narrow enough that Codex will not touch unrelated systems.
• The stop condition protects against guessing.

Smoke Checks

Use these checks when editing or forward-testing this skill:

• Empty objective: show /goalopt <rough objective> usage and do not call create_goal.
• Optimizer unavailable, timed out, or invalid: draft the five-line fallback contract and continue.
• Remote optimizer env absent: do not attempt SSH; use the local optimizer if available or draft the fallback contract.
• Active unfinished goal exists: get_goal prevents replacement; report the active goal and ask for explicit redirect instead of calling create_goal.
• Successful creation: call create_goal exactly once with the formatted objective and omit token_budget unless Pafi explicitly supplied one.
• Completion discipline: call update_goal(status="complete") only after the verify: evidence is actually true.

Basic packaging validation:

GOALOPT_ROOT="${GOALOPT_ROOT:-$PWD}"  # run from the skill directory or set GOALOPT_ROOT
SKILL_CREATOR_ROOT="${CODEX_HOME:-$HOME/.codex}/skills/.system/skill-creator"
python3 "$SKILL_CREATOR_ROOT/scripts/quick_validate.py" "$GOALOPT_ROOT"

Expected native-goal calls:

After create_goal, normal goal rules apply:

• Use update_goal(status="complete") only after the verification condition is actually true.
• Use update_goal(status="blocked") only under Codex's native blocked rules.
• Do not mark a goal complete because the optimizer generated a contract; completion requires real evidence from tools, files, tests, reports, or user-visible output.

Reporting

After setting the goal, tell Pafi:

• The optimized outcome.
• The verification line.
• Any important boundary or stop condition.
• Whether Codex started execution or only prepared the goal.

Keep the report short. Do not mention NexusOS dispatch unless the user asked for it.

Safety

• Do not create external tasks, send Telegram messages, or mutate databases just because a goal was created. The goal only scopes Codex's work in the current thread.
• Do not use remote execution for the optimizer when a simple fallback contract is enough and the task is time-sensitive.
• Do not include secrets, tokens, or raw private credentials in the goal text.
• Do not replace or clear an unfinished active goal silently.

Version

• v1.0.1-codex (2026-07-10): Audited the Claude goalopt adapter and Codex port; documented the unavailable local optimizer and made direct fallback the normal host behavior.
• v1.0.0-codex (2026-07-05): Hermes-native Codex port using native goal tools, fallback contracts, bounded optional optimizer behavior, smoke checks, and no NexusOS dispatch adapter.