Agent Teams - Parallel Team-Based Development

Parallel Multi-Agent Orchestration using Claude Code Agent Teams

Agent Teams is an experimental feature in Claude Code v2.1.32+ that processes complex multi-domain tasks in parallel using team-based approach.

Overview

Agent Teams is a feature where J.A.R.V.I.S./F.R.I.D.A.Y. orchestrators compose multiple specialized agents into teams to perform work in parallel.

Sub-Agent Approach vs Agent Teams

Aspect	Sub-Agent Approach	Agent Teams Approach
Execution	Sequential	Parallel
Communication	Task() call/return	Real-time collaboration via SendMessage
Task Management	Orchestrator manages directly	Autonomous distribution via shared TaskList
State	Stateless	State maintained during team session
Best For	Single domain, simple tasks	Multi-domain, complex tasks

Activation Requirements

Prerequisites

Claude Code Version: v2.1.32 or higher
Environment Variable: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
Config File: team.enabled: true in .jikime/config/workflow.yaml

bash

# Set environment variable
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

# Or add to settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Auto-Activation Conditions

Team mode is automatically activated when any of the following conditions are met:

Condition	Threshold	Description
Domain Count	>= 3	frontend, backend, database, etc.
File Count	>= 10	Number of files to be modified
Complexity Score	>= 7	Scale of 1-10

Quick Start Guide

Step 1: Environment Setup

bash

# 1. Check Claude Code version (v2.1.32 or higher required)
claude --version

# 2. Set environment variable (in terminal)
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

# 3. Or add to ~/.claude/settings.json for permanent setting
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Step 2: Verify Project Configuration

bash

# Initialize JikiME-ADK (skip if already done)
jikime-adk init

# Verify team settings in workflow.yaml
cat .jikime/config/workflow.yaml | grep -A 5 "team:"

Step 3: Run Team Mode

bash

# Use team mode in Plan Phase
/jikime:1-plan "Implement user authentication system" --team

# Use team mode in Run Phase
/jikime:2-run SPEC-AUTH-001 --team

Detailed Usage Guide

Scenario 1: New Feature Development (Full Stack)

When developing a complex feature with backend, frontend, and tests in parallel:

bash

# 1. Plan Phase - Analyze requirements as a team
/jikime:1-plan "Implement OAuth 2.0 social login (Google, GitHub, Kakao)" --team

# What happens internally:
# - team-researcher: Analyzes existing auth code
# - team-analyst: Identifies requirements and edge cases
# - team-architect: Makes technical design and architecture decisions
# → Result: SPEC-SOCIAL-LOGIN-001.md generated

# 2. After SPEC approval, Run Phase - Implement as a team
/jikime:2-run SPEC-SOCIAL-LOGIN-001 --team

# What happens internally:
# - team-backend-dev: OAuth provider integration, API endpoints
# - team-frontend-dev: Login buttons, callback page
# - team-tester: E2E tests, unit tests
# - team-quality: TRUST 5 quality verification

# 3. Sync after completion
/jikime:3-sync SPEC-SOCIAL-LOGIN-001

Scenario 2: UI/UX-Focused Feature Development

When developing UI-focused features with a designer included:

bash

# Use design_implementation pattern
/jikime:2-run SPEC-DASHBOARD-001 --team --pattern=design_implementation

# Team composition:
# - team-designer: Design tokens, component styles
# - team-backend-dev: Dashboard data API
# - team-frontend-dev: React component implementation
# - team-tester: Visual regression testing

Scenario 3: Complex Bug Investigation

When investigating multiple hypotheses in parallel:

bash

# Use investigation pattern
/jikime:build-fix --team

# Team composition (competitive hypothesis investigation):
# - hypothesis-1: Memory leak hypothesis
# - hypothesis-2: Race condition hypothesis
# - hypothesis-3: API timeout hypothesis
# → The first hypothesis to find the cause wins

Scenario 4: Pre-Production Quality Verification

When quality gates are critical:

bash

# Use quality_gate pattern
/jikime:2-run SPEC-PAYMENT-001 --team --pattern=quality_gate

