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

The guidance schema contract is an XML-style structural block inside 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 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. 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. 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 (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 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 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), 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 – Contains the <guidance_schema_contract> block (lines 15–25) that lists required sections and references the external schema.
• docs/guidance-schema.md – The canonical schema definition referenced on line 16 of AGENTS.md, providing detailed validation rules and type definitions.
• 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 using Node.js and Python.

Node.js Extraction

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

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 file.

Summary

• The guidance schema contract in oh-my-codex is an XML-wrapped block within 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 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.

Where is the canonical schema definition located?

The authoritative schema definition resides in docs/guidance-schema.md, as referenced on line 16 of the 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—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 to add domain-specific overlays, provided they do not interfere with the mandatory structural elements defined in the <guidance_schema_contract> block.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}