ADR-002: Scope and Deliverables

Defines HyperGen's scope as a protocol specification with lightweight reference implementation (Scope B).

Status: Accepted Date: 2026-03-28

Context

Open-source protocol projects face a fundamental tension between three scopes:

(A) Specification only — A document describing the protocol. Risk: "Does it actually work?" remains unanswered, leading to low adoption.
(B) Specification + lightweight reference implementation — A spec with minimal, copyable code proving it works. The shadcn/ui model: "use it as-is or as a starting point."
(C) Specification + production framework — A spec with a full SDK/library. Risk: becomes "yet another framework" — exactly what HyperGen opposes.

HyperGen adopts Scope (B): Protocol specification + lightweight reference implementation.

Deliverable	Description	Purpose
Protocol Specification	Formal definition of the HyperGen protocol: message format, streaming semantics, HTMX attribute conventions, security model, theming integration	The normative document. Implementations MUST conform to this.
Reference Client	Minimal browser-side code (~200 lines) that receives HyperGen streams and renders them	Proves the protocol works. Meant to be copied, not installed.
Reference Server Helpers	Minimal server-side utilities for generating HyperGen-compliant HTML streams	Optional convenience. Any HTTP server that outputs the right HTML works.
Examples	Working examples showing HyperGen with various agent frameworks (Claude, OpenAI, local LLMs)	Demonstrates agent-agnosticism in practice.
Documentation Site	Published docs covering spec, guides, ADRs, and examples	Primary entry point for developers.

No npm install hypergen package meant to be a long-term dependency
No framework-specific adapter packages (no hypergen-langchain, no hypergen-crewai)
No opinionated component library
No hosted infrastructure or SaaS

Optional, minimal client libraries MAY exist for languages like TypeScript, Python, Go, etc. These libraries:

MUST be simple enough to be understood in a single reading (~200-500 lines)
MUST be positioned as "reference implementations you can copy" rather than required dependencies
MUST NOT introduce framework-specific coupling
Developers MUST be able to implement the protocol from the specification alone, without using any library

Low barrier to entry. Developers can adopt HyperGen by reading the spec and writing a few lines of code.
No vendor lock-in. There is nothing to lock into — no package to depend on, no account to create.
Community implementations welcome. Third parties are free to build full-featured libraries on top of the specification. We celebrate this but do not gatekeep it.
Maintenance burden is low. Reference implementations are intentionally minimal, reducing the surface area for bugs and breaking changes.