# Team composition:
# - team-backend-dev: Payment logic implementation
# - team-frontend-dev: Payment UI implementation
# - team-tester: Security tests, payment flow tests
# - team-quality: TRUST 5 + security audit + performance verification

Team Mode vs Solo Mode Selection Guide

Situation	Recommended Mode	Command
Simple bug fix	Solo	`/jikime:2-run SPEC-001 --solo`
Single file modification	Solo	`/jikime:2-run SPEC-001 --solo`
Multi-domain feature	Team	`/jikime:2-run SPEC-001 --team`
10+ file changes	Team	Auto-detected
UI + API + DB changes	Team	`/jikime:2-run SPEC-001 --team`
Complex refactoring	Team	`/jikime:2-run SPEC-001 --team`

Team Collaboration Patterns

SendMessage Usage Examples

javascript

// Backend → Frontend: API ready notification
SendMessage(
  recipient: "frontend-dev",
  type: "api_ready",
  content: {
    endpoint: "POST /api/auth/oauth/callback",
    schema: {
      provider: "string",
      code: "string",
      state: "string"
    },
    response: {
      user: "User",
      accessToken: "string",
      refreshToken: "string"
    }
  }
)

// Frontend → Tester: Component ready notification
SendMessage(
  recipient: "tester",
  type: "component_ready",
  content: {
    component: "SocialLoginButton",
    path: "src/components/auth/SocialLoginButton.tsx",
    testable: true,
    props: ["provider", "onSuccess", "onError"]
  }
)

// Tester → Quality: Tests passed notification
SendMessage(
  recipient: "quality",
  type: "tests_passed",
  content: {
    coverage: 87,
    passedTests: 45,
    failedTests: 0,
    duration: "2m 34s"
  }
)

// Quality → Team Lead: Quality gate passed
SendMessage(
  recipient: "team-lead",
  type: "quality_gate_passed",
  content: {
    trust5Score: 4.2,
    securityIssues: 0,
    performanceScore: "A",
    recommendation: "Ready for production"
  }
)

File Change Request Pattern

javascript

// Frontend requesting Backend type change
SendMessage(
  recipient: "backend-dev",
  type: "change_request",
  content: {
    file: "src/types/auth.ts",
    requestedChange: "Add 'profileImage' field to User type",
    reason: "Required for social login avatar display",
    priority: "high"
  }
)

// Backend response
SendMessage(
  recipient: "frontend-dev",
  type: "change_completed",
  content: {
    file: "src/types/auth.ts",
    change: "Added profileImage: string | null to User type",
    commitRef: "abc123"
  }
)

Troubleshooting

Problem 1: Team Mode Not Activating

Symptom: Sequential execution despite using --team flag

Solution:

bash

# 1. Check Claude Code version
claude --version  # Must be v2.1.32 or higher

# 2. Verify environment variable
echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS  # Should be "1"

# 3. Check configuration file
cat .jikime/config/workflow.yaml | grep "team:" -A 3
# Verify enabled: true

# 4. Force activation
/jikime:2-run SPEC-001 --team --force

Problem 2: Teammate Communication Failure

Symptom: SendMessage not being delivered

Solution:

bash

# 1. Verify team session status
# Check if team name is correct

# 2. Verify recipient name (use exact name)
# ✅ "backend-dev"
# ❌ "team-backend-dev"
# ❌ "backendDev"

# 3. Restart team
/jikime:team-restart

Problem 3: File Conflicts

Symptom: Two teammates trying to modify the same file

Solution:

javascript

// 1. Request from owner instead of modifying directly
SendMessage(
  recipient: "backend-dev",  // File owner
  type: "change_request",
  content: {
    file: "src/types/user.ts",
    requestedChange: "Add socialProvider field",
    reason: "Needed for OAuth integration"
  }
)

// 2. Coordinate before modifying shared files
// src/types/**, src/utils/** etc. require coordination via SendMessage

Problem 4: Teammate Idle

Symptom: Teammate waiting without tasks

Solution:

javascript

// Check unassigned tasks in TaskList
TaskList()

