Agent minimum-context protocol — find before deriving — How any AI agent operates on this repo with minimum upfront token cost. Read knowledge/_navigation.md FIRST. Grep before writing. Terse self-contained files. [[wikilinks]] for chaining. Commit knowledge same-turn. Plus a cookbook of recurring tasks with entry-point file paths.
2025 agents.md discipline — tight context, knowledge bundle, don't drift to 2026 yolo — User locked the 2025 mindset on 2026-06-23: AGENTS.md stays short + sharp, knowledge/ is the brain, every concept gets a file. Reject the 'just let agents figure it out from context' 2026 yolo for non-toy projects. For oriz family this means: AGENTS.md ≤200 lines pointing at README.md and knowledge/, never inline rules in AGENTS.md if a knowledge file exists, prune stale knowledge weekly, treat context as a precious limited resource.
Karpathy guidelines — surface uncertainty, clean orphans, goal-loop execution — ACTIVE every coding task. State assumptions before acting. Surface ambiguity via MCQ. Clean imports you orphaned. Define success criteria + loop. Overlapping sections (no defensive code, surgical changes, match style) cross-ref to Ponytail — not restated.
Auto-grill on architectural decisions — Before any multi-file architectural choice (storage, auth, deploy, payments, framework, data model), agents MUST run the grill skill or its inline equivalent (3–4 ranked-recommendation questions via AskUserQuestion). Decision must be locked into knowledge/decisions/ before code lands. Locked 2026-06-23 in response to user explicitly choosing the auto-grill cadence. Compounds with self-update-on-every-decision: grill produces the decision, that rule files it.
Grill the user on every new input that contradicts existing knowledge — Whenever the user's latest message contradicts, narrows, widens, or reverses a decision already in knowledge/, the agent must explicitly call out the delta, ask the user to confirm whether to overwrite knowledge or treat as one-off, and only then act. Latest user input is the source of truth ONLY after explicit confirmation.
Grill on LOC removal >= 50 lines per sweep (TIGHTENED 2026-06-22 evening) — TIGHTENED 2026-06-22 evening: threshold dropped from 1000 LOC → 50 LOC. When a dedup/refactor/cleanup sweep removes ≥50 lines of code in a single agent action, the agent MUST surface this as a delta, ask the user MCQs about what was removed + why, offer restoration paths, and confirm before deleting. Reason: 50-LOC sweeps can hide substantive functional removal (an entire component, a route, a feature). Design pattern consolidation safe ONLY after grill; content/feature deletion NEVER safe without grill.
Grill-to-knowledge — every grill-me answer lands in knowledge/ — When the user invokes grill-me or runs a sequence of design questions, EVERY locked answer (question stem + chosen option + rejected options + 'why') MUST land in knowledge/ in the same conversation. No locked answer may live only in chat history. The conversation context is the audit trail; the decision file is the durable truth.
Keep knowledge fresh — read first, write current truth, delete obsoletes — Every session reads knowledge before acting, writes decisions into knowledge as CURRENT TRUTH (not historical logs), and deletes obsoleted content same-turn. Knowledge files are snapshots of what IS, not journeys of how we got here.
Loop engineering — how agent loops should be structured — ReAct (Thought-Action-Observation) is the default loop. Tool-call budgets per class (read-only 50, mutating 10, sub-agent spawn 5). Halt conditions are explicit, not emergent (goal-met, budget-exceeded, repeated-state, tool-fails-3x, user-interrupt, context >80%). Observation summarization for outputs >200 lines / binary / repeated. Context-shrink on 2nd repeat failure, halt + grill on 3rd. PEVR for multi-file architectural work; evaluator-optimizer for quality-driven tasks.
Always Read a file before Edit — Always Read a file in the current session before calling Edit. The harness enforces this; the rule restates the why so agents don't fight it — it prevents stale-match failures and accidental clobbering.
Self-update on every decision (durable info only) — Every durable architectural / naming / stack / external-fact decision the user makes in chat MUST be reflected in knowledge/ before the conversation ends. But DO NOT write count bumps, migration timestamps, step logs, or restatements of the diff — those waste tokens and add noise. Capture only what future-you cannot easily re-derive from code + git history.