Collaboration

🤝 ClawCode Collaboration — User Guide

From solo coding to team orchestration — unlock multi-agent collaboration in your terminal.

---

Table of Contents

• Overview
• ClawTeam — Engineering Task Orchestration
  • 14 Built-in Engineering Roles
  • Usage
  • Deep Loop — Closed-Loop Convergence
• DesignTeam — Product Design Collaboration
  • 6 Design Roles
  • 7-Phase Design Workflow
  • Usage
• Research Team — Collaborative Investigation
  • 8 Research Roles
  • 3 Parallel Phases
  • Usage
• Saddle — Pipeline-Driven Development Framework
  • The Pipeline: spec → design → develop
  • Modes — Collaboration as Configuration
  • Collaboration Config — Groups & Primitives
  • Saddle Studio — Visual Mode Editor
  • Saddle CLI Quick Reference
• Multi-Model Workflows
• Subagent System — The Collaboration Foundation
• Agent Customization
  • Agent File Format
  • Merge Order
• Session Management & Branching
• MCP — Model Context Protocol Integration
• Plugin System — Extend Collaboration
• Team Experience Learning (TECAP)
• How It All Fits Together

---

Overview

ClawCode isn't just a chat-based coding assistant — it's a multi-agent collaboration platform built into your terminal. At its core, collaboration in ClawCode means:

Concept	What It Means for You
Role-based orchestration	Dispatch tasks to specialized AI roles (architect, QA, researcher, designer…) that work together
Pipeline-driven delivery	Run structured workflows: specification → design → development, each with its own team
Deep loop convergence	Iterate automatically until quality thresholds are met, with measurable gap tracking
Cross-team memory	Team experience is captured and reused — the system learns from past collaborations
Plugin extensibility	Connect external tools, MCP servers, and custom agent definitions

The collaboration stack has four layers, each building on the previous:

┌─────────────────────────────────────────────────┐
│          User Commands                           │
│  /clawteam  /designteam  /research  /multi-*     │
├─────────────────────────────────────────────────┤
│          Orchestration Engine                    │
│  TeamService · PipelineRunner · Role Selection   │
├─────────────────────────────────────────────────┤
│          Agent Runtime                           │
│  SubAgent spawning · Tool mediation · Sessions   │
├─────────────────────────────────────────────────┤
│          Learning & Memory                       │
│  TECAP capsules · Session memory · Experience DB │
└─────────────────────────────────────────────────┘

---

ClawTeam — Engineering Task Orchestration

/clawteam is ClawCode's built-in multi-role engineering task orchestration command. You describe a requirement in natural language, and it dispatches multiple specialist AI agents to collaboratively plan, implement, and validate the solution.

14 Built-in Engineering Roles

Role	Specialty	Tool Access
Product Manager	Product strategy, scope, acceptance criteria	Read, Glob, Grep, Bash
Business Analyst	Business requirements, stakeholder alignment	Read, Glob, Grep, Bash
System Architect	Architecture design, trade-off analysis	Read, Glob, Grep, Bash
UI/UX Designer	User flows, interaction design, usability	Read, Glob, Grep, Bash
Dev Manager	Engineering execution planning	Read, Glob, Grep, Bash
Team Lead	Cross-role coordination, alignment	Read, Glob, Grep, Bash
Backend Engineer	Backend implementation, APIs, data layer	Read, Write, Edit, Glob, Grep, Bash
Frontend Engineer	Frontend implementation, UI components	Read, Write, Edit, Glob, Grep, Bash
Mobile Engineer	Mobile platform implementation	Read, Write, Edit, Glob, Grep, Bash
DevOps	CI/CD, release automation, infrastructure	Read, Write, Edit, Glob, Grep, Bash
QA Engineer	Test strategy, quality validation	Read, Write, Edit, Glob, Grep, Bash
SRE	Reliability, observability, on-call	Read, Write, Edit, Glob, Grep, Bash
Project Manager	Scheduling, governance, risk tracking	Read, Glob, Grep, Bash
Scrum Master	Agile process, retrospectives, blockers	Read, Glob, Grep, Bash

💡 Key insight: Roles with Write/Edit tools can modify your codebase. Roles with only Read tools contribute analysis and strategy without touching files.

Usage

# Auto-select roles and orchestrate collaboratively
/clawteam Build an order management system with audit logging

# Use a single specialist role
/clawteam:qa Review the authentication module for security issues

# Explicit single-role mode
/clawteam --agent clawteam-system-architect Design the microservices boundary

