Team Issue Resolution

Unified team skill: issue processing pipeline (explore → plan → implement → review → integrate). All team members invoke with --role=xxx to route to role-specific execution.

Scope: Issue processing flow (plan → queue → execute). Issue creation/discovery handled by issue-discover, CRUD management by issue-manage.

Architecture

┌───────────────────────────────────────────────┐
│  Skill(skill="team-issue")                     │
│  args="<issue-ids>" or args="--role=xxx"       │
└───────────────────┬───────────────────────────┘
                    │ Role Router
         ┌──── --role present? ────┐
         │ NO                      │ YES
         ↓                         ↓
  Orchestration Mode         Role Dispatch
  (auto → coordinator)      (route to role.md)
         │
    ┌────┴────┬───────────┬───────────┬───────────┬───────────┐
    ↓         ↓           ↓           ↓           ↓           ↓
┌──────────┐┌─────────┐┌─────────┐┌─────────┐┌──────────┐┌──────────┐
│coordinator││explorer ││planner  ││reviewer ││integrator││implementer│
│          ││EXPLORE-*││SOLVE-*  ││AUDIT-*  ││MARSHAL-* ││BUILD-*   │
└──────────┘└─────────┘└─────────┘└─────────┘└──────────┘└──────────┘

Command Architecture

roles/
├── coordinator.md      # Pipeline orchestration (Phase 1/5 inline, Phase 2-4 core logic)
├── explorer.md         # Context analysis (ACE + cli-explore-agent)
├── planner.md          # Solution design (wraps issue-plan-agent)
├── reviewer.md         # Solution review (technical feasibility + risk assessment)
├── integrator.md       # Queue orchestration (wraps issue-queue-agent)
└── implementer.md      # Code implementation (wraps code-developer)

Role Router

Input Parsing

Parse $ARGUMENTS to extract --role. If absent → Orchestration Mode (auto route to coordinator). Extract issue IDs and --mode from remaining arguments.

Role Registry

⚠️ COMPACT PROTECTION: 角色文件是执行文档，不是参考资料。当 context compression 发生后，角色指令仅剩摘要时，必须立即 Read 对应 role.md 重新加载后再继续执行。不得基于摘要执行任何 Phase。

Dispatch

1. Extract --role from arguments
2. If no --role → route to coordinator (Orchestration Mode)
3. Look up role in registry → Read the role file → Execute its phases

Orchestration Mode

When invoked without --role, coordinator auto-starts. User provides issue IDs and optional mode.

Invocation: Skill(skill="team-issue", args="<issue-ids> [--mode=<mode>]")

Lifecycle:

User provides issue IDs
  → coordinator Phase 1-3: Mode detection → TeamCreate → Create task chain
  → coordinator Phase 4: spawn first batch workers (background) → STOP
  → Worker executes → SendMessage callback → coordinator advances next step
  → Loop until pipeline complete → Phase 5 report

User Commands (wake paused coordinator):

Shared Infrastructure

The following templates apply to all worker roles. Each role.md only needs to write Phase 2-4 role-specific logic.

Worker Phase 1: Task Discovery (shared by all workers)

Every worker executes the same task discovery flow on startup:

1. Call TaskList() to get all tasks
2. Filter: subject matches this role’s prefix + owner is this role + status is pending + blockedBy is empty
3. No tasks → idle wait
4. Has tasks → TaskGet for details → TaskUpdate mark in_progress

Resume Artifact Check (prevent duplicate output after resume):

• Check whether this task’s output artifact already exists
• Artifact complete → skip to Phase 5 report completion
• Artifact incomplete or missing → normal Phase 2-4 execution

Worker Phase 5: Report (shared by all workers)

Standard reporting flow after task completion:

1. Message Bus: Call mcp__ccw-tools__team_msg to log message
   • Parameters: operation=”log”, team=, from=, to=”coordinator”, type=, summary=”[] “, ref=
   • CLI fallback: When MCP unavailable → ccw team log --team <session-id> --from <role> --to coordinator --type <type> --summary "[<role>] ..." --json
   • Note: team must be session ID (e.g., ISS-xxx-date), NOT team name. Extract from Session: field in task description.
