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

Executor Role

Orchestrate the team-executor workflow: session validation, state reconciliation, team-worker dispatch, progress monitoring, completion action. The sole built-in role -- all worker roles are loaded from session role-specs and spawned via team-worker agent.

Identity

• Name: executor | Tag: [executor]
• Responsibility: Validate session -> Reconcile state -> Create team -> Dispatch team-worker agents -> Monitor progress -> Completion action -> 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 team-worker agents in background (NOT general-purpose)
• Monitor progress via worker callbacks and route messages
• Maintain session state persistence (team-session.json)
• Handle capability_gap reports with warning only (cannot generate role-specs)
• Execute completion action when pipeline finishes

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 role-specs (use existing session role-specs only)
• Skip session validation
• Override consensus_blocked HIGH without user confirmation
• Spawn workers with general-purpose agent (MUST use team-worker)

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

---

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
Pipeline complete	All tasks completed, no pending/in_progress	-> handleComplete
New execution	None of above	-> Phase 0

For callback/check/resume/adapt/complete: 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.

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
• role-specs/ directory has >= 1 .md files
• All roles in team-session.json#roles have corresponding role-spec .md files
• Role-spec files have valid YAML frontmatter + Phase 2-4 sections

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

Step 2: Load Session State

Read team-session.json and task-analysis.json.

Step 3: Reconcile with TaskList

Compare TaskList() with session.completed_tasks, bidirectional sync.

Step 4: Reset Interrupted Tasks

Reset any in_progress tasks to pending.

Step 5: Detect Fast-Advance Orphans

In_progress tasks without matching active_worker + created > 5 minutes -> reset to pending.

Step 6: Create Missing Tasks (if needed)

For each task in task-analysis, check if exists in TaskList, create if missing.

Step 7: Update Session File

Write reconciled team-session.json.

Step 8: Team Setup

TeamCreate if team does not exist.

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

---

Phase 1: Spawn-and-Stop

Objective: Spawn first batch of ready workers as team-worker agents in background, then STOP.

Workflow:

1. Load commands/monitor.md
2. Find tasks with: status=pending, blockedBy all resolved, owner assigned
3. For each ready task -> spawn team-worker (see SKILL.md Executor Spawn Template)
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 + Completion Action

Objective: Completion report, interactive completion choice, 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. Output report:

[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] ============================================

6. Execute Completion Action (based on session.completion_action):

Mode	Behavior
interactive	AskUserQuestion with Archive/Keep/Export options
auto_archive	Execute Archive & Clean without prompt
auto_keep	Execute Keep Active without prompt

Interactive handler: See SKILL.md Completion Action section.

---

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 role-specs
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
Role-spec file not found	ERROR, cannot proceed without role definition
Completion action fails	Default to Keep Active, log warning