moai-workflow-team

name	moai-workflow-team
description	Agent Teams workflow management for MoAI-ADK. Handles team creation, teammate spawning, task decomposition, inter-agent messaging, and graceful shutdown. Integrates with SPEC workflow for team-based Plan and Run phases. Supports dual-mode execution with automatic fallback to sub-agent mode when teams are unavailable.
license	Apache-2.0
compatibility	Designed for Claude Code
allowed-tools	Task TeamCreate TeamDelete SendMessage TaskCreate TaskUpdate TaskList TaskGet Read Grep Glob AskUserQuestion
user-invocable	false
metadata	{"version":"1.1.0","category":"workflow","status":"experimental","updated":"2026-02-07","modularized":"false","tags":"team, agent-teams, collaboration, parallel, dual-mode","related-skills":"moai-workflow-spec, moai-workflow-ddd, moai-workflow-tdd"}
progressive_disclosure	{"enabled":true,"level1_tokens":100,"level2_tokens":8000}
triggers	{"keywords":["team","agent-team","parallel","collaborate","teammates","--team"],"agents":["moai"],"phases":["plan","run"]}

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)