2. SendMessage: Send result to coordinator (content and summary both prefixed with [<role>])
3. TaskUpdate: Mark task completed
4. Loop: Return to Phase 1 to check next task

Wisdom Accumulation (all roles)

Cross-task knowledge accumulation. Coordinator creates wisdom/ directory at session initialization.

Directory:

<session-folder>/wisdom/
├── learnings.md      # Patterns and insights
├── decisions.md      # Architecture and design decisions
├── conventions.md    # Codebase conventions
└── issues.md         # Known risks and issues

Worker Load (Phase 2): Extract Session: <path> from task description, read wisdom directory files. Worker Contribute (Phase 4/5): Write this task’s discoveries to corresponding wisdom files.

Role Isolation Rules

Coordinator additional restrictions: Do not write/modify code directly, do not call implementation subagents (issue-plan-agent etc.), do not execute analysis/review directly.

Output Tagging

All outputs must carry [role_name] prefix in both SendMessage content/summary and team_msg summary.

Message Bus (All Roles)

Every SendMessage before, must call mcp__ccw-tools__team_msg to log:

Parameters: operation=”log”, team=, from=, to=”coordinator”, type=, summary=”[] “, ref=

CLI fallback: When MCP unavailable → ccw team log --team <session-id> --from <role> --to coordinator --type <type> --summary "[<role>] ..." --json

Note: team must be session ID (e.g., ISS-xxx-date), NOT team name. Extract from Session: field in task description.

Message types by role:

Team Configuration

Pipeline Modes

Quick Mode (1-2 simple issues):
  EXPLORE-001 → SOLVE-001 → MARSHAL-001 → BUILD-001

Full Mode (complex issues, with review):
  EXPLORE-001 → SOLVE-001 → AUDIT-001 ─┬─(approved)→ MARSHAL-001 → BUILD-001..N(parallel)
                                         └─(rejected)→ SOLVE-fix → AUDIT-002(re-review, max 2x)

Batch Mode (5-100 issues):
  EXPLORE-001..N(batch<=5) → SOLVE-001..N(batch<=3) → AUDIT-001(batch) → MARSHAL-001 → BUILD-001..M(DAG parallel)

Mode Auto-Detection

When user does not specify --mode, auto-detect based on issue count and complexity:

Review Gate (Full/Batch modes)

Cadence Control

Beat model: Event-driven, each beat = coordinator wake → process → spawn → STOP. Issue beat: explore → plan → implement → review → integrate.

Beat Cycle (single beat)
═══════════════════════════════════════════════════════════
  Event                   Coordinator              Workers
───────────────────────────────────────────────────────────
  callback/resume ──→ ┌─ handleCallback ─┐
                      │  mark completed   │
                      │  check pipeline   │
                      ├─ handleSpawnNext ─┤
                      │  find ready tasks │
                      │  spawn workers ───┼──→ [Worker A] Phase 1-5
                      │  (parallel OK)  ──┼──→ [Worker B] Phase 1-5
                      └─ STOP (idle) ─────┘         │
                                                     │
  callback ←─────────────────────────────────────────┘
  (next beat)              SendMessage + TaskUpdate(completed)
═══════════════════════════════════════════════════════════

Pipeline beat views:

Quick Mode (4 beats, strictly serial)
──────────────────────────────────────────────────────────
Beat  1         2         3              4
      │         │         │              │
      EXPLORE → SOLVE → MARSHAL ──→ BUILD
      ▲                                  ▲
   pipeline                           pipeline
    start                              done

EXPLORE=explorer  SOLVE=planner  MARSHAL=integrator  BUILD=implementer

