Pr To Spec

The flight envelope for agentic coding.

CodeRabbit reviews for humans. pr-to-spec converts for agents.

Turn any code change — a GitHub PR, a local branch, staged edits — into a structured, agent-consumable spec with intent drift detection. CLI and MCP server — use it from the terminal or as a plugin in Claude Code, Cursor, and Windsurf.

What It Does

declare intent → make changes → pr-to-spec check → agent sees clean/drift/high-risk

1. Declare intent: Tell pr-to-spec what you're building, what scope is allowed, and your risk ceiling
2. Make changes: Work normally in your branch
3. Check drift: pr-to-spec check --json produces a structured spec + drift signals
4. Agent consumes: Any agent reads the envelope and acts accordingly

Quick Start

Local Diff (no GitHub needed)

# Analyze your current branch vs main
pr-to-spec scan --branch main --json

# Analyze staged changes only
pr-to-spec scan --staged --json

# Analyze last 3 commits
pr-to-spec scan --diff 3 --json

Intent + Drift Detection

# 1. Declare what this change is supposed to do
pr-to-spec intent set \
  --goal "Add rate limiting to API" \
  --scope "src/middleware/**" \
  --forbid "src/db/**" \
  --max-risk medium \
  --type feature

# 2. After making changes, check for drift
pr-to-spec check --json
# exit 0 = clean, exit 2 = high-risk, exit 3 = drift detected

# Show current intent
pr-to-spec intent show

GitHub PR Analysis

# Analyze a GitHub PR
pr-to-spec --repo owner/repo --pr 42 --json | your-agent review

# Extract just the risk flags
pr-to-spec --repo owner/repo --pr 42 --json | jq '.spec.risk_flags'

# Feed to Claude for review
pr-to-spec --repo owner/repo --pr 42 --json \
  | claude --print "Review this spec and decide: approve, request changes, or needs info"

MCP Server

pr-to-spec ships an MCP server for IDE integration. When installed as a Claude Code plugin, these tools are available automatically.

Tools

Plugin Installation

Install as a Claude Code plugin:

claude plugin add jeremylongshore/pr-to-spec

Or add to your project's .mcp.json:

{
  "mcpServers": {
    "pr-spec-analyzer": {
      "command": "node",
      "args": ["path/to/dist/servers/pr-spec-analyzer.js"]
    }
  }
}

Agent Protocol

All --json output is wrapped in the agent protocol envelope:

{
  "version": 1,
  "command": "check",
  "status": "drift_detected",
  "exit_code": 3,
  "signals": [
    {
      "type": "forbidden_touch",
      "description": "1 forbidden file(s) modified",
      "severity": "high",
      "details": ["src/db/schema.ts"]
    }
  ],
  "spec": { ... },
  "intent": { ... }
}

Exit Codes

Drift Signals

CLI Reference

pr-to-spec (analyze a GitHub PR)

Options:
  --repo <owner/name>      GitHub repository (required)
  --pr <number>            Pull request number (required)
  --out <directory>        Output directory (default: ./output)
  --token <token>          GitHub token (or set GITHUB_TOKEN env var)
  --format <format>        Output: yaml, markdown, json, both (default: both)
  --stdout                 Print to stdout instead of files
  --quiet                  Suppress logging
  --field <path>           Extract a single field (dot notation)
  --json                   Shorthand for --format json --stdout --quiet
  --comment                Post spec summary as a PR comment
  --ai-enhance             Enhance spec with AI-generated insights
  --debug                  Log API requests, git commands, and timing
  -V, --version            Show version
  -h, --help               Show help

pr-to-spec scan (analyze local changes)

Options:
  --branch <ref>           Base branch to diff against (default: main)
  --diff <n>               Diff last N commits
  --staged                 Analyze staged changes only
  --out <directory>        Output directory (default: ./output)
  --format <format>        Output: yaml, markdown, json, both
  --stdout                 Print to stdout
  --quiet                  Suppress logging
  --json                   Shorthand for --format json --stdout --quiet
  --field <path>           Extract a single field

pr-to-spec intent (manage intent declaration)

Subcommands:
  set                      Set the intent for this project
  show                     Show the current intent
  analyze                  Analyze assumptions and surface decisions
  approve                  Approve the current intent (draft → approved)
  lock                     Lock the current intent (approved → locked)
  gate                     Evaluate intent gate policy

intent set Options:
  --goal <text>            What this change is trying to achieve (required)
  --scope <glob...>        Expected file globs (repeatable)
  --forbid <glob...>       Forbidden file globs (repeatable)
  --max-risk <level>       Maximum acceptable risk: low, medium, high
  --type <type>            Expected change type: feature, bugfix, refactor, etc.
  --size-budget <n>        Max total lines changed
  --json                   Output as JSON