AGENTS.md

1# AGENTS.md
2 
3> Read this if you are an AI coding agent and the user has pointed you
4> at this repo. This file tells you what to do.
5 
6## What this repo is
7 
8A collection of self-contained drop-in fixes for prompt-caching bugs
9in popular LLM agent harnesses (Cline, Roo Code, Continue, OpenCode,
10Aider). Each fix lives at `skills/<slug>/SKILL.md` and is everything
11you need to land the patch: target file, symptom, diff, verification.
12 
13## What you should do
14 
15When the user asks you to apply this repo:
16 
17### Step 1 — identify which harnesses are in their project
18 
19Quick checks:
20 
21| Harness | Detection |
22|---------|-----------|
23| Cline | `package.json` contains `"name": "claude-dev"` or `"cline"`; or path contains `src/core/api/providers/anthropic.ts` |
24| Roo Code | `package.json` contains `"roo-cline"` or `"roo-code"`; path `src/api/providers/` |
25| Aider | `pyproject.toml` or `setup.py` declares `aider`; path `aider/coders/` |
26| OpenCode | path `packages/opencode/src/provider/transform.ts` |
27| Continue | path `packages/openai-adapters/src/apis/Anthropic.ts` or `core/llm/llms/Bedrock.ts` |
28 
29If none match, the user may want you to apply skills to their *own*
30agent harness using these as templates. Ask them.
31 
32### Step 2 — for each matching harness, check each relevant skill
33 
34For every `skills/<slug>/SKILL.md`:
35 
361. Read the YAML frontmatter:
37   - `target_harness` — matches user's project?
38   - `target_files` — exist at those paths?
39   - `target_commit` — is the user's checkout near that commit, or
40     have things drifted?
412. Read the "Symptom" section. Verify the symptom exists in the
42   user's code before applying. If it doesn't (e.g. user is on a
43   newer version where the bug is fixed), SKIP that skill and report.
443. If symptom present, apply the diff in the "Fix" section. If the
45   diff doesn't apply cleanly (line drift), do the equivalent edit
46   manually preserving the intent.
474. Run the "Verify" section. Most verifications require capturing
48   the wire (mitmproxy or harness debug log) and inspecting response
49   `usage` fields. If you can't run a live verify, at minimum confirm
50   the syntax of the patched file is valid (compile/type-check).
51 
52### Step 3 — report back
53 
54Tell the user:
55 
56- Which skills applied cleanly
57- Which skipped and why (symptom not present / file moved / etc.)
58- Which failed verification and were reverted
59- Estimated savings based on the per-skill `estimated_savings` field
60 
61### Step 4 — don't bundle skills into one commit
62 
63One skill = one commit (or PR). Easy to review and easy to revert
64individually if one regresses. Use the skill name as the commit
65message subject.
66 
67## What you should NOT do
68 
69- **Don't modify the skills themselves** unless the user explicitly
70  asks. If you spot a bug in a skill, write it up as a comment or
71  patch and stop there.
72- **Don't apply skills speculatively.** Every skill has a target
73  file + symptom check; verify before applying. The fixes are
74  surgical, not heuristic.
75- **Don't replace `cache_control` with random UUIDs or session IDs
76  thinking it'll "randomize the cache".** That's the #1 footgun. See
77  `docs/gotchas.md` #9b.
78- **Don't combine skills into one mega-fix.** Each one is atomic for
79  a reason — separate bugs can have separate reviewers and separate
80  upstream PRs.
81- **Don't open upstream PRs without the user's explicit go-ahead.**
82  The skills are written to be applied locally; pushing them upstream
83  is a separate decision the user owns.
84 
85## Useful reference paths
86 
87If you need to understand WHY a fix matters before applying:
88 
89- `docs/concepts/anthropic.md` — Anthropic prompt caching mechanics
90- `docs/concepts/openai.md` — OpenAI prompt caching + `prompt_cache_key`
91- `docs/concepts/gemini.md` — Gemini implicit + explicit caching
92- `docs/concepts/bedrock.md` — Bedrock `cachePoint` semantics
93- `docs/gotchas.md` — 16 numbered failure modes
94- `docs/verification.md` — how to confirm caching is working
95 
96For the audit evidence behind each skill:
97 
98- `audits/<harness>.md` — full source audit + permalinks
99 
100## Verifying your work
101 
102The repo ships `tools/check_cache.py` — a zero-dependency Python
103script that fires any request body twice and dumps the cache token
104diff. Use it as a smoke test:
105 
106```bash
107# After applying a skill that targets Anthropic:
108python3 tools/check_cache.py --provider anthropic --body /tmp/req.json
109# Expect: warm.cache_read > 0 and significantly larger than warm.input
110```
111 
112If `cache_read` is 0 on the warm call, the fix didn't land or there's
113a second upstream issue. Stop and report rather than retrying blindly.
114 
115## Development setup
116 
117### Prerequisites
118 
119- Python 3.11+ (stdlib only — no pip install needed)
120- Node.js 18+ (for `markdownlint-cli2` via npx)
121 
122### Build / lint / test commands
123 
124```bash
125# Python syntax check (CI job: python-syntax)
126python3 -m py_compile tools/check_cache.py tools/check_docs_consistency.py
127 
128# Docs consistency guard (CI job: consistency)
129python3 tools/check_docs_consistency.py
130 
131# Markdown lint (CI job: markdown-lint)
132npx markdownlint-cli2 '**/*.md' '!**/node_modules/**'
133 
134# Python unit tests (CI job: python-tests)
135python3 -m pytest tests/ -v
136 
137# Python type check (CI job: python-typecheck)
138python3 -m mypy tools/ --strict
139 
140# Secrets scan (CI job: secrets-scan — requires gitleaks binary)
141gitleaks dir . --no-banner
142```
143 
144### CI
145 
146GitHub Actions workflow at `.github/workflows/ci.yml` runs on every
147push and PR: gitleaks, markdownlint, python syntax, docs consistency,
148pytest, mypy, and link check.
149 
150## When in doubt
151 
152Read the SKILL.md fully. They're written to be self-explanatory for
153agents. If a skill is ambiguous, treat that as a bug in the skill
154and ask the user how to proceed rather than guessing.
155