Goal to Proof

Make AI agents do the right work, finish it, and prove it.

한국어 · Website · Methodology · Validation

Goal to Proof is a lightweight closure contract for AI agents. It turns authorized, non-trivial work into an observed outcome instead of a plausible completion claim.

It does not give an agent new permissions, choose your goals, or force a heavyweight process onto simple work. It changes exactly one thing — the definition of "done": each in-scope requirement needs direct, scope-matched evidence from the latest relevant state.

npx skills add aiopshwang/goal-to-proof

One command installs the canonical Agent Skills package. Codex and Claude Code marketplace routes are covered in Install.

The problem it solves

Agents often stop one boundary too early:

• a plan exists, but the requested change was never made;
• a component passes, but the real integration path was not exercised;
• a file was generated, but the intended audience cannot use it;
• a push succeeded, but the public artifact was never read back;
• a proxy check passed, so the broader outcome was implied rather than observed.

Each of these produces a completion report that reads fine — until you ask for proof.

See it

A unit test is green while the runnable path is broken: cli.py calls greeting(''), so the program prints Hello, instead of Hello, World. Same fixture, same Sonnet agent, same fix. Here is how each arm reported it.

Without the skill:

Both pass. The fix was one character: cli.py was passing an empty string to greeting(), producing 'Hello, ' instead of the expected 'Hello, World'. Changing it to greeting('World') satisfies the smoke test's assertion. No remaining uncertainty.

With the skill:

Both paths now pass.

Outcome: The smoke test was failing because cli.py called greeting(''), producing Hello, instead of Hello, World. Fixed by passing 'World' as the argument.

Evidence:

• Before fix — smoke test: AssertionError: Hello, (directly observed)
• After fix — smoke test: SMOKE: PASS (directly observed)
• Unit test: still OK — no regression (directly observed)

No remaining uncertainty.

Both are verbatim from recorded runs under evals/. Both agents fixed the bug. The difference is that the second one tells you what it saw, before and after, and which layer each observation covers — so you can check its claim instead of trusting it. When direct proof is unavailable, the skill requires precise labels instead: verified, partially verified, or not verified.

How it works: the closure contract

For work that needs real closure, the skill identifies four things:

1. Result — what must be different when the task is done.
2. Target — who or what must be able to use or observe it.
3. Proof — the most direct practical observation that separates success from plausible-looking failure.
4. Boundaries — what is authorized, excluded, or requires new authority.

The agent then chooses the lightest workflow that can reach that result, completes the dependent steps, and maps every completion claim to evidence. The user stays in control while the agent is responsible for execution and verification inside the approved boundary:

What makes it different

• A completion gate, not another methodology. Domain skills still own planning, design, debugging, research, and implementation; Goal to Proof only defines when the work counts as done.
• Claim-shaped proof discipline. Evidence must match the scope of the claim and come from the latest relevant state — a convenient proxy check never stands in for the requested outcome.
• Published, evidence-scoped validation. The repository ships a public evaluation gate — activation, behavior, and hard-gate cases with recorded results in evals/ — and claims nothing beyond what those records support.

When to use it

Use Goal to Proof when a deliverable has dependent steps, crosses an integration or publication boundary, or is likely to stop at a plan, partial artifact, isolated component, or proxy check.

Typical examples include:

• implementing and exercising a user-visible feature;
• fixing a bug and reproducing the original path after the change;
• publishing an artifact and reading the remote state back;
• producing a document, visual, or curriculum and opening the final render;
• completing research whose material claims need traceable primary sources;
• delivering a non-trivial diagnosis, evidence-backed decision memo, or executable plan as the requested result;
• carrying an approved multi-step operation through its actual target environment.

It should not activate implicitly for simple questions, translation or formatting, open-ended ideation, routine self-contained edits with an obvious direct check, or read-only requests whose sole deliverable is an answer and that do not exercise a target workflow. A plan, diagnosis, or decision document can still be a positive case when that non-trivial artifact is itself the requested result.

Install

Agent Skills installer

Install the canonical Agent Skills package with the portable installer:

npx skills add aiopshwang/goal-to-proof

Choose your agent and installation scope in the prompt. Packaging describes the intended distribution path; consult validation evidence and release notes for the environments actually exercised.

Codex marketplace

codex plugin marketplace add aiopshwang/goal-to-proof
codex plugin add goal-to-proof@goal-to-proof

