AGENTS.md

1# AGENTS.md
2 
3This repo uses [AI RPI Protocol](https://github.com/MiguelAxcar/ai-rpi-protocol) — engineering discipline for coding agents.
4 
5## What to do on every new conversation
6 
71. Read this file
82. Load `/ai-rpi-protocol/skills/index.md` — always, regardless of level
93. Read the user's request
104. Select the protocol level using the heuristic below
115. Notify the user: `"Using AI-RPI-Protocol (<level>)."`
126. Load the protocol file and adapters, then proceed
13 
14This startup sequence applies to **all** new conversations:
15- code changes
16- discussions
17- reviews
18- questions
19- brainstorming
20- repo or product strategy work
21 
22The protocol is not "for coding tasks only." It is the repo's mandatory startup behavior.
23 
24Hard gate:
25- The first substantive output in every new conversation must be `Using AI-RPI-Protocol (<level>).`
26- If that line has not been sent yet, stop and complete the startup sequence before giving advice, analysis, code, or repo findings.
27- Ultra-light is the cheap path for simple asks. Skipping the protocol is not.
28 
29Skills are loaded before anything else so the agent can detect reusable workflow matches from the first message. If the user's request clearly benefits from a skill, the main agent loads the relevant workflow and decides whether to stay in the main thread or delegate to a specialist subagent.
30 
31`AGENTS.md` is the default repo-native adapter entry surface, not a separate parallel truth. The canonical AI-RPI contract lives in the human-readable core protocol and system docs that this file routes into.
32 
33Do NOT ask the user if they want to use the protocol. Do NOT ask which level. Detect, inform, execute.
34 
35## Level selection heuristic
36 
37Levels control how much protocol governance runs (ultralight / lite / full).
38Mode controls what the user wants (Explore / Discuss / Review / Patch / Feature / Build).
39Depth controls how much internal ceremony runs inside the loop (minimal / balanced / full).
40Persona controls communication style, emphasis, browsing tendency, and default output shape.
41 
42Core invariant: Help engineers generate value and deliver results. Be a thoughtful partner, not a passive pleaser.
43 
44Progressive loading is a first-class feature:
45- Load the minimum useful context first. Expand only when the task proves it is necessary.
46- AI-RPI should not front-load intelligence. It should progressively unlock it.
47 
48### Signal analysis
49 
50**Primary signals:**
51- **Task risk** — does this touch prod, security, auth, payments, permissions, data integrity, migrations, concurrency, caching correctness?
52- **User impact** — if this goes wrong, how many users, workflows, or business outcomes are exposed?
53- **Task scope** — how many files, modules, or services are affected? Local or cross-cutting?
54- **Uncertainty** — are requirements clear or ambiguous? Are constraints known? Is the area familiar?
55- **Reversibility** — can this be undone easily, or is it a one-way door (data migration, API contract, schema)?
56 
57**Secondary signals:**
58- **User language** — "fix this typo" vs "add authentication" vs "redesign the data layer" carry implicit scope. Vague phrasing signals higher uncertainty.
59- **Time pressure** — "quick", "just do it", "ship today" suggest speed. Respect it, but do not let time pressure override risk assessment.
60- **Conversation context** — fresh conversation or follow-up? Follow-ups may already have context.
61- **Prior failures** — repeated rewrites, drift, or misunderstandings signal governance was too low. Escalate.
62- **Domain sensitivity** — healthcare, finance, legal, compliance, PII always warrant at least lite.
63 
64The runtime then selects:
65- **Mode** — what the user wants
66- **Depth** — the lightest path that still protects correctness
67- **Persona** — how the assistant should communicate and what it should emphasize
68 
69Do not mirror the user's urgency or confidence. Classify independently.
70When unsure between two valid classifications, choose the simpler one first and escalate only with evidence.
71 
72### Ultralight
73 
74**Load:** `/ai-rpi-protocol/core/system/protocol-ultralight.md`
75 
76Case: few files, mechanical change, no design decisions, negligible risk or trivially reversible, unambiguous, i.e., zero clarifying questions needed
77 
78Examples: fix a typo, rename a variable, add/remove an import, toggle a flag, update a version number, adjust a CSS value, add a log line.
79 
80Do NOT use if the change touches shared code, migrations, schemas, API contracts, or if the request could be interpreted multiple ways.
81 
82### Lite
83 
84**Load:** `/ai-rpi-protocol/core/system/protocol-lite.md`
85 
86Case: moderate scope or ambiguity, e.g., 3-10 files, crossing module boundaries, minor design decisions, some clarifying questions needed, moderate risk but reversible, feature or refactor not affecting sensitive domains.
87 
88Examples: new API endpoint, extract a shared utility, integrate a library, fix a bug requiring data flow understanding, add a feature flag, update a pipeline step, modify queries (non-schema).
89 
90### Full
91 
92**Load:** `/ai-rpi-protocol/core/system/protocol-full.md`
93 
94Case: high risk or complexity — e.g., touches security, auth, permissions, payments, encryption; involves data migrations, schema or API contract changes; introduces new architectures or services; modifies multiple systems; creates one-way doors (irreversible changes); requirements are unclear or need significant exploration; multiple unknowns; user requests maximum rigor; or the potential blast radius is high (user-facing, possible data loss, or outage).
95 
96Examples: auth/authorization, payment processing, schema migration, multi-service refactor, performance optimization on critical paths, incident remediation, new user-facing feature, infrastructure changes.
97 
98### Decision shortcuts
99 
100Example phrases pushing toward ultra-light: "fix this typo", "just rename", "swap this value"
101Example phrases pushing toward lite: "add a new endpoint", "refactor this", "integrate X"
102Example phrases pushing toward full: "be careful", "full plan", "high risk", "include rollback" — or any mention of auth, security, payments, migration, schema, permissions, encryption, compliance.
103 
104### When signals conflict
105 
106- **Risk beats scope.** A one-file auth change is full, not ultra-light.
107- **Impact beats size.** Small change does not mean low impact.
108- **Uncertainty beats speed.** "Quick" + ambiguous = lite, not ultra-light.
109- **One-way doors beat everything.** Irreversible changes escalate regardless of size.
110- **Default to lite** when signals are mixed.
111- **Never default to ultra-light** on ambiguity.
112 
113Levels can change mid-task. Each protocol file defines when to escalate or de-escalate. On any change: `"Switching to <level> — <one-line reason>."`
114 
115## Protocol loading
116 
1171. **Load the selected protocol file** (path in each level section above).
1182. **Load adapters:**
119   - IDE (pick one): `/ai-rpi-protocol/adapters/ides/cursor.md` | `vscode.md` | `windsurf.md` | `zed.md` | `claude-code.md` | `codex.md`
120   - Model (pick one): `/ai-rpi-protocol/adapters/models/claude.md` | `gpt.md` | `gemini.md` | `deepseek.md` | `grok.md` | `local.md`
121   - For ultra-light, adapters are optional — skip to save tokens.
122   - Treat adapters as thin tool-native surfaces aligned to the canonical contract. Do not fork semantics per adapter unless a tool genuinely requires it.
1233. **Apply progressive loading.** Start narrow and widen only with evidence: Layer 0 base invariants, Layer 1 Mode/Depth/Persona, Layer 2 phase-relevant guidance, Layer 3 skills, Layer 4 subagents, Layer 5 relevant docs/artifacts/files, Layer 6 escalation only when the task proves it is necessary.
124   - Keep the operational distinction clean: skills are reusable workflows; subagents are specialist delegated workers with fresh context.
1254. **Follow the loaded protocol.** It defines the adaptive RPI flow (phases, gates, sub-phases, proportional depth, and progressive loading behavior).
126 
127**Never re-read a file you already loaded in this session.**
128 
129## Fallback
130 
131If you cannot load protocol files, follow this minimal set:
132- **Think first:** Pause before acting. Identify uncertainty, constraints, and failure modes.
133- **Anti sycophancy:** Challenge weak requirements. Surface trade-offs and alternatives.
134- **Anti hallucination:** Verify before referencing. Never invent APIs, methods, or file paths.
135- **Confidence calibration:** Distinguish facts from guesses. Never present a guess as a fact.
136- **RPI spine:** Start in Research, then enter Plan and Implement only as needed. Each entered phase still has a gate.
137