Agent skill

team-issue

Unified team skill for issue resolution. Uses team-worker agent architecture with role directories for domain logic. Coordinator orchestrates pipeline, workers are team-worker agents. Triggers on "team issue".

View SKILL.md on GitHub Repository
Stars 1,785
Forks 148

Install this agent skill to your Project

npx add-skill https://github.com/catlog22/Claude-Code-Workflow/tree/main/.codex/skills/team-issue

SKILL.md

Team Issue Resolution

Orchestrate issue resolution pipeline: explore context -> plan solution -> review (optional) -> marshal queue -> implement. Supports Quick, Full, and Batch pipelines with review-fix cycle.

Architecture

Skill(skill="team-issue", args="<issue-ids> [--mode=<mode>]")
                    |
         SKILL.md (this file) = Router
                    |
     +--------------+--------------+
     |                             |
  no --role flag              --role <name>
     |                             |
  Coordinator                  Worker
  roles/coordinator/role.md    roles/<name>/role.md
     |
     +-- clarify -> dispatch -> spawn workers -> STOP
                                    |
             +-------+-------+-------+-------+
             v       v       v       v       v
          [explor] [plann] [review] [integ] [imple]

Role Registry

Role Path Prefix Inner Loop
coordinator roles/coordinator/role.md — —
explorer roles/explorer/role.md EXPLORE-* false
planner roles/planner/role.md SOLVE-* false
reviewer roles/reviewer/role.md AUDIT-* false
integrator roles/integrator/role.md MARSHAL-* false
implementer roles/implementer/role.md BUILD-* false

Role Router

Parse $ARGUMENTS:

  • Has --role <name> -> Read roles/<name>/role.md, execute Phase 2-4
  • No --role -> roles/coordinator/role.md, execute entry router

Delegation Lock

Coordinator is a PURE ORCHESTRATOR. It coordinates, it does NOT do.

Before calling ANY tool, apply this check:

Tool Call Verdict Reason
spawn_agent, wait_agent, close_agent, send_message, assign_task ALLOWED Orchestration
list_agents ALLOWED Agent health check
request_user_input ALLOWED User interaction
mcp__ccw-tools__team_msg ALLOWED Message bus
Read/Write on .workflow/.team/ files ALLOWED Session state
Read on roles/, commands/, specs/ ALLOWED Loading own instructions
Read/Grep/Glob on project source code BLOCKED Delegate to worker
Edit on any file outside .workflow/ BLOCKED Delegate to worker
Bash("ccw cli ...") BLOCKED Only workers call CLI
Bash running build/test/lint commands BLOCKED Delegate to worker

If a tool call is BLOCKED: STOP. Create a task, spawn a worker.

No exceptions for "simple" tasks. Even a single-file read-and-report MUST go through spawn_agent.

Shared Constants

  • Session prefix: TISL
  • Session path: .workflow/.team/TISL-<slug>-<date>/
  • Team name: issue
  • CLI tools: ccw cli --mode analysis (read-only), ccw cli --mode write (modifications)
  • Message bus: mcp__ccw-tools__team_msg(session_id=<session-id>, ...)

Worker Spawn Template

Coordinator spawns workers using this template:

spawn_agent({
  agent_type: "team_worker",
  task_name: "<task-id>",
  fork_context: false,
  items: [
    { type: "text", text: `## Role Assignment
role: <role>
role_spec: <skill_root>/roles/<role>/role.md
session: <session-folder>
session_id: <session-id>
requirement: <task-description>
inner_loop: false

Read role_spec file (<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions.` },

    { type: "text", text: `## Task Context
task_id: <task-id>
title: <task-title>
description: <task-description>
pipeline_phase: <pipeline-phase>` },

    { type: "text", text: `## Upstream Context
<prev_context>` }
  ]
})

After spawning, use wait_agent({ targets: [...], timeout_ms: 900000 }) to collect results, then close_agent({ target }) each worker.

Parallel spawn (Batch mode, N explorer or M implementer instances):

spawn_agent({
  agent_type: "team_worker",
  task_name: "<task-id>",
  fork_context: false,
  items: [
    { type: "text", text: `## Role Assignment
role: <role>
role_spec: <skill_root>/roles/<role>/role.md
session: <session-folder>
session_id: <session-id>
requirement: <task-description>
agent_name: <role>-<N>
inner_loop: false

Read role_spec file (<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions.` },

    { type: "text", text: `## Task Context
task_id: <task-id>
title: <task-title>
description: <task-description>
pipeline_phase: <pipeline-phase>` },

    { type: "text", text: `## Upstream Context
<prev_context>` }
  ]
})

After spawning, use wait_agent({ targets: [...], timeout_ms: 900000 }) to collect results, then close_agent({ target }) each worker.

