ACKit Optimize — Codex Instruction Auditor

• 

• 

• 

• 

Inspiration

AI coding agents are powerful, but their results depend heavily on the quality of the instructions and repository context they receive.

In real software projects, guidance is often scattered across AGENTS.md, nested agent files, workflow documents, task records, CI configuration, and previous session notes. As repositories evolve, these instructions can become duplicated, contradictory, stale, overly broad, or difficult to verify.

I originally built AgentContextKit as an offline-first repository preparation and safety tool for AI-assisted development.

During OpenAI Build Week 2026, I built ACKit Optimize — Codex Instruction Auditor as a new current-source extension. Its purpose is to audit the instruction layer supplied to Codex and other coding agents before those instructions become expensive, confusing, or unsafe.

What it does

ACKit Optimize adds a first-class command:

ackit optimize

The current-source implementation can:

• Discover root and nested AGENTS.md files and other supported agent/workflow instruction surfaces.
• Resolve directory scope, inheritance, precedence, applicability, and valid nested overrides.
• Preserve original source paths and line ranges while normalizing instruction text conservatively.
• Detect exact duplicates, near-duplicates, contradictions, platform conflicts, package-manager conflicts, build/test conflicts, vague rules, unverifiable rules, stale local references, broad rules, shadowing, repeated boilerplate, unsafe automatic actions, and safety-boundary conflicts.
• Produce stable findings through ACKITOPT001 to ACKITOPT015.
• Report characters, words, lines, and a clearly labeled deterministic token estimate.
• Export console, JSON, Markdown, SARIF 2.1.0, and self-contained offline HTML reports.
• Generate an explicit-path, review-only optimization proposal.
• Preserve valid scoped overrides and mandatory safety constraints.
• Leave unresolved conflicts and unsafe decisions for human review.
• Avoid rewriting source instruction files.
• Run locally without an API key or a required network service.

The proposal workflow is deliberately non-destructive. There is no --apply mode. Existing instruction files are never silently replaced.

A safe synthetic demo is included under:

samples/ackit-optimize-demo

The demo contains nested instructions, duplicates, a genuine conflict, a valid scoped override, vague guidance, and unsafe automatic-action examples without using private repositories or customer data.

Important release boundary: the published AgentContextKit 1.0.0-rc.1 package predates ACKit Optimize. Judges should build the current master source to test the Build Week feature. The existing RC1 package, tag, GitHub prerelease, assets, and attestations were not modified.

How I built it

AgentContextKit is a cross-platform C# and .NET 10 command-line application.

ACKit Optimize was integrated into the existing architecture rather than created as an isolated prototype. The implementation separates:

• Instruction discovery and file-system safety.
• Scope and inheritance resolution.
• Conservative parsing and normalization.
• Deterministic metrics and finding rules.
• Stable IDs and output ordering.
• Console and machine-readable reporting.
• Non-destructive proposal generation.
• CLI parsing, localization, and exit-code behavior.
• Synthetic fixtures, schema tests, golden tests, and cross-platform smoke tests.

The Build Week work was developed through six focused commits after the verified pre-feature baseline. Five commits contain the planning, implementation, proposal, demo, and public documentation. A final evidence-only commit records the completed validation state.

OpenAI Codex with GPT-5.6 assisted with:

• Repository inspection.
• Task decomposition.
• Implementation drafts.
• Regression-test creation.
• Documentation drafting.
• Local command execution.
• Failure diagnosis.
• Read-only GitHub Actions monitoring.

The checked-in Optimize runtime itself is deterministic C#. It does not call GPT-5.6 or any external model.

Human-controlled decisions included:

• Product scope and acceptance criteria.
• Safety, privacy, and release boundaries.
• Commit and push authorization.
• Whether a scoped override is intentional.
• Whether any proposal should be adopted.
• Every package, release, tag, deployment, and credential decision.

Challenges I ran into

Distinguishing duplication from valid scope

Two similar instructions are not necessarily duplicates. A nested AGENTS.md rule may intentionally override a root instruction for one directory. The auditor therefore needed deterministic scope and precedence resolution before reporting conflicts or redundancy.

Reducing noise without hiding real problems

Early repository dogfooding treated historical notes and informational bullets as active instructions. I refined the parser and matching rules so the tool remains conservative without suppressing valid findings.

Staying deterministic and offline

Natural-language analysis can easily become model-dependent. ACKit Optimize instead uses local, documented rules and heuristics so findings are reproducible in development and CI.

Protecting source instructions

An optimizer should not silently rewrite the files that control an AI agent. Proposal output therefore requires an explicit repository-relative path, uses create-new behavior, blocks unsafe path traversal, preserves source mapping, and leaves unresolved decisions to a human.

Maintaining stable cross-platform output

Paths, line endings, shells, and file-system behavior differ across Windows, Linux, and macOS. Stable ordering, repository-relative paths, schemas, golden files, and source-package smoke tests were required to keep output consistent.

Accomplishments that I am proud of

• Implemented a first-class ackit optimize workflow.
• Added 15 stable instruction-audit rule families.
• Added deterministic nested scope, inheritance, precedence, and valid-override handling.
• Added console, JSON, Markdown, SARIF, and offline HTML output.
• Added an explicit-path, review-only optimization proposal with source mapping.
• Added a public-safe synthetic demo and reproducible judging workflow.
• Preserved the offline-first and no-required-API-key model.
• Kept the published v1.0.0-rc.1 release immutable.
• Increased the full automated suite from the 431-test baseline to 463 passing tests.
• Added 31 focused ACKit Optimize tests.
• Passed final CI on Windows and Ubuntu.
• Passed published-package and current-source smoke workflows on Windows, Ubuntu, and macOS.
• Completed final validation with zero build warnings and zero build errors.

What I learned

Reliable AI coding depends as much on instruction engineering as it does on model capability.

Agent instructions need many of the same qualities as production code:

• Clear scope.
• Explicit constraints.
• Deterministic interpretation.
• Testable acceptance criteria.
• Version control.
• Regression protection.
• Regular maintenance.

I also learned that shorter instructions are not automatically better. The correct goal is to remove ambiguity and avoidable repetition while preserving safety, testing, documentation, and release requirements.

Finally, deterministic local analysis and model-assisted development can complement each other. Codex and GPT-5.6 accelerated the engineering workflow, while the final tool keeps runtime findings reproducible and human decisions explicit.

What's next for ACKit Optimize — Codex Instruction Auditor

Future work may include:

• Visual instruction inheritance and precedence maps.
• Finding baselines for detecting newly introduced instruction problems.
• Pull-request annotations and review suggestions.
• Organization-wide instruction rule packs.
• Historical comparisons between commits.
• IDE integrations.
• Additional supported instruction formats.
• Optional model-assisted explanations kept separate from the deterministic audit and disabled by default.

The immediate next step is to collect user feedback from real repositories before selecting a future package version for ACKit Optimize.

Built With

• .net
• bash
• c#
• ci/cd
• cmd
• codex
• git
• github
• html
• json
• linux
• macos
• markdown
• nuget
• powershell
• sarif
• security
• windows
• xunit
• yaml