ICP-Collab v4

Autonomous bidirectional collaboration system for AI agents (Claude + Codex/GPT + (anything else with CLI).

Agents work independently on the same problem, then negotiate a plan autonomously - you only get notified when decisions are needed.

Features

• Two Collaboration Modes: Design mode (full workflow) or Implement mode (skip to building)
• 2-Agent or 3-Agent Workflows: Lead + Implementor, or Lead + Implementor + Consolidator
• Phased Implementation: Break down work into phases with per-phase QA
• Web Dashboard: Real-time monitoring, mode switching, and approval UI
• Autonomous Collaboration: Agents design, consolidate, and negotiate without user intervention
• User Notifications: Desktop notifications when action is required
• Persistence: State survives broker restarts
• Artifact Storage: Plans, QA reports, and summaries saved to disk

Quick Start

# 1. Clone & install
git clone https://github.com/afadhel/icp-collab.git
cd icp-collab
cd broker && npm install && npm run build
cd ../mcp-collab && npm install && npm run build

# 2. Start broker
cd ../broker && npm start

# 3. Open dashboard
open http://localhost:3033

Architecture

┌──────────────┐                         ┌──────────────┐
│ Claude Code  │                         │  Codex/GPT   │
│              │                         │              │
│  MCP tools:  │◄───── Broker API ──────►│  MCP tools:  │
│  collab_*    │       :3033             │  collab_*    │
└──────────────┘                         └──────────────┘
                         │
                         ▼
              ┌─────────────────────┐
              │   ICP-Broker        │
              │   localhost:3033    │
              │                     │
              │  ┌───────────────┐  │
              │  │ Dashboard UI  │  │
              │  │ Mode Switch   │  │
              │  │ Approval UI   │  │
              │  └───────────────┘  │
              │                     │
              │  ┌───────────────┐  │
              │  │ .colab-data/  │  │
              │  │  state.json   │  │
              │  │  artifacts/   │  │
              │  └───────────────┘  │
              └─────────────────────┘

Two Collaboration Modes

Design Mode (Default)

Full collaborative workflow - agents design independently, consolidate, get approval, then implement.

collab_start({
  task: "Build feature X",
  implementor: "codex",
  consolidator: "glm"  // Optional: 3-agent mode
})

Workflow:

1. Lead designs → 2. Implementor designs → 3. (Consolidator designs) →
2. Consolidation → 5. Lead review → 6. User approval →
3. Implementation → 8. QA → 9. Done

Implement Mode

Skip design phase - use a pre-approved plan and go straight to building.

collab_start_implement({
  task: "Implement the auth feature",
  implementor: "codex",
  planFile: "/path/to/approved-plan.md"
})

Workflow:

1. Lead reads plan, creates breakdown with phases →
2. Implementor reviews, asks questions →
3. Implementor accepts breakdown →
4. For each phase: Implement → Submit → QA → (Fix loop if needed) →
5. Final QA → Done

No user approval required - the plan is already approved.

---

Phase Enforcement

All implementation work must be broken into phases. This ensures incremental QA and prevents large, unreviewed changes.

Required Phase Format

The breakdown (implement mode) or consolidated plan (design mode) must include phases in this exact format:

## Implementation Phases

### Phase 1: Setup and Configuration
- Owner: implementor
- QA: lead
- Exit: Project builds successfully, all config files in place

- Initialize project structure
- Configure dependencies
- Set up environment variables

### Phase 2: Core Implementation
- Owner: implementor
- QA: lead
- Exit: Core features working, unit tests pass

- Build main features
- Add business logic
- Write unit tests

Phase Requirements

Requirement	Description
Minimum 2 phases	Work must be broken into at least 2 meaningful milestones
Sequential numbering	Phases must be numbered 1, 2, 3... with no gaps
Title required	Each phase needs a descriptive title after ### Phase N:
Owner required	- Owner: implementor (or specific agent name)
QA required	- QA: lead (in 2-agent mode, must be lead)
Exit criteria required	- Exit: What must be true to pass QA
Content required	Each phase must have task descriptions

Phase Lifecycle

pending → in_progress → submitted → qa → complete
                                    ↓
                               qa_failed → fixing → qa (re-submit)

In 3-agent mode, third-party QA adds a verification step:

qa → verifying → complete (if lead approves)
              → fixing (if lead sends back)

Validation Warnings

Phase validation is non-blocking. If phases are invalid, the broker accepts the submission but returns a warning and sets phaseValidationError in state:

Warning	Meaning
"No implementation phases detected"	Add ### Phase N: headers
"Minimum 2 phases required"	Break work into more milestones
"Phase numbering must be sequential"	Fix gaps (1, 2, 3 not 1, 3)
"Phase N is missing Owner/QA/Exit"	Add required metadata fields
"Phase N has no task content"	Add task descriptions

When phaseValidationError is set, the workflow continues but phase-specific tools (collab_submit_phase, collab_phase_qa) won't be available.

---

Setup

1. Install dependencies

cd icp-collab

# Broker
cd broker && npm install && npm run build

# MCP Server
cd ../mcp-collab && npm install && npm run build

2. Start the broker

cd icp-collab/broker

# Production:
npm start

# Development (auto-reload):
npm run dev

3. Open the Dashboard

Navigate to http://localhost:3033 to:

• Switch between Design/Implement modes
• Set plan file path (Implement mode)
• Approve/reject plans
• Monitor workflow progress
• View connected agents

4. Configure Claude Code

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "collab": {
      "command": "node",
      "args": ["/path/to/icp-collab/mcp-collab/dist/index.js"],
      "env": {
        "AGENT_NAME": "claude",
        "BROKER_URL": "http://localhost:3033"
      }
    }
  }
}

