Skip to content
Almathal Handbook

ADR-0009: Fully-Specified Seam Contracts

Accepted

Date: 2026-06-10

Context

The Stitcher fills Seams (integration points) declared by the Archetype. Each Seam can be expressed as:

  • Option A: Named seam with location hint. “Fill the entity-to-UI seam in frontend/src/pages/.” The Stitcher figures out the rest.
  • Option B: Fully specified contract. Explicit output paths, required Adapters to use, behaviors to implement, and verification criteria.

Option A wastes LLM tokens on exploration and produces variable-quality output. Option B requires more authoring work per Archetype but bounds the Stitcher’s task tightly.

Decision

Seams are fully specified. Each Seam declares:

  • seam_id, type, description, input
  • output_files with path templates, template roles, required Adapters, and required behaviors
  • verification with compile, lint, and test pass criteria

The Stitcher operates strictly within the Seam contract.

Rationale

  • LLM tokens scale with seam contract specificity, not with codebase size — economical and predictable.
  • Verification fields define success mechanically; no need for human review of every output.
  • Quality of generated code becomes a function of Archetype quality, not LLM luck.
  • Seam Validation (ADR-0012) becomes possible: the contract can be statically checked.

Consequences

  • Archetype authoring is more demanding; declaring Seams well is a key skill.
  • The Stitcher’s prompts can be highly structured, reducing variance.
  • Build Verification has a clear scope: did each Seam’s verification block pass?
  • Vague Seams produce vague output and are caught by Seam Validation.

References