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:
- Check --team/--solo flags (user override)
- Check workflow.yaml execution_mode setting
- If "auto": Analyze complexity score
- Domain count >= 3: team mode
- Affected files >= 10: team mode
- Complexity score >= 7: team mode
- Otherwise: sub-agent mode
- Verify AGENT_TEAMS is enabled
- 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:
- Receive automatic messages from teammates (progress, completion, issues)
- Use SendMessage for direct coordination
- Broadcast critical updates to all teammates
- Resolve file ownership conflicts
- 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:
- Verify all tasks are completed via TaskList
- Send shutdown_request to each teammate:
SendMessage(type: "shutdown_request", recipient: "backend-dev")
- Wait for shutdown approval from each
- Clean up team resources:
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:
| Role |
Ownership |
| backend-dev |
internal/, pkg/, cmd/** |
| tester |
_test.go, testdata/**, test/* |
| quality |
(read-only, no file ownership) |
Web projects (React, Vue, Angular):
| Role |
Ownership |
| backend-dev |
src/api/, src/models/, src/services/** |
| frontend-dev |
src/ui/, src/components/, src/pages/** |
| tester |
tests/, tests/, .test., .spec. |
| quality |
(read-only, no file ownership) |
Full-stack projects (separate client/server):
| Role |
Ownership |
| backend-dev |
server/, api/, src/server/** |
| frontend-dev |
client/, app/, src/client/** |
| data-layer |
db/, migrations/, schema/** |
| tester |
tests/, tests/, *_test.go, .test., .spec. |
| quality |
(read-only, no file ownership) |
Monorepo projects:
| Role |
Ownership |
| Per-domain teammate |
packages//, apps// |
| tester |
/tests/, /tests/, **/*_test.go, **/.test., **/.spec. |
| quality |
(read-only, no file ownership) |
Python projects:
| Role |
Ownership |
| backend-dev |
src//, / |
| tester |
tests/**, **/test_*.py, **/*_test.py |
| quality |
(read-only, no file ownership) |
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
1---2name: moai-workflow-team3description: >4 Agent Teams workflow management for MoAI-ADK. Handles team creation,5 teammate spawning, task decomposition, inter-agent messaging, and6 graceful shutdown. Integrates with SPEC workflow for team-based7 Plan and Run phases. Supports dual-mode execution with automatic8 fallback to sub-agent mode when teams are unavailable.9license: Apache-2.010compatibility: Designed for Claude Code11allowed-tools: Task TeamCreate TeamDelete SendMessage TaskCreate TaskUpdate TaskList TaskGet Read Grep Glob AskUserQuestion12user-invocable: false13metadata:14 source: https://skillmd.com/skills/modu-ai/moai-workflow-team15 version: "1.1.0"16 category: "workflow"17 status: "experimental"18 updated: "2026-02-07"19 modularized: "false"20 tags: "team, agent-teams, collaboration, parallel, dual-mode"21 related-skills: "moai-workflow-spec, moai-workflow-ddd, moai-workflow-tdd"2223# MoAI Extension: Progressive Disclosure24progressive_disclosure:25 enabled: true26 level1_tokens: 10027 level2_tokens: 80002829# MoAI Extension: Triggers30triggers:31 keywords: ["team", "agent-team", "parallel", "collaborate", "teammates", "--team"]32 agents: ["moai"]33 phases: ["plan", "run"]34---3536# MoAI Agent Teams Workflow3738## Overview3940This 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.4142## Prerequisites4344Agent Teams requires:45- `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in settings.json env46- `workflow.team.enabled: true` in workflow.yaml47- Claude Code v2.1.32 or later4849## Mode Selection5051The mode selector determines execution strategy:52531. Check --team/--solo flags (user override)542. Check workflow.yaml execution_mode setting553. If "auto": Analyze complexity score56 - Domain count >= 3: team mode57 - Affected files >= 10: team mode58 - Complexity score >= 7: team mode59 - Otherwise: sub-agent mode604. Verify AGENT_TEAMS is enabled615. If not enabled: warn user, fall back to sub-agent6263## Team Lifecycle6465### Phase 1: Team Creation6667```68TeamCreate(team_name: "moai-{workflow}-{timestamp}")69```7071Team naming convention:72- Plan phase: `moai-plan-SPEC-XXX`73- Run phase: `moai-run-SPEC-XXX`74- Debug: `moai-debug-{issue}`75- Review: `moai-review-{target}`7677### Phase 2: Task Decomposition7879Before spawning teammates, create the complete shared task list:8081```82TaskCreate(subject: "Task description", description: "Detailed requirements")83```8485Rules for task decomposition:86- Each task should be self-contained (one clear deliverable)87- Define dependencies between tasks (addBlockedBy)88- Assign file ownership boundaries per teammate role89- Target 5-6 tasks per teammate for optimal flow90- Tasks should map to SPEC requirements where applicable9192### Phase 3: Teammate Spawning9394Spawn teammates using Task tool with team_name parameter:9596```97Task(98 subagent_type: "team-backend-dev",99 team_name: "moai-run-SPEC-XXX",100 name: "backend-dev",101 prompt: "You are the backend developer for this team. Your file ownership: {detected_ownership}. SPEC context: {spec_summary}",102 mode: "plan"103)104```105106Spawning rules:107- Include SPEC context in the spawn prompt108- Assign file ownership boundaries detected from project structure (see File Ownership Detection)109- Use appropriate model per role (haiku for research, sonnet for implementation)110111Plan approval (when workflow.yaml `team.require_plan_approval: true`):112- Spawn implementation teammates with `mode: "plan"`113- Teammates must submit a plan before writing any code114- Team lead receives plan_approval_request messages from teammates115- Team lead reviews plan scope, file ownership compliance, and approach116- Approve via: `SendMessage(type: "plan_approval_response", request_id: "{id}", recipient: "{name}", approve: true)`117- Reject with feedback via: `SendMessage(type: "plan_approval_response", request_id: "{id}", recipient: "{name}", approve: false, content: "Feedback here")`118- After approval, teammate exits plan mode and begins implementation119- When `require_plan_approval` is false, spawn with `mode: "acceptEdits"` instead120121### Phase 4: Coordination122123MoAI as Team Lead monitors and coordinates:1241251. Receive automatic messages from teammates (progress, completion, issues)1262. Use SendMessage for direct coordination1273. Broadcast critical updates to all teammates1284. Resolve file ownership conflicts1295. Reassign tasks if a teammate is blocked130131Coordination patterns:132- When backend completes API: notify frontend-dev of available endpoints133- When implementation completes: assign quality validation tasks134- When quality finds issues: direct fix messages to responsible teammate135- When all tasks complete: begin shutdown sequence136137Delegate mode (when workflow.yaml `team.delegate_mode: true`):138- MoAI operates in coordination-only mode139- Focus on task assignment, message routing, progress monitoring, and conflict resolution140- Do NOT directly implement code or modify files (no Write, Edit, or Bash for implementation)141- Delegate ALL implementation work to teammates via task assignment and SendMessage142- Read and Grep are permitted for understanding context and reviewing teammate output143- If a task has no suitable teammate, spawn a new one rather than implementing directly144- When delegate_mode is false, team lead may implement small tasks directly alongside teammates145146### Phase 5: Shutdown147148Graceful shutdown sequence:1491501. Verify all tasks are completed via TaskList1512. Send shutdown_request to each teammate:152 ```153 SendMessage(type: "shutdown_request", recipient: "backend-dev")154 ```1553. Wait for shutdown approval from each1564. Clean up team resources:157 ```158 TeamDelete()159 ```160161## File Ownership Strategy162163Prevent write conflicts by assigning exclusive file ownership.164165[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.166167### File Ownership Detection168169Ownership patterns depend on the project type. Detect the project structure first, then assign accordingly:170171**Go projects:**172173| Role | Ownership |174|------|-----------|175| backend-dev | internal/**, pkg/**, cmd/** |176| tester | *_test.go, testdata/**, test/** |177| quality | (read-only, no file ownership) |178179**Web projects (React, Vue, Angular):**180181| Role | Ownership |182|------|-----------|183| backend-dev | src/api/**, src/models/**, src/services/** |184| frontend-dev | src/ui/**, src/components/**, src/pages/** |185| tester | tests/**, __tests__/**, *.test.*, *.spec.* |186| quality | (read-only, no file ownership) |187188**Full-stack projects (separate client/server):**189190| Role | Ownership |191|------|-----------|192| backend-dev | server/**, api/**, src/server/** |193| frontend-dev | client/**, app/**, src/client/** |194| data-layer | db/**, migrations/**, schema/** |195| tester | tests/**, __tests__/**, *_test.go, *.test.*, *.spec.* |196| quality | (read-only, no file ownership) |197198**Monorepo projects:**199200| Role | Ownership |201|------|-----------|202| Per-domain teammate | packages/<domain-name>/**, apps/<domain-name>/** |203| tester | **/tests/**, **/__tests__/**, **/*_test.go, **/*.test.*, **/*.spec.* |204| quality | (read-only, no file ownership) |205206**Python projects:**207208| Role | Ownership |209|------|-----------|210| backend-dev | src/<package>/**, <package>/** |211| tester | tests/**, **/test_*.py, **/*_test.py |212| quality | (read-only, no file ownership) |213214### Ownership Rules215216- No two teammates own the same file217- Shared types/interfaces: owned by the creating teammate, shared via message218- Config files: owned by team lead or explicitly assigned219- If ownership conflict: team lead resolves via SendMessage220- Test files always belong to the tester role regardless of location221222## Team Patterns Reference223224### Plan Research Team225- Roles: researcher (haiku), analyst (sonnet), architect (sonnet)226- Use: Complex SPEC creation requiring multi-angle exploration227- Duration: Short-lived (exploration phase only)228229### Implementation Team230- Roles: backend-dev (sonnet), frontend-dev (sonnet), tester (sonnet)231- Use: Cross-layer feature implementation232- Duration: Medium (full run phase)233234### Full-Stack Team235- Roles: api-layer, ui-layer, data-layer, quality (all sonnet)236- Use: Large-scale full-stack features237- Duration: Medium-long238239### Investigation Team240- Roles: hypothesis-1, hypothesis-2, hypothesis-3 (all haiku)241- Use: Complex debugging with competing theories242- Duration: Short243244### Review Team245- Roles: security-reviewer, perf-reviewer, quality-reviewer (all sonnet)246- Use: Multi-perspective code review247- Duration: Short248249## Error Recovery250251- Teammate crash: Spawn replacement with same role and resume context252- Task stuck: Team lead reassigns to different teammate253- File conflict: Team lead mediates via SendMessage, adjusts ownership254- All teammates idle: Check if tasks remain, assign or shutdown255- Token limit: Shutdown team gracefully, fall back to sub-agent for remaining work256257---258259Version: 1.1.0260Last Updated: 2026-02-07