2025 agents.md discipline — tight context, knowledge bundle, don't drift to 2026 yolo

rule Tue Jun 23 2026 00:00:00 GMT+0000 (Coordinated Universal Time) ruleagents-mdknowledgecontext-managementdiscipline

Rule: 2025 agents.md discipline

What

For this repo and the oriz family:

AGENTS.md stays =200 lines. It POINTS at README.md (canonical entry) and knowledge/index.md (canonical brain). It does NOT inline rules that have their own knowledge file.
Every multi-decision concept gets its own file in knowledge/rules/<slug>.md, knowledge/decisions/<slug>.md, or knowledge/runbooks/<slug>-YYYY-MM-DD.md.
Each markdown front-matter follows the OKF v0.1 spec (knowledge/_okf.md).
Context is precious. Adding a rule means deleting another, or splitting an existing one. The total agent-context payload should be measured, not assumed.
Stale knowledge gets PRUNED, not preserved out of politeness. If a decision is superseded, mark it status: superseded and link the successor.

Why

User pasted the 2025-vs-2026 mindset debate 2026-06-23 and locked the 2025 mindset for this project. Direct quote: "I think it's more nuanced than this... at least for now, I suggest the same for you... for larger projects, I like to be all over it."

This project is NOT a toy. It is the oriz family — 60+ submodules, paying-user infra, family-level cohesion via shared chrome and design tokens. The 2026 "let it hang out" approach is appropriate for a first-person shooter built in a weekend. It is not appropriate here.

How to apply

Before adding to AGENTS.md, ask: does this belong in knowledge/rules/, knowledge/decisions/, or knowledge/runbooks/? If yes, write it there + add a one-line pointer in knowledge/index.md.
When making a decision, write the decision file FIRST, then code from it. Don't write code-then-doc.
Treat AGENTS.md updates as expensive. Every line there is loaded into every agent's context on every invocation across 60 repos.
Run the agents-md-sync skill periodically to dedupe overlapping rules across claude.md / agents.md / gemini.md if the project ever adds those formats.
When pruning: a knowledge file marked superseded for >30 days can be deleted entirely if its successor has absorbed the relevant content. Git history is the durable backup.

How NOT to apply

DON'T let AGENTS.md grow past 200 lines. If it does, it's a smell — extract sections to knowledge/.
DON'T duplicate rules across AGENTS.md and knowledge/rules/*.md. The knowledge file is the source of truth; AGENTS.md points at it.
DON'T preserve stale knowledge "just in case". The "just in case" is git history.
DON'T add a knowledge/ file for one-off decisions that won't recur. The bar is "would a future agent need this to make a similar decision again."

Cross-refs

README.md is the canonical entry — see README.md.
The knowledge brain index — see knowledge/index.md.
Format spec for files in knowledge/ — see knowledge/_okf.md.
Companion rule on filing every locked decision — see [[self-update-on-every-decision]].
Companion rule on confirming knowledge deltas — see [[confirm-knowledge-deltas]].