--- name: team-issue description: Unified team skill for issue resolution. All roles invoke this skill with --role arg for role-specific execution. Triggers on "team issue". allowed-tools: TeamCreate(*), TeamDelete(*), SendMessage(*), TaskCreate(*), TaskUpdate(*), TaskList(*), TaskGet(*), Agent(*), AskUserQuestion(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*) --- # 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="" | +-------------------+-------------------------------+ | Orchestration Mode (auto -> coordinator) | Coordinator (inline) Phase 0-5 orchestration | +-----+-----+-----+-----+-----+ v v v v v [tw] [tw] [tw] [tw] [tw] explor plann review integ- imple- er er er rator menter (tw) = team-worker agent ``` ## 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 | Role | Spec | Task Prefix | Inner Loop | |------|------|-------------|------------| | coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | (none) | - | | explorer | [role-specs/explorer.md](role-specs/explorer.md) | EXPLORE-* | false | | planner | [role-specs/planner.md](role-specs/planner.md) | SOLVE-* | false | | reviewer | [role-specs/reviewer.md](role-specs/reviewer.md) | AUDIT-* | false | | integrator | [role-specs/integrator.md](role-specs/integrator.md) | MARSHAL-* | false | | implementer | [role-specs/implementer.md](role-specs/implementer.md) | BUILD-* | false | > **⚠️ 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=" [--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): | Command | Action | |---------|--------| | `check` / `status` | Output execution status graph, no advancement | | `resume` / `continue` | Check worker states, advance next step | --- ## 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", session_id=, from=, type=, data={ref: ""} - `to` and `summary` auto-defaulted -- do NOT specify explicitly - **CLI fallback**: `ccw team log --session-id --from --type --json` 2. **SendMessage**: Send result to coordinator 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**: ``` /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: ` from task description, read wisdom directory files. **Worker Contribute** (Phase 4/5): Write this task's discoveries to corresponding wisdom files. ### Role Isolation Rules | Allowed | Forbidden | |---------|-----------| | Process tasks with own prefix | Process tasks with other role prefixes | | SendMessage to coordinator | Communicate directly with other workers | | Use tools declared in Toolbox | Create tasks for other roles | | Delegate to reused agents | Modify resources outside own responsibility | 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", session_id=, from=, type=, data={ref: ""} `to` and `summary` auto-defaulted -- do NOT specify explicitly. **CLI fallback**: `ccw team log --session-id --from --type --json` **Message types by role**: | Role | Types | |------|-------| | coordinator | `task_assigned`, `pipeline_update`, `escalation`, `shutdown`, `error` | | explorer | `context_ready`, `impact_assessed`, `error` | | planner | `solution_ready`, `multi_solution`, `error` | | reviewer | `approved`, `rejected`, `concerns`, `error` | | integrator | `queue_ready`, `conflict_found`, `error` | | implementer | `impl_complete`, `impl_failed`, `error` | ### Team Configuration | Setting | Value | |---------|-------| | Team name | issue | | Session directory | `.workflow/.team-plan/issue/` | | Issue data directory | `.workflow/issues/` | --- ## 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: | Condition | Mode | Description | |-----------|------|-------------| | User explicitly specifies `--mode=` | Use specified mode | User override takes priority | | Issue count <= 2 AND no high-priority issues (priority < 4) | `quick` | Simple issues, skip review step | | Issue count <= 2 AND has high-priority issues (priority >= 4) | `full` | Complex issues need review gate | | Issue count > 2 | `batch` | Multiple issues, parallel exploration and implementation | ### Review Gate (Full/Batch modes) | AUDIT Verdict | Action | |---------------|--------| | approved | Proceed to MARSHAL → BUILD | | rejected (round < 2) | Create SOLVE-fix task → AUDIT re-review | | rejected (round >= 2) | Force proceed with warnings, report to user | ### 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**: | Trigger | Location | Behavior | |---------|----------|----------| | Review gate | After AUDIT-* | If approved → MARSHAL; if rejected → SOLVE-fix (max 2 rounds) | | Review loop limit | AUDIT round >= 2 | Force proceed with warnings | | Pipeline stall | No ready + no running | Check missing tasks, report to user | **Stall Detection** (coordinator `handleCheck` executes): | Check | Condition | Resolution | |-------|-----------|------------| | Worker no response | in_progress task no callback | Report waiting task list, suggest user `resume` | | Pipeline deadlock | no ready + no running + has pending | Check blockedBy dependency chain, report blocking point | | Review loop exceeded | AUDIT rejection > 2 rounds | Terminate loop, force proceed with current solution | ### Task Metadata Registry | Task ID | Role | Phase | Dependencies | Description | |---------|------|-------|-------------|-------------| | EXPLORE-001 | explorer | explore | (none) | Context analysis and impact assessment | | EXPLORE-002..N | explorer | explore | (none) | Parallel exploration (Batch mode only) | | SOLVE-001 | planner | plan | EXPLORE-001 (or all EXPLORE-*) | Solution design and task decomposition | | SOLVE-002..N | planner | plan | EXPLORE-* | Parallel solution design (Batch mode only) | | AUDIT-001 | reviewer | review | SOLVE-001 (or all SOLVE-*) | Technical feasibility and risk review | | MARSHAL-001 | integrator | integrate | AUDIT-001 (or last SOLVE-*) | Conflict detection and queue orchestration | | BUILD-001 | implementer | implement | MARSHAL-001 | Code implementation and result submission | | BUILD-002..M | implementer | implement | MARSHAL-001 | Parallel implementation (Batch DAG parallel) | --- ## Coordinator Spawn Template ### v5 Worker Spawn (all roles) When coordinator spawns workers, use `team-worker` agent with role-spec path: ``` Agent({ subagent_type: "team-worker", description: "Spawn worker", team_name: "issue", name: "", run_in_background: true, prompt: `## Role Assignment role: role_spec: .claude/skills/team-issue/role-specs/.md session: session_id: team_name: issue requirement: inner_loop: false 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).` }) ``` **All roles** (explorer, planner, reviewer, integrator, implementer): Set `inner_loop: false`. ### Parallel Spawn (Batch Mode) > When Batch mode has parallel tasks assigned to the same role, spawn N distinct team-worker agents with unique names. **Explorer parallel spawn** (Batch mode, N issues): | Condition | Action | |-----------|--------| | Batch mode with N issues (N > 1) | Spawn min(N, 5) team-worker agents: `explorer-1`, `explorer-2`, ... with `run_in_background: true` | | Quick/Full mode (single explorer) | Standard spawn: single `explorer` team-worker agent | **Implementer parallel spawn** (Batch mode, M BUILD tasks): | Condition | Action | |-----------|--------| | Batch mode with M BUILD tasks (M > 2) | Spawn min(M, 3) team-worker agents: `implementer-1`, `implementer-2`, ... with `run_in_background: true` | | Quick/Full mode (single implementer) | Standard spawn: single `implementer` team-worker agent | **Parallel spawn template**: ``` Agent({ subagent_type: "team-worker", description: "Spawn - worker", team_name: "issue", name: "-", run_in_background: true, prompt: `## Role Assignment role: role_spec: .claude/skills/team-issue/role-specs/.md session: session_id: team_name: issue requirement: agent_name: - inner_loop: false Read role_spec file to load Phase 2-4 domain instructions. Execute built-in Phase 1 (task discovery, owner=-) -> role-spec Phase 2-4 -> built-in Phase 5 (report).` }) ``` **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.). --- ## Completion Action When the pipeline completes (all tasks done, coordinator Phase 5): ``` AskUserQuestion({ questions: [{ question: "Issue resolution pipeline complete. What would you like to do?", header: "Completion", multiSelect: false, options: [ { label: "Archive & Clean (Recommended)", description: "Archive session, clean up tasks and team resources" }, { label: "Keep Active", description: "Keep session active for follow-up work or inspection" }, { label: "Export Results", description: "Export deliverables to a specified location, then clean" } ] }] }) ``` | Choice | Action | |--------|--------| | Archive & Clean | Update session status="completed" -> TeamDelete() -> output final summary | | Keep Active | Update session status="paused" -> output resume instructions: `Skill(skill="team-issue", args="resume")` | | Export Results | AskUserQuestion for target path -> copy deliverables -> Archive & Clean | --- ## Session Directory ``` .workflow/.team-plan/issue/ ├── .msg/ │ ├── messages.jsonl # Message bus log │ └── meta.json # Session state + 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 | Scenario | Resolution | |----------|------------| | Unknown --role value | Error with available role list | | Missing --role arg | Orchestration Mode → auto route to coordinator | | Role file not found | Error with expected path (roles/.md) | | Task prefix conflict | Log warning, proceed | | Review rejection exceeds 2 rounds | Force proceed with warnings | | No issues found for given IDs | Coordinator reports error to user |