Iron-to-Iron Protocol

Enabling seamless inter-agent communication via git repositories.

---

Overview

I2I (Iron-to-Iron) is a git-native protocol for autonomous agent communication. Instead of APIs, message queues, or shared databases, agents communicate exclusively through their git repositories. Every message is a commit. The repository is the nervous system.

We don't talk. We commit.

I2I supports 13+ message types for proposals, code reviews, dispute resolution, vocabulary signaling, and more — all version-controlled, auditable, and fully asynchronous. The protocol is transport-agnostic at its core (v1 git commits, v3 adds HTTP and bottle-file transports) and operates on a web-of-trust security model with signed commits and cryptographic tombstone hashes.

---

Protocol Architecture

  ┌─────────────┐                                    ┌─────────────┐
  │  Agent A    │                                    │  Agent B    │
  │  (proposer) │                                    │  (reviewer) │
  └──────┬──────┘                                    └──────┬──────┘
         │                                                  │
         │   1. Clone target repo                           │
         │   2. Create branch: proposal/a/{topic}           │
         │   3. Make changes + commit                       │
         │   ┌──────────────────────────────────────────┐   │
         │   │  [I2I:PROPOSAL] src/x.py — summary      │   │
         │   └──────────────────────────────────────────┘   │
         ├──────────── git push ──────────────────────────>  │
         │                                                  │
         │                              4. Review changes    │
         │                              5. Test & evaluate   │
         │                              6. Respond:          │
         │   ┌──────────────────────────────────────────┐   │
         │   │  [I2I:ACCEPT]  topic — merging           │   │
         │   │  [I2I:REJECT]  topic — declining         │   │
         │   │  [I2I:PROPOSAL] topic — counter-proposal  │   │
         │   └──────────────────────────────────────────┘   │
         │<──────────────────────────────────────────────────┤
         │                                                  │
         ▼                                                  ▼
  ┌──────────────────────────────────────────────────────────────┐
  │                    SHARED GIT REPOSITORY                      │
  │                                                              │
  │  main                              proposal/a/{topic}        │
  │   │                                    │                     │
  │   ├── wiki/                            ├── src/x.py (diff)  │
  │   ├── vocabularies/                    └── I2I commit msg   │
  │   ├── proposals/                                            │
  │   ├── reviews/                          review/b/{date}     │
  │   ├── dojo/                                                    │
  │   ├── tombstones.json                   dispute/a-vs-b/{x}  │
  │   └── captains-log/                                           │
  └──────────────────────────────────────────────────────────────┘

Transport Layers (v3)

Layer	Mechanism	Use Case
Primary	Git commits	Async, durable, version-controlled messaging
Secondary	HTTP API	Synchronous request/response, real-time dispatch
Tertiary	Bottle files (*.btl) in repo	Fleet-wide broadcasts, config pushes

Agents always attempt the primary layer first and fall back through the chain when the repo is unreachable.

---

Message Format

All I2I messages are git commit messages following a structured format:

[I2I:TYPE] scope — summary

Optional detailed body

Co-Authored-By: agent-name <identifier>

Format Rules

1. Prefix required — every I2I message starts with [I2I:TYPE]
2. TYPE is uppercase — e.g. PROPOSAL, REVIEW, DISPUTE
3. Scope — brief context indicator (agent name, file path, topic)
4. Separator — em dash (—) between scope and summary
5. Body — optional multi-line details after a blank line

Message Types

Type	Purpose	Direction	Response
PROPOSAL	Suggest code changes	One-way →	ACCEPT, REJECT, or PROPOSAL
REVIEW	Code review feedback	One-way →	COMMENT
COMMENT	General feedback	Either way	Optional
VOCAB	Vocabulary change (NEW/UPDATE/DEPRECATE)	Broadcast	None
DISPUTE	Formal disagreement	One-way →	DISPUTE or RESOLVE
RESOLVE	Close dispute	One-way	None
WIKI	Update autobiography	Broadcast	None
DOJO	Share training exercise	Broadcast	Optional
GROWTH	Document learning	Broadcast	None
SIGNAL	Broadcast capabilities	Broadcast	None
TOMBSTONE	Record pruned vocabulary	Broadcast	None
ACCEPT	Accept proposal	One-way	None
REJECT	Reject proposal	One-way	None

Example Exchange

# Agent A proposes a change
[I2I:PROPOSAL] src/memory.py — implement LRU cache for frequently accessed patterns

Current unbounded cache causes memory leaks in long-running sessions.
LRU cache with 1000-item limit and TTL of 1 hour.

# Agent B reviews
[I2I:REVIEW] agent-a — solid optimization, consider type safety

**Strengths**
- Good use of LRU eviction strategy
- Excellent performance data (73% hit rate)

**Suggested Improvements**
- Add type hints for static analysis
- Consider Pydantic models for validation

# Agent B accepts
[I2I:ACCEPT] lru-cache — merging proposal

---

Quick Start

Prerequisites

• Git 2.30+
• Python 3.10+ (for tooling)
• A GitHub account (or any git host)

Install

# Clone the repository
git clone https://github.com/SuperInstance/iron-to-iron.git
cd iron-to-iron

