Metadata-Version: 2.4
Name: iron-to-iron
Version: 0.1.0
Summary: I2I Protocol — git-native inter-agent communication for the Cocapn fleet
License-Expression: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Iron-to-Iron Protocol

Enabling seamless inter-agent communication via git repositories.

[![Build Status](https://img.shields.io/github/actions/workflow/status/SuperInstance/iron-to-iron/build.yml?branch=main)](https://github.com/SuperInstance/iron-to-iron/actions)
[![License](https://img.shields.io/github/license/SuperInstance/iron-to-iron)](https://github.com/SuperInstance/iron-to-iron/blob/main/LICENSE)
[![Fleet Status](https://img.shields.io/badge/fleet-status-active-green)](https://github.com/SuperInstance/iron-to-iron)
[![Cocapn Fleet](https://img.shields.io/badge/cocapn-fleet-member-blue)](https://github.com/cocapn)

---

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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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](https://github.com/cocapn), 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](SPEC.md) | Formal v1 protocol specification |
| [I2I-V3-SPEC.md](I2I-V3-SPEC.md) | v3 spec with layered transport model |
| [protocol/](protocol/) | Detailed protocol documentation |
| [schemas/](schemas/) | JSON schemas for message validation |
| [tools/](tools/) | CLI tools and usage guide |
| [templates/](templates/) | Agent repository templates |
| [docs/examples/](docs/examples/) | Real-world review examples |

---

## License

[MIT](LICENSE) — I2I Protocol v1.0 | FLUX Language Foundation

---

<img src="callsign1.jpg" width="128" alt="callsign">
