What Is an Agent Contract in Archify? A Complete Technical Guide

An agent contract in Archify is the formal agreement that defines the data format, validation steps, and runtime guarantees required for LLM agents to generate architectural diagrams through the Archify skill.

In the Archify ecosystem, LLM agents like Cursor, Claude Code, and Codex CLI interact with the system through a strict protocol known as the agent contract. This contract codifies exactly what data an agent must produce and how Archify validates, processes, and renders that data into interactive artifacts.

The Three Components of the Archify Agent Contract

The agent contract consists of three tightly-coupled components that govern the entire lifecycle from generation to rendering.

Typed JSON IR (Intermediate Representation)

The foundation of the contract is the Typed JSON IR, a schema-validated description of diagrams. According to archify/SKILL.md, this IR must include fields like type, meta, nodes, and edges, along with explicit versioning via schema_version (set to 2 for new layouts or 1 for legacy fixed-geometry workflows). The schema definitions live in archify/schemas/*.schema.json, ensuring that any JSON payload produced by an agent follows a predictable structure.

Generation and Validation Contract

Before delivery, every candidate diagram must pass the generation and validation contract defined in steps 1-5 of archify/SKILL.md. This component specifies the exact CLI commands an agent must invoke—validate, deliver, and preview—and mandates a specific error format using diagnostics[] with supportedFixes. The test suite in archify/test/workflow-semantic-contract.test.mjs enforces these invariants, guaranteeing that diagrams are syntactically correct, layout-checked, and pass nine artifact checks before delivery.

Viewer Runtime Contract

The final component governs how rendered diagrams behave. The viewer runtime contract, documented in viewer/README.md and implemented in modules like viewer/export.js and viewer/semantic-lens.js, exposes a public API including Archify.exportMenu, Archify.focus, and Archify.lens. This ensures that downstream agents can programmatically request share cards, motion exports, or lens operations without knowing implementation details.

The Agent-Archify Contract Lifecycle

The interaction follows three distinct phases that ensure deterministic, reproducible results.

1. Input Contract – The agent generates a JSON payload complying with archify/schemas/*.schema.json.
2. Processing Contract – Archify validates the payload against layout rules and returns a deterministic receipt via validate --json.
3. Output Contract – Upon success, Archify atomically writes a self-contained HTML file with optional PNG/WebM exports, guaranteeing identical viewer behavior across browser sessions.

Implementing the Contract: Practical Examples

To fulfill the contract, an agent must execute specific CLI commands in sequence.

First, generate and validate the candidate:

# Generate candidate JSON

node bin/archify.mjs guide "Map the checkout flow" --json > candidate.json

# Validate against the contract

node bin/archify.mjs validate workflow candidate.json \
    --quality showcase --json

Then deliver only after passing validation:

# Delivery contract execution

node bin/archify.mjs deliver workflow candidate.json \
    checkout-flow.html --quality showcase --open --json

Agent-side implementation typically follows this pattern:

def request_archify_diagram(description: str) -> str:
    # Generation contract: produce Archify JSON

    json_ir = llm.generate_archify_json(description)
    
    # Validation contract: local verification

    receipt = subprocess.run(
        ["node", "bin/archify.mjs", "validate", "architecture", json_ir,
         "--quality", "showcase", "--json"], capture_output=True
    )
    if receipt.returncode != 0:
        raise ValueError("Archify validation errors", receipt.stdout)
    
    # Output contract: deliver artifact

    html_path = "diagram.html"
    subprocess.run([
        "node", "bin/archify.mjs", "deliver", "architecture", json_ir,
        html_path, "--quality", "showcase", "--open", "--json"
    ])
    return html_path

Key Files Defining the Contract

The following source files codify the agent contract:

• archify/SKILL.md – Central definition of generation, validation, and delivery contracts.
• archify/schemas/*.schema.json – JSON schemas enforcing schema_version and node/edge structures.
• archify/test/workflow-semantic-contract.test.mjs – Test suite validating contract invariants.
• viewer/README.md – Export, focus, and lens contracts for viewer interactions.
• viewer/export.js – Implements export methods and share-card generation.
• viewer/semantic-lens.js – Lens contract implementation for kind selection.
• viewer/intent-trace.js – Intent trace contract for hover/focus previews.
• viewer/route-probe.js – Route probe contract for directed path selection.

Summary

• An agent contract formalizes the interface between LLM agents and the Archify skill.
• The contract comprises three components: Typed JSON IR, Generation & Validation rules, and Viewer Runtime guarantees.
• Agents must produce schema-compliant JSON (schema_version 1 or 2) located in archify/schemas/.
• Validation requires running archify.mjs validate before any deliver operation.
• The viewer exposes a stable API via Archify.exportMenu, Archify.focus, and related methods.
• All contract terms are versioned and enforced at runtime, ensuring deterministic, reproducible results.

Frequently Asked Questions

What happens if an agent submits invalid JSON to Archify?

Archify rejects the payload during the processing contract phase. The validate command returns a structured error response containing a diagnostics[] array with supportedFixes, allowing the agent to programmatically identify and correct schema violations before attempting delivery.

Which schema versions does the Archify agent contract support?

The contract recognizes two versions: schema_version: 2 for new flexible layouts and schema_version: 1 for legacy fixed-geometry workflows. Agents must specify the appropriate version in their JSON IR to ensure compatibility with the validation logic in archify/schemas/.

How does the viewer runtime contract benefit automated agents?

The viewer runtime contract exposes stable JavaScript APIs like Archify.exportMenu and Archify.lens through files such as viewer/export.js and viewer/semantic-lens.js. This allows agents to request specific downstream operations—such as generating share cards or exporting motion GIFs—without coupling to internal implementation details.

Where is the complete agent contract documented?

The authoritative source is archify/SKILL.md, which defines the complete generation, validation, and delivery protocol. Supplementary details appear in viewer/README.md for viewer-specific interactions and throughout the archify/schemas/ directory for structural requirements.

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