pave
Documentation for the AI agent era. Structured, verifiable, and ready to be consumed by your robot overlords. π€
What is PAVED? π§±
PAVED is a documentation framework designed for the human+agent workflow. When AI agents need to understand, author, and maintain documentation, prose isn't enough. They need ground truth, constraints, examples, and verification.
P Purpose
What is this thing? What problem does it solve? 1-3 sentences. Include non-goals. Agents need to know boundaries. π―
A API / Interface
How do you use it? CLI commands, HTTP endpoints, config keys. Agents thrive on tables and schemas. π‘
V Verification
How do you know it's working? Golden commands, expected outputs, healthchecks. Without verification, agents hallucinate correctness. β
E Examples
Concrete copy-paste examples. Happy path, realistic path, failure path. Agents use examples as shape matching. π
D Decisions
Why this design? What must not change? Tradeoffs. This prevents agents from refactoring your intent away. π
Why pave? π
"Write docs like you're training a careful junior engineer who can run commands but can't read minds."
π Structured Templates
Scaffold new documentation with pave new. Components, runbooks, ADRs - all with the right sections already in place.
π€ Agent-Native Prompts
Generate AI agent prompts with pave prompt. Your project's rules, templates, and context - packaged for LLMs.
πΊοΈ Auto-Generated Index
Keep your docs navigable with pave index. Automatically scans, categorizes, and creates a doc map.
β Validation Rules
Enforce doc quality with pave check. Max lines, required sections, verification steps - all configurable.
Quick Start β‘
# Initialize pave in your project
pave init
# Create a new component doc
pave new component my-service
# Generate an index of all docs
pave index
# Validate your documentation
pave check