Claude-Code-Workflow/.claude/skills/team-executor/SKILL.md

name, description, allowed-tools

name	description	allowed-tools
team-executor	Lightweight session execution skill. Resumes existing team-coordinate sessions for pure execution. No analysis, no role generation -- only loads and executes. Session path required. Triggers on "team executor".	TeamCreate(*), TeamDelete(*), SendMessage(*), TaskCreate(*), TaskUpdate(*), TaskList(*), TaskGet(*), Task(*), AskUserQuestion(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*)

Team Executor

Lightweight session execution skill: load session -> reconcile state -> spawn workers -> execute -> deliver. No analysis, no role generation -- only executes existing team-coordinate sessions.

Architecture

+---------------------------------------------------+
|  Skill(skill="team-executor")                      |
|  args="--session=<path>" [REQUIRED]                |
|  args="--role=<name>" (for worker dispatch)        |
+-------------------+-------------------------------+
                    | Session Validation
         +---- --session valid? ----+
         | NO                       | YES
         v                          v
    Error immediately         Role Router
    (no session)                  |
                          +-------+-------+
                          | --role present?
                          |       |
                     YES  |       | NO
                     v    |       v
              Route to    |   Orchestration Mode
              session     |   -> executor
              role.md     |

---

Session Validation (BEFORE routing)

CRITICAL: Session validation MUST occur before any role routing.

Parse Arguments

Extract from $ARGUMENTS:

• --session=<path>: Path to team-coordinate session folder (REQUIRED)
• --role=<name>: Role to dispatch (optional, defaults to orchestration mode)

Validation Steps

1. Check --session provided:

   • If missing -> ERROR: "Session required. Usage: --session="
   • Do NOT proceed

2. Validate session structure (see specs/session-schema.md):

   • Directory exists at path
   • team-session.json exists and valid JSON
   • task-analysis.json exists and valid JSON
   • roles/ directory has at least one .md file
   • Each role in team-session.json#roles has corresponding .md file in roles/

3. Validation failure:

   • Report specific missing component
   • Suggest re-running team-coordinate or checking path
   • Do NOT proceed

Validation Checklist

Session Validation Checklist:
[ ] --session argument provided
[ ] Directory exists at path
[ ] team-session.json exists and parses
[ ] task-analysis.json exists and parses
[ ] roles/ directory has >= 1 .md files
[ ] All session.roles[] have corresponding roles/<role>.md

---

Role Router

Dispatch Logic

Scenario	Action
No --session	ERROR immediately
--session invalid	ERROR with specific reason
No --role	Orchestration Mode -> executor
--role=executor	Read built-in roles/executor/role.md
--role=<other>	Read <session>/roles/<role>.md

Orchestration Mode

When invoked without --role, executor auto-starts.

Invocation: Skill(skill="team-executor", args="--session=<session-folder>")

Lifecycle:

Validate session
  -> executor Phase 0: Reconcile state (reset interrupted, detect orphans)
  -> executor Phase 1: Spawn first batch workers (background) -> STOP
  -> Worker executes -> SendMessage callback -> executor advances next step
  -> Loop until pipeline complete -> Phase 2 report

User Commands (wake paused executor):

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

---

Role Registry

Role	File	Type
executor	roles/executor/role.md	built-in orchestrator
(dynamic)	<session>/roles/<role-name>.md	loaded from session

COMPACT PROTECTION: Role files are execution documents. After context compression, role instructions become summaries only -- MUST immediately Read the role.md to reload before continuing. Never execute any Phase based on summaries.

---

Shared Infrastructure

The following templates apply to all worker roles. Each loaded role.md follows the same structure.

Worker Phase 1: Task Discovery (all workers shared)

Each worker on startup executes the same task discovery flow:

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 if this task's output artifacts already exist
• Artifacts complete -> skip to Phase 5 report completion
• Artifacts incomplete or missing -> normal Phase 2-4 execution

Worker Phase 5: Report + Fast-Advance (all workers shared)

Task completion with optional fast-advance to skip executor round-trip:

1. Message Bus: Call mcp__ccw-tools__team_msg to log message
   • Params: operation="log", team=, from=, to="executor", type=, summary="[]
     ", ref=
   • team must be session ID (e.g., TC-my-project-2026-02-27), NOT team name. Extract from task description Session: field -> take folder name.
   • CLI fallback: ccw team log --team <session-id> --from <role> --to executor --type <type> --summary "[<role>] ..." --json
2. TaskUpdate: Mark task completed
3. Fast-Advance Check:
   • Call TaskList(), find pending tasks whose blockedBy are ALL completed
   • If exactly 1 ready task AND its owner matches a simple successor pattern -> spawn it directly (skip executor)
   • Otherwise -> SendMessage to executor for orchestration
4. Loop: Back to Phase 1 to check for next task

Fast-Advance Rules:

Condition	Action
Same-prefix successor (Inner Loop role)	Do not spawn, main agent inner loop (Phase 5-L)
1 ready task, simple linear successor, different prefix	Spawn directly via Task(run_in_background: true)
Multiple ready tasks (parallel window)	SendMessage to executor (needs orchestration)
No ready tasks + others running	SendMessage to executor (status update)
No ready tasks + nothing running	SendMessage to executor (pipeline may be complete)

Fast-advance failure recovery: If a fast-advanced task fails, the executor detects it as an orphaned in_progress task on next resume/check and resets it to pending for re-spawn. Self-healing. See monitor.md.

