audit-prompt-caching: Instructions file for Codex

Repository Guidelines

Project Purpose

This repository maintains the portable audit-prompt-caching Codex/agent skill. The skill audits LLM prompt and prefix caching behavior, provider cache telemetry, prompt-prefix stability, cache ROI, and self-hosted KV/cache routing issues.

Layout

• audit-prompt-caching/SKILL.md: main skill instructions and trigger surface.
• audit-prompt-caching/references/: provider and scenario references loaded selectively by the skill.
• audit-prompt-caching/scripts/: dependency-free Python audit helpers.
• audit-prompt-caching/evals/: behavioral and trigger eval prompts.
• tests/test_prompt_cache_scripts.py: unittest coverage for bundled scripts and package checks.
• tests/test_routing_logs.py: normalized routing evidence and CLI coverage.
• docs/superpowers/plans/: implementation plans for multi-step changes.

Development Rules

• Keep scripts dependency-free and Python stdlib-only unless the user explicitly approves otherwise.
• Use apply_patch for manual edits.
• Preserve provider-specific behavior in references; avoid broad rewrites unless the task asks for them.
• For multi-step work, create a plan in docs/superpowers/plans/YYYY-MM-DD-<feature>.md before implementation.
• Use TDD for script behavior changes: add or update a failing test, verify RED, implement minimal code, verify GREEN.
• Do not claim completion without fresh verification output.

Verification Commands

Run all script tests, including normalized routing evidence:

python3 -m unittest discover -s tests -p 'test_*.py'

Validate the skill package:

python3 audit-prompt-caching/scripts/validate_skill_package.py audit-prompt-caching
python3 audit-prompt-caching/scripts/run_trigger_eval.py audit-prompt-caching

Check Python syntax:

python3 - <<'PY'
from pathlib import Path
for path in [*Path('audit-prompt-caching/scripts').glob('*.py'), *Path('tests').glob('*.py')]:
    compile(path.read_text(), str(path), 'exec')
    print(f'ok {path}')
PY