// Assign task to idle teammate
TaskCreate(
  subject: "Implement error handling for OAuth callback",
  description: "Add try-catch and error UI for failed OAuth",
  owner: "frontend-dev"  // Assign to idle teammate
)

Problem 5: Quality Gate Failure

Symptom: team-quality rejecting work

Solution:

bash

# 1. Check quality report
# Review failure reason in message from team-quality

# 2. Common failure reasons:
# - Test coverage below threshold (80% required)
# - Lint errors present
# - Security vulnerabilities found
# - Performance criteria not met

# 3. Request fix from relevant teammate
SendMessage(
  recipient: "tester",
  type: "coverage_required",
  content: {
    current: 72,
    required: 80,
    uncoveredFiles: ["src/services/oauth.ts"]
  }
)

Best Practices

1. Optimize Team Composition

yaml

# Recommended team composition by project size
small_project:  # < 5 files
  mode: solo

medium_project:  # 5-20 files
  mode: team
  pattern: implementation
  roles: [backend-dev, frontend-dev, tester]

large_project:  # > 20 files
  mode: team
  pattern: quality_gate
  roles: [backend-dev, frontend-dev, designer, tester, quality]

2. Effective File Ownership Setup

yaml

# Set clear boundaries
file_ownership:
  team-backend-dev:
    - "src/api/**"
    - "src/services/**"
    - "src/repositories/**"
    - "prisma/**"

  team-frontend-dev:
    - "src/components/**"
    - "src/pages/**"
    - "src/hooks/**"
    - "src/stores/**"

  # Minimize shared files
  shared:
    - "src/types/**"  # Only type definitions shared

3. Minimize Communication

javascript

// ❌ Bad: Too frequent communication
SendMessage(recipient: "frontend-dev", type: "progress", content: "Started task")
SendMessage(recipient: "frontend-dev", type: "progress", content: "50% done")
SendMessage(recipient: "frontend-dev", type: "progress", content: "Almost done")

// ✅ Good: Only meaningful communication
SendMessage(
  recipient: "frontend-dev",
  type: "api_ready",
  content: { endpoint: "/api/users", schema: {...} }
)

4. Utilize Quality Gates

yaml

# Always include quality teammate for critical features
critical_features:
  - payment
  - authentication
  - user_data

pattern_for_critical: quality_gate

5. Prepare for Fallback

yaml

# Sub-Agent fallback configuration
workflow:
  team:
    fallback:
      enabled: true
      log_level: "warn"
      preserve_progress: true  # Preserve progress

Team Agent List

Plan Phase Agents (Read-Only)

Agent	Model	Role	Skill
team-researcher	haiku	Codebase exploration, architecture analysis	jikime-foundation-philosopher
team-analyst	inherit	Requirements analysis, edge case identification	jikime-workflow-spec
team-architect	inherit	Technical design, alternative evaluation	jikime-domain-architecture

Run Phase Agents (Implementation Permissions)

Agent	Model	Role	File Ownership
team-backend-dev	inherit	API, services, business logic implementation	`src/api/`, `src/services/`
team-frontend-dev	inherit	UI components, pages implementation	`src/components/`, `src/pages/`
team-designer	inherit	UI/UX design, design tokens	`design/`, `src/styles/tokens/`
team-tester	inherit	Test writing, coverage verification	`tests/`, `/.test.`
team-quality	inherit (read-only)	TRUST 5 verification, quality gates	-

Team Composition Patterns

1. plan_research (Plan Phase)

Parallel research team for SPEC document generation

yaml

roles:
  - researcher  # Codebase exploration
  - analyst     # Requirements analysis
  - architect   # Technical design

When to Use: /jikime:1-plan --team or auto-detected complexity

2. implementation (Run Phase)

Development team for feature implementation

yaml

roles:
  - backend-dev   # Server side
  - frontend-dev  # Client side
  - tester        # Testing

When to Use: /jikime:2-run SPEC-001 --team

3. design_implementation

Feature implementation with UI/UX focus

yaml

roles:
  - designer      # UI/UX design
  - backend-dev
  - frontend-dev
  - tester

