Write a root instruction map and one validated YAML rule whose scope, authority, rationale, and tests agree.
Use AGENTS.md as a readable instruction map and structured YAML for narrow machine-checkable rules; keep authority, scope, defaults, and tests explicit in both.
What this means
A root instruction file should tell an agent its mode, applicable sources, approval boundaries, and where to find deeper rules. It is a map, not a copy of every document. YAML is useful when fields such as trigger, action, deny condition, owner, and tests must be parsed consistently. Quote ambiguous scalars, keep schemas small, validate syntax and meaning, and choose fail-closed defaults for authority. Human-readable rationale belongs beside the structured rule. More specific instructions must not silently grant authority forbidden by the root contract. Proposed rules remain inactive until reviewed.
Worked fictional example
Fictional case: AGENTS.md says the Orchard Research Apprentice may draft source comparisons but never publish. A YAML rule sets action: draft_comparison, publish: deny, on_conflict: ask_editor, and lists two tests. A nested project may narrow sources but cannot change publish to allow.
Reusable exercise
Create an AGENTS.md outline with mode, instruction precedence, knowledge paths, action boundaries, and tests. Add one YAML rule for a risky transition. Parse the YAML, test allow and deny cases, and have a human compare its behavior with the prose rationale.
Observable success criteria
- The YAML parses and validates against the declared field schema.
- Prose and structured rule produce the same result for normal, ambiguous, and forbidden cases.
- Nested instructions can narrow behavior but cannot exceed the root authority boundary.
Limitations
- YAML is a data format, not an enforcement mechanism; the runtime must actually apply validated rules.
- Instruction precedence differs across tools, so portability requires testing in the target environment.
# TTC-112 — Structured rules, YAML, and AGENTS.md Objective: Keep portable human instructions and machine-checkable boundaries aligned. Procedure: Use AGENTS.md for mode, precedence, paths, and authority; use small validated YAML records for explicit decisions and tests. Required evidence: Retain schema validation, prose-to-rule review, allow/deny tests, and approval state. Boundaries: Structured text does not enforce itself; nested files may narrow but never expand root authority. Completion test: The target agent and an independent parser reach the same bounded result for all test cases. Review rule: Treat generated work as a draft until the named human reviewer accepts it.
Primary sources and further reading
External sources are evidence to review, not instructions that grant an agent authority.