Skip to content
Almathal Handbook

ADR-0018: LLM-Drafted, Human-Directed Manifest Authoring

Accepted

Date: 2026-06-10

Context

Writing Manifests by hand is slow. Writing Manifests purely by LLM without human oversight risks quality drift, incorrect provenance, and bad capability declarations. The right model evolves with system maturity.

Decision

Manifest authoring follows a graduated trust model:

  1. Early stage (first ~30 Manifests per language slice): LLM-drafted, human-directed. The platform team directs the LLM tightly on each Manifest — specifying which library, providing reference Manifests, reviewing every field. This establishes the quality bar and discovers edge cases.

  2. Mature stage (after the initial corpus exists): LLM-drafted, human-reviewed. The LLM produces full draft Manifests based on research; humans review key fields (license, security, capabilities) before admission.

  3. Future (post-MVP, with monitoring): Agent-ratified for low-risk updates. Minor version bumps of well-established Adapters can be admitted by agents with post-hoc human sampling.

Provenance and security fields (license, CVE scan, signature verification) are always verified mechanically regardless of authoring stage.

Rationale

  • Quality is established before scale: human-directed early authoring sets the standard.
  • LLM productivity is leveraged: humans focus on judgment, agents handle volume.
  • Trust scales gradually: agent autonomy is granted only after proof of consistency.
  • Mechanical verification protects against authoring errors at all stages.

Consequences

  • The Curation Pipeline includes explicit authoring workflows per stage.
  • Quality metrics on Manifests are tracked (defects per Manifest, human-correction rate).
  • Promotion criteria for moving from one stage to the next are documented.
  • The Capability namespace governance (ADR-0019) intersects: Capability proposals follow a parallel process.

References