Full Mode (5-7 beats, with review gate)
──────────────────────────────────────────────────────────
Beat  1         2         3              4         5
      │         │         │              │         │
      EXPLORE → SOLVE → AUDIT ─┬─(ok)→ MARSHAL → BUILD
                               │
                          (rejected?)
                        SOLVE-fix → AUDIT-2 → MARSHAL → BUILD

Batch Mode (parallel windows)
──────────────────────────────────────────────────────────
Beat  1                    2                 3         4              5
 ┌────┴────┐         ┌────┴────┐             │         │         ┌────┴────┐
 EXP-1..N    →   SOLVE-1..N    →  AUDIT → MARSHAL → BUILD-1..M
 ▲                                                         ▲
 parallel                                               DAG parallel
 window (<=5)                                          window (<=3)

Checkpoints:

Stall Detection (coordinator handleCheck executes):

Task Metadata Registry

Coordinator Spawn Template

When coordinator spawns workers, use background mode (Spawn-and-Stop).

Standard spawn (single agent per role): For Quick/Full mode, spawn one agent per role. Explorer, planner, reviewer, integrator each get a single agent.

Parallel spawn (Batch mode): For Batch mode with multiple issues, spawn N explorer agents in parallel (max 5) and M implementer agents in parallel (max 3). Each parallel agent only processes tasks where owner matches its agent name.

Spawn template:

Task({
  subagent_type: "general-purpose",
  description: "Spawn <role> worker",
  team_name: "issue",
  name: "<role>",
  run_in_background: true,
  prompt: `You are team "issue" <ROLE>.

## Primary Directive
All your work must be executed through Skill to load role definition:
Skill(skill="team-issue", args="--role=<role>")

Current requirement: <task-description>
Session: <session-folder>

## Role Guidelines
- Only process <PREFIX>-* tasks, do not execute other role work
- All output prefixed with [<role>] identifier
- Only communicate with coordinator
- Do not use TaskCreate for other roles
- Call mcp__ccw-tools__team_msg before every SendMessage

## Workflow
1. Call Skill -> load role definition and execution logic
2. Follow role.md 5-Phase flow
3. team_msg + SendMessage results to coordinator
4. TaskUpdate completed -> check next task`
})

Parallel Spawn (Batch Mode)

When Batch mode has parallel tasks assigned to the same role, spawn N distinct agents with unique names. A single agent can only process tasks serially.

Explorer parallel spawn (Batch mode, N issues):

Implementer parallel spawn (Batch mode, M BUILD tasks):

Parallel spawn template:

Task({
  subagent_type: "general-purpose",
  description: "Spawn <role>-<N> worker",
  team_name: "issue",
  name: "<role>-<N>",
  run_in_background: true,
  prompt: `You are team "issue" <ROLE> (<role>-<N>).
Your agent name is "<role>-<N>", use this name for task discovery owner matching.

## Primary Directive
Skill(skill="team-issue", args="--role=<role> --agent-name=<role>-<N>")

## Role Guidelines
- Only process tasks where owner === "<role>-<N>" with <PREFIX>-* prefix
- All output prefixed with [<role>] identifier

## Workflow
1. TaskList -> find tasks where owner === "<role>-<N>" with <PREFIX>-* prefix
2. Skill -> execute role definition
3. team_msg + SendMessage results to coordinator
4. TaskUpdate completed -> check next task`
})

Dispatch must match agent names: When dispatching parallel tasks, coordinator sets each task’s owner to the corresponding instance name (explorer-1, explorer-2, etc. or implementer-1, implementer-2, etc.). In role.md, task discovery uses --agent-name for owner matching.

Session Directory

.workflow/.team-plan/issue/
├── team-session.json           # Session state
├── shared-memory.json          # Cross-role state
├── wisdom/                     # Cross-task knowledge
│   ├── learnings.md
│   ├── decisions.md
│   ├── conventions.md
│   └── issues.md
├── explorations/               # Explorer output
├── solutions/                  # Planner output
├── audits/                     # Reviewer output
├── queue/                      # Integrator output
└── builds/                     # Implementer output

Error Handling