team-coordinate

Agent timeout: spawn_agent 异步执行且无内置超时 — 除明确短任务外一律 spawn_agent 后立即 wait_agent({ timeout_ms: 3600000 })（上限 1 小时）阻塞等待，绝不依赖 30000 默认值；timed_out: true 且 Agent 未完成时再次 wait_agent 续等，不丢弃。批量场景使用 spawn_agents_on_csv({ max_runtime_seconds: 3600, ... })。

Plan tracking: codex 无 TaskCreate/TaskUpdate/TodoWrite 任务板。进度清单用 update_plan({ explanation?, plan: [{ step, status }] }) 维护（整体提交步骤数组，status: pending | in_progress | completed），权威状态始终在 session 工件中；依赖/认领（addBlockedBy/owner）是工件字段，不是工具参数。

<required_reading> @~/.maestro/workflows/run-mode-lite.md </required_reading>

Team Coordinate

Universal team coordination skill: analyze task -> generate role-specs -> dispatch -> execute -> deliver. Only the coordinator is built-in. All worker roles are dynamically generated as lightweight role-spec files and spawned via the team-worker agent.

Architecture

+---------------------------------------------------+
|  spawn_agent({ task_name: "team_coordinate", message: "Execute skill team-coordinate" })                 |
|  args="task description"                           |
+-------------------+-------------------------------+
                    |
         Orchestration Mode (auto -> coordinator)
                    |
              Coordinator (built-in)
              Phase 0-5 orchestration
                    |
    +-------+-------+-------+-------+
    v       v       v       v       v
 [team-worker agents, each loaded with a dynamic role-spec]
  (roles generated at runtime from task analysis)

  CLI Tools (callable by any worker):
    maestro delegate --mode analysis  - analysis and exploration
    maestro delegate --mode write     - code generation and modification

Shared Constants

Constant	Value
Session prefix	TC
Session path	{run_dir}/work/team/
Worker agent	team-worker
Message bus	mcp__maestro__team_msg(session_id=<run-id>, ...)
CLI analysis	maestro delegate --mode analysis
CLI write	maestro delegate --mode write
Max roles	5

Role Router

This skill is coordinator-only. Workers do NOT invoke this skill -- they are spawned as team-worker agents directly.

Input Parsing

Parse $ARGUMENTS. No --role needed -- always routes to coordinator.

Role Registry

Only coordinator is statically registered. All other roles are dynamic, stored as role-specs in session.

Role	File	Type
coordinator	roles/coordinator/role.md	built-in orchestrator
(dynamic)	{run_dir}/work/team/role-specs/<role-name>.md	runtime-generated role-spec

CLI Tool Usage

Workers can use CLI tools for analysis and code operations:

Tool	Purpose
maestro delegate --mode analysis	Analysis, exploration, pattern discovery
maestro delegate --mode write	Code generation, modification, refactoring

Dispatch

Always route to coordinator. Coordinator reads roles/coordinator/role.md and executes its phases.

Orchestration Mode

User just provides task description.

Invocation: spawn_agent({ task_name: "team_coordinate", message: "Execute skill team-coordinate, args: task description" })

Lifecycle:

User provides task description
  -> coordinator Phase 1: task analysis (detect capabilities, build dependency graph)
  -> coordinator Phase 2: generate role-specs + initialize session
  -> coordinator Phase 3: create task chain from dependency graph
  -> coordinator Phase 4: spawn first batch workers (background) -> STOP
  -> Worker executes -> send_message callback -> coordinator advances next step
  -> Loop until pipeline complete -> Phase 5 report + completion action

User Commands (wake paused coordinator):

Command	Action
check / status	Output execution status graph, no advancement
resume / continue	Check worker states, advance next step
revise <TASK-ID> [feedback]	Revise specific task with optional feedback
feedback <text>	Inject feedback into active pipeline
improve [dimension]	Auto-improve weakest quality dimension

---

Coordinator Spawn Template

v2 Worker Spawn (all roles)

When coordinator spawns workers, use team-worker agent with role-spec path:

spawn_agent({
  subagent_type: "team-worker",
  description: "Spawn <role> worker",
  team_name: <team-name>,
  name: "<role>",
  run_in_background: true,
  prompt: `## Role Assignment
role: <role>
role_spec: {run_dir}/work/team/role-specs/<role>.md
session: {run_dir}/work/team
session_id: <run-id>
team_name: <team-name>
requirement: <task-description>
inner_loop: <true|false>

## Progress Milestones
session_id: <run-id>
Report progress via team_msg at natural phase boundaries (context loaded -> core work done -> verification).
Report blockers immediately via team_msg type="blocker".
Report completion via team_msg type="task_complete" after final send_message.

Read role_spec file to load Phase 2-4 domain instructions.
Execute built-in Phase 1 (task discovery) -> role-spec Phase 2-4 -> built-in Phase 5 (report).`
})

