execute-tasks

name	execute-tasks
description	Execute pending SDD tasks in dependency order with wave-based concurrent execution via subagent dispatch and structured verification. Requires a harness that supports subagent dispatch (parallel task-executor agents). Reads task files from .agents/tasks/ and manages execution sessions in .agents/sessions/. Supports task group filtering and configurable parallelism. Use when user says "execute tasks", "run tasks", "start execution", "work on tasks", or wants to execute generated tasks autonomously.
metadata	{"argument-hint":"[task-id] [--task-group <group>] [--retries <n>] [--max-parallel <n>]","type":"workflow","harness-hints":{"prefer-non-streaming":true,"reason":"Long-running autonomous execution with session file accumulation may exceed streaming limits"},"agents":[{"name":"task-executor","file":"agents/task-executor.md","shared":false}]}
allowed-tools	Read Write Glob Grep Bash

Execute Tasks Skill

This skill orchestrates autonomous execution of SDD tasks stored as JSON files in .agents/tasks/. It builds a dependency-aware execution plan, dispatches a task-executor 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.

Tasks are managed entirely through file-based operations (Read, Write, Glob) on .agents/tasks/ directories — no harness-specific task tools required.

Load Reference Skills

Before starting, load the task schema and file operations:

Read: ../sdd-tasks/SKILL.md

This provides the task JSON schema, status lifecycle, file-based CRUD operations, dependency patterns, and anti-patterns.

Core Principles

1. Understand Before Implementing

Never write code without first understanding:

