# What Is the Role of AGENT_GUIDE.md in OpenMontage? The Complete Agent Contract Explained

> Discover the crucial role of AGENT_GUIDE.md in OpenMontage. This essential file defines agent behavior and mandatory workflows, ensuring a strict pipeline-first architecture for video composition.

- Repository: [Calesthio/OpenMontage](https://github.com/calesthio/OpenMontage)
- Tags: deep-dive
- Published: 2026-08-29

---

**[`AGENT_GUIDE.md`](https://github.com/calesthio/OpenMontage/blob/main/AGENT_GUIDE.md) serves as the central operating manual and behavioral contract for every AI agent in the OpenMontage system, defining mandatory workflows from user onboarding to final video composition while enforcing a strict pipeline-first architecture.**

In the `calesthio/OpenMontage` repository, [`AGENT_GUIDE.md`](https://github.com/calesthio/OpenMontage/blob/main/AGENT_GUIDE.md) functions as the definitive behavioral contract that governs how autonomous agents interact with users, process video references, and execute production pipelines. This file establishes the architectural rules that ensure every agent action remains transparent, auditable, and aligned with the system's layered knowledge architecture. Unlike general documentation, it acts as executable policy, mandating specific file reads and decision checkpoints before any tool invocation.

## Core Responsibilities of AGENT_GUIDE.md in OpenMontage

### Onboarding and First-Interaction Flow

The guide mandates that agents must initiate the **onboarding skill** located at [`skills/meta/onboarding.md`](https://github.com/calesthio/OpenMontage/blob/main/skills/meta/onboarding.md) whenever encountering vague or exploratory user requests. This protocol ensures the agent runs discovery processes, classifies the user's setup, and offers starter prompts before performing any actual work. By enforcing this initial consultation, [`AGENT_GUIDE.md`](https://github.com/calesthio/OpenMontage/blob/main/AGENT_GUIDE.md) prevents premature tool execution and guarantees contextual awareness.

### Reference-Video Handling Protocol

When users supply video references, [`AGENT_GUIDE.md`](https://github.com/calesthio/OpenMontage/blob/main/AGENT_GUIDE.md) forces agents to follow the `video-reference-analyst` workflow defined in [`skills/meta/video-reference-analyst.md`](https://github.com/calesthio/OpenMontage/blob/main/skills/meta/video-reference-analyst.md). Agents must produce a grounded summary of the reference video before proceeding to pipeline selection. This requirement ensures production decisions remain anchored to specific visual requirements rather than generic assumptions.

### Rule Zero: Pipeline-First Architecture

The most critical mandate in [`AGENT_GUIDE.md`](https://github.com/calesthio/OpenMontage/blob/main/AGENT_GUIDE.md) is **Rule Zero**, which requires all production requests to pass through defined pipelines in `pipeline_defs/`. According to the source code contract, the agent must:

1. Identify the correct pipeline manifest from the `pipeline_defs/` directory.
2. Read the pipeline's stage-director skill at `skills/pipelines/<pipeline>/<stage>-director.md`.
3. Execute each stage only after consuming its director skill.
4. Never bypass the pipeline or generate ad-hoc scripts.

This rule ensures compositional consistency and prevents arbitrary code execution outside the structured workflow.

### Decision-Communication Contracts

Before invoking any paid or consequential tool call, agents must announce the exact tool, provider, model, and reasoning to the user. The guide requires explicit user approval whenever major decisions change, such as swapping providers or switching between render runtimes. This transparency mandate prevents unexpected charges and maintains user agency over production choices.

### Runtime and Composition Rules

[`AGENT_GUIDE.md`](https://github.com/calesthio/OpenMontage/blob/main/AGENT_GUIDE.md) imposes hard constraints on runtime selection for video composition. Agents must present **both** available composition runtimes—Remotion and HyperFrames—to users, log every runtime selection in `decision_log`, and escalate any blockers rather than silently substituting alternatives. This dual-presentation requirement ensures users retain informed choice over rendering technologies.

### Escalation and Blocker Handling

When steps fail due to authentication errors, provider outages, tool bugs, or quality issues, agents must surface a **structured blocker** with clear option lists. The guide prohibits automatic retry loops without user approval, referencing the checkpoint protocol implemented in [`lib/checkpoint.py`](https://github.com/calesthio/OpenMontage/blob/main/lib/checkpoint.py). This structured failure mode prevents silent automation of potentially problematic operations.

### The Three-Layer Knowledge Model

The guide documents OpenMontage's **three-layer architecture**: tools (Layer 1), skills (Layer 2), and `.agents/skills` (Layer 3). Agents must read the relevant general skill (Layer 2) and the provider-specific skill (Layer 3) before invoking any tool from [`tools/tool_registry.py`](https://github.com/calesthio/OpenMontage/blob/main/tools/tool_registry.py). This layered approach ensures agents understand implementation details, rate limits, and contextual requirements before accessing system capabilities.

## Technical Implementation: Enforcing the Guide

The following Python utilities demonstrate how OpenMontage systems programmatically enforce [`AGENT_GUIDE.md`](https://github.com/calesthio/OpenMontage/blob/main/AGENT_GUIDE.md) contracts. These implementations illustrate the core principles of **reading relevant skills first** and **never bypassing the pipeline**.

Loading the guide for debugging or documentation generation:

```python
from pathlib import Path

def load_agent_guide() -> str:
    """Read the AGENT_GUIDE.md file from the repository root."""
    guide_path = Path(__file__).parents[1] / "AGENT_GUIDE.md"
    return guide_path.read_text(encoding="utf-8")

print(load_agent_guide()[:200])  # Show the first 200 characters

```

Enforcing Rule Zero before pipeline execution:

```python
def run_stage(pipeline_name: str, stage: str):
    # 1. Read the stage-director skill

    skill_path = Path("skills/pipelines") / pipeline_name / f"{stage}-director.md"
    director = skill_path.read_text()

    # 2. Verify the skill exists (Rule Zero)

    if not director:
        raise RuntimeError(f"Missing director skill for {pipeline_name}/{stage}")

    # 3. Execute the stage only after the skill is read

    print(f"Running {stage} of {pipeline_name} using director skill.")
    # ... call the appropriate tool here ...

```

## Integration with the OpenMontage Ecosystem

[`AGENT_GUIDE.md`](https://github.com/calesthio/OpenMontage/blob/main/AGENT_GUIDE.md) does not operate in isolation but coordinates with specific architectural components referenced throughout its directives:

- **[`PROJECT_CONTEXT.md`](https://github.com/calesthio/OpenMontage/blob/main/PROJECT_CONTEXT.md)**: Provides high-level architectural context that informs the operational rules specified in the guide.
- **`pipeline_defs/`**: Contains YAML manifests defining production pipelines that agents must parse before execution.
- **[`skills/meta/onboarding.md`](https://github.com/calesthio/OpenMontage/blob/main/skills/meta/onboarding.md)**: Mandatory entry point for discovery workflows during initial user interactions.
- **[`skills/meta/video-reference-analyst.md`](https://github.com/calesthio/OpenMontage/blob/main/skills/meta/video-reference-analyst.md)**: Specialized skill for processing reference video inputs.
- **`.agents/skills/`**: Provider-specific implementations (Layer 3) required before any tool calls.
- **[`lib/checkpoint.py`](https://github.com/calesthio/OpenMontage/blob/main/lib/checkpoint.py)**: Implements the human-approval gating referenced in escalation protocols.
- **[`tools/tool_registry.py`](https://github.com/calesthio/OpenMontage/blob/main/tools/tool_registry.py)**: The central capability registry agents query only after reading mandatory skills.

## Summary

- [`AGENT_GUIDE.md`](https://github.com/calesthio/OpenMontage/blob/main/AGENT_GUIDE.md) serves as the **single source of truth** for agent behavior in the OpenMontage system.
- The guide enforces a **pipeline-first architecture** (Rule Zero) requiring consumption of stage-director skills from `skills/pipelines/<pipeline>/<stage>-director.md` before execution.
- Agents must follow mandatory onboarding and reference-video analysis workflows defined in `skills/meta/` before processing requests.
- All consequential tool calls require explicit decision logging in `decision_log` and user approval for provider or runtime changes.
- The **three-layer knowledge model** mandates reading both general skills and provider-specific skills from `.agents/skills/` before invoking tools.
- Escalation protocols reference [`lib/checkpoint.py`](https://github.com/calesthio/OpenMontage/blob/main/lib/checkpoint.py) to handle failures through structured blockers rather than silent automation.

## Frequently Asked Questions

### What happens if an OpenMontage agent bypasses the pipeline requirements in AGENT_GUIDE.md?

The guide explicitly prohibits bypassing defined pipelines or writing ad-hoc scripts. Agents must identify the correct pipeline manifest in `pipeline_defs/`, read the corresponding stage-director skill at `skills/pipelines/<pipeline>/<stage>-director.md`, and execute stages sequentially. Violating Rule Zero breaks the system's auditable chain of execution and violates the core contract specified in the file.

### How does AGENT_GUIDE.md ensure transparency when agents select expensive tools?

Before any paid tool invocation, agents must announce the exact tool name, provider, model, and reasoning. The guide mandates logging these decisions in `decision_log` and requires explicit user approval for major changes such as switching between composition runtimes like Remotion and HyperFrames. This creates an immutable record of agent decisions for cost auditing.

### What is the relationship between AGENT_GUIDE.md and PROJECT_CONTEXT.md?

While [`AGENT_GUIDE.md`](https://github.com/calesthio/OpenMontage/blob/main/AGENT_GUIDE.md) specifies operational rules and behavioral contracts for agents, [`PROJECT_CONTEXT.md`](https://github.com/calesthio/OpenMontage/blob/main/PROJECT_CONTEXT.md) provides the high-level architectural context and design philosophy that informs those rules. Agents reference both files to understand both the system's structural design and their specific execution constraints within the OpenMontage architecture.

### Why does AGENT_GUIDE.md require agents to read skills before calling tools?

The guide implements a **three-layer knowledge model** where agents must consult Layer 2 (general skills) and Layer 3 (provider-specific skills in `.agents/skills/`) before accessing Layer 1 (tools in [`tools/tool_registry.py`](https://github.com/calesthio/OpenMontage/blob/main/tools/tool_registry.py)). This ensures agents understand implementation details, rate limits, and contextual requirements, preventing blind tool invocation and ensuring informed decision-making aligned with system capabilities.