Problem
The Warlock skill (.claude/skills/warlock) references an INTEGRATING.md — "guide for engineers integrating the Warlock into a consumer application; update this when changing the public API" — but the file doesn't actually exist. The repo only has README.md and CONTRIBUTING.md.
Right now the README doubles as both the charter/design doc and the de-facto integration reference. That works, but there's no single place that walks a consumer (context-mill, and future ones) through wiring the Warlock in end to end.
What it should cover
- Installing the Warlock as a dependency (incl. the
git+https://... install pattern context-mill currently uses, and how to refresh it)
- Minimal
scan() usage + reading ScanMatch (rule, metadata, matchedStrings)
- Opt-in
triageMatches() usage: providing an LLM callback, batching/truncation behavior, the fail-safe-to-true_positive contract
- Which parts of the API are stable vs. which evolve (rule names are not API; categories/severities are)
- A note that consumers decide actions — the Warlock only detects
Why the Warlock is the right home
Integration guidance for the Warlock's public API belongs next to the API it documents, so it stays in sync when the API changes. Putting it in a consumer repo would drift and wouldn't serve future consumers equally.
Context
Surfaced while adding the matchedStrings field to ScanMatch — updating the docs revealed the referenced INTEGRATING.md was never created.
Problem
The Warlock skill (
.claude/skills/warlock) references anINTEGRATING.md— "guide for engineers integrating the Warlock into a consumer application; update this when changing the public API" — but the file doesn't actually exist. The repo only hasREADME.mdandCONTRIBUTING.md.Right now the README doubles as both the charter/design doc and the de-facto integration reference. That works, but there's no single place that walks a consumer (context-mill, and future ones) through wiring the Warlock in end to end.
What it should cover
git+https://...install pattern context-mill currently uses, and how to refresh it)scan()usage + readingScanMatch(rule,metadata,matchedStrings)triageMatches()usage: providing an LLM callback, batching/truncation behavior, the fail-safe-to-true_positivecontractWhy the Warlock is the right home
Integration guidance for the Warlock's public API belongs next to the API it documents, so it stays in sync when the API changes. Putting it in a consumer repo would drift and wouldn't serve future consumers equally.
Context
Surfaced while adding the
matchedStringsfield toScanMatch— updating the docs revealed the referencedINTEGRATING.mdwas never created.