docs: add adapter development guide (#541)

[nextlevelshit]

Summary

• Created comprehensive adapter development guide at docs/guides/adapter-development.md
• Covers adapter architecture, writing custom adapters, testing, and best practices
• Includes detailed examples and troubleshooting

Test plan

• go test -race ./... passes
• Documentation is clear and complete

[nextlevelshit]

Code Review (Wave Pipeline)

Verdict: APPROVE

PR #544 adds a comprehensive adapter development guide (docs/guides/adapter-development.md) along with supporting spec/plan/tasks files. This is a documentation-only change — no Go source code, configuration, or executable code is modified. The guide is well-structured, covers all four required sections (interface, streaming, sandbox, testing), and all struct/interface references have been verified against the current source.

No critical or high-severity issues were found. No security concerns.

---

Suggested Improvements

These are non-blocking and can be addressed in a follow-up:

1. Skeleton adapter race condition note (adapter-development.md:176-187) — The stdoutDone/cmd.Wait() ordering in the skeleton is simplified compared to the production pattern in claude.go. Add a comment noting this is illustrative and pointing to claude.go for the robust pattern.

2. AdapterRunConfig comments disclaimer (adapter-development.md:30-67) — Inline comments on the struct don't match the source file. Add a note that comments are for documentation purposes and to see internal/adapter/adapter.go for the canonical definition.

3. extractToolTarget usage clarification (adapter-development.md:328) — Clarify that this is a package-level function in claude.go that new adapters can call directly, since all adapters share the adapter package.

4. Missing encoding/json import (adapter-development.md:257-325) — The parseStreamLine example uses json.Unmarshal but the import isn't shown. Add it to the skeleton's import block.

5. Error handling in examples (adapter-development.md:270-313) — Several json.Unmarshal calls discard errors. Show the error check pattern at least once or add a comment that production code should check these.

6. killProcessGroup source attribution (adapter-development.md:427) — Add a comment noting this lives in internal/adapter/adapter.go, not claude.go.

7. Module path vs GitHub URL (adapter-development.md:339, 538) — Consider a one-liner noting that the Go module path (github.com/recinq/wave) differs from the GitHub URL (github.com/re-cinq/wave).

8. Spec files in repo (specs/541-adapter-dev-guide/) — Confirm whether these planning artifacts are intended to be committed permanently or should be excluded.

---

Positive Observations

• All major types (AdapterRunner, AdapterRunConfig, AdapterResult, StreamEvent, Sandbox, MockAdapter) were verified accurate against source — this is a high-quality, trustworthy reference.
• Cross-referenced documents (docs/concepts/adapters.md, docs/reference/adapters.md, docs/examples/custom-adapter.md) all exist.
• The guide covers the full adapter lifecycle: interface implementation, NDJSON streaming, sandbox integration, and testing with mocks.
• Security posture is unaffected — no code changes, no credentials, no configuration modifications.

---

Generated by Wave pr-review pipeline