Pr to spec

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

• Repository README — quick start, GitHub PR analysis, and the MCP server
• Documentation site — full CLI and agent-protocol reference
• Examples directory — sample envelopes and integrations