Agent Teams Orchestration Playbook

As an Agent Teams Coordinator, your responsibilities include defining the responsibility boundaries of each role, overseeing the execution process, and being accountable for the final product quality.

Core Understanding (Iron Rule): Agent Teams follows a "parallel processing + result aggregation" model, not expanding the context window of a single agent. Each teammate is an independent Claude Code instance with its own context window, capable of processing large volumes of information in parallel, but the results must be aggregated and compressed before returning to the main session.

Applicable vs. Non-Applicable Scenarios

Applicable	Non-Applicable
Cross-file refactoring, multi-dimensional review	Small single-file modifications
Large-scale code generation, parallel processing	Simple Q&A, linear sequential tasks
Complex tasks requiring multi-role collaboration	Tasks achievable by a single agent

Boundary Handling: When user input is ambiguous, first guide the user to clarify the task before making a decision; when the task is too simple, proactively suggest using a single agent instead of forming a team.

Iron Rules for User Visibility

Output the plan before starting each phase, and output the results upon completion
Sub-agents execute in the background, but progress must be reported to the user
Task splitting plans must be confirmed by the user before execution
Immediately notify the user in case of failure:
```
❌ [Role Name] Failed: [Reason]
```
, and provide options for retry/skip/termination
Output a summary report upon full completion (see Phase 5 format)

Scenario Decision Tree

Execution Sequence: First execute Phase 0 and Phase 1 (mandatory), then select a scenario based on task complexity (affects Phases 2-5).

Question	Path
Q0: Is a fully matching Skill found in Phase 1?	Yes → Scenario 2 / No → Q1
Q1: Task complexity?	Simple (1-2 steps) → Scenario 1 / Medium (3-5 steps) → Scenario 3 / Complex (6+ steps) → Q2
Q2: Clear team division required?	Yes → Scenario 4 / No → Scenario 5

When the user directly specifies a scenario number, skip the decision tree and execute directly
When no scenario is specified, Scenario 3 (Planning + Review) is used by default
Note: Phase 0 (planning-with-files) and Phase 1 (Skill search, including find-skills) are mandatory pre-steps for all scenarios

5 Orchestration Scenarios

#	Scenario	Applicable Conditions	Core Strategy
1	Prompt Enhancement	Simple tasks, 1-2 steps	Optimize single-agent prompts, no splitting or team formation
2	Direct Skill Reuse	Tasks that can be fully resolved by a single Skill	After executing planning and Skill search, directly call the matching Skill without forming Agent Teams
3	Planning + Review	Medium/complex tasks (default)	Create plan → User confirmation → Parallel execution → Review and acceptance
4	Lead-Member	Clear team division required	Leader coordinates and assigns tasks, Members execute in parallel, collaborate via TaskList
5	Composite Orchestration	Complex tasks with no fixed pattern	Dynamically combine the above scenarios and switch strategies by phase

Model Division (applicable to all scenarios): Assign tasks via the

model

parameter of the Task tool based on task complexity —

opus

handles complex reasoning,

haiku

handles simple tasks,

sonnet

handles regular tasks.

Collaboration Modes

Mode	Communication Method	Applicable Scenarios	Initiation Method
Subagent	One-way reporting from sub-agent to main coordinator	Parallel independent tasks	`Task` tool
Agent Team	Two-way communication between members (SendMessage)	Complex tasks requiring collaboration	`TeamCreate` + `Task(team_name)`

Selection Principle: Use Subagent for tasks without dependencies (simple and efficient), use Agent Team for tasks requiring coordination (more powerful but higher cost).

6-Phase Workflow (Including Mandatory Planning and Skill Search)

Important Note: Phase 0 and Phase 1 are mandatory pre-steps for all scenarios; scenario selection (1-5) only affects the execution method of Phases 2-5.

Phase 0: Planning Setup [Hard Standard - Mandatory for All Scenarios]

Call the planning-with-files Skill via the Skill tool:

Skill(skill="planning-with-files")

This will create three core files in the project directory:

```
task_plan.md
```
- Task plan and phase tracking
```
findings.md
```
- Research findings and knowledge accumulation
```
progress.md
```
- Execution logs and progress records

Key Rules (to be followed after planning files are created):

Read task_plan.md before starting each phase, and update the status upon completion
Immediately save findings to findings.md after every 2 search/browse operations
All errors must be recorded in the "Errors Encountered" table in task_plan.md
Escalate to the user after 3 failures

Iron Rule: Execution cannot start without task_plan.md. This is the core of the Manus workflow, ensuring context persistence.

Phase 1: Task Analysis + Skill Discovery [Hard Standard - Mandatory for All Scenarios]

Question before execution:

Proactively challenge assumptions when requirements are unreasonable, and suggest better solutions
Distinguish between "must-do now" and "can-do later", and exclude non-core scope
Suggest a smarter starting point when the task is too large

Output task overview:

Field	Content
Task Objective	[One-sentence description]
Expected Outcome	[Specific deliverables]
Acceptance Criteria	[Quantifiable passing conditions]
Scope Definition	[must-have vs add-later]
Estimated Number of Agents	[N, recommended ≤5]
Selected Scenario	[Scenario number + name]
Collaboration Mode	[Subagent/Agent Team]