# Iterative deep loop with convergence tracking
/clawteam --deep_loop Refactor the payment processing module

# Deep loop with a custom iteration cap
/clawteam --deep_loop --max_iters 10 Implement real-time notification system

Deep Loop — Closed-Loop Convergence

When --deep_loop is enabled, ClawTeam runs a structured multi-iteration loop where each iteration follows four steps:

Step	Purpose
1. Inspect	Analyze previous outcome, identify defects, risks, and gaps
2. Deepen Design	Refine architecture, interfaces, and trade-offs
3. Expand Implementation	Broaden feature scope and test coverage
4. Final Convergence	Evaluate delta score, decide whether to continue

Convergence criteria are configurable:

Parameter	Default	Meaning
min_gap_delta	0.05	Minimum improvement per iteration to continue
convergence_rounds	2	Consecutive rounds below delta to declare convergence
handoff_target	0.85	Success rate threshold for role handoffs
max_iters	100	Hard cap on iterations
max_rollbacks	2	Maximum rollback attempts on critical degrade

Each iteration outputs structured metrics — gap_before, gap_after, gap_delta, deviation_reason — so you can track exactly how the team is converging toward the goal.

---

DesignTeam — Product Design Collaboration

/designteam is the product design-oriented multi-role orchestration command, complementary to /clawteam (which focuses on engineering). It produces structured design documentation through collaborative role-based workflows.

6 Design Roles

Role	Specialty
User Researcher	Qualitative/quantitative framing, personas, journey signals, research questions
Interaction Designer	Task flows, states, navigation, information architecture, interaction specs
UI Designer	Layout hierarchy, UI patterns, components, density, design system alignment
Product Designer	Problem framing, outcomes, success metrics, scope prioritization
Visual/Ops Designer	Brand-consistent visuals, marketing/growth touchpoints, conversion layout
Experience Design Expert	Cross-cutting experience principles, heuristic review, accessibility, risk synthesis

Each role can optionally have a structured YAML configuration (in .claw/design/designteam/) providing output hints, method recommendations, references, and anti-patterns:

role_id: designteam-user-researcher
summary: Frame research questions, evidence gaps, and user signals
primary_outputs:
  "User & Scenarios": primary
  "Research Summary": primary
  "Open Questions": consulted
method_hints:
  - interviews
  - journey_map
  - competitive_scan
  - assumption_mapping
anti_patterns:
  - "Guessing personas without labeling assumptions"

7-Phase Design Workflow

When deep loop is enabled, DesignTeam follows a structured seven-phase design process:

Phase	Name	Key Activities
1	Exploration & Research	Stakeholder interviews, competitive analysis, user research
2	Definition & Strategy	Affinity diagrams, "How Might We" framing, value proposition
3	Ideation & Divergence	Brainstorming, Crazy 8s, sketching, storyboards
4	Prototyping & Validation	Interactive prototypes, usability testing, A/B concepts
5	Refinement & Delivery	Visual specs, motion design, design tokens, walkthrough
6	Development Follow-up	Requirement clarification, interaction walkthrough, UI acceptance
7	Iteration & Metrics	Analytics review, satisfaction surveys, user callbacks
8+	Integration & Convergence	Merge full design document, resolve remaining gaps

Each iteration maps to one phase; after phase 7, the system enters convergence mode to finalize.

Usage

# Auto-orchestrate all design roles
/designteam Design a collaborative document editing experience

# Single design specialist
/designteam:designteam-ui-designer Create a component library for the dashboard

# Deep loop through the 7-phase design workflow
/designteam --deep_loop Redesign the onboarding flow for better activation

# Deep loop with iteration cap
/designteam --deep_loop --max_iters 8 Create a design system for the fintech platform

---

Research Team — Collaborative Investigation

ResearchTeam extends ClawCode's research mode with role-based parallel collaboration for multi-phase academic and technical investigations.

8 Research Roles

Role	Specialty
Literature Researcher	Literature retrieval, source curation, citation coverage
Data Collector	Raw evidence collection, data normalization
Methodology Designer	Method and controls design, bias checks
Deep Analyst	Deep analysis, statistical checks, pattern extraction
Critical Reviewer	Critical review of assumptions, methods, gaps
Synthesis Writer	Synthesize findings into structured narrative
Fact Verifier	Factual claims validation, citation verification
Evidence Curator	Evidence archive and provenance mapping

3 Parallel Phases

Research Team executes in three parallel phases, each with a defined merge strategy:

