# Agent Tradition > Give AI coding agents durable institutional memory: purpose, falsifiable beliefs, narrative lessons, and hook-enforced session accountability, so each session makes the next one smarter instead of starting blind. - Skill: `ariaxhan/agent-tradition` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add ariaxhan/agent-tradition` - Raw SKILL.md: https://api.skillmd.com/api/skills/ariaxhan/agent-tradition/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: ariaxhan (https://skillmd.com/u/ariaxhan) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/ariaxhan/agent-tradition --- # Agent Tradition: institutional memory for AI coding agents ## What this is A small, portable `_meta/` layer you drop into any repo. It gives an AI agent the three things a new teammate would get on day one but an agent normally never gets: **why this project exists, what we currently believe works, and the scars from everything we already tried.** Plain text files, version-controlled, read at the start of work and written at the end. No service, no database required. ## The problem it solves: agent amnesia Every session, a coding agent wakes up with zero memory. It re-derives the same architecture, re-proposes a rejected approach, re-walks a wall someone already bruised on, and re-learns a lesson that cost real hours last week. The intelligence is high; the *continuity* is zero. Tradition is the continuity layer: the part of the mind that persists when the session ends, so judgment compounds instead of resetting to blank every time. ## The five-file vocabulary Five files under `_meta/`, each answering a different question. Together they're the institutional memory; apart, each changes a specific decision. - **telos.md: WHY this repo exists.** One or two stable sentences of purpose (not goals, not tasks). Changes in years, not weeks. It's the spine: it anchors every other file and tells an agent what "good" is even aimed at. Example: *"A billing service whose single job is to never double-charge a customer."* - **ethos.md: HOW work behaves unsupervised.** Character, not rules. The disposition an agent brings before any specific rule applies: skeptical, evidence-seeking, minimal, honest about failure. Inherited and rarely edited. Where a rule is silent, ethos decides. Example: *"Verify live; 'committed' is never 'done.'"* - **doctrine.md: current FALSIFIABLE beliefs.** Each entry is a standing bet: **belief · confidence · evidence · what would falsify it · review date.** This file is *supposed* to change. The discipline is the falsifier: *an entry with no falsifier is faith, not doctrine.* Example: *"Postgres advisory locks are enough for our concurrency, falsified if we see a double-write under load test."* - **canon/: narrative memory.** Preserved *stories* of failures, breakthroughs, and precedents, kept with their **context, conflict, and consequence**, not flattened to a one-line rule. A rule says "don't delete that folder"; canon keeps *why someone did, what it cost, and how it was recovered*, so the judgment transmits, not just the prohibition. If it fits in one line, it belongs in doctrine, not here. - **phronesis.md: distilled judgment.** Practical wisdom extracted ONLY from patterns that **recurred across multiple sessions**: one case is an anecdote, not phronesis. Every entry carries its own **"danger of overgeneralizing"** counter-indication, so the wisdom doesn't harden into dogma. Example: *"Audit the premise before executing, but don't re-litigate well-specified, low-stakes asks."* ## The commission → chronicle work loop Wrapped around substantial work are two units that turn a session into a reusable record: - **Commission** (written BEFORE): the work order. Scope, granted authority, desired outcomes-as-end-states (not a step recipe), boundaries, and how "done" gets verified live. It grants authority and context, then leaves the path to the agent. If you're writing every step, you're writing a plan, not a commission. - **Chronicle** (written AFTER): the honest "what actually happened" account: attempted, changed, **verified-live**, failed, deferred, and any disagreements with the ask. Not a success report; it must survive a future reality audit. The disagreements and failures are the most valuable part, because that's what the next agent inherits. ## How to make it stick: hooks, not honor-system Prose rules drift under load: an agent skips the file it was "supposed" to read. So the loop is **hook-enforced**, not aspirational. Three hooks (full spec in `reference/adoption.md`): 1. **SessionStart: surface.** Prints the telos chain and points the agent at ethos + doctrine + canon before any source work. The tradition can't be invisible. 2. **PreToolUse (Write|Edit): commission-scaffold.** On the first *source* edit of a session with no active commission, auto-creates a commission stub. No wall; it always allows the edit, it just refuses to let work start untracked. 3. **Stop: chronicle-gate.** A session that changed source **cannot end** until a chronicle exists. This is the load-bearing one: it's what forces memory to actually get written instead of evaporating with the context window. ## How to adopt it in your repo 1. Create `_meta/` with the five files. Generic fill-in-the-blank templates for all five (plus commission + chronicle) are in **`reference/adoption.md`**, copy them and replace the bracketed parts. 2. Add the three hooks to `.claude/hooks/` and register them in `.claude/settings.json` (SessionStart / PreToolUse `Write|Edit` / Stop). The hook bodies + registration JSON are in `reference/adoption.md`. 3. Fill in `telos.md` first: it's the spine; the hooks key off its presence. 4. Seed `ethos.md` and `doctrine.md` from the baseline templates; leave `canon/` and `phronesis.md` empty. They earn their entries from real sessions. 5. Commit `_meta/`. Never gitignore it: untracked memory is unrecoverable memory. ## What NOT to do - **Don't flatten canon into rules.** A one-line "don't do X" loses the context that makes the judgment transferable. Keep the story. - **Don't write doctrine without a falsifier.** No "what would prove this wrong" = it's faith; move it to ethos or delete it. - **Don't promote one case to phronesis.** Wait for the pattern to recur, and always attach the danger of overgeneralizing. - **Don't let it become a note-hoard.** A file never read at the moment it would change a decision is rot. Every entry earns its place by changing behavior, or it's pruned. - **Don't write a chronicle that's all wins.** If nothing failed and nothing was deferred, you're hiding something the next agent needs. - **Don't rely on honor-system reading.** If a behavior must hold, it's a hook, not a sentence.