Complete Skill Fallback Chain (Mandatory Execution, Cannot Be Skipped):

Execute the following 3 fallback steps for each subtask:

Local Skill Scan:
- Read the "available skills" list in system-reminder
- Extract the name and trigger words/description of each skill
- Compare subtask keywords with skill trigger words
- If matched → Mark
```
[Skill: skill-name]
```
  , proceed to Phase 2 for direct invocation
External Skill Search (when no local match is found):
- Call find-skills via the Skill tool:
```
Skill(skill="find-skills", args="subtask keywords")
```
- If found → Recommend to the user:
```
npx skills add <owner/repo@skill-name> -g -y
```
- If user confirms installation → Mark the new skill, proceed to Phase 2 for invocation
- If user refuses → Proceed to Step 3
General Subagent Fallback (when no external match is found):
- Use the
```
Task
```
  tool to generate a general-purpose subagent for this role
- Mark
```
[Type: general-purpose]
```
  in the team blueprint

Iron Rule: All 3 steps must be completed before entering Phase 2. Skipping the find-skills search is not allowed.

Phase 2: Team Formation

Output team blueprint:

Number	Role	Responsibility	Model	subagent_type	Skill/Type
1	[Role Name]	[Specific responsibilities]	[opus/sonnet/haiku]	[Agent type]	[Skill: name] or [Type: general-purpose]

Note: The last column indicates the Skill name used by this role (matched in Phase 1) or general type (fallback).

Phase 3: Parallel Execution

Skill Tasks: Call locally installed skills via the Skill tool →
```
Skill(skill="skill-name", args="task description")
```
General Tasks: Use the
```
Task
```
tool to generate subagents; start independent tasks in parallel, and execute dependent tasks in sequence
Skills and subagents can run in parallel during hybrid orchestration

Report after each agent/skill completes:

✅ [Role Name] Completed: [One-sentence result]

Provide options to the user when encountering problems instead of making decisions silently

Agent → Skill Delegation (3 Modes for Subagents Calling Skills):

General-purpose subagents have access to all tools, including the Skill tool.

Mode	Process	Applicable Scenarios
Direct Call by Coordinator	Coordinator → `Skill(skill="name")` → Result	Single-step Skill tasks that do not require parallel execution
Delegated Call	Coordinator → `Task(prompt="Please use /skill-name to complete X")` → Subagent → `Skill` → Report	Multiple Skills executed in parallel, or time-consuming Skills
Team Member Call	`TeamCreate` → Assign tasks → Member → `Skill` → Report via `SendMessage`	Complex tasks requiring coordination between members

Key Point for Delegated Call: Clearly specify the Skill name and parameters in the Task prompt, and the subagent will automatically recognize and invoke it.

Phase 4: Quality Gate & Product Polishing

Acceptance Check: Check item by item against the acceptance criteria defined in Phase 1.

Product Polishing (Not only functionally complete, but also excellent in user experience):

Boundary Handling: Whether abnormal inputs, null values, and extreme cases are covered
Professionalism: Whether naming conventions, code style, and error prompts are user-friendly
Completeness: Whether documents, configuration instructions, and usage examples are complete

If all checks pass → Proceed to Phase 5. If not → Send back for revision, maximum 2 rounds; if still not passing, notify the user for manual intervention.

Phase 5: Result Delivery & Deployment Handover

Output execution report:

Item	Content
Total Tasks	X tasks, Y succeeded, Z failed
Results of Each Agent	[Role]: [Status] - [Key Output]
Summary Conclusion	[Final conclusion integrating all results]
Follow-up Recommendations	[Improvement directions not covered currently but worth implementing]

Deployment Handover (Provided On Demand):

Operation Method: Startup commands, environment requirements, configuration instructions
Verification Steps: List of operations that users can perform for self-verification
Known Limitations: Boundaries and constraints of the current version

Execution Bottom Line

[Hard Standards]: 0. Mandatory Use of planning-with-files: For any complex task, must first call

Skill(skill="planning-with-files")

to create task_plan.md, findings.md, progress.md

Mandatory Execution of Complete Skill Fallback Chain: Local scan →
```
Skill(skill="find-skills", args="...")
```
search → General subagent; no steps can be skipped

[Other Principles]: 2. First clarify the goal, then define the organizational structure — clarify the task first when it is unclear, then decide whether to form a team 3. Team size is determined by task complexity; the number of parallel agents is recommended to be no more than 5 4. Key milestones must have quality gates and rollback points 5. Do not assume any external tools are available; verify before execution (including find-skills) 6. Browser windows are independent by default and do not share context 7. Cost is only a constraint, not a fixed commitment — do not make unrealistic cost estimates 8. Dangerous operations and large-scale changes must be confirmed by the user first

Fault Handling

Fault Type	Handling Strategy
Agent Execution Failure	Notify the user, and provide options for retry/skip/termination
Skill Unavailable	Degrade according to the fallback chain: Local Skill → find-skills → General subagent
Model Timeout	Adjust task complexity or split into smaller subtasks
Quality Not Up to Standard	Send back for revision up to 2 rounds; if still not passing, notify the user for manual intervention
Context Overflow	Split into smaller subtasks and execute in batches

agent-teams-playbook

NPX Install

Tags

SKILL.md Content (Chinese)