Skip to main content
AI/MLjeremylongshore

pr-to-spec

Analyze code changes and detect intent drift using pr-to-spec CLI

Stars
2,267
Source
jeremylongshore/claude-code-plugins-plus-skills
Updated
2026-05-31
Slug
jeremylongshore--claude-code-plugins-plus-skills--pr-to-spec
View on GitHubRaw SKILL.md

// install — copy + paste into any project

mkdir -p .claude/skills && curl -fsSL https://raw.githubusercontent.com/jeremylongshore/claude-code-plugins-plus-skills/HEAD/plugins/mcp/pr-to-spec/.claude/skills/pr-to-spec/SKILL.md -o .claude/skills/pr-to-spec.md

Drops the SKILL.md into .claude/skills/pr-to-spec.md. Works with Claude Code, Cursor, and any agent that loads SKILL.md files from .claude/skills/.

pr-to-spec Skill

Overview

Convert code changes into structured, agent-consumable specs with intent drift detection. The workflow is: declare what a change is supposed to do (intent set), make the changes, then check — the CLI produces a spec of what actually changed plus drift signals against the declared intent, wrapped in a versioned JSON envelope any agent can consume.

Prerequisites

  • The pr-to-spec CLI on PATH (it ships with this plugin; standalone install and MCP-server usage are covered in the repo README).
  • A git repository with something to analyze — a branch diverging from main, staged edits, or recent commits.

Usage

/pr-to-spec scan

Analyze current branch changes vs main and output a structured spec.

pr-to-spec scan --branch main --json

Use --diff N to scan last N commits, or --staged for staged changes only.

/pr-to-spec check

Scan current changes AND check for drift against declared intent.

pr-to-spec check --json

Returns exit code 3 if drift is detected, 2 if high-risk, 0 if clean.

/pr-to-spec intent set

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

/pr-to-spec intent show

Show the current intent declaration.

pr-to-spec intent show --json

Output format

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

{
  "version": 1,
  "command": "check",
  "status": "drift_detected",
  "exit_code": 3,
  "signals": [...],
  "spec": {...},
  "intent": {...}
}

The spec field is the structured description of what changed, intent is the declared intent (when one exists), and signals carries the drift and risk findings that produced the status and exit_code.

Error Handling

Interpret exit codes — they are the contract:

Code Meaning
0 Clean — no issues
1 Error
2 High-risk changes detected
3 Drift detected
  • Exit 3 (drift) — the change touched files outside the declared scope, hit a --forbid pattern, or diverged from the declared goal. Stop and investigate before continuing; either fix the change or re-declare intent deliberately.
  • Exit 2 (high-risk) — the change exceeds the declared --max-risk ceiling. Review the signals array for which risk flags fired.
  • Exit 1 (error) — the CLI itself failed (not a git repo, no intent declared for check, malformed arguments). The message on stderr says which; fix the invocation rather than the code.

Examples

Full declare → change → check loop:

pr-to-spec intent set --goal "Add rate limiting to API" --scope "src/middleware/**" --forbid "src/db/**" --max-risk medium
# ...make the changes...
pr-to-spec check --json    # exit 0 = clean, 2 = high-risk, 3 = drift

Wire it into a project's CLAUDE.md so every significant change runs the loop:

## Change Validation

Before any significant code change:
1. Set intent: `pr-to-spec intent set --goal "..." --scope "..." --max-risk medium`
2. After changes: `pr-to-spec check --json` — exit 3 means drift, investigate before continuing

Resources