# Guidance Schema Contract in oh-my-codex AGENTS.md: Required Sections Explained

> Understand the guidance schema contract in oh-my-codex AGENTS.md, detailing its six required sections to standardize agent behavior. Learn how it ensures robust and predictable agent execution.

- Repository: [Bellman/oh-my-codex](https://github.com/Yeachan-Heo/oh-my-codex)
- Tags: api-reference
- Published: 2026-04-03

---

**The guidance schema contract is an XML-style structural block inside [`AGENTS.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/AGENTS.md) that mandates six required sections—Role & Intent, Operating Principles, Execution Protocol, Constraints & Safety, Verification & Completion, and Recovery & Lifecycle Overlays—to standardize agent behavior across the oh-my-codex framework.**

The oh-my-codex repository defines a strict guidance schema contract that governs how every [`AGENTS.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/AGENTS.md) file must be organized. This contract ensures consistent agent orchestration by enforcing specific required sections and referencing an external schema definition at [`docs/guidance-schema.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/docs/guidance-schema.md). Understanding this contract is essential for anyone implementing or validating OMG (Oh-My-Codex) workspace configurations.

## What Is the Guidance Schema Contract?

The **guidance schema contract** is a structural definition embedded within the top-level operating document [`AGENTS.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/AGENTS.md). It lives inside a dedicated XML-style block demarcated by `<guidance_schema_contract>` tags and specifies the mandatory organizational framework that every agent configuration must follow.

According to the source code in [`AGENTS.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/AGENTS.md) (lines 15–25), this contract enumerates the exact sections required for compliance. It also references the canonical schema definition on line 16, pointing to [`docs/guidance-schema.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/docs/guidance-schema.md) as the single source of truth for detailed validation rules.

## The Six Required Sections in oh-my-codex AGENTS.md

The contract explicitly requires six specific sections that every [`AGENTS.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/AGENTS.md) implementation must provide. These sections define the operational boundaries and behavioral constraints for agents within the OMG framework.

### Role & Intent

This section requires a title and opening paragraphs that clearly state the agent’s designated role and its overall intent. It serves as the primary descriptor for what the agent is designed to accomplish within the workspace.

### Operating Principles

Wrapped in `<operating_principles>` tags, this section defines the core principles that guide the agent’s decision-making and behavioral patterns during execution.

### Execution Protocol

This section details the operational mechanics including delegation patterns, model routing strategies, the agent catalog, available skills, and the team-pipeline configuration. It functions as the technical blueprint for how tasks are distributed and processed.

### Constraints & Safety

This section specifies keyword detection mechanisms, cancellation handling procedures, and state-management rules that prevent unauthorized or harmful operations.

### Verification & Completion

Marked by `<verification>` tags and continuation checks inside `<execution_protocols>`, this section establishes the criteria for task validation and completion confirmation.

### Recovery & Lifecycle Overlays

This section reserves runtime-marker hooks for overlays such as `<!-- OMX:RUNTIME:START -->` and `<!-- OMX:RUNTIME:END -->` (found at lines 27–28 of [`AGENTS.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/AGENTS.md)), enabling dynamic state injection without violating the core contract.

## Source File Structure and Schema References

The guidance schema contract is implemented across three critical files that together enforce compliance:

- **[`AGENTS.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/AGENTS.md)** – Contains the `<guidance_schema_contract>` block (lines 15–25) that lists required sections and references the external schema.
- **[`docs/guidance-schema.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/docs/guidance-schema.md)** – The canonical schema definition referenced on line 16 of [`AGENTS.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/AGENTS.md), providing detailed validation rules and type definitions.
- **[`templates/AGENTS.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/templates/AGENTS.md)** – A scaffolding template that includes placeholder blocks for the contract, ensuring new workspaces initialize with compliant structure.

The contract also reserves specific XML comment markers for runtime overlays, allowing extensions to inject state between `<!-- OMX:RUNTIME:START -->` and `<!-- OMX:RUNTIME:END -->` without breaking the structural validation.

## Programmatically Parsing the Contract

