gabrielmoreira 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-specCLI 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
--forbidpattern, 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-riskceiling. Review thesignalsarray 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