Agent Roles

Understanding Agent Roles

CCCC deploys multiple AI agents in distinct roles, each contributing to the collaborative workflow. Understanding these roles helps you configure and optimize your multi-agent orchestration.

Primary Peer Agents (PeerA & PeerB)

The Dual-Peer Model

At the heart of CCCC are two co-equal peer agents that work as equals:

PeerA ←→ PeerB
  ↑         ↑
  └─────────┘
  Challenge & Collaborate

Default configuration:

PeerA: Claude Code (Anthropic)
PeerB: Codex CLI (OpenAI)

Peer Responsibilities

Each peer agent:

Proposes solutions based on current task and context
Challenges peer proposals with counterarguments
Provides evidence for their positions
Refines approaches based on peer feedback
Documents decisions in POR.md/SUBPOR.md

Why Two Peers?

Single-agent tools suffer from:

Problem	Impact	Peer Solution
Direction drift	Loses focus on goals	Peers realign each other
Narrow vision	Misses alternatives	Cross-perspective challenge
Mental decay	Context degradation	Mutual verification
Confirmation bias	Unchecked assumptions	Adversarial testing

With two peers, errors are caught faster and quality improves through constructive debate.

Peer Interaction Pattern

PeerA: "I propose using JWT for authentication"
PeerB: "Counter: What about session-based auth for this use case?"
PeerA: "Evidence: JWT allows stateless scaling..."
PeerB: "Agreed with modification: JWT + refresh tokens"
→ Consensus reached, logged to SUBPOR.md

Foreman Agent

The Supervisor Role

The Foreman is an optional supervisor agent that provides oversight and course correction:

foreman:
  enabled: true
  interval: 15m    # Check every 15 minutes
  agent: claude-code

Foreman Responsibilities

Progress Monitoring: Reviews POR.md and SUBPOR.md for progress
Goal Realignment: Ensures peers stay focused on strategic objectives
Conflict Resolution: Breaks deadlocks when peers can't reach consensus
Quality Gates: Validates that outputs meet quality standards
Resource Management: Adjusts orchestration if issues detected

When to Use Foreman

Enable Foreman for:

Long-running tasks (>2 hours)
Complex multi-milestone projects
Tasks requiring strict adherence to specifications
Autonomous overnight operation

Skip Foreman for:

Quick bug fixes
Simple feature additions
When actively monitoring yourself

Foreman Configuration

foreman:
  enabled: true
  interval: 15m
  agent: claude-code

  checks:
    - goal_alignment
    - progress_rate
    - quality_standards
    - peer_consensus

  actions:
    on_drift: realign
    on_stall: intervene
    on_deadlock: resolve

Foreman Workflow

Every 15 minutes:
  1. Read POR.md and SUBPOR.md
  2. Assess progress against milestones
  3. Check for goal drift or stalls
  4. Intervene if needed:
     - Send realignment message to peers
     - Break consensus deadlock
     - Escalate to human via IM
  5. Log assessment to .cccc/foreman.log

Auxiliary Agent

The Specialist Role

The Auxiliary agent provides additional perspective for complex tasks:

agents:
  primary_a: claude-code
  primary_b: codex-cli
  auxiliary: gemini-cli

When Auxiliary Activates

Auxiliary is called for:

Tasks marked as "complex" or "critical"
When peers deadlock after multiple rounds
Specialized domains (research, analysis, security review)
Third-opinion validation before major decisions

Auxiliary Configuration

auxiliary:
  agent: gemini-cli
  enabled_for:
    - complex_tasks
    - deadlock_resolution
    - security_review
    - architecture_decisions

  activation:
    complexity_threshold: high
    deadlock_rounds: 3

Auxiliary Workflow

Normal task:
  PeerA ←→ PeerB → Consensus → Implementation

Complex task:
  PeerA ←→ PeerB → Deadlock
    ↓
  Auxiliary consulted
    ↓
  Three-way consensus → Implementation

Role Interactions

Complete Orchestration Flow

┌─────────────────────────────────────┐
│           Human (via IM)            │
│         Monitor & Override          │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│            Foreman                  │
│    Supervise every 15 minutes       │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│         Peer Agents                 │
│    PeerA ←→ PeerB                   │
│    Propose, Challenge, Refine       │
└──────────────┬──────────────────────┘
               │
               ▼ (if needed)
┌─────────────────────────────────────┐
│          Auxiliary                  │
│    Third opinion, Specialist        │
└─────────────────────────────────────┘

Communication Between Roles

All agents communicate through the Mailbox Protocol:

.cccc/mailbox/
├── peera_to_peerb.json
├── peerb_to_peera.json
├── foreman_to_peers.json
└── peers_to_foreman.json

See Mailbox Protocol for details.

Configuring Agent Roles

Minimal Setup (Peers Only)

agents:
  primary_a: claude-code
  primary_b: codex-cli

Standard Setup (Peers + Foreman)

agents:
  primary_a: claude-code
  primary_b: codex-cli

foreman:
  enabled: true
  interval: 15m

Full Setup (All Roles)

agents:
  primary_a: claude-code
  primary_b: codex-cli
  auxiliary: gemini-cli

foreman:
  enabled: true
  interval: 15m

auxiliary:
  enabled_for:
    - complex_tasks
    - deadlock_resolution

Customizing Agent Behavior

Per-Role Temperature

agents:
  primary_a:
    name: claude-code
    temperature: 0.7
    role_style: analytical

  primary_b:
    name: codex-cli
    temperature: 0.8
    role_style: creative

Complementary Roles

Configure peers to complement each other:

PeerA Style	PeerB Style	Best For
Analytical	Creative	Feature development
Conservative	Aggressive	Risk-balanced decisions
Detail-focused	Big-picture	Architecture design
Fast iteration	Thorough review	Rapid prototyping

Example: Research Configuration

agents:
  primary_a:
    name: claude-code
    role_style: skeptical_analyst

  primary_b:
    name: gemini-cli
    role_style: exploratory_researcher

auxiliary:
  name: codex-cli
  role_style: fact_checker

Best Practices

1. Start Simple

Begin with just peer agents. Add Foreman and Auxiliary as needs arise.

2. Match Tools to Roles

Claude: Strong at analysis and nuanced reasoning
ChatGPT/Codex: Fast iteration and creative solutions
Gemini: Research and multi-modal tasks

3. Monitor Role Effectiveness

Check SUBPOR.md for patterns:

Are peers reaching consensus efficiently?
Is Foreman intervening too often (or not enough)?
When does Auxiliary add value?

4. Adjust Intervals

Foreman interval depends on task:

Quick tasks: 30m or disable
Long tasks: 15m
Overnight runs: 10m

Troubleshooting

Peers Never Agree

# Increase max rounds
cccc run --max-rounds 10

# Lower consensus threshold
cccc run --consensus 0.7

# Or check SUBPOR.md for systematic disagreement patterns

Foreman Over-Intervenes

foreman:
  interval: 30m  # Increase interval
  sensitivity: low  # Reduce intervention frequency

Auxiliary Not Helpful

Review what triggers Auxiliary:

auxiliary:
  enabled_for:
    - deadlock_resolution  # Only on deadlock
  # Remove other triggers if not adding value

Next Steps

Learn about the Mailbox Protocol for agent communication
Explore Configuration for detailed settings
Review Usage Guide for practical workflows