Claude-Code-Workflow/.codex/skills/team-executor/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 session -> Dispatch team_worker agents -> Monitor progress -> Completion action -> Report results

Boundaries

MUST

• Validate session structure before any execution
• Reconcile session state with tasks.json on startup
• Reset in_progress tasks to pending (interrupted tasks)
• Detect fast-advance orphans and reset to pending
• Spawn team_worker agents via spawn_agent and wait via wait_agent
• Monitor progress via wait_agent and route messages
• Maintain session state persistence (tasks.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 CLI tools or spawn utility members directly for implementation (code-developer, etc.)
• 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
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 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
• tasks.json exists and parses
• task-analysis.json exists and parses
• role-specs/ directory has >= 1 .md files
• All roles in tasks.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 tasks.json and task-analysis.json.

Step 3: Reconcile with tasks.json

Compare tasks.json task statuses with session expectations, 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_agents + created > 5 minutes -> reset to pending.

Step 6: Create Missing Tasks (if needed)

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

Step 7: Update Session File

Write reconciled tasks.json.

Step 8: Session Setup

Initialize session folder if needed.

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

---

Phase 1: Spawn-and-Wait

Objective: Spawn first batch of ready workers as team_worker agents, wait for completion, then continue.

Workflow:

1. Load commands/monitor.md
2. Find tasks with: status=pending, deps all resolved, owner assigned
3. For each ready task -> spawn team_worker via spawn_agent, wait via wait_agent
4. Process results, advance pipeline
5. Repeat until all tasks complete or pipeline blocked
6. Output status summary with execution graph

Pipeline advancement driven by:

• Synchronous wait_agent loop (automatic)
• 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 tasks.json completion_action):

Mode	Behavior
interactive	request_user_input with Archive/Keep/Export options
auto_archive	Execute Archive & Clean (rm -rf session folder) 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	Reset task to pending in tasks.json, respawn via spawn_agent
Session corruption	Attempt recovery, fallback to manual reconciliation
capability_gap reported	handleAdapt: WARN only, cannot generate new role-specs
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