ETHOS.md | NVIDIA NeMo Platform

ETHOS.md is the intent layer for a production agent. It’s a simple, open standard for detecting and resolving divergence between developer intent and agent execution.

The goal of ETHOS.md is to transform scattered intent into a shared contract that builders, reviewers, and optimizers can use. Code shows implementation. Ethos is the only place that records mission, constraints, success and failure, and what may change.

Why it exists

Critical agent context lives outside the codebase: business objectives, developer intent, success and failure criteria, and safe modification boundaries. Humans rarely write all of that down. An optimizer that only sees code and traces cannot tell a real failure from a trade-off you already accepted.

Without an Ethos, every new agent has to rediscover that context, and automated changes are aligned to whatever the traces happen to show. With one, the same file can steer a new build, guide a review of logs and evals, reveal divergence from intent, and keep an optimization loop inside human-set bounds.

Scattered context, one contract

Intent arrives in pieces:

The codebase — files, docs, configs, and logic. This is what the agent does today.
Traces and logs — telemetry, errors, and metrics. This is how a run looked, not whether that look was acceptable.
Business goals — objectives, value, and the result the agent is accountable for.
Developer intent — tone, priorities, and the judgment calls that never made it into a ticket.
Constraints — limits, policies, and guardrails no change may cross.

ETHOS.md is the portable snapshot of that contract. Write the intended state, not only the implemented one. Where they differ, say so.

What it unlocks

It unlocks	Meaning
Portable context	Every builder, reviewer, and optimizer starts from the same file instead of reconstructing intent from the repo.
Shared contract	Humans and agents agree on purpose, bounds, and what counts as divergence.
Spec-driven creation	Purpose, goals, and expected behavior are explicit before code exists, so implementation follows intent instead of inferring it later.
Safe changes	Optimization agents know what they may change, what needs approval, and what they must not touch.
Recursive updates	As you clarify intent while reviewing a change or an Insight, the Ethos absorbs it. The file is meant to stay current; a stale Ethos steers the next loop the wrong way.

Change Scope is the machine-readable part of “safe changes”: each lever is yes (allowed), no (must not change), or with-approval.

Ethos is not `AGENTS.md`

The two files serve different agents.

	`AGENTS.md`	`ETHOS.md`
When it matters	Any repo a coding agent should navigate	When the repo, or a package in it, is an agent
Job	How to contribute: layout, conventions, commands	Intent, goals, and constraints — the PRD layer optimization agents need
Typical location	Repository root	Next to the agent (`agents/<agent-name>-ethos/ETHOS.md` on NeMo Platform)

What’s in the file

A Markdown file with front matter. Section bodies stay human-readable; the headings are the outline other agents parse.

Section	Captures
`Role`	What the agent does, in one concrete sentence.
`Purpose & Outcomes`	Why it exists, and the result it is judged by.
`Scope`	Who it serves, in-scope work, and boundaries.
`Tools`	APIs, tools, and knowledge sources it can use.
`Harness`	How this agent actually runs.
`Behavior`	Rules, tone, refusals, and policies.
`Principles`	How to decide when no rule in `Behavior` covers the case.
`Success Criteria`	What good production behavior looks like.
`Trade-offs`	Hard gates, priority order, and unacceptable regressions.
`Constraints`	Limits no optimization may cross.
`Evaluation Setup`	How it is tested and measured.
`Metric Semantics`	What metric names actually mean, and the claims they do not support.
`Change Scope`	What optimization agents may modify.
`Vision`	Where the agent is headed, beyond today’s scope.
`Open Questions`	Unknowns to resolve.

Creating an ETHOS.md

On NeMo Platform, invoke the nemo-explore skill to learn about your agent, and gather intent through some Q&A, then nemo-ethos writes agents/<agent-name>-ethos/ETHOS.md. You can also author the file by hand. See Plugins and Skills.