# Execute Tasks > Maximum number of tasks to execute simultaneously per wave. Default is 5. Overrides settings file value. Use when this capability is needed. - Skill: `tomevault-io/execute-tasks` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/execute-tasks` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/execute-tasks/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/execute-tasks --- # Execute Tasks Skill This skill orchestrates autonomous task execution for Claude Code Tasks. It builds a dependency-aware execution plan, launches a dedicated agent for each task through a 4-phase workflow (Understand, Implement, Verify, Complete), handles retries with failure context, and shares learnings across tasks through a shared execution context file. ## Core Principles ### 1. Understand Before Implementing Never write code without first understanding: - What the task requires (acceptance criteria or inferred requirements) - What code already exists (read before modify) - What conventions the project follows (CLAUDE.md, existing patterns) - What earlier tasks discovered (shared execution context) ### 2. Follow Existing Patterns Match the codebase's established patterns: - Coding style, naming conventions, file organization - Error handling approach, logging patterns - Test framework, test structure, assertion style - Import ordering, module organization ### 3. Verify Against Criteria Do not assume implementation is correct. Verify by: - Walking through each acceptance criterion for spec-generated tasks - Running tests and linters for all tasks - Confirming the core change works as intended - Checking for regressions in existing functionality ### 4. Report Honestly Produce accurate verification results: - PASS only when all Functional criteria pass and tests pass - PARTIAL when non-critical criteria fail but core works - FAIL when Functional criteria or tests fail - Never mark a task complete if verification fails ## Orchestration Workflow This skill orchestrates task execution through a 10-step loop. See `references/orchestration.md` for the full detailed procedure. ### Step 1: Load Task List Retrieve all tasks via `TaskList`. If a `--task-group` argument was provided, filter tasks to only those with matching `metadata.task_group`. If a specific `task-id` argument was provided, validate it exists. ### Step 2: Validate State Handle edge cases: empty list, all completed, specific task blocked, no unblocked tasks, circular dependencies. ### Step 3: Build Execution Plan Resolve `max_parallel` setting using precedence: `--max-parallel` CLI arg > `.claude/agent-alchemy.local.md` setting > default 5. Build a dependency graph from pending tasks. Assign tasks to waves using topological levels: Wave 1 = no dependencies, Wave 2 = depends on Wave 1 tasks, etc. Sort within waves by priority (critical > high > medium > low > unprioritized), break ties by "unblocks most others." Cap each wave at `max_parallel` tasks. ### Step 4: Check Settings Read `.claude/agent-alchemy.local.md` if it exists for execution preferences, including `max_parallel` setting. CLI `--max-parallel` argument takes precedence over the settings file value. ### Step 5: Initialize Execution Directory Generate a `task_execution_id` using three-tier resolution: (1) if `--task-group` provided → `{task_group}-{YYYYMMDD}-{HHMMSS}`, (2) else if all open tasks share the same `metadata.task_group` → `{task_group}-{YYYYMMDD}-{HHMMSS}`, (3) else → `exec-session-{YYYYMMDD}-{HHMMSS}`. Clean any stale `__live_session__/` files by archiving them to `.claude/sessions/interrupted-{YYYYMMDD}-{HHMMSS}/`, resetting any `in_progress` tasks from the interrupted session back to `pending`. Check for and enforce the concurrency guard via `.lock` file. Create `.claude/sessions/__live_session__/` directory containing: - `execution_plan.md` — saved execution plan from Step 5 - `execution_context.md` — initialized with standard template - `task_log.md` — initialized with table headers (Task ID, Subject, Status, Attempts, Duration, Token Usage) - `tasks/` — subdirectory for archiving completed task files - `progress.md` — initialized with status template for real-time progress tracking - `execution_pointer.md` at `~/.claude/tasks/{CLAUDE_CODE_TASK_LIST_ID}/` — created immediately with absolute path to `.claude/sessions/__live_session__/` ### Step 6: Present Execution Plan and Confirm Display the plan showing tasks to execute, blocked tasks, and completed count. Also display the details of step 5 which includes the session directory path (`.claude/sessions/__live_session__/`) and files created, including the execution pointer file location. Then ask the user to confirm before proceeding with execution. If the user cancels, stop without modifying any tasks. ### Step 7: Initialize Execution Context Read `.claude/sessions/__live_session__/execution_context.md` (created in Step 5). If a prior execution context exists, look in `.claude/sessions/` for the most recent timestamped subfolder and merge relevant learnings into the new one. ### Step 8: Execute Loop Execute tasks in waves. For each wave: snapshot `execution_context.md`, mark wave tasks `in_progress`, update `progress.md` with all active tasks, launch up to `max_parallel` background agents simultaneously via **parallel Task tool calls with `run_in_background: true`**, recording the `{task_list_id → background_task_id}` mapping from each Task tool response. Each agent writes to `context-task-{id}.md` and a compact `result-task-{id}.md` (completion signal). The orchestrator polls for result files via the `poll-for-results.sh` script in a single Bash invocation (with `timeout: 2760000`), then batch-reads results to process outcomes — avoiding full agent output in context. After polling, the orchestrator calls `TaskOutput` on each background task_id to reap the process and extract per-task `duration_ms` and `total_tokens` usage metadata for the task log. If `TaskOutput` times out (agent stuck), `TaskStop` is called to force-terminate the agent. Failed tasks with retries remaining are re-launched as background agents (same TaskOutput reaping after retry polling). After all wave agents complete: merge per-task context files into `execution_context.md`, clean up result and context files, archive completed task JSONs, refresh TaskList for newly unblocked tasks, form next wave, repeat. ### Step 9: Session Summary Display execution results with pass/fail counts, total execution time (sum of per-task `duration_ms`), failed task list, newly unblocked tasks, and total token usage (sum of per-task `total_tokens` captured via `TaskOutput`). Save `session_summary.md` to `.claude/sessions/__live_session__/`. Archive the session by moving all contents from `__live_session__/` to `.claude/sessions/{task_execution_id}/`, leaving `__live_session__/` as an empty directory. `execution_pointer.md` stays pointing to `__live_session__/`. ### Step 10: Update CLAUDE.md Review execution context for project-wide changes (new patterns, dependencies, commands, structure changes, design decisions). Make targeted edits to CLAUDE.md if meaningful changes occurred. Skip if only task-specific or internal implementation details. ## Task Classification Determine whether a task is spec-generated or general to select the right verification approach. ### Detection Algorithm 1. **Check description format**: Look for `**Acceptance Criteria:**` with categorized criteria (`_Functional:_`, `_Edge Cases:_`, etc.) 2. **Check metadata**: Look for `metadata.spec_path` field 3. **Check source reference**: Look for `Source: {path} Section {number}` in the description If any check matches -> **spec-generated task** (use criterion-based verification) If none match -> **General task** (use inferred verification) ## 4-Phase Workflow Each task is executed by the `agent-alchemy-sdd:task-executor` agent through these phases: ### Phase 1: Understand Load context and understand scope before writing code. - Read the execute-tasks skill and references - Read `.claude/sessions/__live_session__/execution_context.md` for learnings from prior tasks - Load task details via `TaskGet` - Classify the task (spec-generated vs general) - Parse acceptance criteria or infer requirements from description - Explore affected files via Glob/Grep - Read `CLAUDE.md` for project conventions ### Phase 2: Implement Execute the code changes following project patterns. - Read all target files before modifying them - Follow the project's implementation order (data -> service -> interface -> tests) - Match existing coding patterns and conventions - Write tests if specified in testing requirements - Run mid-implementation checks (linter, existing tests) to catch issues early ### Phase 3: Verify Verify implementation against task requirements using the adaptive approach. - **spec-generated tasks**: Walk each acceptance criteria category (Functional, Edge Cases, Error Handling, Performance), check testing requirements, run tests - **General tasks**: Infer "done" from description, run existing tests, run linter, verify core change is implemented ### Phase 4: Complete Report results and share learnings. - Determine status (PASS/PARTIAL/FAIL) based on verification results - If PASS: mark task as `completed` via `TaskUpdate` - If PARTIAL or FAIL: leave as `in_progress` for the orchestrator to decide on retry - Write learnings to `.claude/sessions/__live_session__/context-task-{id}.md` (files discovered, patterns learned, issues encountered) - Write compact result to `.claude/sessions/__live_session__/result-task-{id}.md` (status, verification summary, files modified, issues) — this is the **last** file written and signals completion to the orchestrator - Return minimal status line: `DONE: [{id}] {subject} - {PASS|PARTIAL|FAIL}` ## Adaptive Verification Overview Verification adapts based on task type: | Task Type | Verification Method | Pass Threshold | |-----------|-------------------|----------------| | spec-generated | Criterion-by-criterion evaluation | All Functional + Tests must pass | | General | Inferred checklist from description | Core change works + Tests pass | **Critical rule**: All Functional criteria must pass for a PASS result. Edge Cases, Error Handling, and Performance failures result in PARTIAL but do not block completion. ## Shared Execution Context Tasks within an execution session share learnings through `.claude/sessions/__live_session__/execution_context.md`: - **Write-based updates**: All orchestrator writes to session artifacts (`execution_context.md`, `task_log.md`, `progress.md`) use Write (full file replacement) via a read-modify-write pattern, never Edit. This ensures atomic, reliable updates regardless of file size. - **Snapshot before wave**: The orchestrator snapshots `execution_context.md` before launching each wave — all agents in a wave read the same baseline - **Per-task writes**: Each agent writes to `context-task-{id}.md` instead of the shared file, regardless of `max_parallel` setting. This eliminates write contention and avoids fragile Edit operations on shared files. - **Result file protocol**: Each agent writes a compact `result-task-{id}.md` (~18 lines) as its very last action. The orchestrator polls for these files and reads them instead of consuming full agent output, reducing context consumption by ~79% per wave. - **Merge after wave**: After all agents in a wave complete, the orchestrator appends all `context-task-{id}.md` content to the `## Task History` section of `execution_context.md` and deletes the per-task files. Result files for PASS tasks are also deleted; FAIL result files are retained for post-analysis. - **Sections**: Project Patterns, Key Decisions, Known Issues, File Map, Task History This enables later tasks to benefit from earlier discoveries and retry attempts to learn from previous failures. ## Key Behaviors - **Autonomous execution loop**: After the user confirms the execution plan, no further prompts occur between tasks. The loop runs without interruption once started. - **Background agent execution**: Agents run as background tasks (`run_in_background: true`), returning ~3 lines (task_id + output_file) instead of ~100+ lines of full output. This reduces orchestrator context consumption by ~79% per wave. - **Agent process reaping**: After polling confirms result files exist, the orchestrator calls `TaskOutput` on each background task_id to reap the process and extract per-task `duration_ms` and `total_tokens` usage metadata. If `TaskOutput` times out, `TaskStop` force-terminates the stuck agent. This prevents lingering background processes. - **Result file protocol**: Each agent writes a compact `result-task-{id}.md` (~18 lines) as its very last action. The orchestrator polls for these files via `poll-for-results.sh` in a single Bash invocation (with `timeout: 2760000`), then batch-reads them for processing. The result file doubles as a completion signal. - **Batched session file updates**: Instead of per-task read-modify-write on `task_log.md` and `progress.md`, all updates are batched into a single read-modify-write cycle per file per wave. - **Wave-based parallelism**: Tasks at the same dependency level run simultaneously, up to `max_parallel` concurrent agents per wave. Tasks in later waves wait until their dependencies in earlier waves complete. - **One agent per task, multiple per wave**: Each task gets a fresh agent invocation with isolated context, but multiple agents run concurrently within a wave. - **Per-task context isolation**: Each agent writes to `context-task-{id}.md` regardless of `max_parallel` setting. The orchestrator merges these after each wave. This eliminates write contention and fragile Edit operations on shared files. - **Within-wave retry**: Failed tasks with retries remaining are re-launched as background agents. The orchestrator polls for retry result files using `poll-for-results.sh` (same pattern as initial wave polling). - **Configurable parallelism**: Default 5 concurrent tasks, configurable via `--max-parallel` argument or `.claude/agent-alchemy.local.md` settings. Set to 1 for sequential execution. - **Configurable retries**: Default 3 attempts per task, configurable via `retries` argument. - **Retry with context**: Each retry includes failure details from the previous attempt's result file so the agent can try a different approach. - **Dynamic unblocking**: After each wave completes, the dependency graph is refreshed and newly unblocked tasks are added to the next wave. - **Honest failure handling**: After retries exhausted, tasks stay `in_progress` (not completed), and execution continues. - **Circular dependency detection**: If all remaining tasks are blocked by each other, break at the weakest link (task with fewest blockers) and log a warning. - **Shared context**: Agents read the snapshot of `execution_context.md` and write learnings to per-task context files. The orchestrator appends per-task content to the Task History section between waves. - **Resilient context sharing**: If a task-executor fails to write its context or result file, the orchestrator falls back to `TaskOutput` to capture diagnostic output. - **Single-session invariant**: Only one execution session can run at a time per project. A `.lock` file in `__live_session__/` prevents concurrent invocations. - **Interrupted session recovery**: Stale sessions are detected and archived; tasks left `in_progress` are automatically reset to `pending`. ## Example Usage ### Execute all unblocked tasks ``` /agent-alchemy-sdd:execute-tasks ``` ### Execute a specific task ``` /agent-alchemy-sdd:execute-tasks 5 ``` ### Execute with custom retry limit ``` /agent-alchemy-sdd:execute-tasks --retries 1 ``` ### Execute specific task with retries ``` /agent-alchemy-sdd:execute-tasks 5 --retries 5 ``` ### Execute tasks for a specific group ``` /agent-alchemy-sdd:execute-tasks --task-group user-authentication ``` ### Execute specific group with custom retries ``` /agent-alchemy-sdd:execute-tasks --task-group payments --retries 1 ``` ### Execute with limited parallelism ``` /agent-alchemy-sdd:execute-tasks --max-parallel 2 ``` ### Execute sequentially (no concurrency) ``` /agent-alchemy-sdd:execute-tasks --max-parallel 1 ``` ### Execute group with custom parallelism and retries ``` /agent-alchemy-sdd:execute-tasks --task-group payments --max-parallel 3 --retries 1 ``` ## Reference Files - `references/orchestration.md` - 10-step orchestration loop with execution plan, retry handling, and session summary - `references/execution-workflow.md` - Detailed phase-by-phase procedures for the 4-phase workflow - `references/verification-patterns.md` - Task classification, criterion verification, pass/fail rules, and failure reporting format --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/sequenzia) — claim your Tome and manage your conversions.