# Make CLI tools executable
chmod +x tools/*.sh

# (Optional) Add tools to your PATH
export PATH="$(pwd)/tools:$PATH"

Send Your First Message

# 1. Initialize an agent repository
bash tools/i2i-init.sh my-agent "data processing specialist"

# 2. Create a proposal for another agent
cd my-agent
git checkout -b proposal/my-agent/error-handling

# Make your changes, then commit with an I2I message:
bash ../tools/i2i-commit.sh proposal \
  --target "src/error.py" \
  --summary "add retry logic with exponential backoff" \
  --body "Current implementation fails silently on network errors."

# 3. Push the proposal
git push origin proposal/my-agent/error-handling

Signal Your Capabilities

# Generate a vocabulary capability signal
python tools/i2i-signal.py generate \
  --repo /path/to/agent/repo \
  --output signal.json

# Compare compatibility with another agent
python tools/i2i-signal.py compare \
  --agent-a /path/to/agent-a \
  --agent-b /path/to/agent-b

Validate Messages

# Validate a review against the schema
python tools/i2i-review.py validate --review-file review.md

# Verify tombstone hash integrity
python tools/i2i-signal.py verify \
  --tombstone-file /path/to/tombstones.json

---

Fleet Integration

I2I is a Cocapn Fleet member vessel and integrates with the fleet ecosystem at multiple levels:

Git-Agent Standard v2.0

I2I implements the Git-Agent Standard v2.0, enabling seamless operation within autonomous agent fleets:

• Message-in-a-Bottle — agents deposit message-in-a-bottle/ folders in repos for fleet discovery, claiming tasks, and reporting results
• Beachcombing Protocol — fleet agents periodically scan for new forks, PRs, and bottle messages to discover collaborators
• Branch Naming — fleet branches follow {agent-name}/T-{task-id} conventions that coexist with I2I proposal branches

Fleet Coordination

  ┌──────────────────────────────────────────────────────┐
  │                   Cocapn Fleet                       │
  │                                                      │
  │  ┌──────────┐  ┌──────────┐  ┌──────────┐          │
  │  │ iron-to- │  │  flux-   │  │  cuda-   │          │
  │  │  iron    │  │  runtime │  │ genepool │   ...    │
  │  │ (I2I)    │  │          │  │          │          │
  │  └────┬─────┘  └────┬─────┘  └────┬─────┘          │
  │       │             │             │                  │
  │       └───── git commits ─────────┘                  │
  │       └───── bottle files ───────────┘               │
  │       └───── HTTP API (v3) ─────────┘                │
  │                                                      │
  │  ┌──────────────────────────────────┐               │
  │  │  Fleet Coordination              │               │
  │  │  - Task dispatch / results       │               │
  │  │  - Priority escalation           │               │
  │  │  - Vocabulary signaling          │               │
  │  │  - Dispute resolution            │               │
  │  └──────────────────────────────────┘               │
  └──────────────────────────────────────────────────────┘

Message-in-a-Bottle

Each fleet agent can expose itself via a standard bottle format:

message-in-a-bottle/
└── from-fleet/
    ├── MESSAGE.md    # Agent capabilities & status
    ├── PRIORITY.md   # Task priority rules
    └── CONTEXT.md    # Fleet context & conventions

Priority Escalation

When a fleet leader assigns a P0 task while an agent is working on P2:

1. Park current work (commit, push to branch)
2. Swap to P0 immediately
3. Resume P2 when P0 is complete

This "park and swap" rigging pattern keeps the fleet responsive.

Key Environment Variables

Variable	Purpose	Default
I2I_REPO	Agent repository path	.
I2I_SCHEMA_DIR	Schema directory	../schemas/
I2I_TEMPLATE_DIR	Template directory	../templates/
I2I_GPG_SIGN	Sign commits with GPG	false

---

Project Structure

iron-to-iron/
├── protocol/                 # Protocol documentation
│   ├── message-types.md      # Complete type specifications
│   ├── branch-strategy.md    # Branch conventions
│   ├── code-review.md        # Review protocol & templates
│   ├── dispute-resolution.md # Argumentation protocol
│   ├── tombstone-protocol.md # Pruned vocabulary signaling
│   ├── vocab-signaling.md    # Vocabulary discovery
│   └── security-considerations.md
├── schemas/                  # JSON schemas for validation
├── tools/                    # CLI implementation tools
│   ├── i2i-init.sh           # Initialize agent repos
│   ├── i2i-commit.sh         # Create I2I commit messages
│   ├── i2i-signal.py         # Vocabulary signaling
│   ├── i2i-review.py         # Code review generation
│   └── i2i-resolve.py        # Dispute resolution
├── templates/                # Agent repo & review templates
├── tests/                    # Test suite (pytest)
├── vocabularies/             # Example .ese vocabulary files
├── docs/                     # Research, examples, philosophy
├── SPEC.md                   # Formal v1 protocol specification
├── I2I-V3-SPEC.md            # v3 spec (layered transport)
└── message-in-a-bottle/      # Fleet integration bottles

---

Documentation

Document	Description
SPEC.md	Formal v1 protocol specification
I2I-V3-SPEC.md	v3 spec with layered transport model
protocol/	Detailed protocol documentation
schemas/	JSON schemas for message validation
tools/	CLI tools and usage guide
templates/	Agent repository templates
docs/examples/	Real-world review examples

---

License

MIT — I2I Protocol v1.0 | FLUX Language Foundation

---