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

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, 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.

{
  "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. This file serves as the single source of truth for generation, validation, and viewer contracts.

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

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

Via URL:

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.

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 showing the contract field in context:

{
  "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:

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 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.
• 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. The start page template in 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.

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