tutorial: Writing a Vibe-Check language adapter (in-process Go and external JSON-RPC)

[jflowers]

Moved from zero-dot-force/vibe-check#22 (cross-org, so recreated here rather than transferred — tutorials are authored/published from this website repo). The original has been closed with a pointer to this issue.

Cross-repo note: all bare #N references below point to zero-dot-force/vibe-check and are fully qualified accordingly; spec paths (openspec/specs/...) live in that repo, not this one.

Tutorial opportunity: authoring a Vibe-Check language adapter

Source: verification re-review of the archived universal-coupling-model change, whose delta specs are now synced into the canonical spec library (the stable spec-of-record).

Why now: the adapter contracts are now a stable spec-of-record, so a tutorial documents a fixed target rather than a moving one (all in zero-dot-force/vibe-check):

• openspec/specs/adapter-interface/spec.md — the in-process Go Adapter interface (Analyze, Language, Capabilities) plus registration and capability discovery.
• openspec/specs/analyzer-protocol/spec.md — the external, out-of-process JSON-RPC 2.0 protocol over stdin/stdout (analyze, capabilities, shutdown), including protocol versioning, newline framing, timeouts, and subprocess security.
• openspec/specs/metrics-schema/spec.md — the ModuleGraph JSON interchange schema the adapter must produce.
• openspec/specs/universal-metrics-model/spec.md — the metric definitions, and the requirement that each adapter document its abstract/concrete and LCOM field mappings.

Target audience: engineers adding support for a new language (for example the Python adapter, zero-dot-force/vibe-check#9, or a future Rust adapter), including authors who do not write Go and will integrate via the external JSON-RPC protocol.

Suggested structure:

1. Choose an integration path: in-process Go Adapter vs external JSON-RPC subprocess.
2. Implement the contract (interface methods, or JSON-RPC handlers for analyze/capabilities/shutdown).
3. Declare capabilities and emit partial status plus warnings for unsupported metrics.
4. Produce a schema-valid ModuleGraph (schemaVersion, language, warnings, status).
5. Document the abstract/concrete type mapping and LCOM field mapping for the language.
6. Handle the security contract: path validation, environment sanitization, response and stderr size limits.
7. Register and run the adapter end to end.

Prerequisites / sequencing: best authored once a reference adapter ships. The Go adapter (zero-dot-force/vibe-check#2) has now shipped in v0.1.0 (PR zero-dot-force/vibe-check#21), so examples can be grounded in working code.

Owner: content team (The Scribe / The Herald). This issue tracks the opportunity only; it does not write the tutorial.

Related:

• vibe-check analyze — Go-native package-level coupling metrics zero-dot-force/vibe-check#2 (Go adapter — shipped in v0.1.0)
• rattler — Python coupling adapter for vibe-check zero-dot-force/vibe-check#9 (Python adapter)
• docs: Create README.md and CHANGELOG.md for initial metrics package release zero-dot-force/vibe-check#18 (docs: README/CHANGELOG — closed; shipped in PR fix: replace 6 stale Hivemind references with Dewey #21)
• blog announcement — moved to this repo as blog: Announcing Vibe-Check — Martin Metrics for Go Codebases #276 (original blog: Announcing Vibe-Check — Martin Metrics for Go Codebases zero-dot-force/vibe-check#19 closed)
• Archived change: zero-dot-force/vibe-check → openspec/changes/archive/2026-08-31-universal-coupling-model/

Filed by The Curator (documentation and content pipeline triage) during spec-review verification.

---

Recreated from zero-dot-force/vibe-check#22 by an AI agent.