prov

Provenance-first planning CLI for AI agent workflows

Prov creates and maintains an intent graph that tracks the complete provenance chain from high-level specifications through implementation decisions, plans, and code artifacts. When code becomes cheap to generate, the economics of software shift dramatically. Prov captures what matters most: the intent behind your system.

Philosophy

This project is inspired by The Phoenix Architecture, which argues that in an era of generative AI, code is no longer scarce—it's abundant, fast, and increasingly disposable. The true assets become specifications, evaluations, and decision records, not the implementation itself.

Core principles:

• Regenerable Systems: Components can be deleted and recreated from stored intent while maintaining behavior guarantees
• Provenance Over Code: Specifications, constraints, and decisions are the durable artifacts; code is derived
• Intent Graphs: Meaning is encoded in content-addressed graphs capturing requirements, constraints, plans, and decisions
• Evaluation-First: Behavior is specified through durable evaluations (property tests, invariants, contracts) that survive implementation changes

Installation

From npm

npm install -g @rengler33/prov

From source

git clone https://github.com/rengler33/prov.git
cd prov
npm install
npm run build

Single executable (Bun)

npm run build:bun
# Creates ./bin/prov - a standalone executable

Requirements: Node.js 18+

Quick Start

# Initialize provenance tracking in your project
prov init

# Create a specification via CLI (no manual YAML needed!)
prov spec create --name authentication \
  --title "User Authentication" \
  --intent "Handle user login and session management" \
  --req "login:Users can authenticate via OAuth2 or password" \
  --req "session:Sessions expire after 24 hours of inactivity"

# Create constraints via CLI
prov constraint create --name security \
  --title "Security Constraints" \
  --description "Security invariants for all code" \
  --inv "no-plaintext:Passwords must never be stored in plaintext:command:grep -r 'password.*=' src/"

# Or add existing YAML files
prov spec add spec/authentication.spec.yaml
prov constraint add constraints/security.constraints.yaml

# Create a plan derived from specs
prov plan create --from spec:authentication:v1 --with constraint:security:v1

# Execute plan steps and trace artifacts back to their origins
prov trace add src/auth/oauth.ts --to step:authentication:1

Core Concepts

Specifications

Declarative descriptions of what your system should do. Specs contain requirements that drive implementation.

# spec/authentication.spec.yaml
id: spec:authentication:v1
title: User Authentication
requirements:
  - id: req:auth:1
    description: Users must authenticate via OAuth2 or password
  - id: req:auth:2
    description: Sessions expire after 24 hours of inactivity

Constraints

Invariants that must always hold, regardless of which requirements are being implemented.

# constraints/security.constraints.yaml
id: constraint:security:v1
invariants:
  - id: inv:sec:1
    description: Passwords must never be logged or stored in plaintext
  - id: inv:sec:2
    description: All API endpoints must require authentication

Plans

Implementation roadmaps derived from specifications. Plans contain steps that can be executed and tracked.

prov plan create --from spec:authentication --title "Implement OAuth2"
prov plan show plan:abc123
prov plan next plan:abc123  # Get the next step to work on

Traces

Links between code artifacts and the plan steps (and ultimately specs/constraints) they implement.

# Trace a file to a plan step
prov trace add --file src/auth/oauth.ts --step plan:abc123:step-1

# See why an artifact exists
prov trace why src/auth/oauth.ts

# Scan for untraced files
prov trace scan

The Intent Graph

All entities form a directed acyclic graph (DAG) with cryptographic content addressing:

Specifications ──→ Requirements
       │                │
       ↓                ↓
Constraints ───→ Plans ──→ Steps ──→ Traces ──→ Artifacts
       │                      │
       ↓                      ↓
Invariants              Decisions

Declarative Creation

Instead of manually writing YAML files, you can create specs and constraints directly via CLI flags. This is especially useful for AI agents that may struggle with precise YAML formatting.

Creating Specifications

prov spec create --name my-feature \
  --title "My Feature Specification" \
  --intent "Describe what this feature does" \
  --req "init:Initialize the feature:setup completes;config loaded" \
  --req "run:Execute the main logic" \
  --dep "run:init"

Options:

• --name <name> - Spec name (lowercase alphanumeric with hyphens) (required)
• --title <title> - Human-readable title
• --intent <text> - Intent description
• --version <semver> - Semantic version (default: 1.0.0)
• --status <status> - Status: draft|active|deprecated|archived
• --req <req> - Add requirement: "id:description" or "id:description:acceptance1;acceptance2"
• --dep <dep> - Add dependency: "req-id:depends-on-id"
• --output <file> - Output file path
• --force - Overwrite existing file
• --no-register - Skip automatic registration in graph

Creating Constraints

prov constraint create --name security \
  --title "Security Constraints" \
  --description "Security rules that must always hold" \
  --inv "no-secrets:No hardcoded secrets:command:git secrets --scan" \
  --inv "no-eval:No eval usage:command:grep -r 'eval(' src/ && exit 1 || exit 0"

Options:

