The Mental Model: Agent, Instructions, Tools, and Artifacts
OpenMontage is easiest to understand as a set of boundaries: the agent decides how to move through a production, instructions define the permitted path, tools perform bounded operations, and artifacts carry meaning from one stage to the next. This chapter traces those boundaries so a reader can follow one decision from a pipeline definition to a validated output without confusing project policy with a vendor's technical documentation.
The distinction matters because the repository contains many kinds of knowledge at once. A provider may explain how to generate a clip. OpenMontage must still decide whether that provider is available, appropriate for the brief, compatible with the selected pipeline, and safe to use without changing the approved delivery. Treating all of those questions as “the tool” would make the system look simpler than it is.
Three layers answer three different questions
The first layer answers what exists and when it may be used. It consists principally of tool contracts and pipeline manifests. A tool identifies its capability and provider, reports its runtime and dependencies, declares the inputs and outputs it accepts, and can expose fallbacks, resource needs, and links to deeper skills. A pipeline manifest defines the stages of a production, the artifacts each stage requires and produces, the tools it can use, the review criteria, and whether a human approval gate applies.
This layer is intentionally factual and operational. It should be possible to ask whether a speech tool is currently available, whether a renderer is installed, or whether an asset stage is allowed to call a given capability. The answer should come from the live contract and manifest, not from a remembered provider list. A tool may be present in the repository but unavailable because its binary, Python package, credential, or hardware dependency is missing. Existence in source code is not the same as availability in a run.
The second layer answers how OpenMontage wants a capability used in a particular production. These are the project skills and stage-director instructions. They translate a general capability into a workflow: what to inspect first, how to preserve the selected visual direction, when to sample rather than batch, which artifact to write, what to review, and when to stop for a person. A composition engine's own documentation cannot answer all of those questions because they depend on the pipeline and the promise made to the user.
The third layer answers how the underlying technology works. The repository's Layer 3 skills contain provider- or framework-specific knowledge: prompting patterns, animation constraints, speech behavior, rendering rules, or command-line requirements. This is where the technical details belong. A HyperFrames skill can explain how HTML, CSS, and GSAP timelines are authored; an OpenMontage skill can explain when that runtime fits a brief and how its artifacts map into a project workspace.
Keeping the layers separate prevents two opposite mistakes. The first is treating a vendor API as the production workflow. An API can accept a prompt and return a clip while saying nothing about scene coverage, approval, provenance, or the consequences of a fallback. The second is treating a project rule as a property of the technology. If OpenMontage prefers one renderer for a specific class of brief, that does not mean the renderer is universally superior; it means the project has made a contextual choice that should remain visible.
A concrete example is a motion-graphics brief that could be rendered through Remotion or HyperFrames. The tool layer reports whether each runtime is available and what it supports. The project layer explains the decision matrix and requires the agent to present both options when both are available. The technology layer explains the mechanics of the selected runtime. The three layers cooperate, but none can safely replace the others.
The boundary also clarifies what happens when a capability is missing. The tool contract can report the missing dependency. The pipeline can determine whether the absence blocks the chosen treatment. The stage skill can require the agent to explain the trade-off before switching paths. This is more honest than allowing a generic fallback to silently rewrite the brief, and it gives the human a meaningful decision instead of a technical surprise.
The diagram is a responsibility map, not a file tree. The agent reads the manifest; the manifest points to the instructions for a stage; those instructions use a tool contract; a tool returns a meaningful artifact; a checkpoint preserves that artifact; and a human may approve the transition. Layer 3 knowledge informs the tool's use without becoming the project's control policy.
A pipeline manifest is a contract between stages
OpenMontage's pipeline manifest is declarative: it describes the production without being the production's hidden Python controller. A stage entry can specify its name, director skill, required inputs, outputs, available tools, review focus, success criteria, and approval default. The agent reads this description and performs the work through the stated interfaces.
That arrangement constrains the next stage without hard-coding every possible production. A script stage can require an approved proposal. A scene-planning stage can require a script and produce a plan with timed scenes and asset requirements. An asset stage can be told which selectors or generators are permitted. A compose stage can require an edit decision artifact and a render report. The exact contents vary by pipeline, but the contract is stable: a stage does not merely leave behind whatever files happened to appear in a directory; it produces a named piece of meaning for the next stage.
This is why canonical artifacts matter more than an inventory of internal files. A file path says where something is. An artifact says what the production believes at that point. A proposal packet carries a selected concept, production plan, cost estimate, and approval status. A scene plan says how the script is being translated into visual units. An asset manifest connects media to scenes and can preserve provenance. Edit decisions specify the timeline and audio choices. A render report records what was produced and how it was verified.
The artifact boundary reduces informal assumptions. If the next stage expects an asset manifest, it has a defined object to validate and inspect. If the manifest is incomplete or schema-invalid, the defect can be caught before it becomes a mysterious rendering failure. The artifact is not necessarily the media itself; it is the structured account of what the media means in the production. Media files live alongside that account, but they do not replace it.
Imagine the difference in a short explainer. A script file can contain words, but the next stage needs to know more than the words: which sections exist, how long they should run, what the voice should emphasize, and what visual change each section requires. A scene plan then translates those sections into timed visual units. The asset manifest connects those units to actual images, clips, narration, or music. Edit decisions determine how the pieces meet on a timeline. If each handoff is only an informal folder of files, the agent must reconstruct intent from names and guesses. If each handoff is a canonical artifact, the next stage receives both material and the reasoning context needed to use it.
This does not make artifacts infallible. A well-formed scene plan can still be creatively weak, and a valid asset path can still point to the wrong emotional register. The contract narrows ambiguity; it does not replace judgment. That distinction is important because it explains why OpenMontage combines structured artifacts with review criteria and human gates rather than treating schema validity as a quality certificate.
The contract is also what allows specialized pipelines to share an architecture without pretending that their creative work is identical. An animated explainer may move from research and proposal to narration, visual scenes, and charts. A documentary montage may begin with a thematic brief, build a retrieval corpus, choose clips for slots, and lock an edit around rhythm and music. Character animation may add character design, rig planning, and pose libraries before the scene plan. These pipelines share the idea of stage contracts and review, but their stages and quality criteria reflect different media problems.
The shared architecture is therefore an abstraction over responsibilities, not a demand that every medium use the same recipe. “Assets” in an explainer can mean generated images and a narration track; in a documentary it can mean retrieved clips with source URLs and license information; in character animation it can mean a reusable rig and pose library. The name of a stage remains useful only when the contract beneath it preserves the information the next stage needs. A common label hides important differences if it is allowed to erase those inputs, outputs, or review criteria.
The maturity label is part of that interpretation. A manifest marked production is a stronger signal of intended readiness than one marked beta, but neither label is an independent benchmark. The reviewed repository marks documentary montage and character animation as beta while marking animated explainer and cinematic as production. A reader should therefore ask what the selected manifest requires, what tools are live, and what the compose path can actually verify. “The project supports this mode” is not the same as “this mode is equally hardened for every user.”
This also shows why OpenMontage's extensibility is primarily declarative and textual. A new pipeline can be described through a manifest and stage skills; a new tool can enter through the BaseTool contract and registry discovery. That makes the system adaptable, but it does not make extensions consequence-free. A skill can change agent behavior. A playbook can change the visual language. A tool can introduce a new dependency or fallback. The contracts and review rules are what make those changes visible enough to evaluate.
The practical benefit is that maintenance can happen at the level where a problem is observed. If the project has the capability but lacks a rule for using it in a documentary edit, a skill can express that policy. If a provider needs a new dependency declaration, the tool contract can expose it to preflight. If a pipeline repeatedly produces the wrong kind of handoff, its manifest or artifact definition can be tightened. The risk is the mirror image: a textual change can alter behavior widely, so the project still needs versioned manifests, validation, and an honest maturity label.
The boundary the agent cannot escape
An instruction-driven architecture gains flexibility by moving some intelligence out of fixed code and into documents that an agent interprets. That creates a corresponding dependency on compliance. The system can define a required reading order and a gate policy; it cannot make an external assistant understand every instruction perfectly. The project documentation is explicit about this dependence rather than hiding it behind a claim of full automation.
This is why the architecture should not be judged by whether it eliminates human reasoning. Its more modest achievement is to give reasoning owners and places: the manifest owns stage order, the skill owns contextual procedure, the tool owns capability execution, the artifact owns the stage's meaning, and the checkpoint owns persisted progress. When a result is wrong, that separation offers a path to ask which boundary failed. When the boundaries are blurred, debugging becomes guesswork.
The next step is to watch these interfaces over time. A static map can tell us who owns a decision, but not what happens when narration runs long, a provider becomes unavailable, or a later stage discovers that an earlier assumption no longer fits. That requires following the pipeline as a feedback loop rather than as a directory of components.