ai-rpi-protocol

# AI RPI Protocol

> Make AI coding assistants instantly more reliable

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Version](https://img.shields.io/badge/version-1.1.0-green.svg)](./CHANGELOG.md)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](http://makeapullrequest.com)

AI-RPI is a portable, repo-native workflow for coding agents.

You drop it into a repository, wire the entry surface your agent already reads, and the agent starts working with a stronger operating model: research before coding, challenge weak assumptions, adapt rigor to risk, validate before claiming done, and package results for the next human.

The goal is practical: fewer blind edits, fewer confident mistakes, cleaner reviews, and less rework.

Works across modern coding-agent workflows, including Codex, Claude Code, GitHub Copilot agents, Cursor, and similar repo-native environments.

## Why Teams Need This

Most AI coding failures are not syntax failures. They are reliability failures.

The agent moves too fast, assumes too much, agrees too easily, misses repo constraints, and produces plausible code before anyone has checked whether the framing was right. That is why small asks turn into rewrites, PR reviews turn into archaeology, and "fast" AI work burns tokens on repair loops instead of progress.

AI-RPI exists to make that behavior more reliable without turning everyday work into ceremony.

## What You Get

- **Research before code** so the agent looks at the repo before it starts freelancing
- **Challenge instead of yes-machine behavior** so weak ideas and missing constraints surface earlier
- **Adaptive rigor** so small fixes stay light and risky work gets more scrutiny
- **Validation before "done"** so passing prose is not mistaken for proof
- **Reviewable handoffs** so humans can quickly inspect what changed, what was verified, and what still needs attention

## Before And After

Without AI-RPI:

- ask for a PR review and get vague praise plus scattered nitpicks
- ask for a bug fix and get a cleanup campaign with weak grounding
- ask for a feature and get implementation before trade-offs are visible

With AI-RPI:

- the agent starts from Research and cites repo evidence
- the plan exposes trade-offs before implementation hardens
- validation and reviewer focus are part of the output, not an afterthought

## What It Is

AI-RPI is not trying to replace your model, IDE, CI, or engineering judgment. It gives those tools a clearer contract inside real repos.

## Try It In 60 Seconds

1. Add this repo to your project as `/ai-rpi-protocol`
2. Wire the root entry point your environment already respects:
   - **Most IDEs** (Cursor, VS Code, Windsurf, Zed): `cp /ai-rpi-protocol/AGENTS.md ./AGENTS.md`
   - **Claude Code** (CLI or VS Code extension): `cp /ai-rpi-protocol/CLAUDE.md ./CLAUDE.md`
3. Keep working in your normal environment

That is the quick profile. For bootstrap, health checks, upgrades, and team-oriented install methods, see [core/system/setup-lifecycle.md](./core/system/setup-lifecycle.md).

## Why It Converts Better Than Prompt Tweaks

Prompts help, but they reset too much work every session.

AI-RPI puts the workflow in the repo itself, so the discipline is portable, reviewable, and repeatable across sessions, people, and tools.

## Use It When

These are the five adoption scenarios AI-RPI is optimized to make clearer and safer:

1. **Understand a codebase or checkout flow**
   Ask the agent to trace a real flow. AI-RPI pushes it to inspect the repo first, map the path, cite evidence, and separate verified behavior from guesses.
2. **Review a colleague's PR**
   AI-RPI packages findings, confidence gaps, validation evidence, and reviewer focus instead of dumping an unstructured summary.
3. **Fix a small bug without over-ceremony**
   Narrow patches can stay narrow. The protocol still forces enough grounding to avoid the classic "tiny fix, surprising regression" pattern.
4. **Shape and implement a feature safely**
   The agent can explore options, surface trade-offs, and only then move into implementation with a reviewable execution path.
5. **Build a startup POC with discipline**
   You can move fast without fully dropping rigor: lighter artifacts, pragmatic defaults, and clearer founder, engineer, and stakeholder handoffs.

## What Changes After Install

Under the hood, your coding agent will now:

- **Start from Research** instead of guessing from the prompt alone
- **Challenge weak ideas** instead of acting like a yes-machine
- **Show real options** instead of fake alternatives around one preferred answer
- **Display evidence** with file paths and grounded repo context
- **Calibrate confidence** so verified facts and guesses do not sound the same
- **Adapt by mode and depth** so patches stay lean and risky work gets more scrutiny
- **Use deterministic guardrails** when the surface is risky enough that prose guidance is not sufficient
- **Package outcomes for humans** so engineers, reviewers, tech leads, PM-founders, and stakeholders get different kinds of summaries when they should

The point is practical: make AI coding assistants more reliable in the place that matters, your repo.

## Mini Case Studies

These are representative patterns from real coding-agent work, not vanity metrics.

### 1. Checkout-flow understanding

Without a protocol, "explain checkout" often becomes a shallow summary or a confident guess based on naming. With AI-RPI, the better outcome is a traced path: entry point, state transitions, pricing logic, failure paths, and explicit unknowns. That changes the follow-up conversation from "is this probably right?" to "which branch of the flow do we want to change?"

### 2. PR review that is actually reviewable

Unstructured AI review usually mixes nitpicks, speculation, and shallow praise. AI-RPI pushes review toward findings, evidence, confidence, and reviewer focus. The useful output is not "looks good overall". It is "here are the real risks, here is what was validated, and here is where a human reviewer should spend attention first."

### 3. Small bug fix without a mini rewrite

Agents often over-help. A small bug becomes a refactor because the model sees an opportunity to redesign. AI-RPI keeps bounded work bounded by default, but still forces enough repo grounding to avoid blind edits. That is the difference between a two-line fix and an unnecessary cleanup campaign.

### 4. Feature shaping before implementation drift

Feature work breaks when the agent starts coding before the trade-offs are visible. AI-RPI makes the agent clarify the scope, compare real approaches, and line up validation expectations before implementation hardens. That usually avoids the "technically correct, product-wrong" result.

### 5. Startup POC with cleaner founder handoffs

Startup teams often want speed and just enough rigor to stay sane. AI-RPI fits that mode well: lighter planning, stronger implementation discipline, and clearer packaging for founder updates, merge-readiness, and next-step ownership.

## Why AI-RPI Instead Of...

### Better prompts

Prompts are useful, but they reset too much work every time. AI-RPI encodes the workflow in the repo so the discipline survives across sessions, people, and tools.

### A prompt pack or instruction file only

Prompt packs help with wording. AI-RPI is broader: phase discipline, adaptive depth, validation model, guardrails, role-aware packaging, adapters, and memory handling.

### One vendor's agent workflow

Vendor-native workflows can be strong, but they are still vendor-native. AI-RPI is built to travel across repo-native surfaces without rewriting the whole operating model per IDE or model.

### Freeform vibe coding

Freeform prompting is great at feeling fast. It is much worse at staying grounded, reviewable, and transferable. AI-RPI is for teams that want AI help without betting quality on whoever typed the best

[truncated…]