Skip to main content
skill CX Codex

contract-first-agents — Claude Code skill for agent coordination

The contract-first-agents skill gives a multi-agent team a shared contract before parallel work begins, then checks the combined output. Use it when separate modules or document sections must fit together.

MIT ★ 138 updated 2026-09-03

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add happycapy-ai/Happycapy-skills --skill contract-first-agents -a claude-code
Open on GitHub

What contract-first-agents does

Before launching workers, the team lead defines the modules, exported names, interfaces, shared types, and dependencies. Each worker receives the complete contract along with its assignment, so parallel contributions follow the same boundaries. The example stores the document at ~/.claude/teams/{team-name}/contract.md.

Once the work is merged, the lead checks syntax, imports, naming, and required exports. If problems remain, a fixer agent gets the specific findings and is told to change those issues without restructuring the output. The protocol skips contract setup for single-agent work, independent tasks, and research that needs no integration. That makes the upfront planning an extra step for tasks without shared interfaces.

What it helps with

  • define module interfaces before parallel implementation
  • assign related project sections to separate agents
  • check that imports match exported names
  • fix validation findings without regenerating whole sections

Example prompts for the agent

  • Set up a shared contract, then split this project into modules for parallel agents.
  • Have the team agree on exported names and interfaces before writing the modules.
  • Check the merged files against the contract and fix only the reported mismatches.

How to install contract-first-agents

1Skills CLI (Vercel)

npx skills add happycapy-ai/Happycapy-skills --skill contract-first-agents -a claude-code

2Manually: put the files in place

~/.claude/skills/contract-first-agents/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/contract-first-agents/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about contract-first-agents

How do I install contract-first-agents in Claude Code?

Run npx skills add happycapy-ai/Happycapy-skills --skill contract-first-agents -a claude-code. The skill file is installed at ~/.claude/skills/contract-first-agents/SKILL.md.

What does contract-first-agents do?

It structures multi-agent work around a shared contract, parallel assignments, and validation of the merged output. When checks find problems, a fixer agent addresses the listed issues without rebuilding the sections.

When should I skip the contract?

The protocol recommends skipping it for single-agent tasks, independent assignments with no cross-references, and research that does not require integration.

Source text

SKILL.md · MIT
---
name: contract-first-agents
description: "Contract-First Map-Reduce coordination protocol for native TeamCreate multi-agent teams. Wraps TeamCreate, Task (teammates), SendMessage with an upfront shared contract phase that eliminates 75% of integration errors. Based on 400+ experiment research proving 52.5% quality improvement over naive coordination."
version: 1.0.0
author: HappyCapy Research
triggers:
  - contract first agents
  - contract first team
  - coordinated agents
  - multi agent contract
  - team with contract
  - optimal team coordination
  - contract-first
---

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

```markdown
# === 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

### Phase 2: PARALLEL EXECUTION (Worker Agents)

Spawn worker agents using the Task tool with `team_name` parameter. Each worker's prompt MUST include:

```
[FULL CONTRACT TEXT - every worker gets the COMPLETE contract]

---

YOUR ASSIGNMENT: [Specific section/module]

You are Agent [N] of [Total]. You are producing [section name].

CRITICAL INSTRUCTIONS:
1. Follow the contract EXACTLY. Do not deviate from specified names, types, or conventions.
2. Your section will be merged with outputs from other agents working in parallel.
3. Use ONLY the exported names specified in the contract when referencing other modules.
4. Do NOT rename, reorganize, or "improve" the interface - follow the contract.
5. Write your output to: [exact file path]
```

**Spawn all workers in parallel** using a single message with multiple Task tool calls.

### Phase 3: AUTOMATED VALIDATION (Team Lead or Script)

After all workers complete, the team lead validates the merged output:

```python
# Validation checks (in priority order):
1. Syntax validity    - Can the output be parsed? (ast.parse, eslint --no-fix, etc.)
2. Import resolution  - Do all imports match actual exports?
3. Name consistency   - Is the naming convention uniform throughout?
4. Completeness       - Are all contracted exports present?
5. Style consistency  - Indent, docstrings, error handling patterns
6. Cross-references   - Do function calls use correct signatures?
```

Save validation results. If all pass -> done. If issues found -> Phase 4.

### Phase 4: TARGETED FIX (Fixer Agent, only if needed)

Spawn ONE fixer agent that receives:
- The merged output
- The specific validation errors (exact line numbers, exact issues)
- The original contract

**The fixer ONLY fixes the specific issues found. It does NOT regenerate or restructure.**

## Implementation with Native Tools

```python
# Step 1: Create team
TeamCreate(team_name="my-project", description="Building X with contract-first protocol")