You can inspect configured sources with codex plugin marketplace list. Codex marketplace packaging follows OpenAI's plugin packaging documentation.

Claude Code marketplace

claude plugin marketplace add aiopshwang/goal-to-proof
claude plugin install goal-to-proof@goal-to-proof

In a Claude Code managed plugin install, the skill is namespaced as /goal-to-proof:goal-to-proof; a standalone Agent Skills install may expose /goal-to-proof. See Anthropic's marketplace and skill documentation.

Invoke

In Codex, invoke it explicitly when you want closure behavior:

Use $goal-to-proof to carry this approved change through the real target and prove it.

The skill may also activate automatically when its description matches a non-trivial closure task. Explicit invocation is useful when the main risk is premature completion.

Design principles

• Outcome over artifact: a generated thing is not automatically a usable result.
• Claim-shaped proof: test the scope of the claim, not a convenient proxy.
• Latest-state evidence: re-check after the final relevant change.
• Real boundary when practical: exercise the actual integration, audience, device, account, render, or remote state.
• Authority stays with the user: no publication, spending, disclosure, irreversible action, or scope expansion without authorization.
• Low ceremony: simple work stays simple; process appears only when it protects closure.
• Honest limits: missing access or evidence narrows the completion claim.

Read the full product principles and methodology.

Validation and claims

This project separates three different facts:

1. Package validity: manifests and skill structure satisfy their validators.
2. Host behavior: a named host can discover, install, and invoke the package in an exercised environment.
3. Task outcome: an agent using the skill improves closure on a defined evaluation case.

Passing one layer does not prove the next. See Benchmarks & validation for the evaluation contract and scoped evidence. No universal productivity or success-rate claim is made.

What has actually been measured with a control arm (full record). The same task was given twice — once with the skill reachable, once without — on Claude Code with sonnet and on Codex with gpt-5.6-sol.

• What the skill changed, where it changed anything, was the report: whether the final answer named the observations it relied on and separated what it verified from what it did not. It did not make the agent fix more bugs or pass more oracles — both arms passed every deterministic check on every case.
• On Codex at high reasoning effort, both arms already reported that way. These small cases cannot detect a difference against that baseline.
• Under prompts that never name the skill it fired 8/8 on one case and 5/5 on another, stayed silent on the routine edit its description excludes, and missed 0/6 on a case it should have caught. It is not a reliable automatic trigger; the Invoke line is the dependable path when premature completion is the risk.

The report-quality comparison was scored by an LLM judge that was later found to change its verdict on identical text. Those scores are kept in the record as what was observed and are not quoted here as an effect size.

Origin and privacy

The initial behavior model was distilled from aggregate analysis of prior real working sessions. The analysis looked for repeated operating patterns such as intent alignment, scope control, autonomous execution inside approval boundaries, end-to-end verification, durable checkpoints, and evidence-first reporting.

Raw conversations were never included in this repository. Personal names, secrets, one-off preferences, private content, session transcripts, and private corpus metadata were excluded from the published skill. The source material informed the design; it is not a performance benchmark.

Project map

skills/goal-to-proof/          Canonical Agent Skill
.codex-plugin/                 Codex plugin manifest
.agents/plugins/               Codex marketplace catalog
.claude-plugin/                Claude Code plugin and marketplace metadata
evals/                         Behavior cases and evaluation data
tests/                         Package and policy checks
docs/                          GitHub Pages source

The repository root is the plugin root. There is one canonical SKILL.md; platform packages point to it rather than maintaining divergent copies.

aiopshwang skill family

Independent, evidence-first Agent Skills that work well together:

• verify-regression-tests — prove that a regression test actually detects its intended defect.
• ship-mobile-app — production mobile work across domain, state, lifecycle, platform, and release boundaries.
• data-analysis-ml-agent-skills — decision-grade data analysis and ML: audits, leakage-safe experiments, validation, reproducible handoff.
• fresh-eyes-check — a context-free second model checks whether an earlier instruction still fits before you act on it.

evidence-first-problem-solving was merged into this skill at v1.1.0; its diagnosis loop lives in references/diagnosis-and-proof.md.

Contributing

Issues and focused pull requests are welcome. Behavioral changes should include a case that would fail without the change and should preserve non-trigger behavior for simple work. See CONTRIBUTING.md and the Code of Conduct.

License

MIT © Hyunsik Hwang (aiopshwang).