goal-progress

Goal Progress

Goal Progress adds verified checklist progress to one native Codex Goal.

The Skill is the only user-facing activation entry. Internal tools never activate it by themselves.

Entry

Start only after explicit Skill selection or the canonical marker. Do not activate for an ordinary

Goal, a status question, update_plan, or a general mention of progress.

After the explicit start, continue for the bound Goal without requiring the marker on every later turn.

When trusted SessionStart context says the Contract is active, call goal_progress_get and continue

without asking the user to repeat the marker. Do not call goal_progress_activate again.

Keep progress work in the current thread and current model. Never start a hidden thread, child Agent,

external model, or model API call for progress. Only the main execution Agent may use write tools; a

nested or child Agent must not initialize, update, rescope, or set phase.

Hooks supply _runtimeContext and _runtimeProof; omit both from authored arguments.

Read revisions from tool results. Core calculates every percentage.

Start Or Resume

Read [Activation and recovery](references/activation-and-recovery.md) for a first activation,

cancellation, or recovery.

1. Remove every pure Skill marker line and preserve all other body lines in order.
2. If the user explicitly asks to change an existing native Goal, use Codex update_goal first.

Goal text goes only to the native Goal tool.

1. Call goal_progress_activate with an empty object as the first Goal Progress tool.
2. Follow progressAction exactly:

• get: call goal_progress_get and reuse the existing Contract.
• initialize: prepare the Checklist and call goal_progress_initialize with source and

objectives. Omit contractId; the plugin generates and returns it. Do not call goal_progress_get first.

• rescope-or-replace: compare the current native Goal with the existing Checklist. Rescope

only affected results, or initialize a fresh Contract for a major change.

• none: do not call another Goal Progress tool.

1. Report active only after goal_progress_get or goal_progress_initialize succeeds.

If activation returns NATIVE_GOAL_REQUIRED, create a native Goal from the marker-free user body

with Codex create_goal, then call empty goal_progress_activate once more. If the body is empty,

ask the user for the Goal instead of creating an empty one.

IDs At A Glance

• First initialization: omit contractId. Later writes copy the returned contractId unchanged.
• Objective IDs: C1, C2. Child IDs: C1.1, C1.2, C2.1. These are not UUIDs.
• Reuse IDs for existing results, even after reordering or renaming. Correct only the field named

in a validation error; leave the native Goal and accepted Checklist unchanged.

Checklist

Before generating a Checklist for the first time, changing the acceptance scope, or replacing a

Contract, read [Checklist organization and scope changes](references/checklist-and-scope.md).

When restoring existing progress or updating completion status, continue using the existing

Checklist, IDs, and weights.

Work Loop

Keep update_plan as an execution plan. Never turn its steps into the Goal denominator.

Complete normal Goal work. After a concrete fact is completed or verified, call

goal_progress_get, then goal_progress_update with stable target IDs and the returned revision.

Leave uncertain work unchanged. Active work alone does not earn progress.

Never call a model merely to refresh progress. Core computes every percentage.

On a revision conflict, review the returned current summary before retrying.

Native Goal Changes

The model may create or update the native Goal with Codex native Goal tools. Goal Progress follows

the trusted current native Goal after that change.

When the trusted native Goal changes, classify the change as minor or major in the current model.

Do not use text similarity, another model, or another thread.

Do not ask the user to invoke Goal Progress again.

A wording-only change keeps the existing Checklist. A minor scope change keeps the Contract and

uses goal_progress_rescope for affected results only.

A major change prepares a fresh Contract and uses goal_progress_initialize.

Ordinary implementation, bug-fix, or update_plan changes do neither.

Finish

Run final verification and update only verified remaining targets.

Mark the native Goal complete only when its objective is achieved.

Set Goal Progress to completed only after both the Contract and native Goal are complete.

References

• [Activation and recovery](references/activation-and-recovery.md)
• [Checklist and scope](references/checklist-and-scope.md)
• [Contract examples](references/contract-examples.md)

Uninstall

For an explicit request to uninstall the source plugin, call goal_progress_uninstall when available. It removes this plugin, its Helper and its progress data while keeping native Goals and other plugins. Do not use uninstall to finish or hide a Goal. The first response means removal has started; the returned status log contains the final result.