# Step 2: Team lead generates the contract
# Save contract to a shared file: ~/.claude/teams/{team-name}/contract.md

# Step 3: Spawn workers with full contract in their prompts
Task(
    name="worker-auth",
    team_name="my-project",
    subagent_type="general-purpose",
    prompt=f"""
    {FULL_CONTRACT_TEXT}

    YOUR ASSIGNMENT: auth module
    Write to: /workspace/project/auth.py
    Follow the contract exactly.
    """
)
# ... spawn all workers in parallel

# Step 4: After workers complete, validate
# Team lead reads all output files and runs validation checks

# Step 5: If issues found, spawn fixer
Task(
    name="fixer",
    team_name="my-project",
    subagent_type="general-purpose",
    prompt=f"""
    Fix these specific issues in the merged output:
    {VALIDATION_ERRORS}

    Original contract: {CONTRACT}
    Do NOT restructure. Only fix the specific issues listed.
    """
)

# Step 6: Cleanup
SendMessage(type="shutdown_request", recipient="worker-auth")
# ... shutdown all workers
TeamDelete()
```

## When to Use This Protocol

**ALWAYS use for:**
- Any task requiring 3+ agents
- Tasks producing code that must interoperate
- Large document generation (multiple sections that reference each other)
- Any task where agents produce outputs that will be merged

**SKIP the contract for:**
- Completely independent tasks (no cross-references)
- Single-agent tasks
- Research/exploration tasks (no integration needed)

## Key Principles

1. **The contract IS the coordination** - review phases add <5% value if contract is good
2. **Every agent gets the FULL contract** - not just their section's part
3. **Specific beats general** - "use snake_case" beats "be consistent"
4. **Parallel beats sequential** - contract enables parallel work; pipelines sacrifice speed for marginal gain
5. **Targeted fixes beat regeneration** - fix specific issues, don't redo entire sections
6. **10+ agents need validation** - probability of ANY error increases with agent count

© HappyCapy Research · MIT · happycapy-ai/Happycapy-skills

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set41

The whole set →
agent-0-repo-qualifier agent-0-repo-qualifier grades GitHub repositories before issue hunting starts: commit recency, license, maintainer response, CLA blockers. Hands a scored shortlist to the next agent. CX Codex ★ 138repo stars agent-7-pr-creator The agent-7-pr-creator subagent reviews completed changes, prepares commits and a PR description, then opens a pull request with gh. It runs after Agents 4, 5, and 6. CX Codex ★ 138repo stars agent-1-issue-scout agent-1-issue-scout — a Claude subagent that scans pre-qualified GitHub repos for unclaimed good first issues and hands one scored pick to the next agent in the chain. CX Codex ★ 138repo stars html-over-markdown html-over-markdown generates self-contained HTML files with visual layouts, SVG diagrams, and interactive controls instead of plain Markdown. CX Codex +1 ★ 138repo stars agent-9-status-monitor agent-9-status-monitor — a Claude subagent that polls your open pull requests, catches merges, closures, new reviews and CI failures, then updates the contribution history and alerts the other agents in the swarm. CX Codex ★ 138repo stars generate-image generate-image generates images from text prompts and edits existing pictures via the AI Gateway API. Connects Claude Code to Gemini, Byteplus Seedream, and GPT-Image models. CX Codex +1 ★ 138repo stars agent-0-strategic-planner The agent-0-strategic-planner subagent ranks GitHub issues by user impact and feasibility. Use it to find meaningful contribution opportunities instead of spending effort on cosmetic fixes. CX Codex ★ 138repo stars claude-code-templates Installs and drives the claude-code-templates CLI: a catalog of agents, slash commands, MCP servers, hooks and project templates for Claude, plus session monitoring. CX Codex +1 ★ 138repo stars

Project sponsors

Companies that keep this analytics open