adaptive-manifest-schema

Canonical MANIFEST.toml schema for the Adaptive Interfaces ecosystem.

Part of the Adaptive Interfaces ecosystem.

Introduction

Every Adaptive Interfaces repository includes a MANIFEST.toml that declares its identity, scope, dependencies, provided artifacts, and tooling configuration. This repository defines and validates that schema.

adaptive-manifest-schema has no upstream Adaptive Interfaces dependencies. All other repos in the ecosystem depend on it. It is the foundation layer.

Scope: Included

• The canonical MANIFEST.toml schema definition (schema/manifest-1.toml)
• A CLI validator (adaptive-manifest validate)
• Field definitions, types, and invariants for all schema sections
• Cross-field validation rules including agent safety field enum enforcement
• A Python library for reading and validating manifests programmatically

Scope: Excluded

• Repo scaffolding or generation tools
• Convention file management
• CI workflow templates
• Schemas specific to other organizations (SE, civic-interconnect, etc.)

Safety

Agents working in codebases can cause serious harm when given permissions beyond what a task requires. A known failure mode is an agent that understands a constraint but overrides it under goal pressure. The constraint must be architectural, not just instructional.

This schema encodes a read-generate-review cycle as the architectural checkpoint:

• Agents read files and produce artifacts.
• Humans review before anything is applied.
• No agent has autonomous write access to production systems.

The [agent] section in every MANIFEST.toml declares this posture explicitly:

[agent]
conformance = "https://github.com/adaptive-interfaces/adaptive-conformance-specification"
skill = "SKILL.md"
permissions = "read-generate"
checkpoint = "human-review-required"
scope = "this-repo-only"
stop_on_ambiguity = true

The validator enforces allowed values for permissions, checkpoint, and scope. Conservative defaults apply when fields are omitted. Omitting [agent] entirely does not grant additional permissions. See DECISIONS.md D-006 for full rationale.

Contents

• API Reference - auto-generated from src/adaptive_manifest_schema/

Command Reference

Show command reference

In a machine terminal

Open a machine terminal where you want the project:

git clone https://github.com/adaptive-interfaces/adaptive-manifest-schema

cd adaptive-manifest-schema
code .

In a VS Code terminal

# uv cache clean # if corrupted
uv self update
uv python pin 3.15
uv sync --extra dev --extra docs --upgrade

uvx pre-commit install

git add -A
uvx pre-commit run --all-files
# repeat if changes were made
git add -A
uvx pre-commit run --all-files

# validate schema source of truth (this repo only)
uv run adaptive-manifest validate-schema --strict

# validate repo MANIFEST.toml against schema (also used downstream)
uv run adaptive-manifest validate --strict

# do chores
uv run python -m pyright
uv run python -m pytest
uv run python -m zensical build

# build package artifacts
uv run python -m build

# validate package metadata
uv run python -m twine check dist/*

# confirm wheel contains runtime schema artifact
uv run python -c "import pathlib, zipfile; wheels=list(pathlib.Path('dist').glob('*.whl')); assert wheels, 'No wheel found'; wheel=wheels[-1]; names=zipfile.ZipFile(wheel).namelist(); print([n for n in names if n.endswith('manifest-schema.toml')]); assert 'adaptive_manifest_schema/manifest-schema.toml' in names"

# save progress
git add -A
git commit -m "update"
git push -u origin main

Agent Usage

This repository is structured for agent-assisted maintenance. Read these files in order before generating any artifact:

1. MANIFEST.toml - repository contract and agent configuration
2. SKILL.md - operating guide and interface contract
3. DECISIONS.md - design rationale
4. AGENTS.md - workflow requirements
5. AGENT_CONDUCT.md - behavioral constraints

Documentation

Documentation Site

See also

• CHANGELOG.md
• CITATION.cff

License

MIT © 2026 Adaptive Interfaces