# 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 |