AI RPI Protocol

Make AI coding assistants instantly more reliable

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.

Autonomy Posture

AI-RPI is an engineering exoskeleton by default. When explicitly asked and authorized by the user, it can shift into a more autonomous execution posture for suitable work.

This direction is inspired by Ralph: iterative step/phase execution, explicit verification at each step, and fresh-eyes validation passes to reduce false confidence between iterations.

In practice, AI-RPI keeps autonomy conditional, not assumed:

• exoskeleton by default
• authorized autonomy only with explicit user authorization
• deterministic validation and guardrails still apply before "done" claims

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.

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:

• Act as Mission Control — coordinate subagents for research, implementation, verification, and review instead of doing everything in one pass
• 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 PRD-driven execution for non-trivial work — each feature gets a PRD with built-in verification, implemented by subagents, verified by fresh-eyes subagents
• Track delivery state so multi-step work doesn't lose progress or coherence
• 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
• Suggest code review at completion and spawn a multi-agent review if accepted

The point is pr