Add INTEGRATING.md guide for consumers
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 0
- Forks
- 1
- PR merge metrics
- No merged PRs in 30d
Description
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 + readingScanMatch(rule,metadata,matchedStrings) - Opt-in
triageMatches()usage: providing an LLM callback, batching/truncation behavior, the fail-safe-to-true_positivecontract - 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.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Read README.md, CONTRIBUTING.md, and the .claude/skills/warlock reference before creating INTEGRATING.md. Document dependency installation and refresh steps, scan() and ScanMatch usage, opt-in triageMatches() behavior, stable versus evolving API elements, and the consumer's responsibility for actions; done means a consumer can follow the guide end to end.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 78/100