# Adapter development guide

> Add a platform or runtime adapter without crossing Switchyard domain boundaries.

Add operating-system or external-tool behavior behind an application-owned
interface. Keep domains platform-neutral and preserve the dependency direction
adapter/transport to application to domain. Do not add OS branches to domain
models, a service locator, or a generic command helper.

An adapter change includes capability detection, typed unavailable/degraded
errors, argument-array execution, cancellation, bounded output, redaction where
data crosses a sink, and tests for success, failure, cancellation, permissions,
and reconciliation. Platform files use explicit Go build tags and must compile
in the Linux and Windows `platform-check` target. Native behavior also runs on
its host in CI.

Process adapters must preserve fingerprint ownership and whole-tree stop.
Port adapters return facts and provenance rather than inferred ownership.
Terminal adapters implement resize, Unicode/ANSI transport, bounded detach,
tree termination, and user-visible output only. Launchers accept only typed
terminal/editor/browser operations; browser targets remain HTTP(S).

Plugin adapters belong out of process and use the public `sdk/plugin` protocol
plus conformance kit. Provider-specific AI code stays under
`internal/agents/providers`; provider output remains untrusted schema input.

Update an ADR before changing an accepted boundary, generate contracts rather
than editing generated files, document the platform matrix, and attach progress
evidence for the phase or vertical slice.