5. Configure Codex (or other agents)

Same MCP config with "AGENT_NAME": "codex" or "AGENT_NAME": "glm".

Important: Agent names must be exactly "claude", "codex", or "glm" (lowercase).

---

MCP Tools Reference

Starting Tasks

Tool	Description
collab_start	Start Design mode task (you become Lead)
collab_start_implement	Start Implement mode task (you become Lead)
collab_join	Join an existing task started by another agent

Design Mode Tools

Tool	Who	Description
collab_submit_design	All	Submit your independent design proposal
collab_submit_plan	Consolidator/Impl	Submit the consolidated plan
collab_approve_plan	Lead	Approve the consolidated plan
collab_request_changes	Lead	Request changes to the plan

Implement Mode Tools

Tool	Who	Description
collab_submit_breakdown	Lead	Submit implementation breakdown with phases
collab_ask_question	Implementor	Ask clarifying question about breakdown
collab_answer_question	Lead	Answer implementor's question
collab_accept_breakdown	Implementor	Accept breakdown, start implementing

Implementation & QA Tools

Tool	Who	Description
collab_submit_implementation	Implementor	Submit final implementation (phases are optional)
collab_submit_phase	Implementor	Submit current phase for QA
collab_phase_qa	Lead	Review current phase, pass or fail
collab_phase_fixes	Implementor	Submit fixes for current phase
collab_verify_qa	Lead	Verify third-party QA (3-agent mode only)
collab_submit_qa	Lead/Consolidator	Submit final QA report
collab_submit_fixes	Implementor	Submit fixes for QA findings

Polling & State

Tool	Description
collab_wait	CRITICAL: Wait for your turn (call continuously!)
collab_state	Check current workflow state

---

Critical: Continuous Polling

You MUST call collab_wait() in a loop until the task completes!

// After EVERY action:
collab_wait()  // Wait for next turn
// When it returns, call again immediately
collab_wait()  // Keep polling
// Repeat until task is "done"

The workflow will STALL if agents stop polling.

---

Broker API

Core Endpoints

Endpoint	Description
GET /	Dashboard UI
GET /health	Health check
GET /state	Get workflow state
POST /reset	Clear all state

Mode Control

Endpoint	Description
POST /set-mode	Set mode `{mode: "design"

User Actions

Endpoint	Description
POST /user-approve	Approve: {approved: true} or reject: {approved: false, feedback: "..."}

Artifacts

Endpoint	Description
GET /artifacts	Get saved artifacts
GET /transcript	Full conversation history

---

Environment Variables

Variable	Default	Description
AGENT_NAME	-	Required: claude, codex, or glm
BROKER_URL	http://localhost:3033	Broker URL
PORT	3033	Broker port
DATA_DIR	.colab-data	State/artifact storage
TIMEOUT_MS	300000	Stall detection (5 min)

---

Example: Design Mode Session

Terminal 1 - Start broker:

cd icp-collab/broker && npm run dev

Claude (Lead) starts task:

collab_start({ task: "Add dark mode toggle", implementor: "codex" })

// Submit design
collab_submit_design({ design: "Use CSS variables with React context..." })
collab_wait()

Codex (Implementor) joins:

collab_join()

// Submit design
collab_submit_design({ design: "Use styled-components ThemeProvider..." })
collab_wait()

// Consolidate both designs
collab_submit_plan({ plan: "Combined approach: CSS vars + context..." })
collab_wait()

Claude reviews and approves:

collab_approve_plan()
collab_wait()

User approves via dashboard at http://localhost:3033

Codex implements:

// ... implements the feature ...
collab_submit_implementation({ summary: "Created ThemeContext, ThemeToggle..." })
collab_wait()

Claude does QA:

collab_submit_qa({ report: "All tests pass", passed: true })

Done!

---

Example: Implement Mode Session

Claude (Lead) starts with approved plan:

collab_start_implement({
  task: "Implement dark mode",
  implementor: "codex",
  planFile: "/path/to/dark-mode-plan.md"
})

// Read plan and create breakdown
collab_submit_breakdown({
  breakdown: `
