run-tasks

What this skill does

# Run Tasks Skill

This skill orchestrates autonomous task execution using Claude Code's native Agent Team system. It takes tasks produced by `/create-tasks`, builds a dependency-aware execution plan, and executes them in waves via a 3-tier agent hierarchy: Orchestrator (this skill) plans and coordinates waves, Wave Leads manage parallel executors within each wave, and Context Managers handle knowledge flow between tasks.

The wave-lead creates its own team and coordinates teammates via `SendMessage`. The orchestrator communicates with the wave-lead via file-based summaries (`wave-{N}-summary.md`).

## Load Reference Skills

Before executing any step, load the foundational references for task management and team orchestration:

### Tasks Reference
```
Read ${CLAUDE_PLUGIN_ROOT}/../claude-tools/skills/claude-code-tasks/SKILL.md
```

### Teams Reference
```
Read ${CLAUDE_PLUGIN_ROOT}/../claude-tools/skills/claude-code-teams/SKILL.md
```

These references provide tool parameters, lifecycle rules, messaging protocols, and orchestration patterns. The SDD-specific execution procedures are in the orchestration reference below.

### Orchestration Patterns Reference (optional, for context)
```
Read ${CLAUDE_PLUGIN_ROOT}/../claude-tools/skills/claude-code-teams/references/orchestration-patterns.md
```

### Orchestration Reference
```
Read ${CLAUDE_PLUGIN_ROOT}/skills/run-tasks/references/orchestration.md
```

If any reference file cannot be read, stop and report: "ERROR: Cannot load required reference. Verify the plugin installation is complete."

## Argument Parsing

Parse the following arguments from the user's invocation:

| Argument | Format | Default | Description |
|----------|--------|---------|-------------|
| `<task-id>` | positional integer | _(none — all tasks)_ | Execute a single specific task by ID. Mutually exclusive with `--task-group` and `--phase`. |
| `--task-group` | `<name>` | _(none — all tasks)_ | Filter tasks to those with matching `metadata.task_group` |
| `--phase` | `<N>` or `<N,M,...>` | _(none — all phases)_ | Comma-separated integers. Filter tasks by `metadata.spec_phase`. Tasks without `spec_phase` are excluded when active. |
| `--max-parallel` | `<N>` | _(from settings)_ | Override `run-tasks.max_parallel` setting for this run. Must be a positive integer. |
| `--retries` | `<N>` | _(from settings)_ | Override `run-tasks.max_retries` setting for this run. Must be a non-negative integer (0 = no retries). |
| `--dry-run` | _(flag)_ | `false` | Complete Steps 1-3 only: load, plan, display. No agents spawned, no session directory created. |

When both `--task-group` and `--phase` are provided, both filters apply (intersection). CLI args `--max-parallel` and `--retries` take precedence over settings file values.

**Validation:**
- `--phase` values must be positive integers. If a non-integer value is provided (e.g., `--phase abc`), report: "Invalid --phase value: must be comma-separated positive integers (e.g., --phase 1,2)." and stop.
- `--max-parallel` must be a positive integer. If invalid, report: "Invalid --max-parallel value: must be a positive integer." and stop.
- `--retries` must be a non-negative integer. If invalid, report: "Invalid --retries value: must be a non-negative integer." and stop.
- If `<task-id>` is provided alongside `--task-group` or `--phase`, report: "Cannot combine task ID with --task-group or --phase filters." and stop.
- If no tasks match the applied filters, report the available values. For `--phase`: "No tasks found for phase(s) {N}. Available phases: {sorted distinct spec_phase values}." For `--task-group`: "No tasks found for group '{name}'. Available groups: {sorted distinct task_group values}."

## 7-Step Orchestration Loop

### Step 1: Load & Validate

Load the full task list via `TaskList`. Apply `--task-group` and `--phase` filters if provided. Validate the resulting task set:

- **Empty task list**: Suggest running `/create-tasks` first.
- **All tasks completed**: Report summary with completion counts and stop.
- **No unblocked tasks**: Report the blocking chains preventing progress.
- **Circular dependencies**: Detect cycles, break at the weakest link (task with fewest blockers), and warn the user in the execution plan.

See `references/orchestration.md` Step 1 for the full procedure.

### Step 2: Configure & Plan

Read settings from `.claude/agent-alchemy.local.md` (use defaults if the file is missing). Build the execution plan:

1. **Topological sort**: Assign tasks to waves based on dependency levels. Wave 1 = tasks with no unmet dependencies. Wave N = tasks whose blockers are all in earlier waves or already completed.
2. **Priority ordering within waves**: Sort by priority (critical > high > medium > low > unprioritized), break ties by "unblocks most others."
3. **Wave capping**: Each wave limited to `max_parallel` tasks (default: 5, configurable via settings).

See `references/orchestration.md` Step 2 for settings and the full planning procedure.

### Step 3: Confirm

Present the execution plan to the user via `AskUserQuestion`:

- Total task count, wave count, and estimated team composition per wave. For waves with task count >= `context_manager_threshold`: 1 wave-lead + 1 context-manager + N executors. For smaller waves: 1 wave-lead + N executors (no CM).
- Per-wave breakdown with task subjects, priorities, and model tiers. Waves that skip CM are annotated with "(no context manager)".
- Any circular dependency warnings or broken links.

**If `--dry-run`**: Display the full plan details (wave breakdown, task assignments, model tiers, timeout estimates) and exit. No `TaskUpdate` calls, no session directory created, no agents spawned.

**If the user cancels**: Clean exit with no tasks modified.

See `references/orchestration.md` Step 3 for display format details.

### Step 4: Initialize Session

Create the session directory and handle interrupted session recovery:

1. **Generate session ID**: `{task-group}-{YYYYMMDD}-{HHMMSS}` (or `exec-session-{YYYYMMDD}-{HHMMSS}` if no group).
2. **Check for existing `__live_session__/` content**: If found, offer the user a choice via `AskUserQuestion`: resume (reset `in_progress` tasks to `pending`) or fresh start (archive to `.claude/sessions/interrupted-{timestamp}/`).
3. **Create session artifacts** in `.claude/sessions/__live_session__/`:
   - `execution_context.md` — empty template
   - `task_log.md` — header row only
   - `execution_plan.md` — populated from Step 2
   - `progress.jsonl` — `session_start` event

See `references/orchestration.md` Step 4 for the full initialization procedure and session ID generation rules.

### Step 5: Execute Waves

For each wave in the execution plan:

1. **Refresh unblocked tasks** via `TaskList` (dynamic unblocking after prior wave completions).
2. **Launch wave-lead** as a foreground subagent via `Task` (no `team_name` — the wave-lead creates its own team internally).
3. **Read wave summary file** from `{session_dir}/wave-{N}-summary.md` after the foreground Task completes.
4. **Process wave summary**: Update `task_log.md`, write `wave_complete` event to `progress.jsonl`, handle Tier 3 escalations (present failures to user via `AskUserQuestion` with options: Fix manually, Skip, Provide guidance, Abort).
5. **Verify cleanup**: Check that the wave-lead deleted its team. If the team directory still exists, force-stop any survivors via `TaskStop`. Includes inter-wave verification and cooldown before starting the next wave.
6. **Repeat** until no more unblocked tasks remain.

See `references/orchestration.md` Step 5 for the full wave execution procedure, retry escalation flow, and wave-lead crash recovery.

### Step 6: Summarize & Archive

Generate a session summary and archive the session:

- Write `session_summary.md` with pass/partial/fail/skipped counts, total execution time, per-wave breakdown, failed task list with reasons, and key decisions made during execution. PARTIAL tasks (core functionality works, non-c