Worker Inner Loop (roles with multiple same-prefix serial tasks)

When a role has 2+ serial same-prefix tasks, it loops internally instead of spawning new agents:

Inner Loop flow:

Phase 1: Discover task (first time)
  |
  +- Found task -> Phase 2-3: Load context + Execute work
  |                |
  |                v
  |          Phase 4: Validation (+ optional Inline Discuss)
  |                |
  |                v
  |          Phase 5-L: Loop Completion
  |                |
  |                +- TaskUpdate completed
  |                +- team_msg log
  |                +- Accumulate summary to context_accumulator
  |                |
  |                +- More same-prefix tasks?
  |                |   +- YES -> back to Phase 1 (inner loop)
  |                |   +- NO -> Phase 5-F: Final Report
  |                |
  |                +- Interrupt conditions?
  |                    +- consensus_blocked HIGH -> SendMessage -> STOP
  |                    +- Errors >= 3 -> SendMessage -> STOP
  |
  +- Phase 5-F: Final Report
       +- SendMessage (all task summaries)
       +- STOP

Phase 5-L vs Phase 5-F:

Step	Phase 5-L (looping)	Phase 5-F (final)
TaskUpdate completed	YES	YES
team_msg log	YES	YES
Accumulate summary	YES	-
SendMessage to executor	NO	YES (all tasks summary)
Fast-Advance to next prefix	-	YES (check cross-prefix successors)

Wisdom Accumulation (all roles)

Cross-task knowledge accumulation. Loaded from session at startup.

Directory:

<session-folder>/wisdom/
+-- learnings.md      # Patterns and insights
+-- decisions.md      # Design and strategy decisions
+-- issues.md         # Known risks and issues

Worker load (Phase 2): Extract Session: <path> from task description, read wisdom files. Worker contribute (Phase 4/5): Write discoveries to corresponding wisdom files.

Role Isolation Rules

Allowed	Prohibited
Process own prefix tasks	Process other role's prefix tasks
SendMessage to executor	Directly communicate with other workers
Use tools appropriate to responsibility	Create tasks for other roles
Fast-advance simple successors	Spawn parallel worker batches
Report capability_gap to executor	Attempt work outside scope

Executor additionally prohibited: directly write/modify deliverable artifacts, call implementation subagents directly, directly execute analysis/test/review, generate new roles.

---

Cadence Control

Beat model: Event-driven, each beat = executor wake -> process -> spawn -> STOP.

Beat Cycle (single beat)
======================================================================
  Event                   Executor                 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)
======================================================================

  Fast-Advance (skips executor for simple linear successors)
======================================================================
  [Worker A] Phase 5 complete
    +- 1 ready task? simple successor? --> spawn Worker B directly
    +- complex case? --> SendMessage to executor
======================================================================

---

Executor Spawn Template

Standard Worker (single-task role)

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

## Primary Instruction
All your work MUST be executed by calling Skill to get role definition:
Skill(skill="team-executor", args="--role=<role> --session=<session-folder>")

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

## Role Guidelines
- Only process <PREFIX>-* tasks, do not execute other role work
- All output prefixed with [<role>] tag
- Only communicate with executor
- Do not use TaskCreate to create tasks for other roles
- Before each SendMessage, call mcp__ccw-tools__team_msg to log (team=<session-id> from Session field, NOT team name)
- After task completion, check for fast-advance opportunity (see SKILL.md Phase 5)

## Workflow
1. Call Skill -> get role definition and execution logic
2. Follow role.md 5-Phase flow
3. team_msg(team=<session-id>) + SendMessage results to executor
4. TaskUpdate completed -> check next task or fast-advance`
})

Inner Loop Worker (multi-task role)

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

## Primary Instruction
All your work MUST be executed by calling Skill to get role definition:
Skill(skill="team-executor", args="--role=<role> --session=<session-folder>")

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

## Inner Loop Mode
You will handle ALL <PREFIX>-* tasks in this session, not just the first one.
After completing each task, loop back to find the next <PREFIX>-* task.
Only SendMessage to executor when:
- All <PREFIX>-* tasks are done
- A consensus_blocked HIGH occurs
- Errors accumulate (>= 3)

## Role Guidelines
- Only process <PREFIX>-* tasks, do not execute other role work
- All output prefixed with [<role>] tag
- Only communicate with executor
- Do not use TaskCreate to create tasks for other roles
- Before each SendMessage, call mcp__ccw-tools__team_msg to log (team=<session-id> from Session field, NOT team name)
- Use subagent calls for heavy work, retain summaries in context`
})

---

Integration with team-coordinate

Scenario	Skill
New task, no session	team-coordinate
Existing session, resume execution	team-executor
Session needs new roles	team-coordinate (with --resume)
Pure execution, no analysis	team-executor

---

Error Handling

Scenario	Resolution
No --session provided	ERROR immediately with usage message
Session directory not found	ERROR with path, suggest checking path
team-session.json missing	ERROR, session incomplete, suggest re-run team-coordinate
task-analysis.json missing	ERROR, session incomplete, suggest re-run team-coordinate
No roles in session	ERROR, session incomplete, suggest re-run team-coordinate
Role file not found	ERROR with expected path
capability_gap reported	Warn only, cannot generate new roles (see monitor.md handleAdapt)
Fast-advance spawns wrong task	Executor reconciles on next callback