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

> Discover the technical details of agent contracts in Archify. Learn how these agreements define data formats, validation, and runtime guarantees for LLM agents to generate architectural diagrams effectively.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: deep-dive
- Published: 2026-09-12

---

**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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/viewer/README.md) and implemented in modules like [`viewer/export.js`](https://github.com/tt-a1i/archify/blob/main/viewer/export.js) and [`viewer/semantic-lens.js`](https://github.com/tt-a1i/archify/blob/main/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:

```bash

# 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:

```bash

# 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:

```python
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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/viewer/README.md)** – Export, focus, and lens contracts for viewer interactions.
- **[`viewer/export.js`](https://github.com/tt-a1i/archify/blob/main/viewer/export.js)** – Implements export methods and share-card generation.
- **[`viewer/semantic-lens.js`](https://github.com/tt-a1i/archify/blob/main/viewer/semantic-lens.js)** – Lens contract implementation for kind selection.
- **[`viewer/intent-trace.js`](https://github.com/tt-a1i/archify/blob/main/viewer/intent-trace.js)** – Intent trace contract for hover/focus previews.
- **[`viewer/route-probe.js`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/viewer/export.js) and [`viewer/semantic-lens.js`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md), which defines the complete generation, validation, and delivery protocol. Supplementary details appear in [`viewer/README.md`](https://github.com/tt-a1i/archify/blob/main/viewer/README.md) for viewer-specific interactions and throughout the `archify/schemas/` directory for structural requirements.