Phase	Roles	Merge Strategy
Literature Survey	Literature Researcher + Data Collector	Union (combine all findings)
Analysis & Review	Deep Analyst + Critical Reviewer	Conflict Resolution (resolve contradictions)
Synthesis & Verification	Synthesis Writer + Fact Verifier	Sequential Review (writer drafts, verifier checks)

Up to 4 workers execute in parallel, with convergence checks after each phase to determine if results are sufficient.

Usage

Via slash command:

/research start quantum error correction -w team_research
/research start "LLM hallucination detection" -w team_audit --roles literature_researcher,deep_analyst
/research start "transformer architecture survey" -w team_survey

Via CLI:

clawcode research team "quantum error correction" \
  --roles literature_researcher,deep_analyst,fact_verifier \
  --strategy parallel \
  --max-iters 5

Available team workflows:

Workflow	Description
team_research	Full multi-role collaborative research (5 agents)
team_audit	Claims/code/reference audit (3 agents)
team_survey	Literature survey with evidence curation (3 agents)

---

Saddle — Pipeline-Driven Development Framework

Saddle is ClawCode's standalone collaboration-paradigm-driven development framework. It turns a one-line requirement into a structured, multi-stage project roadmap through a versionable pipeline.

The Pipeline: spec → design → develop

┌──────────┐     ┌──────────┐     ┌──────────┐
│   Spec    │────▶│  Design  │────▶│ Develop  │
│          │     │          │     │          │
│ Scope    │     │ DesignTeam│     │ ClawTeam │
│ Tasks    │     │ 6 roles  │     │ 14 roles │
│ Checklist│     │          │     │          │
└──────────┘     └──────────┘     └──────────┘

Each stage is independently configurable and can be re-run with different modes without rebuilding context.

Stage	Purpose	Outputs
Spec	Clarify scope, split work, define acceptance	spec.md, tasks.md, checklist.md, meta.json
Design	Multi-role design orchestration	Full orchestration prompt, agent selection, deep-loop config
Develop	Multi-role engineering execution	Full orchestration prompt, agent selection, deep-loop config

Together these form the "North Star bundle" — a complete project roadmap that serves as an alignment anchor for implementation.

Modes — Collaboration as Configuration

Modes are YAML files that define how the team collaborates. Instead of scattering conventions across chat logs, Saddle pins collaboration behavior in the repository.

Three built-in modes:

Mode	Key Settings	When to Use
default	Full prompts, minimal agent selection, no deep loop	Standard projects
fast	Compact prompts, 12-iteration cap, higher thresholds	Quick prototypes, tight deadlines
deep	Full deep loop, balanced agent selection, tight convergence	Critical systems, high-quality requirements

Example mode configuration:

name: fast
pipeline:
  enabled: true
  order: [spec, design, develop]
design:
  enabled: true
  deep_loop: false
  max_iters: 12
  prompt_profile: compact
develop:
  enabled: true
  deep_loop: false
  max_iters: 12
  prompt_profile: compact
agent_selection:
  strategy: minimal
thresholds:
  min_gap_delta: 0.08
  convergence_rounds: 2
  handoff_target: 0.85
tool_policy:
  enable_web_search: true
  enable_shell: true
  enable_subagent: true
  risk_level: balanced

Collaboration Config — Groups & Primitives

For fine-grained control, Saddle introduces a three-layer collaboration primitive system:

Layer	Description
Groups (Swimlanes)	Parallel execution lanes: design-research, design-ux, dev-planning, dev-execution, etc.
Primitives	Named collaboration steps with input/output schemas, constraints, and group assignment
Operation Primitives	Shorthand string list that auto-maps to groups by index

This allows you to define exactly who does what, in what order, with what constraints — all version-controlled in the mode YAML.

Saddle Studio — Visual Mode Editor

Saddle includes a browser-based visual editor (React + Vite) for designing and managing modes:

Feature	Description
Mode Studio	Load, edit, validate, and save mode configurations
Collaboration Editor	Drag-and-drop groups and primitives, edit schemas
i18n	English / Chinese interface toggle
Live Validation	Validate mode configs before saving to disk

Launch: saddle serve → open http://127.0.0.1:1995/studio

Saddle CLI Quick Reference

# Full pipeline
saddle run "Build an order system with audit logging" --mode fast

# Individual stages
saddle spec "requirement"
saddle design "requirement"
saddle develop "requirement"

# Mode management
saddle mode list
saddle mode show <name>
saddle mode validate <name>