4. quality_gate

Production deployment with quality verification focus

yaml

roles:
  - backend-dev
  - frontend-dev
  - tester
  - quality       # TRUST 5 verification

5. investigation

Competitive hypothesis investigation for complex bugs

yaml

roles:
  - hypothesis-1
  - hypothesis-2
  - hypothesis-3
model: haiku  # Fast and inexpensive model

When to Use: /jikime:build-fix --team

Workflows

Team Plan Workflow

┌─────────────────────────────────────────────────────────┐
│  Phase 0: TeamCreate("jikime-plan-{feature}")           │
│  ↓                                                       │
│  Phase 1: Parallel Spawn                                 │
│  ├─ Task(team-researcher) ──┐                           │
│  ├─ Task(team-analyst) ─────┼─→ Parallel Execution      │
│  └─ Task(team-architect) ───┘                           │
│  ↓                                                       │
│  Phase 2: Monitoring & Coordination                      │
│  (Real-time collaboration via SendMessage)               │
│  ↓                                                       │
│  Phase 3: Result Integration → SPEC Document Generation  │
│  ↓                                                       │
│  Phase 4: User Approval (AskUserQuestion)               │
│  ↓                                                       │
│  Phase 5: TeamDelete + /clear                           │
└─────────────────────────────────────────────────────────┘

Team Run Workflow

