MoAI Agent Teams Workflow

Overview

This skill manages Agent Teams execution for MoAI workflows. When team mode is selected (via --team flag, auto-detection, or configuration), MoAI operates as Team Lead coordinating persistent teammates.

Prerequisites

Agent Teams requires:

• •CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in settings.json env
• •workflow.team.enabled: true in workflow.yaml
• •Claude Code v2.1.32 or later

Mode Selection

The mode selector determines execution strategy:

1. •Check --team/--solo flags (user override)
2. •Check workflow.yaml execution_mode setting
3. •If "auto": Analyze complexity score
   • •Domain count >= 3: team mode
   • •Affected files >= 10: team mode
   • •Complexity score >= 7: team mode
   • •Otherwise: sub-agent mode
4. •Verify AGENT_TEAMS is enabled
5. •If not enabled: warn user, fall back to sub-agent

Team Lifecycle

Phase 1: Team Creation

TeamCreate(team_name: "moai-{workflow}-{timestamp}")

Team naming convention:

• •Plan phase: moai-plan-SPEC-XXX
• •Run phase: moai-run-SPEC-XXX
• •Debug: moai-debug-{issue}
• •Review: moai-review-{target}

Phase 2: Task Decomposition

Before spawning teammates, create the complete shared task list:

TaskCreate(subject: "Task description", description: "Detailed requirements")

Rules for task decomposition:

• •Each task should be self-contained (one clear deliverable)
• •Define dependencies between tasks (addBlockedBy)
• •Assign file ownership boundaries per teammate role
• •Target 5-6 tasks per teammate for optimal flow
• •Tasks should map to SPEC requirements where applicable

Phase 3: Teammate Spawning

Spawn teammates using Task tool with team_name parameter:

Task(
  subagent_type: "team-backend-dev",
  team_name: "moai-run-SPEC-XXX",
  name: "backend-dev",
  prompt: "You are the backend developer for this team. Your file ownership: {detected_ownership}. SPEC context: {spec_summary}",
  mode: "plan"
)

Spawning rules:

• •Include SPEC context in the spawn prompt
• •Assign file ownership boundaries detected from project structure (see File Ownership Detection)
• •Use appropriate model per role (haiku for research, sonnet for implementation)

Plan approval (when workflow.yaml team.require_plan_approval: true):

• •Spawn implementation teammates with mode: "plan"
• •Teammates must submit a plan before writing any code
• •Team lead receives plan_approval_request messages from teammates
• •Team lead reviews plan scope, file ownership compliance, and approach
• •Approve via: SendMessage(type: "plan_approval_response", request_id: "{id}", recipient: "{name}", approve: true)
• •Reject with feedback via: SendMessage(type: "plan_approval_response", request_id: "{id}", recipient: "{name}", approve: false, content: "Feedback here")
• •After approval, teammate exits plan mode and begins implementation
• •When require_plan_approval is false, spawn with mode: "acceptEdits" instead

Phase 4: Coordination

MoAI as Team Lead monitors and coordinates:

1. •Receive automatic messages from teammates (progress, completion, issues)
2. •Use SendMessage for direct coordination
3. •Broadcast critical updates to all teammates
4. •Resolve file ownership conflicts
5. •Reassign tasks if a teammate is blocked

Coordination patterns:

• •When backend completes API: notify frontend-dev of available endpoints
• •When implementation completes: assign quality validation tasks
• •When quality finds issues: direct fix messages to responsible teammate
• •When all tasks complete: begin shutdown sequence

Delegate mode (when workflow.yaml team.delegate_mode: true):

• •MoAI operates in coordination-only mode
• •Focus on task assignment, message routing, progress monitoring, and conflict resolution
• •Do NOT directly implement code or modify files (no Write, Edit, or Bash for implementation)
• •Delegate ALL implementation work to teammates via task assignment and SendMessage
• •Read and Grep are permitted for understanding context and reviewing teammate output
• •If a task has no suitable teammate, spawn a new one rather than implementing directly
• •When delegate_mode is false, team lead may implement small tasks directly alongside teammates

Phase 5: Shutdown

Graceful shutdown sequence:

1. •Verify all tasks are completed via TaskList
2. •Send shutdown_request to each teammate:
   code

   SendMessage(type: "shutdown_request", recipient: "backend-dev")
   

3. •Wait for shutdown approval from each
4. •Clean up team resources:
   code

   TeamDelete()
   

File Ownership Strategy

Prevent write conflicts by assigning exclusive file ownership.

[HARD] Team lead MUST analyze project structure before assigning ownership. Use Explore agent or Glob/Grep to map directory structure and assign ownership boundaries that match the actual project layout. Never use hardcoded patterns from a different project type.

File Ownership Detection

Ownership patterns depend on the project type. Detect the project structure first, then assign accordingly:

Go projects:

Web projects (React, Vue, Angular):

Full-stack projects (separate client/server):

Monorepo projects:

Python projects:

Ownership Rules

• •No two teammates own the same file
• •Shared types/interfaces: owned by the creating teammate, shared via message
• •Config files: owned by team lead or explicitly assigned
• •If ownership conflict: team lead resolves via SendMessage
• •Test files always belong to the tester role regardless of location

Team Patterns Reference

Plan Research Team

• •Roles: researcher (haiku), analyst (sonnet), architect (sonnet)
• •Use: Complex SPEC creation requiring multi-angle exploration
• •Duration: Short-lived (exploration phase only)

Implementation Team

• •Roles: backend-dev (sonnet), frontend-dev (sonnet), tester (sonnet)
• •Use: Cross-layer feature implementation
• •Duration: Medium (full run phase)

Full-Stack Team

• •Roles: api-layer, ui-layer, data-layer, quality (all sonnet)
• •Use: Large-scale full-stack features
• •Duration: Medium-long

Investigation Team

• •Roles: hypothesis-1, hypothesis-2, hypothesis-3 (all haiku)
• •Use: Complex debugging with competing theories
• •Duration: Short

Review Team

• •Roles: security-reviewer, perf-reviewer, quality-reviewer (all sonnet)
• •Use: Multi-perspective code review
• •Duration: Short

Error Recovery

• •Teammate crash: Spawn replacement with same role and resume context
• •Task stuck: Team lead reassigns to different teammate
• •File conflict: Team lead mediates via SendMessage, adjusts ownership
• •All teammates idle: Check if tasks remain, assign or shutdown
• •Token limit: Shutdown team gracefully, fall back to sub-agent for remaining work

Version: 1.1.0 Last Updated: 2026-02-07