Model Selection Guide

Role model reasoning_effort Rationale
Explorer (EXPLORE-*) (default) medium Context gathering, file reading, less reasoning
Planner (SOLVE-*) (default) high Solution design requires deep analysis
Reviewer (AUDIT-*) (default) high Code review and plan validation need full reasoning
Integrator (MARSHAL-*) (default) medium Queue ordering and dependency resolution
Implementer (BUILD-*) (default) high Code generation needs precision

Override model/reasoning_effort in spawn_agent when cost optimization is needed:

spawn_agent({
  agent_type: "team_worker",
  task_name: "<task-id>",
  fork_context: false,
  model: "<model-override>",
  reasoning_effort: "<effort-level>",
  items: [...]
})

User Commands

Command Action
check / status View execution status graph, no advancement
resume / continue Check worker states, advance next step

Session Directory

.workflow/.team/TISL-<slug>-<date>/
├── session.json                    # Session metadata + pipeline + fix_cycles
├── task-analysis.json              # Coordinator analyze output
├── .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
│   └── context-<issueId>.json
├── solutions/                      # Planner output
│   └── solution-<issueId>.json
├── audits/                         # Reviewer output
│   └── audit-report.json
├── queue/                          # Integrator output (also .workflow/issues/queue/)
└── builds/                         # Implementer output

Specs Reference

  • specs/pipelines.md — Pipeline definitions and task registry

v4 Agent Coordination

Message Semantics

Intent API Example
Send exploration context to running planner send_message Queue EXPLORE-* findings to SOLVE-* worker
Not used in this skill assign_task No resident agents -- all workers are one-shot
Check running agents list_agents Verify parallel explorer/implementer health

Pipeline Pattern

Pipeline with context passing: explore -> plan -> review (optional) -> marshal -> implement. In Batch mode, N explorers and M implementers run in parallel:

// Batch mode: spawn N explorers in parallel (max 5)
const explorerNames = ["EXPLORE-001", "EXPLORE-002", ..., "EXPLORE-00N"]
for (const name of explorerNames) {
  spawn_agent({ agent_type: "team_worker", task_name: name, ... })
}
wait_agent({ targets: explorerNames, timeout_ms: 900000 })

// After MARSHAL completes: spawn M implementers in parallel (max 3)
const buildNames = ["BUILD-001", "BUILD-002", ..., "BUILD-00M"]
for (const name of buildNames) {
  spawn_agent({ agent_type: "team_worker", task_name: name, ... })
}
wait_agent({ targets: buildNames, timeout_ms: 900000 })

Review-Fix Cycle

Reviewer (AUDIT-*) may reject plans, triggering fix cycles (max 2). Dynamic SOLVE-fix and AUDIT re-review tasks are created in tasks.json.

Agent Health Check

Use list_agents({}) in handleResume and handleComplete:

// Reconcile session state with actual running agents
const running = list_agents({})
// Compare with tasks.json active_agents
// Reset orphaned tasks (in_progress but agent gone) to pending

Named Agent Targeting

Workers are spawned with task_name: "<task-id>" enabling direct addressing:

  • send_message({ target: "SOLVE-001", items: [...] }) -- queue exploration context to running planner
  • close_agent({ target: "BUILD-001" }) -- cleanup by name after completion

Error Handling

Scenario Resolution
Unknown command Error with available command list
Role not found Error with role registry
CLI tool fails Worker fallback to direct implementation
Fast-advance conflict Coordinator reconciles on next callback
Completion action fails Default to Keep Active
Review rejection exceeds 2 rounds Force convergence to integrator
No issues found for given IDs Coordinator reports error to user
Deferred BUILD count unknown Defer to MARSHAL callback

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

catlog22/Claude-Code-Workflow

investigate

Chain-loaded investigation. 5-phase Iron Law methodology with root cause gate.

1,785 148
Explore
catlog22/Claude-Code-Workflow

workflow-plan

Chain-loaded workflow planning. 6-phase with mode routing and conflict detection.

1,785 148
Explore
catlog22/Claude-Code-Workflow

review-cycle

Chain-loaded review cycle. 3-mode routing for session, module, or fix review.

1,785 148
Explore
catlog22/Claude-Code-Workflow

workflow-tdd-plan

Chain-loaded TDD planning. 7-phase with Red-Green-Refactor task generation.

1,785 148
Explore
catlog22/Claude-Code-Workflow

spec-generator

Chain-loaded spec generation. 8-phase with quality gate loop and auto-fix.

1,785 148
Explore
catlog22/Claude-Code-Workflow

brainstorm

Chain-loaded brainstorming. 4-phase dual-mode with auto multi-role and single-role paths.

1,785 148
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results