# HTTP API server (with Studio)
saddle serve

# Deep-loop finalization
saddle finalize clawteam <session_id> assistant_output.txt

Also available from ClawCode:

clawcode saddle run "requirement" --mode fast
clawcode saddle mode list

---

Multi-Model Workflows

ClawCode provides five specialized multi-model collaborative workflows for different execution scenarios:

Command	Focus	Key Phases
/multi-plan	Planning only (no code edits)	Research → Parallel Analysis → Cross-validation → Plan Delivery
/multi-execute	Collaborative execution	Execute → Audit → Verify with traceable artifacts
/multi-backend	Backend-focused delivery	Prepare → Research → Ideation → Plan → Execute → Optimize → Review
/multi-frontend	Frontend-focused delivery	Same phase sequence, frontend-oriented roles
/multi-workflow	Full-stack collaboration	Parallel backend + frontend analysis, dual-review optimization

All multi-* commands share a common routing infrastructure with:

• Model pool selection — choose which LLM models to use for each role
• Fallback chains — automatic fallback if a model is unavailable
• Strategy options — quality-first, balanced, speed-first, cost-first

---

Subagent System — The Collaboration Foundation

Underneath every team command is ClawCode's subagent system — the mechanism that enables nested agent execution with isolated tool sets and independent sessions.

How It Works

When a team command dispatches work to multiple roles:

