Ethos Orchestrate

<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->

<!-- SPDX-License-Identifier: Apache-2.0 -->

Ethos orchestrate

Purpose

Help a developer create and maintain their agent's ETHOS.md. Route each request to the narrow sub-flow that owns it, and carry what is already known into that sub-flow so the user is never asked twice.

Continue from prior context

When a user or another workflow supplies an earlier Ethos conversation, reuse the selected repository, agent, file location, and requested operation. Skip the repeated opening and completed questions. Check that prior findings and answers still apply to this agent; distinguish source evidence from explicit user replies, retaining where each answer came from. Without usable prior context, use the standalone entry below.

Resume the earliest unfinished work. Missing or conflicting intent goes to ethos-explore; completed intent goes to draft review or ethos-write as needed. Before writing, recover the exact accepted draft and the user's confirmation. If either is unavailable or the draft changed, review the draft again while retaining completed answers. Review a suitable existing file without rewriting it. Reuse an earlier saved-content review only when the contents are unchanged, the confirmation applies to this agent, and current findings reveal no conflict.

On a pause or completion, report the file location, actual validation outcome, unresolved questions, and what the user confirmed or still needs to review. Carry relevant answers and draft context back to the invoking conversation or workflow, which owns any persistence. These skills write only ETHOS.md; they require no external state format. Missing validation or a required sub-flow must be reported as unfinished work, not completion.

Choose the entry route

For a continuation, use the context above. The following routing and opening apply to standalone requests.

Locate an existing file first: the user's path, otherwise ETHOS.md at the repository root or at the root of the selected agent's package.

find . -maxdepth 4 -iname ETHOS.md -not -path '*/.git/*' -not -path '*/node_modules/*' 2>/dev/null | grep . || echo "no ETHOS.md yet"

When several apply, take the earliest row that matches. A request phrased as "write the ETHOS.md" with no prior interview in this conversation still goes through ethos-explore: writing needs intent the code cannot supply.

Show the path ahead

For a fresh request to create an ETHOS.md, open with this checklist using literal - [ ] checkboxes, marking the first step We're here:

• [ ] Explore the agent — read its code and docs and draft what they establish.

• [ ] Confirm intent — answer a few questions the code cannot: purpose, principles, and vision.

• [ ] Review the draft — see the whole ETHOS.md and correct it.

• [ ] Save and validate — write the file, check it, and confirm the final contents.

End with "Ready to start?" and wait. On return visits, resume the earliest unfinished step instead of repeating the opening.

The standard

ETHOS.md records intent the user confirmed, not intent you inferred.

• Code, prompts, configs, and docs establish what the agent does today. They draft Tools, Harness, Evaluation Setup, and similar sections.

• Only the user establishes purpose, principles, vision, trade-offs, and constraints. An inferred answer is a draft to confirm, never a filled section.

• An honest _(none)_, recorded in Open Questions, beats a plausible guess.

• The bundled validator establishes structure: front matter, schema version, and the fourteen required sections. A file that validates can still be wrong; the user's review establishes that it is right.

Vocabulary

Sub-flows

Load the selected sub-flow skill when its step begins and follow it. This file carries the standard and the routing; the sub-flow carries the steps.

Boundaries

• Write only the ETHOS.md. Never edit the agent's code, prompts, configs, or evals. The file goes at the user's path or the repository root, and nothing is committed automatically.

• Preserve what exists. Keep custom sections, extra front-matter keys, author, and created_timestamp on edits.

• Capture intent without authorizing application changes. Do not ask optimization or change-permission questions in the interview, draft review, or completion checkpoint. Creating an ETHOS.md implies no follow-up to optimize or change the agent. If the user later requests such work, its workflow owns the permission decisions.

• Keep runtime safety requirements. Record behavioral constraints and approval requirements for actions the agent takes during operation, such as issuing refunds. These describe intended behavior, not permission to edit the application. Also preserve already-confirmed organizational safety and review policies and their known owners without reopening permission questions.

• No run settings. Spend caps, experiment counts, and per-run limits belong to the tool that runs them, not to ETHOS.md.

Communicating with the user

Do not assume the user knows the term. Before the first question, explain in a sentence or two that ETHOS.md records what the agent should do, what it should avoid, and what a good result looks like, and that people and agents working on the agent read it first. Make the explanation concrete for this agent. Reuse that explanation when it has already been given.

Ask one question per message, prefer multiple choice grounded in what the scan found, and always allow "I don't know". When reporting an existing file, lead with whether it validates and what it says the agent is for, then the gaps.

Prerequisites

A local checkout of the agent, or a description of a planned one. Validation needs Python 3.10+.

Limitations

ETHOS.md is a snapshot of intent; it does not prove the agent behaves that way. Measuring that belongs to evaluation tools.

Troubleshooting

• Several candidate files or agents: ask which agent the ETHOS.md describes.

• Validator unavailable: check the structure by reading the file against the template, and say the check was not run.

• User cannot state a concrete Role: stop, explain that the file is not useful without one, and offer to resume later.

Examples

Request: "Help me write an ETHOS.md for this support bot."
Route: ethos-explore, after the path-ahead checklist.
Deliverable: a reviewed, validated ETHOS.md at the repository root.

Request: "Add a no-PII rule to Constraints in our ETHOS.md."
Route: ethos-write, editing Constraints in place.
Deliverable: the updated file, validated, with the change shown for review.

Request: "We still have the ETHOS.md we wrote last month."
Route: this skill, checking the existing file.
Deliverable: the existing ETHOS.md with unchanged name and contents, validated.