## Phase 1: Theme Context
- Create ThemeContext.tsx
- Add useTheme hook

## Phase 2: Toggle Component
- Create ThemeToggle.tsx
- Add to header
`
})
collab_wait()

Codex reviews:

collab_join()

// Ask question if needed
collab_ask_question({ question: "Use localStorage or cookies?" })
collab_wait()

Claude answers:

collab_answer_question({ answer: "Use localStorage" })
collab_wait()

Codex accepts and implements phase by phase:

collab_accept_breakdown()

// Implement Phase 1
collab_submit_phase({ summary: "Created ThemeContext" })
collab_wait()

// After Phase 1 QA passes, implement Phase 2
collab_submit_phase({ summary: "Created ThemeToggle" })
collab_wait()

Claude reviews each phase:

collab_phase_qa({ report: "Phase 1 looks good", passed: true })
collab_wait()

collab_phase_qa({ report: "Phase 2 complete", passed: true })

Done!

---

Artifacts

All artifacts saved to .colab-data/artifacts/:

File	Description
task.txt	Original task description
plan.md	Approved plan
breakdown.md	Implementation breakdown (Implement mode)
qa_report.md	QA findings
summary.md	Completion summary

---

Troubleshooting

Issue	Solution
Agents not connecting	Check AGENT_NAME is exactly claude, codex, or glm
Workflow stalled	Ensure agents are continuously calling collab_wait()
MCP tools not found	Rebuild: cd mcp-collab && npm run build
State corrupted	Reset: curl -X POST http://localhost:3033/reset
Broker not responding	Check broker is running: npm start in broker/

---

Manual Test Checklist

Use these checklists to verify phase enforcement is working correctly.

2-Agent Flow (Lead + Implementor)

□ Start implement mode with planFile
□ Lead submits breakdown with valid phases (min 2)
□ Verify: Invalid phases are accepted with warning and phaseValidationError set
□ Implementor accepts breakdown
□ Verify: currentPhaseIndex starts at 0, phase 1 status is "in_progress"

For each phase:
□ Implementor submits phase (collab_submit_phase)
□ Verify: Phase status changes to "submitted"
□ Lead submits QA (collab_phase_qa)
□ If QA fails:
  □ Verify: Phase status is "qa_failed", step is "phase_fixes"
  □ Implementor submits fixes (collab_phase_fixes)
  □ Verify: Phase goes back to QA
□ If QA passes:
  □ Verify: Phase status is "complete"
  □ Verify: Next phase becomes "in_progress" (or task completes)

□ Verify: Only lead can submit phase QA
□ Verify: Only implementor can submit phases
□ Verify: Dashboard shows correct phase progress

3-Agent Flow (Lead + Implementor + Consolidator)

□ All 2-agent checks above PLUS:

For phases where QA is NOT lead:
□ Third-party (consolidator or phase.qaAssignee) submits QA
□ Verify: Phase status is "verifying", step is "phase_verify"
□ Lead verifies QA (collab_verify_qa)
□ If lead approves:
  □ Verify: Phase completes, next phase starts
□ If lead rejects:
  □ Verify: Phase goes to "fixing" for implementor

□ Verify: Lead can always submit QA directly (bypasses verification)
□ Verify: Dashboard shows "verifying" status correctly

Phase Validation Edge Cases

□ Warn/Flag: 0 phases detected (phaseValidationError set)
□ Warn/Flag: Only 1 phase (minimum 2 required)
□ Warn/Flag: Phase numbering gaps (1, 3 instead of 1, 2)
□ Warn/Flag: Missing "- Owner:" line
□ Warn/Flag: Missing "- QA:" line
□ Warn/Flag: Missing "- Exit:" line
□ Warn/Flag: Phase with no content after metadata
□ Accept: Valid phases with extra whitespace
□ Accept: Phases with markdown formatting in content

---

Rebuilding After Changes

# Rebuild broker
cd icp-collab/broker && npm run build

# Rebuild MCP server
cd icp-collab/mcp-collab && npm run build

# Restart broker (Ctrl+C first if running)
npm start

---

License

Apache 2.0