Developers can validate compliance by extracting the contract block programmatically. The following examples demonstrate how to parse the required sections from [`AGENTS.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/AGENTS.md) using Node.js and Python.

### Node.js Extraction

```javascript
import fs from 'fs';
import path from 'path';

// Load the AGENTS.md file
const agentsPath = path.resolve(__dirname, '../AGENTS.md');
const agentsContent = fs.readFileSync(agentsPath, 'utf8');

// Extract the <guidance_schema_contract> block
const contractMatch = agentsContent.match(
  /<guidance_schema_contract>([\s\S]*?)<\/guidance_schema_contract>/
);
const contract = contractMatch?.[1].trim();

console.log('Guidance-Schema Contract:\n', contract);

```

This script loads the operating document and extracts the XML block containing the required sections list, enabling automated validation workflows.

### Python Validation

```python
import re, pathlib

agents_md = pathlib.Path("../AGENTS.md").read_text()

# Find the contract block

contract = re.search(r"<guidance_schema_contract>(.*?)</guidance_schema_contract>", 
                     agents_md, re.DOTALL).group(1)

required = [
    "Role & Intent",
    "Operating Principles",
    "Execution Protocol",
    "Constraints & Safety",
    "Verification & Completion",
    "Recovery & Lifecycle Overlays",
]

missing = [s for s in required if s not in contract]
if missing:
    print("Missing required sections:", missing)
else:
    print("All required sections are present.")

```

This Python implementation performs a sanity check to verify that all six mandated sections from the oh-my-codex guidance schema contract are present in the local [`AGENTS.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/AGENTS.md) file.

## Summary

- The **guidance schema contract** in oh-my-codex is an XML-wrapped block within [`AGENTS.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/AGENTS.md) (lines 15–25) that standardizes agent documentation structure.
- It mandates **six required sections**: Role & Intent, Operating Principles, Execution Protocol, Constraints & Safety, Verification & Completion, and Recovery & Lifecycle Overlays.
- The contract references **[`docs/guidance-schema.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/docs/guidance-schema.md)** as the authoritative schema definition for detailed validation rules.
- **Runtime overlays** use reserved markers (`<!-- OMX:RUNTIME:START/END -->`) defined at lines 27–28 to allow dynamic extensions without breaking the core contract.
- Tools like `omx explore` can programmatically parse this contract to verify workspace compliance before executing orchestration workflows.

## Frequently Asked Questions

### What happens if an AGENTS.md file misses a required section?

Missing any of the six required sections defined in the guidance schema contract violates the structural integrity of the OMG framework. Validation tools will flag the workspace as non-compliant, and orchestration agents may refuse to execute tasks until the missing sections—such as Operating Principles or Execution Protocol—are properly defined according to the schema in [`docs/guidance-schema.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/docs/guidance-schema.md).

### Where is the canonical schema definition located?

The authoritative schema definition resides in **[`docs/guidance-schema.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/docs/guidance-schema.md)**, as referenced on line 16 of the main [`AGENTS.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/AGENTS.md) file. This separation allows the guidance schema contract to remain a lightweight structural pointer while maintaining detailed validation logic in a dedicated documentation file that can be versioned independently.

### How do runtime lifecycle overlays work within the contract?

The contract reserves specific XML comment markers—`<!-- OMX:RUNTIME:START -->` and `<!-- OMX:RUNTIME:END -->` found at lines 27–28 of [`AGENTS.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/AGENTS.md)—to inject dynamic state information without altering the core document structure. These markers enable runtime systems to append temporary execution context while keeping the underlying guidance schema contract intact for static validation.

### Can I extend the guidance schema contract with custom sections?

While the contract strictly enforces the six required sections for base compliance, the Recovery & Lifecycle Overlays section explicitly provides extension hooks. Custom tooling can leverage the reserved runtime markers and the referenced schema in [`docs/guidance-schema.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/docs/guidance-schema.md) to add domain-specific overlays, provided they do not interfere with the mandatory structural elements defined in the `<guidance_schema_contract>` block.