Inner Loop roles (role has 2+ serial same-prefix tasks): Set inner_loop: true. The team-worker agent handles the loop internally.

Single-task roles: Set inner_loop: false.

---

Completion Action

When pipeline completes (all tasks done), coordinator presents an interactive choice:

request_user_input({
  questions: [{
    question: "Team pipeline complete. What would you like to do?",
    header: "Completion",
    multiSelect: false,
    options: [
      { label: "Archive & Clean (Recommended)", description: "Archive session, clean up team" },
      { label: "Keep Active", description: "Keep session for follow-up work" },
      { label: "Export Results", description: "Export deliverables to target directory, then clean" }
    ]
  }]
})

Action Handlers

Choice	Steps
Archive & Clean	Update session status="completed" -> TeamDelete -> output final summary with artifact paths
Keep Active	Update session status="paused" -> output: "Resume with: spawn_agent({ task_name: "team_coordinate", message: "Execute skill team-coordinate, args: resume" })"
Export Results	request_user_input(target path) -> copy artifacts to target -> Archive & Clean

---

Specs Reference

Spec	Purpose
specs/pipelines.md	Dynamic pipeline model, task naming, dependency graph
specs/role-spec-template.md	Template for dynamic role-spec generation
specs/quality-gates.md	Quality thresholds and scoring dimensions
specs/knowledge-transfer.md	Context transfer protocols between roles

---

Session Directory

{run_dir}/
+-- outputs/                    # Formal worker deliverables
|   +-- <artifact>.md
+-- evidence/discussions/       # Inline discuss records
|   +-- <round>.md
+-- report.md                   # Human-readable synthesis + handoff
+-- work/team/                  # Team coordination (non-artifact)
    +-- team-session.json       # Session state + dynamic role registry
    +-- task-analysis.json      # Phase 1 output: capabilities, dependency graph
    +-- role-specs/             # Dynamic role-spec definitions (generated Phase 2)
    |   +-- <role-1>.md         # Lightweight: frontmatter + Phase 2-4 only
    |   +-- <role-2>.md
    +-- .msg/                   # Team message bus + state
    |   +-- messages.jsonl      # Message log
    |   +-- meta.json           # Session metadata + cross-role state
    +-- wisdom/                 # Cross-task knowledge
    |   +-- learnings.md
    |   +-- decisions.md
    |   +-- issues.md
    +-- explorations/           # Shared explore cache
        +-- cache-index.json
        +-- explore-<angle>.json

team-session.json Schema

{
  "session_id": "TC-<slug>-<date>",
  "task_description": "<original user input>",
  "status": "active | paused | completed",
  "team_name": "<team-name>",
  "roles": [
    {
      "name": "<role-name>",
      "prefix": "<PREFIX>",
      "responsibility_type": "<type>",
      "inner_loop": false,
      "role_spec": "role-specs/<role-name>.md"
    }
  ],
  "pipeline": {
    "dependency_graph": {},
    "tasks_total": 0,
    "tasks_completed": 0
  },
  "active_workers": [],
  "completed_tasks": [],
  "completion_action": "interactive",
  "created_at": "<timestamp>"
}

---

Session Resume

Coordinator supports resume / continue for interrupted sessions:

1. Scan {run_dir}/work/team/team-session.json for active/paused sessions
2. Multiple matches -> request_user_input for selection
3. Audit list_agents -> reconcile session state <-> task status
4. Reset in_progress -> pending (interrupted tasks)
5. Rebuild team and spawn needed workers only
6. Create missing tasks, set dependencies via update_plan({ addBlockedBy })
7. Kick first executable task -> Phase 4 coordination loop

---

Error Handling

Scenario	Resolution
Unknown command	Error with available command list
Dynamic role-spec not found	Error, coordinator may need to regenerate
Command file not found	Fallback to inline execution
CLI tool fails	Worker proceeds with direct implementation, logs warning
Explore cache corrupt	Clear cache, re-explore
Fast-advance spawns wrong task	Coordinator reconciles on next callback
capability_gap reported	Coordinator generates new role-spec via handleAdapt
Completion action fails	Default to Keep Active, log warning