Skip to content
Almathal Handbook

Manifest Authoring

Accepted

This document describes the process for authoring Manifests — the JSON descriptors for Adapters and Modules that live in the central registry. The process follows the graduated trust model established in ADR-0018.

Authoring Stages

Manifest authoring evolves with system maturity. Three stages:

Stage 1: LLM-Drafted, Human-Directed

When: First ~30 Manifests per language slice.

Process:

  1. A platform team member identifies the target library or service
  2. The team member directs an LLM to draft the Manifest, providing:
    • The specific library name and version
    • Reference Manifests for similar Adapters (template-based authoring)
    • Specific requirements (which Capabilities to declare, which Contract to implement)
  3. The LLM produces the draft
  4. The team member reviews every field, corrects errors, refines Capabilities
  5. Mechanical checks run (see below)
  6. The Manifest is admitted

Purpose: Establish quality bar. Discover edge cases. Build the reference corpus future stages depend on.

Stage 2: LLM-Drafted, Human-Reviewed

When: After the initial corpus exists; Manifest authoring needs to scale.

Process:

  1. An agent (or the LLM directly) drafts a full Manifest based on research: upstream documentation, similar Adapters in the registry, library introspection
  2. A Human Reviewer reviews key fields:
    • Identity (slug correct, version current)
    • License (matches upstream, SPDX correct)
    • Security (no open CVEs, signature verified)
    • Capabilities (correctly declared, no fabricated IDs)
    • Provenance (audit trail entry added)
  3. Mechanical checks run
  4. The Manifest is admitted

Purpose: Increase throughput while preserving trust.

Stage 3: Agent-Ratified for Low-Risk Updates

When: Post-MVP, after Stage 2 has proven consistent.

Process:

  1. For low-risk updates (minor version bumps of well-established Adapters, well-defined categories), an agent fully ratifies the Manifest update
  2. A human samples a random subset of agent-ratified updates each week
  3. Patterns of error trigger reverting that category back to Stage 2

Low-risk means: patch or minor version bumps of Adapters in active lifecycle status, in categories with at least 20 prior Manifests, with no changes to declared Capabilities or Contracts, and clean automated checks.

High-risk updates (new categories, security-critical Adapters, breaking changes, Capability changes) remain at Stage 2 indefinitely.

Mechanical Checks (All Stages)

Run automatically on every Manifest submission. Block admission on failure:

CheckTool / Method
License declaration matches upstreamLicense scanner against SPDX
No open CVEs against the declared versionCVE scanner (Trivy, Grype, OSV)
Signature verification (when applicable)GPG/Sigstore verification
JSON Schema validation against Manifest schemaJSON Schema validator
Capability IDs exist in the central registryLookup in Capability namespace
Contract IDs exist in the central registryLookup in Contract namespace
UUID is unique across the registryDatabase constraint
Slug is unique within type and namespaceDatabase constraint
Source coordinates resolveFetch test against Maven/npm/PyPI/OCI
Compatibility declarations don’t contradict existing onesGraph consistency check

Manifest Templates by Type

To accelerate authoring, the platform maintains starter templates per category. Examples:

  • templates/adapter-manifest/persistence.json — boilerplate for persistence Adapters
  • templates/adapter-manifest/llm-provider.json — boilerplate for LLM provider SDKs
  • templates/module-manifest/auth.json — boilerplate for auth Modules

Authors copy a template and fill in specifics rather than starting from a blank Manifest. Templates encode the typical fields, common pitfalls, and reference patterns.

Roles

RoleResponsibilities
Human ReviewerReviews and ratifies Stage 1 and Stage 2 Manifests. Samples Stage 3 outputs.
Author (human or agent)Drafts Manifests under the appropriate stage’s process.
CuratorMaintains the Capability namespace; reviews new Capability proposals.
Security ReviewerReviews high-risk Manifests (cryptography, auth, payments) regardless of stage.

A single platform team member may hold multiple roles in the early days; roles are conceptually separate to support scaling.

Promotion Criteria

A language slice or category moves from Stage 1 to Stage 2 when:

  • At least 25 Stage 1 Manifests have been admitted in the slice or category
  • The Manifest defect rate (corrections required during review) has dropped below 10%
  • Reference Manifests exist for the major patterns in that slice or category

A category moves from Stage 2 to Stage 3 eligibility when:

  • At least 50 Stage 2 Manifests admitted in the category
  • No security or correctness issues traced to authoring in the prior 60 days
  • The category’s Adapters have stable Capability declarations (no namespace churn)

Promotion is approved by the platform engineering lead.

Manifest Update Workflow

When an upstream library releases a new version:

  1. An agent detects the new release (via release feeds, GitHub watches, registry polling)
  2. The agent drafts an updated Manifest (incrementing identity.version)
  3. Mechanical checks run on the new version
  4. Stage 2 or Stage 3 process applies depending on the category
  5. The updated Manifest is admitted; the previous version remains in the registry for historical reference
  6. Generated apps continue to resolve correctly because they reference specific versions (lockfile-style)

Authoring an Adapter Manifest: Walkthrough

A worked example: authoring adapter:java/spring-data-jpa@3.2.4:

  1. Identify target: Spring Data JPA, latest stable release 3.2.4
  2. Copy template: Start from templates/adapter-manifest/persistence.json
  3. Fill identity: ID, UUID (newly generated), version, source (Maven coordinates)
  4. Declare capabilities: crud, transactions, pagination, query-dsl with appropriate sub-fields
  5. Declare contracts: contract:persistence/repository/v1 with Java binding
  6. Fill compatibility: Requires Spring Boot 3.x, Java 17+, compatible with Hibernate 6.x
  7. Fill provenance: Apache-2.0 license, verified at admission, CVE scan clean, audit trail entry
  8. Fill integration: Imports, build dependency snippet, typical usage pattern, common pitfalls
  9. Fill lifecycle: Status active, added_at, maintenance signals
  10. Run mechanical checks
  11. Submit for review (Stage 2)
  12. Reviewer approves → admitted

The whole process takes 30–60 minutes per Adapter in Stage 2 (down from several hours in Stage 1 as the team learned the format).