• What the task requires (structured acceptance criteria)
• What code already exists (read before modify)
• What conventions the project follows (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 category
• Running tests and linters
• 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 9-step loop. See references/orchestration.md for the full detailed procedure.

Step 1: Load Task List

Scan .agents/tasks/ directories using Glob and Read to build the task index. If --task-group was provided, scan only that group's subdirectories. If a specific task-id was provided, locate and validate it exists.

For each task file found, read the JSON and extract: id, title, status, blocked_by, metadata.priority, metadata.task_group, acceptance_criteria, and the full file path.

Step 2: Validate State

Handle edge cases: empty task 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 > .agents/settings.md value > 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 .agents/settings.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 .agents/sessions/interrupted-{YYYYMMDD}-{HHMMSS}/, resetting any in_progress tasks back to pending via file moves. Check for and enforce the concurrency guard via .lock file. Create .agents/sessions/__live_session__/ containing:

• execution_plan.md — saved execution plan
• execution_context.md — initialized with standard template
• task_log.md — initialized with table headers
• tasks/ — subdirectory for archiving completed task files
• progress.md — initialized with status template

Step 6: Present Execution Plan and Confirm

Display the plan showing tasks to execute, blocked tasks, and completed count. Prompt the user to confirm before proceeding. If cancelled, stop without modifying any tasks.

Step 7: Initialize Execution Context

Read .agents/sessions/__live_session__/execution_context.md. If a prior execution context exists in .agents/sessions/, merge relevant learnings from the most recent session.

Step 8: Execute Loop

Execute tasks in waves. For each wave: snapshot execution_context.md, move wave tasks from pending/ to in-progress/ via file operations, dispatch task-executor agents per the Execution Strategy, poll for result files (subagent path), process results, retry failed tasks with context, merge per-task context files into execution_context.md, archive completed task files, refresh unblocked tasks, and form the next wave.

Step 9: Session Summary

Display execution results with pass/fail counts, failed task list, and newly unblocked tasks. Save session_summary.md. Archive the session by moving all contents from __live_session__/ to .agents/sessions/{task_execution_id}/.

SDD Verification

All tasks executed by this skill are expected to have structured acceptance_criteria objects (produced by the create-tasks skill). The acceptance_criteria field in the task JSON contains four arrays:

{
  "acceptance_criteria": {
    "functional": ["criterion 1", "criterion 2"],
    "edge_cases": ["criterion 3"],
    "error_handling": ["criterion 4"],
    "performance": []
  }
}

Verification walks each category:

• Functional: All must pass for a PASS result
• Edge Cases: Failures flagged as PARTIAL, don't block completion
• Error Handling: Failures flagged as PARTIAL, don't block completion
• Performance: Failures flagged as PARTIAL, don't block completion

Fallback: If a task lacks acceptance_criteria (safety net), infer requirements from the description and title fields.

4-Phase Workflow

Each task is executed by the task-executor agent through these phases:

Phase 1: Understand

Load context and understand scope before writing code.

• Read .agents/sessions/__live_session__/execution_context.md for learnings from prior tasks
• Read the task JSON file from .agents/tasks/in-progress/{group}/task-{id}.json
• Parse acceptance_criteria object and testing_requirements array
• Explore affected files via Glob/Grep
• Read project conventions

Phase 2: Implement

Execute the code changes following project patterns.

• Read all target files before modifying them
• Follow 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 the structured acceptance_criteria.

• Walk each category: Functional, Edge Cases, Error Handling, Performance
• Check testing_requirements
• Run tests and linter

Phase 4: Complete

Report results and share learnings.

• Determine status (PASS/PARTIAL/FAIL) based on verification
• If PASS: move task file from in-progress/{group}/ to completed/{group}/ (read JSON fresh, modify only status and updated_at on the parsed object — all other fields unchanged, write complete object to new path, verify acceptance_criteria present, delete old file)
• If PARTIAL or FAIL: leave in in-progress/ for the orchestrator to decide on retry
• Write learnings to .agents/sessions/__live_session__/context-{id}.md
• Write compact result to .agents/sessions/__live_session__/result-{id}.md — this is the last file written and signals completion to the orchestrator
• Return minimal status line: DONE: [{id}] {title} - {PASS|PARTIAL|FAIL}

Shared Execution Context

Tasks within an execution session share learnings through .agents/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
• Snapshot before wave: The orchestrator snapshots execution_context.md before each wave — all agents in a wave read the same baseline
• Per-task writes: Each agent writes to context-{id}.md instead of the shared file, eliminating write contention
• Result file protocol: Each agent writes a compact result-{id}.md (~18 lines) as its very last action. The orchestrator polls for these files instead of consuming full agent output
• Merge after wave: After all agents complete, the orchestrator appends all context-{id}.md content to execution_context.md and deletes the per-task files. PASS result files are deleted; FAIL result files are retained for post-analysis
• Sections: Project Patterns, Key Decisions, Known Issues, File Map, Task History

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.
• Result file protocol: Each agent writes a compact result-{id}.md (~18 lines) as its very last action. The orchestrator polls for these files via scripts/poll-for-results.sh, then reads them for processing.
• Batched session file updates: All updates to task_log.md and progress.md 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.
• One agent per task, multiple per wave: Each task gets a fresh agent invocation with isolated context.
• Per-task context isolation: Each agent writes to context-{id}.md. The orchestrator merges these after each wave.
• Within-wave retry: Failed tasks with retries remaining are re-dispatched with failure context from the previous result file.
• Configurable parallelism: Default 5 concurrent tasks, configurable via --max-parallel argument or .agents/settings.md.
• Configurable retries: Default 3 attempts per task, configurable via --retries argument.
• Dynamic unblocking: After each wave completes, the dependency graph is refreshed and newly unblocked tasks join the next wave.
• Honest failure handling: After retries exhausted, tasks stay in_progress (not completed), and execution continues with the next wave.
• Circular dependency detection: If all remaining tasks block each other, break at the weakest link and log a warning.
• Single-session invariant: Only one execution session can run at a time per project. A .lock file prevents concurrent invocations.
• Interrupted session recovery: Stale sessions are detected and archived; tasks left in_progress are automatically reset to pending via file moves.

Example Usage

Execute all unblocked tasks

/execute-tasks

Execute a specific task

/execute-tasks task-005

Execute tasks for a specific group

/execute-tasks --task-group user-authentication

Execute with custom retry limit

/execute-tasks --retries 1

Execute with limited parallelism

/execute-tasks --max-parallel 2

Execute sequentially (no concurrency)

/execute-tasks --max-parallel 1

Execute group with custom parallelism and retries

/execute-tasks --task-group payments --max-parallel 3 --retries 1

Agents

Agent	File	Dependencies
task-executor	agents/task-executor.md	none

Execution Strategy

Execute agents respecting the wave-based dependency graph. For each wave, dispatch one task-executor subagent per task in the wave, passing the contents of agents/task-executor.md as the task instructions along with the task JSON content, session paths (context write path, result write path), and retry context if applicable. Dispatch all wave agents in parallel in a single message turn. After dispatch, poll for result files using scripts/poll-for-results.sh via a single Bash invocation (with timeout: 2760000). When polling completes, process results as described in references/orchestration.md Step 7d.

Agent Coordination

• The orchestrator manages the full execution lifecycle: task loading, wave planning, agent dispatch, result processing, context merging, and session archival
• Task-executor agents work independently — no cross-agent communication within a wave (hub-and-spoke topology)
• Context sharing happens between waves via the orchestrator's merge step, not during execution
• Each agent reads the wave's snapshot of execution_context.md and writes to isolated per-task files

Reference Files

• references/orchestration.md — 9-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 — Criterion verification, pass/fail rules, and failure reporting format