pr-to-spec

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

Tool	Description
analyze_pr	Analyze a GitHub PR and generate a structured spec
scan_local	Scan local git changes (branch, staged, commits)
check_drift	Check changes against declared intent for drift
set_intent	Declare what a code change should accomplish
show_intent	Show the current intent declaration
analyze_assumptions	Surface implicit decisions with 2x2 matrix

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

Code	Meaning
0	Clean — no issues
1	Error
2	High-risk changes detected
3	Drift from declared intent
4	Gate policy failed

Drift Signals

Signal	Trigger
scope_creep	Files changed outside expected_scope
forbidden_touch	Files matching forbidden_scope were modified
risk_escalation	Detected risk level exceeds max_risk
size_overrun	Total LOC changed exceeds size_budget
type_mismatch	Inferred change type doesn't match expected_type

---

CLI Reference

pr-to-spec (analyze a GitHub PR)