contract-first-agents

Contract-First Map-Reduce Agent Coordination

Wraps native TeamCreate/Task/SendMessage with a proven 4-phase protocol that eliminates 75% of integration errors in multi-agent tasks.

Research Basis

Based on 400+ controlled experiments comparing 7 coordination strategies:

• Naive multi-agent: 0.571 composite quality score
• Contract-First Map-Reduce: 0.871 composite quality score (+52.5%)
• The contract alone accounts for the ENTIRE quality improvement
• Validated across 2-64 agent configurations

The Protocol

Phase 1: CONTRACT GENERATION (Team Lead, ~5% of time)

Before spawning ANY worker agent, the team lead MUST create a Contract Document.

The Contract Document must contain:

# === SHARED CONTRACT: [Project Name] ===

## 1. MODULE MANIFEST
For EVERY module/section an agent will produce:
- Exact filename
- Purpose (1 sentence)
- ALL exported names (exact spelling, exact case)

## 2. INTERFACE DEFINITIONS
For EVERY cross-module reference:
- Exact function/class name
- Exact parameter names and types
- Exact return type
- Source module -> consuming module(s)

## 3. SHARED TYPES
For EVERY data structure shared across modules:
- Exact field names and types
- Validation rules
- Serialization format

## 4. STYLE GUIDE
- Naming: snake_case for functions/variables, PascalCase for classes
- Indentation: [N] spaces
- Docstrings: [Google/NumPy/Sphinx] style on all public functions/classes
- Error handling: exact exception types
- Import convention: "from module import Name"
- Language-specific conventions

## 5. DEPENDENCY MAP
- Which modules import from which
- Execution order constraints (if any)
- Shared state / global configuration

## 6. SECTION BOUNDARIES
For EACH section assigned to an agent:
- What it must produce (exact deliverables)
- What it imports from other sections (exact names)
- What it exports for other sections (exact names)
- How it connects to adjacent sections (transitions, API calls, imports)

Contract Quality Checklist:

• Every exported name is spelled out exactly
• Every cross-module import has a matching export
• Style guide is specific (not "be consistent" but "use snake_case")
• Shared types have exact field names and types
• No ambiguity - an agent reading only the contract can produce correct code