Team Executor

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

Architecture

+---------------------------------------------------+
|  Skill(skill="team-executor")                      |
|  args="--session=<path>" [REQUIRED]                |
+-------------------+-------------------------------+
                    | Session Validation
         +---- --session valid? ----+
         | NO                       | YES
         v                          v
    Error immediately          Orchestration Mode
    (no session)               -> executor
                                    |
                    +-------+-------+-------+
                    v       v       v       v
                 [team-worker agents loaded from session role-specs]

Session Validation (BEFORE routing)

CRITICAL: Session validation MUST occur before any execution.

Parse Arguments

Extract from

$ARGUMENTS

• --session=<path>

  : Path to team-coordinate session folder (REQUIRED)

Validation Steps

1. Check

   --session

   provided:
   • If missing -> ERROR: "Session required. Usage: --session=<path-to-TC-folder>"

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

   • role-specs/

     directory has at least one

     .md

     file
   • Each role in

     team-session.json#roles

     has corresponding

     .md

     file in

     role-specs/

3. Validation failure:

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

Role Router

This skill is executor-only. Workers do NOT invoke this skill -- they are spawned as

team-worker

Dispatch Logic

--session

--session

Orchestration Mode

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 team-worker agents (background) -> STOP
  -> Worker executes -> callback -> executor advances next step
  -> Loop until pipeline complete -> Phase 2 report + completion action

User Commands (wake paused executor):

check

status

resume

continue

Role Registry

<session>/role-specs/<role-name>.md

Executor Spawn Template

v2 Worker Spawn (all roles)

When executor spawns workers, use

team-worker

spawn_agent({
  agent_type: "team_worker",
  task_name: "<task-id>",
  fork_turns: "none",
  message: `## Role Assignment
role: <role>
role_spec: <session-folder>/role-specs/<role>.md
session: <session-folder>
session_id: <session-id>
requirement: <task-description>
inner_loop: <true|false>

Read role_spec file to load Phase 2-4 domain instructions.

## Task Context
task_id: <task-id>
title: <task-title>
description: <task-description>
pipeline_phase: <pipeline-phase>

## Upstream Context
<prev_context>`
})

After spawning, use

wait_agent({ timeout_ms: 1800000 })

result.timed_out

close_agent({ target: <name> })

Model Selection Guide

team-executor loads roles dynamically from session role-specs. Use reasoning_effort based on the role type defined in the session:

• Implementation/fix roles:

  reasoning_effort: "high"

• Verification/test roles:

  reasoning_effort: "medium"

• Default when role type is unclear:

  reasoning_effort: "high"

v4 Agent Coordination

State Reconciliation

On resume, executor reconciles session state with actual running agents:

const running = list_agents({})
// Compare with session's task-analysis.json active tasks
// Reset orphaned tasks (in_progress but agent gone) to pending

Worker Communication

• send_message({ target: "<task-id>", message: "..." })

  -- queue supplementary context

• followup_task({ target: "<task-id>", message: "..." })

  -- assign new work to inner_loop worker

• close_agent({ target: "<task-id>" })

  -- cleanup completed worker

Completion Action

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

functions.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

Integration with team-coordinate

Error Handling