┌─────────────────────────────────────────────────────────┐
│  Phase 0: TeamCreate + Task Decomposition               │
│           (File Ownership Assignment)                    │
│  ↓                                                       │
│  Phase 1: Parallel Implementation Team Spawn            │
│  ├─ backend-dev (src/api/**)                            │
│  ├─ frontend-dev (src/components/**)                    │
│  ├─ tester (tests/**)                                   │
│  └─ quality (read-only)                                 │
│  ↓                                                       │
│  Phase 2: Parallel Implementation                        │
│  - SendMessage("api_ready") → frontend starts work      │
│  - SendMessage("component_ready") → tester starts work  │
│  ↓                                                       │
│  Phase 3: Quality Gate                                   │
│  - team-quality performs TRUST 5 verification           │
│  - Pass: complete, Fail: request fixes                  │
│  ↓                                                       │
│  Phase 4: TeamDelete                                    │
└─────────────────────────────────────────────────────────┘

Team API Reference

TeamCreate

Initializes a team session.

javascript

TeamCreate(team_name: "jikime-plan-auth-feature")

Task (Team Mode)

Creates a teammate. Requires team_name and name parameters.

javascript

Task(
  subagent_type: "team-backend-dev",
  team_name: "jikime-run-spec-001",
  name: "backend-dev",
  prompt: "..."
)

SendMessage

Sends messages between teammates or to team lead.

javascript

// API ready notification
SendMessage(
  recipient: "frontend-dev",
  type: "api_ready",
  content: {
    endpoint: "POST /api/auth/login",
    schema: { email: "string", password: "string" }
  }
)

// Bug report
SendMessage(
  recipient: "backend-dev",
  type: "bug_report",
  content: {
    test: "auth.test.ts:45",
    expected: "200 OK",
    actual: "500 Error"
  }
)

// Shutdown request
SendMessage(
  type: "shutdown_request",
  recipient: "researcher",
  content: "Plan phase complete"
)

TaskCreate/Update/List/Get

Manages shared task list.

javascript

// Create task
TaskCreate(
  subject: "Implement login API",
  description: "...",
  owner: "backend-dev"
)

// Update status
TaskUpdate(taskId: "1", status: "in_progress")
TaskUpdate(taskId: "1", status: "completed")

// List tasks
TaskList()  // Visible to all teammates

// Get details
TaskGet(taskId: "1")

TeamDelete

Terminates team session. Must be called after all teammates have shut down.

javascript

// First send shutdown request to all teammates
SendMessage(type: "shutdown_request", recipient: "all", ...)

// After confirming teammate termination
TeamDelete(team_name: "jikime-run-spec-001")

File Ownership

To prevent file conflicts in team mode, each teammate owns specific file patterns.

yaml

file_ownership:
  team-backend-dev:
    - "src/api/**"
    - "src/services/**"
    - "src/repositories/**"
    - "src/models/**"
    - "src/middleware/**"
    - "prisma/migrations/**"

  team-frontend-dev:
    - "src/components/**"
    - "src/pages/**"
    - "src/app/**"
    - "src/hooks/**"
    - "src/stores/**"
    - "src/styles/**"

  team-designer:
    - "design/**"
    - "src/styles/tokens/**"

  team-tester:
    - "tests/**"
    - "__tests__/**"
    - "**/*.test.*"
    - "**/*.spec.*"
    - "cypress/**"
    - "playwright/**"

  shared:  # Requires coordination via SendMessage
    - "src/types/**"
    - "src/utils/**"
    - "src/lib/**"

Conflict Resolution

When you need to modify a file you don't own:

javascript

// ❌ Don't modify directly

// ✅ Request from file owner
SendMessage(
  recipient: "backend-dev",
  type: "change_request",
  content: {
    file: "src/types/user.ts",
    requested_change: "Add 'refreshToken' field",
    reason: "Needed for token refresh flow"
  }
)

Hook Events

TeammateIdle

Called when a teammate completes work and becomes idle.

yaml

TeammateIdle:
  exit_code_0: "Accept idle state - no more work"
  exit_code_2: "Reject idle - assign additional work from TaskList"

TaskCompleted

Called when a teammate marks a task as completed.

yaml

TaskCompleted:
  exit_code_0: "Accept completion - end task"
  exit_code_2: "Reject completion - additional work required"
  validation:
    - Tests pass
    - Coverage target met
    - No lint errors

Usage Examples

Using Team Mode in Plan Phase

bash

# Explicit team mode
/jikime:1-plan "Implement user authentication system" --team

# Auto-detection (activates automatically if complexity is high)
/jikime:1-plan "Complex multi-domain feature"

Using Team Mode in Run Phase

bash

# Explicit team mode
/jikime:2-run SPEC-001 --team

# Team with designer
/jikime:2-run SPEC-001 --team --pattern=design_implementation

Using Team Mode for Debugging

bash

# Competitive hypothesis investigation
/jikime:build-fix --team

# Investigate multiple hypotheses in parallel

Force Sub-Agent Mode

bash

# Disable team mode (for simple tasks)
/jikime:2-run SPEC-001 --solo

Configuration File

.jikime/config/workflow.yaml

yaml

workflow:
  execution_mode: "auto"  # auto | subagent | team

  team:
    enabled: true
    max_teammates: 10
    default_model: "inherit"
    require_plan_approval: true
    delegate_mode: true
    teammate_display: "auto"

    auto_selection:
      min_domains_for_team: 3
      min_files_for_team: 10
      min_complexity_score: 7

    file_ownership:
      team-backend-dev:
        - "src/api/**"
        - "src/services/**"
      team-frontend-dev:
        - "src/components/**"
        - "src/pages/**"
      team-tester:
        - "tests/**"

    patterns:
      plan_research:
        roles: [researcher, analyst, architect]
      implementation:
        roles: [backend-dev, frontend-dev, tester]

    hooks:
      teammate_idle:
        enabled: true
        validate_work: true
      task_completed:
        enabled: true
        require_quality_check: true

Fallback Behavior

When team mode fails or requirements are not met:

Warning log output
Auto-switch to Sub-Agent mode
Resume from last completed task
No data loss

Fallback Trigger Conditions

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS environment variable not set
workflow.team.enabled: false
TeamCreate failure
Teammate spawn failure
Network error

Version Information

Item	Value
Document Version	1.1.0
Required Claude Code	v2.1.32+
Status	Experimental
Last Updated	2026-02-15

Changelog

Version	Date	Changes
1.1.0	2026-02-15	Added Quick Start Guide, Detailed Usage Guide, Troubleshooting, Best Practices
1.0.0	2026-02-14	Initial documentation

Agent Teams - Parallel Team-Based Development ​

Overview ​

Sub-Agent Approach vs Agent Teams ​

Activation Requirements ​

Prerequisites ​

Auto-Activation Conditions ​

Quick Start Guide ​

Step 1: Environment Setup ​

Step 2: Verify Project Configuration ​

Step 3: Run Team Mode ​

Detailed Usage Guide ​

Scenario 1: New Feature Development (Full Stack) ​

Scenario 2: UI/UX-Focused Feature Development ​

Scenario 3: Complex Bug Investigation ​

Scenario 4: Pre-Production Quality Verification ​

Team Mode vs Solo Mode Selection Guide ​

Team Collaboration Patterns ​

SendMessage Usage Examples ​

File Change Request Pattern ​

Troubleshooting ​

Problem 1: Team Mode Not Activating ​

Problem 2: Teammate Communication Failure ​

Problem 3: File Conflicts ​

Problem 4: Teammate Idle ​

Problem 5: Quality Gate Failure ​

Best Practices ​

1. Optimize Team Composition ​

2. Effective File Ownership Setup ​

3. Minimize Communication ​

4. Utilize Quality Gates ​

5. Prepare for Fallback ​

Team Agent List ​

Plan Phase Agents (Read-Only) ​

Run Phase Agents (Implementation Permissions) ​

Team Composition Patterns ​

1. plan_research (Plan Phase) ​

2. implementation (Run Phase) ​

3. design_implementation ​

4. quality_gate ​

5. investigation ​

Workflows ​

Team Plan Workflow ​

Team Run Workflow ​

Team API Reference ​

TeamCreate ​

Task (Team Mode) ​

SendMessage ​

TaskCreate/Update/List/Get ​

TeamDelete ​

File Ownership ​

Conflict Resolution ​

Hook Events ​

TeammateIdle ​

TaskCompleted ​

Usage Examples ​

Using Team Mode in Plan Phase ​

Using Team Mode in Run Phase ​

Using Team Mode for Debugging ​

Force Sub-Agent Mode ​

Configuration File ​

.jikime/config/workflow.yaml ​

Fallback Behavior ​

Fallback Trigger Conditions ​

Related Documentation ​

Version Information ​

Changelog ​

Agent Teams - Parallel Team-Based Development

Overview

Sub-Agent Approach vs Agent Teams

Activation Requirements

Prerequisites

Auto-Activation Conditions

Quick Start Guide

Step 1: Environment Setup

Step 2: Verify Project Configuration

Step 3: Run Team Mode

Detailed Usage Guide

Scenario 1: New Feature Development (Full Stack)

Scenario 2: UI/UX-Focused Feature Development

Scenario 3: Complex Bug Investigation

Scenario 4: Pre-Production Quality Verification

Team Mode vs Solo Mode Selection Guide

Team Collaboration Patterns

SendMessage Usage Examples

File Change Request Pattern

Troubleshooting

Problem 1: Team Mode Not Activating

Problem 2: Teammate Communication Failure

Problem 3: File Conflicts

Problem 4: Teammate Idle

Problem 5: Quality Gate Failure

Best Practices

1. Optimize Team Composition

2. Effective File Ownership Setup

3. Minimize Communication

4. Utilize Quality Gates

5. Prepare for Fallback

Team Agent List

Plan Phase Agents (Read-Only)

Run Phase Agents (Implementation Permissions)

Team Composition Patterns

1. plan_research (Plan Phase)

2. implementation (Run Phase)

3. design_implementation

4. quality_gate

5. investigation

Workflows

Team Plan Workflow

Team Run Workflow

Team API Reference

TeamCreate

Task (Team Mode)

SendMessage

TaskCreate/Update/List/Get

TeamDelete

File Ownership

Conflict Resolution

Hook Events

TeammateIdle

TaskCompleted

Usage Examples

Using Team Mode in Plan Phase

Using Team Mode in Run Phase

Using Team Mode for Debugging

Force Sub-Agent Mode

Configuration File

.jikime/config/workflow.yaml

Fallback Behavior

Fallback Trigger Conditions

Related Documentation

Version Information

Changelog