goal-cost

name	goal-cost
description	Plan an explicitly requested Codex goal around a user-chosen share of the account's weekly usage. Use for weekly-percentage goal budgets, meter checks, halfway planning, and safe checkpoint stops.

Goal Cost

Use the percentage the user chooses as the working budget for completing the requested goal. The percentage is an advisory boundary on movement of the shared weekly meter.

Check the meter between clear parts of the work. A single part, another task, or a delayed meter update can cross the boundary before the next check. Do not describe the percentage as a hard provider limit or promise an immediate goal pause.

At halfway, compare the work completed with the full result still required. Adjust the plan when needed so the remaining work fits within the percentage.

Create or continue a goal after the user asks for that action. Delegate work or create another task after the user asks for that action.

Set the limit

1. Get an explicit percentage before creating a goal with a usage limit. Ask one direct question when the percentage is missing. The smallest measurable allowance is one percentage point.
2. Treat 10% as 10 percentage points on the weekly meter. The phrase “10% of what remains” means 10 percent of the current remainder. Explain when the result is below one percentage point or exceeds the current window's remaining allowance.
3. Count every change in the shared account meter while the goal runs. Other Codex tasks can use the same allowance. Say so briefly when other tasks are active or likely.
4. Keep the weekly percentage and native token budget separate. Set token_budget when the user asks for one.
5. Keep the user's full requested result as the completion target. Report when the remaining percentage or an active shorter usage window cannot cover it.
6. Use the halfway point and limit described here. Skip time limits and context-compaction rules.

If the user asks about goal cost, read and explain the meter. Create or continue a goal when that action is part of the request.

Resolve scripts/weekly_usage.py relative to this SKILL.md. Before creating the goal, run:

python3 <skill-dir>/scripts/weekly_usage.py --budget <percentage> --pretty

This command reads local session data and makes no network request. Use --source app-server for a live account lookup, or --source auto for a live lookup with local fallback, only when the user explicitly asks for that behavior. The app-server uses the existing Codex login and may contact OpenAI.

For every meter read, require status to be ok. If the helper reports error or unavailable, a shorter usage window is exhausted, or a required field is missing, do not create or continue the goal. Report that the advisory percentage boundary could not be established safely.

Put used_percent, resets_at, midpoint_consumed_percent, and ceiling_consumed_percent in the goal objective. Set the native token_budget when the user separately asks for one.

The native create_goal objective accepts up to 4,000 characters. Keep the objective at or below 3,500 characters. Include the requested result, starting meter, reset time, allowance, halfway point, and limit. The user's full request still applies. Check the length before calling create_goal, and shorten it first if needed.

Include this meaning in the objective:

Work toward this goal with an advisory allowance of N percentage points on the shared weekly Codex usage meter. Other Codex tasks can move the same meter. Check the meter after each part. At halfway, compare the work completed with the work remaining. Adjust the plan when needed so the remaining work fits within the allowance. Finish as soon as the requested work is complete. If a checkpoint reaches the allowance, leave the current action in a safe state and stop. Individual actions and concurrent account activity can exceed the allowance between checks.

Run the goal

Complete one clear part of the work at a time. Size each part for the percentage remaining. Read the meter after each part and before starting another:

python3 <skill-dir>/scripts/weekly_usage.py \
  --budget <percentage> \
  --baseline <current-window-baseline-used-percent> \
  --baseline-reset-at <current-window-baseline-reset-epoch> \
  --last-observed-used <last-used-percent-in-current-window> \
  --consumed-before-reset <percentage-carried-from-earlier-windows> \
  --pretty

Start the first window with the original meter reading as both the baseline and last observed value. Start --consumed-before-reset at 0. After each successful same-window read, replace the last observed value with the returned used_percent before beginning another part.

The weekly meter reports whole-number percentages and covers the whole account. Use observed movement and any carried usage to decide how much of the allowance remains. Report the change as account-wide usage.

Keep the work moving

Each part should advance the requested result or resolve a question that controls the next step.

An unsuccessful step requires new evidence or a changed approach before another attempt. After two attempts on the same obstacle produce no progress, stop that branch and replan from the full remaining goal. Use another path when one is available. Report a blocker when an essential part has no workable path.

Choose focused checks that verify the requested result. Add broader optional coverage when it fits within the percentage.

Check halfway

When midpoint_reached first becomes true, check the work once:

1. State what is complete and what still needs to happen.
2. Compare the share of work completed with the share of the percentage used.
3. Check whether the current approach is working. Identify any stalled or repeated work.
4. Plan the full remaining result within remaining_budget_percent.
5. Focus the remaining usage on work required for completion. Reduce optional investigation and optional coverage when the plan needs room.
6. Leave enough of the allowance to verify the result and report it.
7. Pick a next step that fits within the usage left.

Keep every required part of the requested result in the completion target. Report during the halfway check when the full result no longer appears to fit. Choose the shortest valid path to completion.

The next step can be:

• Continue in this task.
• Give one defined part of the work to a new task.
• Run independent tasks at the same time when the user has asked for delegation or task creation.

If another task is needed, give it a short handoff. Use one editing task at a time for each working directory. Follow any repository rule that explicitly allows concurrent editing.

Include:

• The original starting meter and reset time.
• The total percentage allowed and the amount already used.
• The requested result.
• The work completed and how it was checked.
• The current state and the next action.

Every task counts against the same allowance.

Stop at the limit

When ceiling_reached becomes true:

1. Start no new part of the work.
2. Do only what is needed to leave the current action in a safe state.
3. Report what finished and what remains. Include verification and usage.
4. Mark the goal complete only when its objective is achieved.

If an incomplete goal runs again after the allowance, stop and report that the advisory boundary was reached. Do not claim the goal is paused unless the user actually paused it. Follow the goal tool's rule for when to mark it blocked.

After a weekly reset

If reset_changed is true, first read consumed_before_reset_percent, remaining_budget_percent, and the limit flags from the helper response. Stop if ceiling_reached is true. Do not discard the amount already observed in earlier windows.

When allowance remains, rebase using the values returned by the reset response:

python3 <skill-dir>/scripts/weekly_usage.py \
  --budget <percentage> \
  --baseline <rebase-baseline-used-percent> \
  --baseline-reset-at <rebase-baseline-reset-epoch> \
  --last-observed-used <rebase-baseline-used-percent> \
  --consumed-before-reset <consumed-before-reset-percent> \
  --pretty

Read the new baseline from rebase_baseline_used_percent and the new reset epoch from rebase_baseline_reset_at. Continue with the original allowance after subtracting the carried amount. Stop and report unavailable accounting if the previous observation needed to establish the carry is missing.

Finish early

Complete the goal as soon as the requested work and its verification are done. Report how much the shared meter moved and how much of the allowance remains.

Use this wording in the final report:

The shared weekly meter moved X percentage points while this goal was running. Other Codex tasks may have contributed. Y of the N allowed percentage points were unused.

Report X as shared meter movement.