Skip to content

Add INTEGRATING.md guide for consumers #31

Description

@sarahxsanders

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions