Skip to content

ADR-0013: Thin, replaceable builder behind a three-clause contract

Status: Accepted — product brief (2026-06); confirmed 001-walking-skeleton; amended by 006 (engine selected) and 007 (the platform's build plane, not the builder, commits) Principles served: VII, I, VI Source: docs/design.md D1; specs/001-walking-skeleton/research.md D-8; .specify/memory/constitution.md Principle VII

Context

AI app builders are a commodity layer moving at ecosystem pace; competing head-on with Lovable, Bolt, and the hyperscalers is a losing race and contradicts the product's reframing: the governed lifecycle plane is the product, not the builder. Tend still needs a builder for the prompt-to-app experience, so the question is how to take one without being captured by it.

Decision

v1 integrates an existing open-source AI builder through a thin adapter rather than writing one. The builder's only contracts with Tend are three clauses: talk to the inference gateway, commit to the app repo, never deploy directly — and, since the 007 build plane, never holding a git credential either: the platform's own plane commits the generated tree and stamps the provenance trailers, deliberately never trusting them to the engine. Builder selection ran as a falsification spike (feature 006) and concluded in August 2026 with the OpenHands Software Agent SDK; the walking skeleton could run end to end with either the selected builder or a minimal stub satisfying the adapter contract. The constitution binds this further: Tend must not take on a dependency that raises builder switching cost beyond the contract, and must keep two candidate builders viable.

Alternatives considered

  • Build a proprietary AI builder as the core product — rejected: commodity layer, losing race against Lovable/Bolt/hyperscalers, contradicts the reframing of the product as the governance plane.
  • Direct builder→model calls — rejected: bypasses the boundary gateway.

Consequences

Builder UX quality rides the OSS ecosystem's pace, and switching cost is contained by the narrow contract — builder churn is a recorded product risk mitigated exactly this way. Provenance originates in the platform's plane rather than in the builder — the chain hard-fails without the trailers, so they are not the engine's to supply. Historically the adapter is where builder-side provenance originates: it records prompt-hash and model commit trailers that the build pipeline lifts into attestations (ADR-0005). The contract also got narrower over time, not wider: builder authentication moved to standard OIDC (ADR-0011), reducing the bespoke surface a replacement builder would need to implement.