# How to Define an Agent Contract in Archify: Complete Implementation Guide

> Learn to define an agent contract in Archify. Embed a contract field in your workflow JSON and declare supported agents to enforce strict schema validation.

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

---

**To define an agent contract in Archify, embed a `contract` field (such as `"readable-v2"` or `"fixed-v1"`) in your workflow JSON and declare supported agents in [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md), enabling the compiler to enforce strict schema validation.**

The **agent contract** is the mechanism that ensures any AI coding agent—whether Cursor, Codex, Claude Code, or OpenCode—can generate compatible typed JSON IR for the Archify visualization pipeline. According to the `tt-a1i/archify` source code, this contract is declared in the skill's **SKILL.md** file and enforced at compile time by the workflow compiler.

## Understanding the Agent Contract System

Archify treats the agent that generates the typed JSON IR as a first-class participant. The contract specifies the exact schema and validation rules the agent's output must obey.

The contract value (e.g., `readable-v2`, `fixed-v1`) is a JSON field named **`contract`** inside the workflow source. This single field determines which validation rules apply to the generated diagram. The validator in `archify/renderers/workflow/workflow-compiler.mjs` checks this field and aborts compilation if the output does not match the declared schema【L92-L99】.

## Step-by-Step Guide to Defining an Agent Contract

### 1. Embed the Contract Identifier in Workflow JSON

Add the `contract` field to the root of your workflow JSON file. This informs the compiler which schema version the agent must satisfy.

```json
{
  "title": "Demo workflow",
  "contract": "readable-v2",
  "nodes": [
    { "id": "user", "label": "User", "type": "external" },
    { "id": "agent", "label": "Agent", "type": "backend" }
  ],
  "edges": [
    { "from": "user", "to": "agent", "label": "prompt" }
  ]
}

```

The `contract` field is mandatory. If omitted or mismatched, the compiler rejects the output during the validation phase.

### 2. Declare Supported Agents in SKILL.md

Specify which agents can fulfill the contract by editing [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md). This file serves as the single source of truth for generation, validation, and viewer contracts.

```markdown

## Agent contract

The skill can be used with the following agents:

- `cursor`
- `codex`   ← default
- `claude-code`
- `opencode`

```

This section informs the start page UI and the CLI about available agents. The picker UI in [`scripts/start-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/start-template.html) reads this list to populate the agent selection interface【L232-L238】.

### 3. Select the Agent at Runtime

Users can choose the agent via CLI flags or URL parameters, ensuring the selected agent receives the correct contract identifier.

**Via CLI:**

```bash
npx -y skills add tt-a1i/archify --agent codex --skill archify --global --copy --yes

```

**Via URL:**

```text
https://tt-a1i.github.io/archify/start.html?agent=cursor&type=architecture

```

The chosen agent must produce JSON that validates against the contract specified in the workflow file.

### 4. Validate Contract Compliance

Before delivery, validate that the agent's output satisfies the declared contract using the Archify CLI validator.

```bash
node archify/bin/archify.mjs validate workflow path/to/workflow.json \
    --quality showcase --json

```

On success, the receipt contains `"contract": "readable-v2"`, confirming that the agent fulfilled the contract【L549-L558】. If validation fails, the compiler reports schema violations specific to the contract version.

## Complete Example: Agent-Tool-Call Workflow

Here is a concrete implementation from [`examples/agent-tool-call.workflow.json`](https://github.com/tt-a1i/archify/blob/main/examples/agent-tool-call.workflow.json) showing the contract field in context:

```json
{
  "title": "Agent-Tool-Call demo",
  "contract": "readable-v2",
  "nodes": [
    { "id": "user", "label": "User", "type": "external" },
    { "id": "agent", "label": "Agent", "type": "backend" },
    { "id": "tool", "label": "Tool", "type": "backend" }
  ],
  "edges": [
    { "from": "user", "to": "agent", "label": "prompt" },
    { "from": "agent", "to": "tool", "label": "call" }
  ]
}

```

To validate this specific example:

```bash
node archify/bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json \
    --quality showcase --json

```

## Summary

- **Agent contracts** in Archify are defined by the `contract` field in workflow JSON (values like `readable-v2` or `fixed-v1`).
- The [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md) file declares which agents (Cursor, Codex, Claude Code, OpenCode) are supported for each contract.
- The compiler in `archify/renderers/workflow/workflow-compiler.mjs` enforces contract compliance at lines 92-99, aborting if validation fails.
- Runtime agent selection occurs via CLI (`--agent` flag) or URL parameters, with the UI populated from [`scripts/start-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/start-template.html).
- Use `archify/bin/archify.mjs validate` to verify contract fulfillment before deployment.

## Frequently Asked Questions

### What happens if an agent outputs JSON that violates the contract?

The workflow compiler in `archify/renderers/workflow/workflow-compiler.mjs` detects the mismatch during validation and aborts compilation. The error message specifies which schema rules were violated, preventing broken diagrams from reaching the rendering pipeline.

### Can I use multiple contract versions in the same project?

Yes. Each workflow file specifies its own `contract` field, allowing mixed versions within a single repository. However, ensure the agent you select supports the specific contract version declared in each individual workflow file.

### Where does Archify validate the agent contract?

Validation occurs in `archify/renderers/workflow/workflow-compiler.mjs`. The compiler checks the `contract` field at lines 92-99 to determine which schema to apply, and confirms successful validation at lines 549-558 by including the contract identifier in the output receipt.

### How do I add support for a new agent in Archify?

Add the agent identifier to the **Agent contract** section in [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md). The start page template in [`scripts/start-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/start-template.html) automatically includes the new agent in the selection picker, and the CLI recognizes it immediately for use with the `--agent` flag.