i noticed the problem the third time i updated the same sentence across four different files. the sentence was simple: "this project uses typescript strict mode." it lived in CLAUDE.md, in .cursorrules, in .github/copilot-instructions.md, and in GEMINI.md. four tools, four formats, four maintenance surfaces. the same thought, written four times, for four different audiences that are all, fundamentally, trying to do the same thing: understand my project.
Herald started there. not from a thesis about standards, but from the fatigue of repetition.
the agentic tooling space has exploded in the last year. claude code, cursor, copilot, gemini cli, windsurf, kiro, roo code , the list grows monthly. each tool is genuinely useful. each tool also has its own convention for how you communicate your project's rules, architecture, and intentions to it. most of these conventions are just markdown files with different names in different locations.
the problem is not that these files exist. the problem is that they represent the same knowledge, fragmented. every new tool you adopt means a new file to create. every architectural decision you update means a new round of edits. every convention you refine drifts, slightly, across each file, until the tools are operating from subtly different mental models of your project.
this is not a catastrophic failure. it is a slow erosion. and slow erosions are the hardest kind to notice.
in ancient greece, the herald was the trusted messenger between worlds. between armies. between cities. between gods. heralds were inviolable , their message was always delivered, always trusted, always first. they did not carry their own opinion. they carried the official word of whoever sent them.
the word itself comes from old french herault, rooted in the frankish hariwald , from hari, army, and wald, rule or command. the herald was, etymologically, the one who commanded the army's voice. not a soldier. not a general. the intermediary. the one whose presence guaranteed safe passage and whose words carried institutional weight regardless of who was listening.
i chose the name because the analogy is almost exact. .herald/ arrives before any agent touches your code. it carries your project's official word: the architecture, the conventions, the rules, the intent. every tool reads from the same source. no translation required.
Herald defines a folder, not a file. .herald/ sits at the root of your project and organizes context into five layers. context/ holds the foundational knowledge: what the project is, how it's structured, what conventions it follows. skills/ holds reusable capabilities your agents can invoke , compatible with the existing SKILL.md standard. commands/ holds named single-shot tasks, the equivalent of slash commands that work across every tool. agents/ holds named subagents with precise roles: a reviewer, a tester, a documentation writer. permissions/ holds allow and deny rules, committed to git, auditable, explicit.
each layer is additive. you can start with only context/ and a main.yaml manifest. the system degrades gracefully. it does not demand completeness before it is useful.
one of the constraints i cared about from the beginning was token cost. a context file that loads ten thousand tokens at session start is not a feature. it is a tax. Herald addresses this through tiered loading. the manifest and context/ load always, at around two hundred tokens. skill bodies load only when the agent's task matches the skill. reference files load only when the skill explicitly needs them. if a skill goes unused, it costs nothing.
the philosophy here is that good context is precise context. not comprehensive. not exhaustive. precise.
Herald does not ask you to abandon your existing tooling. the CLI , npx herald-agents compile all , reads your .herald/ source and generates every vendor file your tools expect. CLAUDE.md, .cursorrules, copilot-instructions.md, GEMINI.md, all of them. you edit once. you compile once. the tools receive what they expect.
this is the same mental model as a build system. you do not hand-edit your dist/ folder. you write source, you compile output, you trust the process.
Herald is not just a folder structure. it is a specification. version 1.0 defines conformance levels from B1 to B6, a machine-readable schema for main.yaml, detection algorithms for tool builders, and a compatibility layer that coexists with AGENTS.md and other existing conventions without conflict.
i wrote it as a spec because i believe the problem is not mine to solve alone. if the tooling ecosystem is going to converge, it needs a shared language. the spec is that language. the CLI is just one implementation of it.
Herald is not a product with a backend. it is not a service you subscribe to. the spec is CC0 , public domain. the generator runs entirely in the browser, client-side, no data sent anywhere. the CLI requires no account, no token, no registration. if Herald disappears tomorrow, your .herald/ folder still works. the files are plain text. the manifest is readable yaml. the knowledge belongs to you.
i am skeptical of tools that make themselves indispensable by holding your data. Herald is designed to be forgettable in the best sense: you use it once, commit the folder, and never think about vendor formats again.
the agentic era is early. the conventions are still forming. there is a window, right now, where the cost of establishing a shared standard is low and the benefit is high. Herald is my attempt to contribute something to that window: a simple, open, vendor-neutral format that puts the knowledge back where it belongs , in your repository, under your control, readable by anything.
the name felt right from the start. the herald arrives first. it carries the official word. it does not take sides. it does not belong to any one party. it serves whoever sends it.
that is exactly what i wanted.
you can generate your own .herald/ here and explore the spec here.
the virtuous life is
- a. r. brea written 03/11/26