• --name <name> - Constraint name (lowercase alphanumeric with hyphens) (required)
• --title <title> - Human-readable title
• --description <text> - Constraint description
• --version <semver> - Semantic version (default: 1.0.0)
• --status <status> - Status: draft|active|deprecated|archived
• --inv <inv> - Add invariant: "id:rule:type:value" (type: command|test|assertion|manual)
• --output <file> - Output file path
• --force - Overwrite existing file
• --no-register - Skip automatic registration in graph

Commands

For the complete CLI reference with all options and examples, see docs/CLI.md.

Initialization

| Command | Description | |---------|-------------| | prov init | Initialize provenance tracking in current directory | | prov init --force | Reinitialize (recreates .prov/ directory) |

Specifications

| Command | Description | |---------|-------------| | prov spec create --name <name> [options] | Create a specification via CLI flags | | prov spec add <file> | Add a specification from YAML file | | prov spec list | List all specifications | | prov spec show <id> | Show detailed information about a spec | | prov spec update <id> --status <status> | Update spec status (draft|active|deprecated|archived) | | prov spec validate | Validate all specs against schema |

Constraints

| Command | Description | |---------|-------------| | prov constraint create --name <name> [options] | Create a constraint via CLI flags | | prov constraint add <file> | Add constraints from YAML file | | prov constraint list | List all constraints and invariants | | prov constraint check | Check constraint compliance |

Plans

| Command | Description | |---------|-------------| | prov plan create --from <spec-id> --title <title> | Create a new plan | | prov plan show <plan-id> | Show plan details and steps | | prov plan validate <plan-id> | Validate plan structure | | prov plan next <plan-id> | Get next incomplete step | | prov plan remaining <plan-id> | List remaining steps | | prov plan progress <plan-id> | Show completion progress |

Traces

| Command | Description | |---------|-------------| | prov trace add --file <path> --step <step-id> | Trace artifact to plan step | | prov trace show <file> | Show trace information for a file | | prov trace why <file> | Explain why an artifact exists | | prov trace scan | Find untraced files in project |

Graph

| Command | Description | |---------|-------------| | prov graph show | Display the intent graph | | prov graph export --format <dot\|json> | Export graph for visualization | | prov graph orphans | Find disconnected nodes |

Analysis

| Command | Description | |---------|-------------| | prov impact <entity-id> | Analyze impact of changes to an entity | | prov stale | Find artifacts that may be stale |

AI Agent Integration

| Command | Description | |---------|-------------| | prov agent context | Get context for AI agent consumption | | prov mcp | Start Model Context Protocol server |

Output Formats

All commands support multiple output formats:

prov spec list                    # Auto-detect (table for TTY, YAML for pipe)
prov spec list --format table     # Human-readable table
prov spec list --format yaml      # YAML for processing
prov spec list --format json      # JSON for programmatic use

MCP Server Integration

Prov includes a Model Context Protocol server for AI agent integration:

prov mcp

This exposes tools that allow AI agents to:

• Query the intent graph for context
• Create and manage plans
• Trace artifacts to their origins
• Check constraint compliance
• Identify stale or orphaned artifacts

MCP Configuration

Add to your MCP client configuration:

{
  "mcpServers": {
    "prov": {
      "command": "prov",
      "args": ["mcp"]
    }
  }
}

Architecture

┌─────────────────────────────────────┐
│      CLI Commands (commands/)        │
│  spec, constraint, plan, trace, etc  │
└────────────┬────────────────────────┘
             │
┌────────────▼────────────────────────┐
│    Intent Graph (graph.ts)           │
│  DAG of specs, plans, traces, etc    │
└────────────┬────────────────────────┘
             │
┌────────────▼────────────────────────┐
│    Storage Layer (storage.ts)        │
│  File I/O, locking, persistence      │
└────────────┬────────────────────────┘
             │
┌────────────▼────────────────────────┐
│    Core Types & Utilities            │
│  types.ts, hash.ts, output.ts        │
└─────────────────────────────────────┘

Key design decisions:

• Content addressing: All entities use SHA-256 hashes for change detection
• File-based storage: Graph persisted to .prov/graph.json for simplicity and git compatibility
• Strict typing: Full TypeScript with comprehensive type definitions
• Schema validation: Zod schemas ensure data integrity

Project Structure

.prov/                  # Provenance data directory (git-tracked)
├── graph.json          # The intent graph
└── mappings/           # File-to-trace mappings

spec/                   # Your specifications (YAML)
constraints/            # Your constraints (YAML)
plans/                  # Generated/managed plans

Development

npm run dev           # Watch mode compilation
npm run test          # Run tests in watch mode
npm run test:run      # Run tests once
npm run lint          # Lint code
npm run typecheck     # Type check without emitting
npm run docs          # Generate API documentation
npm run docs:watch    # Generate docs in watch mode

API Documentation

Generate API documentation from TypeScript source:

npm run docs

Documentation is output to docs/api/. Open docs/api/index.html in a browser to view.

Why Provenance?

When AI generates code, you need to know:

• What specification drove this implementation?
• Why was this decision made?
• What constraints must this code respect?
• What breaks if this spec changes?

Prov answers these questions by maintaining the complete derivation chain from intent to artifact. When your specs change, you know exactly which code needs regeneration.

License

MIT