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

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 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 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 prevents premature tool execution and guarantees contextual awareness.

Reference-Video Handling Protocol

When users supply video references, AGENT_GUIDE.md forces agents to follow the video-reference-analyst workflow defined in 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 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 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. 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. 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 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:

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:

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 does not operate in isolation but coordinates with specific architectural components referenced throughout its directives:

• 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: Mandatory entry point for discovery workflows during initial user interactions.
• 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: Implements the human-approval gating referenced in escalation protocols.
• tools/tool_registry.py: The central capability registry agents query only after reading mandatory skills.

Summary

• 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 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 specifies operational rules and behavioral contracts for agents, 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). This ensures agents understand implementation details, rate limits, and contextual requirements, preventing blind tool invocation and ensuring informed decision-making aligned with system capabilities.

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