project-adapters

name	project-adapters
description	Step-by-step workflow for adding, modifying, or debugging a source-format adapter. Use whenever editing an adapter under internal/adapters, internal/canonical, or related fixture files.

Adapters

Mental Model

An adapter is a sealed unit that converts one source format into the canonical event stream. It knows everything about its format and nothing about anything else. See .agents/sow/specs/adapter-contract.md.

Adding a New Adapter

1. Read the format authoritatively first. Open the upstream source mirror under /opt/baddisk/monitoring/repos/ai/<tool>/ and read its persistence code. Sample real files (sanitized) from the operator's environment.

2. Write the spec first. Create .agents/sow/specs/adapter-<name>.md. Required sections: source format, record shape, watch strategy, cursor design, mapping to canonical events, sub-agent linkage, known edge cases, references. The spec is the source of truth; the code follows.

3. Create the package. internal/adapters/<name>/adapter.go. Implement the canonical.Adapter interface. Keep the file under 400 lines; split helpers into sibling files.

4. Commit sanitized fixtures. testdata/<name>/<scenario>/. Scenarios are listed in testing-strategy.md. Run scripts/sanitize-fixture.sh before committing.

5. Write tests. Scan, Tail, cursor resume, error handling, idempotency. Use golden files.

6. Register the factory. internal/adapters/registry.go:

   registry["myadapter"] = myadapter.Factory