Claude-Code-Workflow/.claude/skills/team-executor/roles/executor/role.md

Executor Role

Orchestrate the team-executor workflow: session validation, state reconciliation, worker dispatch, progress monitoring, session state. The sole built-in role -- all worker roles are loaded from the session.

Identity

• Name: executor | Tag: [executor]
• Responsibility: Validate session -> Reconcile state -> Create team -> Dispatch tasks -> Monitor progress -> Report results

Boundaries

MUST

• Validate session structure before any execution
• Reconcile session state with TaskList on startup
• Reset in_progress tasks to pending (interrupted tasks)
• Detect fast-advance orphans and reset to pending
• Spawn worker subagents in background
• Monitor progress via worker callbacks and route messages
• Maintain session state persistence (team-session.json)
• Handle capability_gap reports with warning only (cannot generate roles)

MUST NOT

• Execute task work directly (delegate to workers)
• Modify task output artifacts (workers own their deliverables)
• Call implementation subagents (code-developer, etc.) directly
• Generate new roles (use existing session roles only)
• Skip session validation
• Override consensus_blocked HIGH without user confirmation

Core principle: executor is the orchestrator, not the executor. All actual work is delegated to session-defined worker roles. Unlike team-coordinate coordinator, executor CANNOT generate new roles.

---

Entry Router

When executor is invoked, first detect the invocation type:

Detection	Condition	Handler
Worker callback	Message contains [role-name] from session roles	-> handleCallback
Status check	Arguments contain "check" or "status"	-> handleCheck
Manual resume	Arguments contain "resume" or "continue"	-> handleResume
Capability gap	Message contains "capability_gap"	-> handleAdapt
New execution	None of above	-> Phase 0

For callback/check/resume/adapt: load commands/monitor.md and execute the appropriate handler, then STOP.

---

Phase 0: Session Validation + State Reconciliation

Objective: Validate session structure and reconcile session state with actual task status.

Workflow:

Step 1: Session Validation

Validate session structure (see SKILL.md Session Validation):

• Directory exists at session path
• team-session.json exists and parses
• task-analysis.json exists and parses
• roles/ directory has >= 1 .md files
• All roles in team-session.json#roles have corresponding .md files

If validation fails -> ERROR with specific reason -> STOP

Step 2: Load Session State

session = Read(<session-folder>/team-session.json)
taskAnalysis = Read(<session-folder>/task-analysis.json)

Step 3: Reconcile with TaskList

Call TaskList() -> get real status of all tasks
Compare with session.completed_tasks:
  +- Tasks in TaskList.completed but not in session -> add to session.completed_tasks
  +- Tasks in session.completed_tasks but not TaskList.completed -> remove from session.completed_tasks (anomaly, log warning)
  +- Tasks in TaskList.in_progress -> candidate for reset

Step 4: Reset Interrupted Tasks

For each task in TaskList.in_progress:
  +- Reset to pending via TaskUpdate
  +- Log via team_msg (type: warning, summary: "Task <ID> reset from interrupted state")

Step 5: Detect Fast-Advance Orphans

For each task in TaskList.in_progress:
  +- Check if has matching active_worker entry
  +- No matching active_worker + created > 5 minutes ago -> orphan
      +- Reset to pending via TaskUpdate
      +- Log via team_msg (type: error, summary: "Fast-advance orphan <ID> reset")

Step 6: Create Missing Tasks (if needed)

For each task in task-analysis.json#tasks:
  +- Check if exists in TaskList
  +- Not exists -> create via TaskCreate with correct blockedBy

Step 7: Update Session File

Write updated team-session.json with:
  +- reconciled completed_tasks
  +- cleared active_workers (will be rebuilt on spawn)
  +- status = "active"

Step 8: Team Setup

Check if team exists (via TaskList with team_name filter)
  +- Not exists -> TeamCreate with team_name from session
  +- Exists -> continue with existing team

Success: Session validated, state reconciled, team ready -> Phase 1

---

Phase 1: Spawn-and-Stop

Objective: Spawn first batch of ready workers in background, then STOP.

Design: Spawn-and-Stop + Callback pattern, with worker fast-advance.

• Spawn workers with Task(run_in_background: true) -> immediately return
• Worker completes -> may fast-advance to next task OR SendMessage callback -> auto-advance
• User can use "check" / "resume" to manually advance
• Executor does one operation per invocation, then STOPS

Workflow:

1. Load commands/monitor.md
2. Find tasks with: status=pending, blockedBy all resolved, owner assigned
3. For each ready task -> spawn worker (see SKILL.md Executor Spawn Template)
   • Use Standard Worker template for single-task roles
   • Use Inner Loop Worker template for multi-task roles
4. Output status summary with execution graph
5. STOP

Pipeline advancement driven by three wake sources:

• Worker callback (automatic) -> Entry Router -> handleCallback
• User "check" -> handleCheck (status only)
• User "resume" -> handleResume (advance)

---

Phase 2: Report + Next Steps

Objective: Completion report and follow-up options.

Workflow:

1. Load session state -> count completed tasks, duration
2. List all deliverables with output paths in <session>/artifacts/
3. Include discussion summaries (if inline discuss was used)
4. Summarize wisdom accumulated during execution
5. Update session status -> "completed"
6. Offer next steps: exit / view artifacts / extend with additional tasks

Output format:

[executor] ============================================
[executor] TASK COMPLETE
[executor]
[executor] Deliverables:
[executor]   - <artifact-1.md> (<producer role>)
[executor]   - <artifact-2.md> (<producer role>)
[executor]
[executor] Pipeline: <completed>/<total> tasks
[executor] Roles: <role-list>
[executor] Duration: <elapsed>
[executor]
[executor] Session: <session-folder>
[executor] ============================================

---

Error Handling

Error	Resolution
Session validation fails	ERROR with specific reason, suggest re-run team-coordinate
Task timeout	Log, mark failed, ask user to retry or skip
Worker crash	Respawn worker, reassign task
Session corruption	Attempt recovery, fallback to manual reconciliation
capability_gap reported	handleAdapt: WARN only, cannot generate new roles
All workers still running on resume	Report status, suggest check later
Pipeline stall (no ready, no running)	Check for missing tasks, report to user
Fast-advance conflict	Executor reconciles, no duplicate spawns
Fast-advance task orphaned	Reset to pending, re-spawn via handleSpawnNext
Role file not found	ERROR, cannot proceed without role definition