run-tasks

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-critical criteria have issues) are tracked separately from PASS and FAIL — they are counted as completed but distinguished in metrics.
• Write session_complete event to progress.jsonl.
• Archive: Move __live_session__/ contents to .claude/sessions/{session-id}/.

See references/orchestration.md Step 6 for the summary format and archival procedure.

Step 7: Finalize

Review execution_context.md for project-wide changes and update CLAUDE.md if warranted:

• New dependencies added to the project
• New patterns established during execution
• Architecture decisions made
• New commands or build steps discovered

Skip updates if only task-specific or internal implementation details were recorded.

See references/orchestration.md Step 7 for the CLAUDE.md update criteria.

Key Behaviors

• Orchestration pattern: Extends the Swarm / Self-Organizing Pool pattern (Pattern 3 from claude-code-teams/references/orchestration-patterns.md) with a 3-tier agent hierarchy that adds Context Managers for cross-task knowledge flow and structured retry intelligence.
• 3-tier agent hierarchy: Orchestrator (this skill) handles planning and user interaction. Wave Leads coordinate executors within a wave. Context Managers distribute and collect execution context.
• Agent Team coordination: The wave-lead creates its own team (via TeamCreate) and becomes the team lead. It spawns context managers and executors as teammates using SendMessage for coordination. The orchestrator spawns the wave-lead as a plain foreground subagent and reads results from a summary file.
• Team member spawning: The wave-lead spawns context managers and executors as team members using the Task tool with team_name parameter. This ensures they appear in the team's config.json, enabling defense-in-depth cleanup and proper SendMessage routing. The orchestrator does NOT use team_name when spawning the wave-lead — the wave-lead is the team creator, not a member.
• Wave-based parallelism: Tasks at the same dependency level run simultaneously via the wave-lead's executor team. Tasks in later waves wait until their dependencies complete.
• 3-tier retry model: Tier 1 (Immediate) — wave-lead retries failed executor with failure context. Tier 2 (Context-Enriched) — wave-lead requests additional context from Context Manager and retries. Tier 3 (User Escalation) — persistent failures reported to orchestrator for user decision.
• Wave-lead crash recovery: If a wave-lead crashes or times out, the orchestrator force-stops all team members, resets in-progress tasks to pending, and spawns a new wave-lead (which creates its own fresh team). If the retry also fails, the user is escalated.
• Defense-in-depth cleanup: Agent shutdown is enforced at two levels. (1) The wave-lead shuts down its sub-agents (Step 6b), calls TeamDelete, and reports cleanup results in the wave summary file. (2) The orchestrator verifies cleanup by checking if the team directory still exists and force-stops any survivors via TaskStop. The orchestrator cannot call TeamDelete (not the team lead), so orphaned team directories are cleaned up during session initialization.
• Per-task timeouts: Complexity-based (XS/S: 5 min, M: 10 min, L/XL: 20 min). Override via metadata.timeout_minutes.
• Dry-run mode: --dry-run completes Steps 1-3 only. Displays the full execution plan without spawning agents or creating a session.
• Autonomous after confirmation: After the user confirms at Step 3, no further prompts occur unless a Tier 3 escalation is triggered by persistent failures.
• Graceful abort: Users can stop execution between waves by creating .claude/sessions/__live_session__/.abort from another terminal. The current wave completes, remaining tasks are marked failed, and the session is archived. Optionally include an abort reason as file content (e.g., echo "requirements changed" > .claude/sessions/__live_session__/.abort).
• Single-session invariant: Only one execution session at a time per project. Existing sessions must be resolved before starting a new one.
• Phase and group filtering: --phase and --task-group can be combined (AND logic). Filters narrow the task set before planning.

Quality Gate Hooks

This skill uses Claude Code hooks for automated quality gates during execution:

• TaskCompleted: When a task executor marks a task completed, the verify-task-completion.sh hook runs the project's test suite. If tests fail, the completion is blocked and the task reverts to in_progress with feedback to the executor.
• TeammateIdle: When a teammate goes idle, a role-aware prompt-based hook checks if the agent is a task executor and, if so, verifies it has sent both required messages (TASK RESULT to wave-lead, CONTEXT CONTRIBUTION to context manager) before resting. Non-executor roles (context manager, wave-lead) are not affected.

Hook definitions are in ${CLAUDE_PLUGIN_ROOT}/hooks/hooks.json. For hook event documentation, see claude-code-teams/references/hooks-integration.md.

Example Usage

Execute all pending tasks

/run-tasks

Execute tasks for a specific group

/run-tasks --task-group user-authentication

Execute a specific phase

/run-tasks --phase 1

Execute multiple phases within a group

/run-tasks --task-group payments --phase 1,2

Preview the execution plan without running

/run-tasks --dry-run

Execute a single task

/run-tasks 5

Override parallelism for this run

/run-tasks --max-parallel 2

Disable retries for this run

/run-tasks --retries 0

Abort a running session (from another terminal)

touch .claude/sessions/__live_session__/.abort
# Or with a reason:
echo "requirements changed" > .claude/sessions/__live_session__/.abort

Dry-run with filters

/run-tasks --task-group payments --phase 2 --dry-run

Reference Files

• references/orchestration.md — Detailed 7-step orchestration procedures, wave execution, retry escalation, session management, and CLAUDE.md update criteria
• references/communication-protocols.md — SDD-specific message schemas for the 3-tier hierarchy (6 protocols)
• references/verification-patterns.md — Verification logic for spec-generated vs general tasks
• ${CLAUDE_PLUGIN_ROOT}/../claude-tools/skills/claude-code-tasks/SKILL.md — Task tool parameters and conventions (loaded at init)
• ${CLAUDE_PLUGIN_ROOT}/../claude-tools/skills/claude-code-teams/SKILL.md — Team lifecycle, messaging, and orchestration patterns (loaded at init)
• ${CLAUDE_PLUGIN_ROOT}/../claude-tools/skills/claude-code-teams/references/orchestration-patterns.md — 6 orchestration patterns (loaded at init, for context)
• ${CLAUDE_PLUGIN_ROOT}/../claude-tools/skills/claude-code-teams/references/messaging-protocol.md — SendMessage types, delivery mechanics, shutdown handshake (loaded by agents)
• ${CLAUDE_PLUGIN_ROOT}/../claude-tools/skills/claude-code-teams/references/hooks-integration.md — TeammateIdle/TaskCompleted hook events