CONTRACT_TEMPLATE

CONTRACT Block Template (OR-1.5)

Purpose

Every agent .md file MUST begin with a CONTRACT block -- a YAML declaration inside an HTML comment that describes the agent's interface. The OR-3 DAG walker reads these contracts to build the execution graph.

The CONTRACT block is invisible to the agent at runtime (it is an HTML comment), but it is machine-readable for pipeline orchestration, dependency resolution, and documentation generation.

Format

<!-- CONTRACT_START
name: agent-name
description: One-sentence description of what this agent does.
inputs:
  - name: INPUT_NAME
    type: str | file | query_result
    source: user | system | agent:other-agent-name
    required: true | false
  - name: ANOTHER_INPUT
    type: file
    source: agent:upstream-agent
    required: true
outputs:
  - path: working/output_{{VARIABLE}}.md
    type: markdown | csv | json | image
  - path: outputs/final_{{DATE}}.md
    type: markdown
depends_on:
  - upstream-agent-name
pipeline_step: 5
knowledge_context:
  - .knowledge/datasets/{active}/schema.md
  - .knowledge/datasets/{active}/quirks.md
CONTRACT_END -->

Live Examples

Minimal contract (no dependencies)

From agents/question-framing.md:

<!-- CONTRACT_START
name: question-framing
description: Generate prioritized analytical questions from a business problem, producing a structured question brief with hypotheses and data requirements.
inputs:
  - name: BUSINESS_CONTEXT
    type: str
    source: user
    required: true
  - name: PRODUCT_DESCRIPTION
    type: str
    source: user
    required: true
  - name: AVAILABLE_DATA
    type: str
    source: user
    required: true
outputs:
  - path: outputs/question_brief_{{DATE}}.md
    type: markdown
depends_on: []
knowledge_context: []
pipeline_step: 1
CONTRACT_END -->

Contract with upstream dependency and knowledge context

From agents/data-explorer.md:

<!-- CONTRACT_START
name: data-explorer
description: Discover what data exists in a source, profile its quality and completeness, identify tracking gaps, and recommend supported analyses.
inputs:
  - name: DATA_SOURCE
    type: str
    source: user
    required: true
  - name: ANALYSIS_GOALS
    type: str
    source: user
    required: false
outputs:
  - path: outputs/data_inventory_{{DATE}}.md
    type: markdown
  - path: working/data_inventory_raw.md
    type: markdown
depends_on: []
knowledge_context:
  - .knowledge/datasets/{active}/schema.md
  - .knowledge/datasets/{active}/quirks.md
pipeline_step: 4
CONTRACT_END -->