# Goalopt

> Optimize a rough objective into a precise completion contract, then create a native Codex goal from it. Use when Pafi says /goalopt, goalopt, optimize this goal, or asks to turn a vague task into an autonomous Codex goal with clear verification, constraints, boundaries, and stop conditions. Ported from the Hermes /goalopt plugin behavior, not from the NexusOS dispatch adapter.

- Skill: `cryptopafi/goalopt` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add cryptopafi/goalopt`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cryptopafi/goalopt/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: cryptopafi (https://skillmd.com/u/cryptopafi)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/cryptopafi/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:

```text
<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:

```bash
${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:

```bash
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:

```text
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:

```bash
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:

```text
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:

```text
<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:

```text
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:

```bash
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:

| Scenario | Expected calls |
| --- | --- |
| Empty objective | no goal tool calls |
| Optimizer failure | `get_goal`, then `create_goal` only if no unfinished goal exists |
| Remote env absent | no SSH attempt; local optimizer or fallback contract only |
| Active unfinished goal | `get_goal` only; no replacement `create_goal` |
| Successful creation | `get_goal`, then one `create_goal` with no token budget unless explicit |
| Verified completion | `update_goal(status="complete")` only after `verify:` evidence is true |

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.