Open Standard · Agent Configuration · v1.0 Draft

One context.
Every agent.

Stop maintaining CLAUDE.md, .cursorrules, AGENTS.md and eight other vendor-specific files. Write your project context once — every AI tool reads it.

Generate your .herald/ →BreaGG/Herald
How it works

Three steps to
agent-ready.

01
01

Run the generator

Answer a few questions about your project, tools, and conventions. Under two minutes.

Open wizard →
02
02

Download your .herald/

Get a ZIP with your manifest, context, skills, and permissions — ready to drop in any repo.

03
03

Every agent reads it

Any HERALD-compatible tool picks up .herald/ automatically. One source of truth, forever.

See compatibility →
Etymology · Name · Purpose

Why Herald?

In antiquity, the herald was the inviolable messenger — carrying official word between armies, cities, gods. Their message was always delivered.

.herald/ works the same way. It arrives first. Every tool trusts it.

Etymology · Name · Purpose

Why Herald?

In antiquity, the herald was the inviolable messenger between worlds — armies, cities, gods. Their word was always delivered. .herald/ works the same way.

H
HierarchicalLayers load at the right moment
Layered context. Each layer loads at precisely the right moment — no waste, no gaps.
E
EnvironmentYour full stack, codified
Your project's complete environment, codified. Stack, conventions, architecture, intent.
R
RulesOne source of authority
Explicit rules that travel with the code. Every agent reads the same source of authority.
A
AndConnects tools, replaces none
The bridge. Herald doesn't replace your tools — it connects them. One to many.
L
LayerStart minimal, grow deliberately
Five distinct layers, each serving a purpose. Additive. Start minimal, grow deliberately.
D
DefinitionA spec, not a suggestion
Precise, machine-readable definitions. A standard, not a convention. A spec, not a suggestion.
The Fragmentation Problem
Without Herald — 8 files, 8 formats
CLAUDE.mdClaude Code only
.cursorrulesCursor only
.github/copilot-instructions.mdCopilot only
GEMINI.mdGemini CLI only
.windsurfrulesWindsurf only
.clinerulesRoo Code only
.junie/guidelines.mdJetBrains only
.kiro/steering/Kiro only

Every tool added, every context change — multiplied by eight.

With Herald — one folder, every tool

One folder.
Any agent.

✦Single source of truth, version-controlled
✦Progressive context loading — no waste
✦Works with today's tools and tomorrow's
✦SKILL.md compatible skills
✦Explicit, auditable permissions
✦Open standard — no vendor, no lock-in
Specification

Five layers.
One folder.

Additive. Start with context/ only. Add layers as your project matures.

I
context/
What your project is and how it works

Architecture, conventions, rules. Everything an agent needs before touching a file.

always loaded
II
skills/
Reusable capabilities, invoked on demand

Reusable capabilities your agents invoke. Fully SKILL.md compatible.

on activation
III
commands/
Named tasks that run across every tool

Named single-shot tasks — slash commands that work across every AI tool.

on invocation
IV
agents/
Reviewer, tester, writer — defined once

Named subagents with precise roles: reviewer, tester, docs-writer.

on invocation
V
permissions/
Allow/deny, committed, auditable

Allow/deny rules in git. Auditable, version-controlled, explicit.

always loaded
.herald/ — folder structure
your-project/
└AGENTS.md← fallback
└.herald/
└main.yaml← manifest
└context/
└project.md
└skills/
└create-component/SKILL.md
└commands/
└deploy.md
└agents/
└reviewer.md
└permissions/
└policy.yaml
CLI · No install required

One command.
All vendor files.

The Herald CLI compiles your .herald/ into every vendor format — CLAUDE.md, .cursorrules, copilot-instructions.md and more.

bash
$npx herald-agents init
# scaffold .herald/ interactively
$npx herald-agents compile all
# generate every vendor file
$npx herald-agents compile claude
# → CLAUDE.md only
$npx herald-agents validate
# check against spec
$npx herald-agents status
# inspect what's missing
Repository · CC0 · Public Domain

Everything is open.

Fork it. Implement it. Build on it. The spec belongs to everyone.

spec/v1/↗

Spec v1.0

Formal spec. Layers, manifest, conformance levels B1–B6.

schemas/↗

JSON Schemas

Machine-readable validation for main.yaml, policy.yaml.

examples/↗

Examples

Production configs for Next.js, FastAPI, Go. Copy-ready.

compatibility/↗

Compatibility

Zero-conflict coexistence with AGENTS.md, CLAUDE.md.

herald-cli/↗

CLI Source

TypeScript CLI: init, compile, validate, status.

docs/↗

For Tool Builders

Detection algorithm, conformance, B1 minimum viable.

View full repository — BreaGG/Herald
Compatibility

Works with every tool.

Add .herald/ without touching existing config files.

Claude CodeCursorGitHub CopilotGemini CLIWindsurfZedCodexKiroRoo CodeJetBrains JunieTraeAiderFirebase Studioany agent →

Progressive disclosure

Tier 1
Always loaded
Manifest + context + permissions at session start.
~200 tokens
Tier 2
On activation
Full skill body when the agent matches the current task.
< 5k tokens
Tier 3
On demand
Reference files only when the skill explicitly needs them.
zero if unused
Get started — no account required

Your project,
agent-ready.

Generate your .herald/ config, commit it, and every AI tool reads from the same source of truth — forever.

Generate your config →View on GitHub