pave

PAVED docs for the AI agent era

ADR: Use PAVED Framework for Documentation

Status

Accepted

Context

Traditional documentation approaches fail in AI agent workflows:

  • Large narrative documents are hard for agents to parse and retrieve from
  • Docs without verification steps lead to hallucinated correctness
  • Prose-heavy documentation lacks the structure agents need for accurate output
  • No enforcement mechanisms mean documentation quality degrades over time

We need a documentation framework optimized for human+agent pair work that provides structure, verifiability, and maintainability.

Decision

Adopt the PAVED framework for all project documentation:

  • Purpose: What is this? What problem does it solve? (1-3 sentences, include non-goals)
  • API/Interface: Entry points, commands, schemas, config keys
  • Verification: How to know it’s working - test commands, health checks, expected outputs
  • Examples: Concrete, copy-paste examples (happy path, realistic, failure cases)
  • Decisions: Why this design exists, what must not change, tradeoffs

Additionally:

  • Use atomic “leaf docs” (one concept per document) with index routing
  • Enforce validation rules via pave check
  • Require Verification and Examples sections in all documents
  • Limit documents to 300 lines (split if larger)

Consequences

Positive:

  • Structured docs are easier for agents to parse and work with
  • Verification sections enable agents to validate their changes
  • Small, atomic docs improve retrieval accuracy
  • Enforced rules maintain quality over time
  • Examples provide “shape matching” for accurate agent output

Negative:

  • Higher upfront effort to create documentation
  • All existing docs must be migrated to PAVED format
  • Requires tooling (pave) to enforce rules
  • Some docs may feel overly structured for simple concepts

Neutral:

  • Docs become more like code: versioned, validated, linted
  • Team must learn the PAVED structure

Alternatives Considered

Diataxis Framework

A documentation system with four quadrants: tutorials, how-to guides, technical reference, and explanation.

Why not chosen: Too narrative-focused. Diataxis optimizes for human learning journeys but doesn’t address agent retrieval or verification. The four-quadrant model creates larger documents that are harder to parse.

Plain Markdown

Simple, unstructured markdown files without enforced conventions.

Why not chosen: No structure enforcement means quality degrades over time. No verification requirements mean agents can’t validate their work. Lacks the consistent format agents need for reliable retrieval.

AsciiDoc

A text document format with richer semantics than Markdown.

Why not chosen: More complex syntax without proportional benefits for our use case. Smaller ecosystem of tools. The additional features (complex tables, includes, conditional content) aren’t needed for agent-native docs.

Sphinx/RST

Python documentation generator using reStructuredText.

Why not chosen: Python ecosystem specific. Heavy tooling for what we need. RST syntax is less familiar to developers. Optimized for API documentation generation rather than agent workflows.

Verification

Prerequisites: Install the Rust toolchain via rustup.

Verify the PAVED framework is properly configured:

# Validate all documentation follows PAVED rules
cargo run -- check

Expected: All checks pass with no errors.

Examples

Creating a New Component Doc

# Generate a new component document
cargo run -- new component "Authentication Service"

# This creates docs/authentication-service.md with PAVED sections

Validating Documentation

# Check a specific file
cargo run -- check docs/adrs/001-use-paved-framework.md

# Check all documentation
cargo run -- check

# Strict mode (warnings as errors)
cargo run -- check --strict

PAVED Section Example

A minimal PAVED document structure:

# Component Name

## Purpose
Brief description of what this component does.
Non-goals: what it explicitly does NOT do.

## Interface
- `command`: Description of the command

## Verification
Run `make test` to verify functionality.

## Examples
Example usage of the component.

## Decisions
Key architectural decisions and constraints.