Codex Minimal Diff

Stop Codex from turning a 1-line bugfix into a 12-file refactor.

A minimal-diff guardrail skill and plugin preview for OpenAI Codex.

Codex is powerful. Sometimes too powerful.

This pack helps Codex:

• plan before editing
• patch the smallest safe surface
• avoid unrelated files
• verify honestly
• report changed files, checks, assumptions, and risks

What You Get

• AGENTS.md for always-on repository guidance.
• A Codex skill for bug fixes, test fixes, PR cleanup, and small feature changes where scope creep is a risk.
• references/ for minimal-diff, verification, evidence, and scope-control rules.
• .agents/skills/codex-minimal-diff/agents/openai.yaml metadata for Codex-facing display and invocation behavior.
• A plugin preview under plugin/ for future distribution.
• Safe install, uninstall, doctor, plugin-sync, and diff-scoring scripts.
• Minimal Diff Challenge fixtures for reproducible local comparison.
• CI checks that catch malformed Markdown, shell scripts, skill metadata, plugin metadata, and risky README claims.

30-Second Quickstart

git clone https://github.com/sjh9714/codex-minimal-diff.git /tmp/codex-minimal-diff
/tmp/codex-minimal-diff/scripts/install.sh --repo --target .
bash scripts/doctor.sh .

For remote install without cloning, see the review-first GitHub install below.

Then ask Codex:

Use $codex-minimal-diff. Fix this bug with the smallest safe change.

Install

Recommended: clone, then install

git clone https://github.com/sjh9714/codex-minimal-diff.git
cd your-project
/path/to/codex-minimal-diff/scripts/install.sh --repo --target .

Manual install

Copy these into the root of your repository:

AGENTS.md
.agents/skills/codex-minimal-diff/

If your repository already has an AGENTS.md, merge the relevant rules manually instead of replacing it.

Install from GitHub

Review the script first, then run:

curl -fsSL https://raw.githubusercontent.com/sjh9714/codex-minimal-diff/main/scripts/install.sh -o /tmp/codex-minimal-diff-install.sh
sed -n '1,240p' /tmp/codex-minimal-diff-install.sh
bash /tmp/codex-minimal-diff-install.sh --repo --target .

Other install modes

Dry run

/path/to/codex-minimal-diff/scripts/install.sh --dry-run --target .

Repo install from a checkout

/path/to/codex-minimal-diff/scripts/install.sh --repo --target .

User-level skill install

/path/to/codex-minimal-diff/scripts/install.sh --user

Include plugin preview

/path/to/codex-minimal-diff/scripts/install.sh --repo --target . --plugin-preview

Doctor check

bash scripts/doctor.sh .

Usage

In Codex, explicitly invoke the skill:

Use $codex-minimal-diff. Fix the failing test with the smallest safe change.

Use $codex-minimal-diff. Implement this feature, but do not touch unrelated files.

Use $codex-minimal-diff. Review this diff for scope creep, missing tests, and unclear assumptions.

Codex may also select the skill implicitly when your task matches the skill description.

Minimal Diff Challenge

The Minimal Diff Challenge provides toy fixtures for comparing your own Codex sessions before and after installing the skill.

This is not a benchmark claim. The fixtures let you compare your own Codex sessions using the same small tasks and the same diff scoring script.

Prepare a fixture:

bash benchmarks/minimal-diff-challenge/scripts/prepare-fixture.sh 01-empty-email-crash /tmp/codex-fixture

After installing into the prepared fixture repo and running a Codex session there, score the diff from the fixture root:

bash scripts/score-diff.sh --max-files 2 --max-lines 40

If you are scoring from a separate source checkout instead, use that checkout path:

bash /path/to/codex-minimal-diff/scripts/score-diff.sh --max-files 2 --max-lines 40

The script reports changed files, untracked files, added lines, deleted lines, and optional threshold warnings.

Before / After

Before:

• user asks for a 1-line bugfix
• agent touches 12 files
• agent rewrites nearby code
• agent does not report the exact test command

After:

• agent inspects relevant files
• agent estimates a diff budget
• agent touches 1-2 files
• agent runs the narrowest relevant test
• agent reports changed files and verification honestly

Codex-Native Design

This repository follows Codex-native surfaces:

• AGENTS.md is always-on repo guidance.
• SKILL.md is reusable workflow instruction.
• references/ holds deeper rules without bloating the skill body.
• .agents/skills/codex-minimal-diff/agents/openai.yaml provides Codex-facing metadata.
• plugin/ previews installable packaging for later distribution.

Evidence Status

See EVIDENCE.md, evidence/schema-v1.md, and evidence/runs/.

No public benchmark numbers are claimed yet.

Evidence records are classified by quality level:

• Level 0: anecdotal local run
• Level 1: reproducible local run
• Level 2: paired comparison
• Level 3: small study

Evidence must include commands, changed files, changed line counts, prompts, verification results, final responses, and limitations. Fabricated sessions, testimonials, productivity claims, and endorsement claims do not belong in this project.

Influences, Not Endorsements

This project is influenced by practical software-engineering ideas around responsible agentic engineering, comprehension debt, small safe changes, behavior-preserving refactoring, and human-reviewable diffs.

It is not affiliated with or endorsed by any public figure, author, company, or tool vendor.

Roadmap

• v0.1.0: MVP with AGENTS.md, skill, references, examples, install scripts, and validation.
• v0.2.0: formatting regression hardening, stronger positioning, safer installer, plugin preview, and Minimal Diff Challenge.
• v0.3.0: project, skill, and plugin rename to Codex Minimal Diff.
• v0.4.0: real Codex session reports and contributed evidence.
• v1.0.0: stable plugin packaging and community-submitted challenge results.

Develop

Run the validation scripts before opening a pull request:

bash tests/text-encoding.test.sh
bash tests/line-structure.test.sh
bash tests/validation-negative.test.sh
bash tests/required-files.test.sh
bash tests/markdown-format.test.sh
bash tests/skill-frontmatter.test.sh
bash tests/shell-scripts-execute.test.sh
bash tests/no-placeholder.test.sh
bash tests/readme-claims.test.sh
bash tests/evidence-files.test.sh
bash tests/install-smoke.test.sh
bash tests/install-options.test.sh
bash tests/install-remote-safety.test.sh
bash tests/plugin-manifest.test.sh
bash tests/openai-yaml.test.sh
bash tests/benchmark-files.test.sh
bash -n scripts/*.sh
bash -n tests/*.sh
bash -n .agents/skills/codex-minimal-diff/scripts/*.sh
bash -n benchmarks/minimal-diff-challenge/scripts/*.sh
bash scripts/doctor.sh .
bash scripts/sync-plugin.sh
bash tests/plugin-manifest.test.sh

Korean Summary

Codex가 작은 버그 수정을 12파일 리팩터링으로 키우지 않도록, 최소 diff·범위 통제·검증·최종 보고 형식을 강제하는 AGENTS.md + Skill + plugin preview 패키지입니다.

License

MIT