1. The orchestration prompt is built and injected into the main agent's context
2. The main agent uses the Agent/Task tool to spawn subagents for each selected role
3. Each subagent runs with an isolated tool set (defined by the role's tools allowlist)
4. Subagents create child sessions with their own message history
5. Results are aggregated back into the parent session

Key Properties

Property	Description
Tool isolation	Each subagent only has access to the tools its role allows
Session branching	Child sessions fork from the parent, maintaining context lineage
Auto-approval	Subagents auto-approve within their tool boundaries (no permission dialogs)
Iteration budget	Each subagent has configurable maxTurns to prevent runaway execution

---

Agent Customization

ClawCode's agent system is fully customizable. You can define your own specialist roles or override existing ones.

Agent File Format

Agents are defined as Markdown files with YAML frontmatter:

---
name: my-custom-reviewer
description: Security-focused code reviewer
tools: [Read, Glob, Grep, Bash]
disallowedTools: [Write, Edit]
model: claude-sonnet-4-20250514
maxTurns: 25
---

You are a security-focused code reviewer. Analyze the codebase for:
- Authentication vulnerabilities
- Input validation gaps
- SQL injection risks
- XSS attack surfaces
...

Frontmatter Key	Meaning
name	Agent ID used with the Agent tool
description	Short summary for documentation
tools	Allowlist of tools (e.g., Read, Write, Bash)
disallowedTools	Block list of tools
model	Override the default LLM model
maxTurns	Maximum conversation turns
isolation	Isolation level for the subagent

Merge Order

Agent definitions are loaded with increasing precedence (later wins):

1. Built-in agents (explore, plan, code-review, clawteam-*, designteam-*)
2. User-wide:    ~/.claude/agents/*.md
3. Project:      .claw/agents/ → .clawcode/agents/ → .claude/agents/

This means your project-level agents override user-wide agents, which override built-in agents — giving you full control without modifying the framework.

---

Session Management & Branching

Every collaboration creates and manages sessions — persistent conversation threads with full history tracking.

Session Features

Feature	Description
CRUD operations	Create, read, update, delete sessions
Branching	Fork a new session from any existing session via parent_session_id
Token tracking	Track prompt tokens, completion tokens, and cost per session
Event pubsub	Real-time events for session lifecycle (CREATED, UPDATED, DELETED)
Search	Full-text search across session history

Session Commands

Shortcut / Command	Action
Ctrl + N	Create new session
Ctrl + A	Switch between sessions
Ctrl + Shift + S	Open session panel

Branching in Practice

When a subagent spawns from a team command, it creates a child session that inherits context from the parent. This means:

• Each role's work is tracked independently
• You can revisit any role's session to continue or refine
• The full collaboration tree is preserved for auditing

---

MCP — Model Context Protocol Integration

ClawCode implements a full MCP (Model Context Protocol) client for connecting to external tool and resource servers.

What MCP Enables

Capability	Description
Tool discovery	Automatically discover available tools from connected MCP servers
Resource access	Read resources exposed by MCP servers (files, data, APIs)
Dynamic management	Add/remove MCP servers at runtime without restarting
Namespaced plugins	Plugin MCP servers are namespaced as plugin_name:server_name

Transport Modes

Transport	Use Case
Stdio	Local subprocess-based MCP servers
SSE (HTTP)	Remote HTTP-based MCP servers with Server-Sent Events

How It Connects to Collaboration

MCP tools are available to all agents during team orchestration. This means your custom MCP servers (database clients, API gateways, internal tools) become part of the team's collaborative toolkit.

---

Plugin System — Extend Collaboration

ClawCode includes a Claude Code-compatible plugin system for extending functionality through skills, hooks, MCP servers, and LSP servers.

Plugin Capabilities

Capability	Description
Skills	Reusable prompt templates and workflows
Hooks	Lifecycle events: SessionStart, UserPromptSubmit, Stop, SessionEnd
MCP Servers	Inject external tool servers into agent sessions
LSP Servers	Inject language server integrations (Python, Go, TypeScript)
Slash Commands	Custom commands via plugin namespace

Plugin Data Roots

Mode	Location	Use Case
clawcode (default)	~/.clawcode	ClawCode-native plugins
claude	~/.claude	Shared with Claude Code
custom	Absolute path	Organization-specific plugin directories

Install Sources

Source	Format
Local directory	Path to plugin folder
GitHub	owner/repo
Git URL	Remote git repository
npm / pip	Package registry
git-subdir	Subdirectory within a repository

Official Saddle Plugins

Saddle ships two official plugins for cross-platform collaboration:

Plugin	Platform	Key Features
Claude Code Plugin	Claude Code	Session memory injection, /saddle:run slash command
OpenClaw Plugin	OpenClaw	Context engine integration, pipeline triggers via HTTP

These plugins enable cross-tool collaboration — running Saddle pipelines from within Claude Code or other AI coding tools, with shared memory and context.

---

Team Experience Learning (TECAP)

ClawCode captures collaboration experience in Team Experience Capsules (TECAPs) — structured records of how teams worked together, what went well, and what to improve.

What TECAP Records

Dimension	What's Tracked
Team context	Objective, constraints, participants
Collaboration trace	Steps with owners, types, handoffs between roles
Outcome	Result quality, verification status, risk assessment
Handoff contracts	From-role → to-role with input/output contracts and acceptance criteria
Decision log	Key decisions made during collaboration
Coordination metrics	Handoff success rate, rework ratio, cycle time
Gap tracking	Per-iteration gap scores showing convergence trajectory

Experience Function

TECAP computes a weighted Team Experience Function for scoring collaboration quality:

Weight	Dimension
35%	Delivery quality
25%	Cycle time
20%	Rework ratio
20%	Escalation rate

How TECAP Improves Future Collaborations

Past Collaboration → TECAP Capture → Quality Scoring →
  ↓
Future Collaboration → TECAP Retrieval → Role Selection Hints → Better Outcomes

TECAPs are persisted to .saddle/learning/ and automatically retrieved when similar collaboration patterns are detected in future runs.

---

How It All Fits Together

Here's the complete collaboration flow from user input to deliverable:

User types: /clawteam Build a payment processing system
    │
    ▼
┌─────────────────────────────────────────────────────────┐
│  1. Slash Command Parsing                                │
│     builtin_slash.py parses arguments & flags            │
└──────────────────────┬──────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────┐
│  2. Agent Loading                                        │
│     loader.py merges built-in + user + project agents    │
└──────────────────────┬──────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────┐
│  3. Orchestration Prompt Build                           │
│     TeamService selects roles & builds multi-agent prompt│
└──────────────────────┬──────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────┐
│  4. Main Agent Dispatches Subagents                      │
│     Each role gets an isolated Agent with its tool set   │
│     ┌─────────┐ ┌─────────┐ ┌─────────┐               │
│     │Architect │ │Backend  │ │  QA     │  ...           │
│     │(Read)   │ │(Write)  │ │ (Write) │               │
│     └────┬────┘ └────┬────┘ └────┬────┘               │
│          │           │           │                      │
│          ▼           ▼           ▼                      │
│     Child sessions with independent message history      │
└──────────────────────┬──────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────┐
│  5. Result Aggregation & Convergence                     │
│     Outputs merged, gaps measured, deep loop checked     │
└──────────────────────┬──────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────┐
│  6. TECAP Writeback                                      │
│     Team experience captured for future learning          │
└─────────────────────────────────────────────────────────┘

---

ClawCode — Creative Engineering Cockpit for Serious AI Builders

One terminal. Multiple minds. Better outcomes.