---
argument-hint: "[planId] [taskId]"
description: Execute a single task with dependency validation and status management.
---
# Single Task Execution

You are responsible for executing a single task within a plan while maintaining strict dependency validation and proper status management. Your role is to ensure the task is ready for execution, deploy the appropriate agent, and track execution progress.

---

## Find the AI Task Manager root

```bash
if [ ! -f /tmp/find-ai-task-manager-root.js ]; then
  cat << 'EOF' > /tmp/find-ai-task-manager-root.js
const fs = require('fs');
const path = require('path');

const findRoot = (currentDir) => {
  const taskManagerPath = path.join(currentDir, '.ai/task-manager');
  const metadataPath = path.join(taskManagerPath, '.init-metadata.json');

  try {
    if (fs.existsSync(metadataPath) && JSON.parse(fs.readFileSync(metadataPath, 'utf8')).version) {
      console.log(path.resolve(taskManagerPath));
      process.exit(0);
    }
  } catch (e) {
    // Continue searching
  }

  const parentDir = path.dirname(currentDir);
  if (parentDir.length < currentDir.length) {
    findRoot(parentDir);
  } else {
    process.exit(1);
  }
};

findRoot(process.cwd());
EOF
fi

root=$(node /tmp/find-ai-task-manager-root.js)

if [ -z "$root" ]; then
    echo "Error: Could not find task manager root directory (.ai/task-manager)"
    exit 1
fi
```

Use your internal Todo task tool to track the execution of all parts of the task. Example:

- [ ] Validate task: file, status (including needs-clarification), and dependencies.
- [ ] Set task status to in-progress.
- [ ] Execute the task (agent runs PRE_TASK_EXECUTION hook, then implements).
- [ ] Update task status to completed or failed.
- [ ] Document noteworthy events (if any).
- [ ] Emit structured output for orchestrator.

## Critical Rules

1. **Never skip dependency validation** - Task execution requires all dependencies to be completed
2. **Validate task status** - Never execute tasks that are already completed, in-progress, or needs-clarification
3. **Maintain status integrity** - Update task status throughout the execution lifecycle
4. **Document execution** - Record all outcomes and issues encountered
5. **Provide structured output** - Always emit the structured result block for orchestrator parsing

## Input Requirements
- Plan ID: $1 (required)
- Task ID: $2 (required)
- Task management directory structure: `/`
- Dependency checking script: `$root/.ai/task-manager/config/scripts/check-task-dependencies.cjs`

### Input Validation

First, validate that both arguments are provided:

```bash
if [ -z "$1" ] || [ -z "$2" ]; then
    echo "Error: Both plan ID and task ID are required"
    echo "Usage: /tasks:execute-task [planId] [taskId]"
    echo "Example: /tasks:execute-task 16 03"
    exit 1
fi
```

## Execution Process

### 1. Plan Location

Locate the plan directory using the discovered root:

```bash
plan_id="$1"
task_id="$2"

# Find plan directory
plan_dir=$(find $root/{plans,archive} -type d -name "${plan_id}--*" 2>/dev/null | head -1)

if [ -z "$plan_dir" ]; then
    echo "Error: Plan with ID ${plan_id} not found"
    echo "Available plans:"
    find $root/plans -name "*--*" -type d | head -5
    exit 1
fi

echo "Found plan: $plan_dir"
```

### 2. Task File Validation

Locate and validate the specific task file:

```bash
# Handle both padded (01, 02) and unpadded (1, 2) task IDs
task_file=""
if [ -f "${plan_dir}/tasks/${task_id}--"*.md ]; then
    task_file=$(ls "${plan_dir}/tasks/${task_id}--"*.md 2>/dev/null | head -1)
elif [ -f "${plan_dir}/tasks/0${task_id}--"*.md ]; then
    task_file=$(ls "${plan_dir}/tasks/0${task_id}--"*.md 2>/dev/null | head -1)
fi

if [ -z "$task_file" ] || [ ! -f "$task_file" ]; then
    echo "Error: Task with ID ${task_id} not found in plan ${plan_id}"
    echo "Available tasks in plan:"
    find "$plan_dir/tasks" -name "*.md" -type f | head -5
    exit 1
fi

echo "Found task: $(basename "$task_file")"
```

### 3. Task Status Validation

Check current task status to ensure it can be executed:

```bash
# Extract current status from task frontmatter
current_status=$(awk '
    /^---$/ { if (++delim == 2) exit }
    /^status:/ {
        gsub(/^status:[ \t]*/, "")
        gsub(/^["'\'']/, "")
        gsub(/["'\'']$/, "")
        print
        exit
    }
' "$task_file")

echo "Current task status: ${current_status:-unknown}"

# Validate status allows execution
case "$current_status" in
    "completed")
        echo "Error: Task ${task_id} is already completed"
        echo "Use execute-blueprint to re-execute the entire plan if needed"
        exit 1
        ;;
    "in-progress")
        echo "Error: Task ${task_id} is already in progress"
        echo "Wait for current execution to complete or check for stale processes"
        exit 1
        ;;
    "needs-clarification")
        echo "Error: Task ${task_id} is marked as 'needs-clarification'"
        echo "Resolve clarification questions in the task file before execution"
        exit 1
        ;;
    "pending"|"failed"|"")
        echo "Task status allows execution - proceeding..."
        ;;
    *)
        echo "Warning: Unknown task status '${current_status}' - proceeding with caution..."
        ;;
esac
```

#### Valid Status Transitions

Reference for orchestrators and execution flow:

- `pending` → `in-progress` (execution starts)
- `in-progress` → `completed` (successful execution)
- `in-progress` → `failed` (execution error)
- `failed` → `in-progress` (retry attempt)
- `pending` → `needs-clarification` (set externally by orchestrator or reviewer)
- `needs-clarification` → `pending` (clarification resolved, set externally)

### 4. Dependency Validation

Use the dependency checking script to validate all dependencies:

```bash
# Call the dependency checking script
if ! node $root/config/scripts/check-task-dependencies.cjs "$plan_id" "$task_id"; then
    echo ""
    echo "Task execution blocked by unresolved dependencies."
    echo "Please complete the required dependencies first."
    exit 1
fi

echo ""
echo "✓ All dependencies resolved - proceeding with execution"
```

### 5. Agent Selection

Read task skills and select appropriate task-specific agent:

Read and execute $root/.ai/task-manager/config/hooks/PRE_TASK_ASSIGNMENT.md

### 6. Status Update to In-Progress

Update task status before execution:

```bash
echo "Updating task status to in-progress..."

# Create temporary file with updated status
temp_file=$(mktemp)
awk '
    /^---$/ {
        if (++delim == 1) {
            print
            next
        } else if (delim == 2) {
            print "status: \"in-progress\""
            print
            next
        }
    }
    /^status:/ && delim == 1 {
        print "status: \"in-progress\""
        next
    }
    { print }
' "$task_file" > "$temp_file"

# Replace original file
mv "$temp_file" "$task_file"

echo "✓ Task status updated to in-progress"
```

### 7. Task Execution

Deploy the task using the Task tool with full context:

**Task Deployment**: Use your internal Task tool to execute the task with the following context:
- Task file path: `$task_file`
- Plan directory: `$plan_dir`
- Required skills: `$task_skills`
- Agent selection: Based on skills analysis or general-purpose agent

**The agent MUST perform these steps in order:**

1. **Pre-flight validation**: Read and execute `$root/.ai/task-manager/config/hooks/PRE_TASK_EXECUTION.md` before starting any implementation work.
2. **Execute the task**: Read the complete task file and implement according to its requirements, including:
   - Objective and acceptance criteria
   - Technical requirements and implementation notes
   - Input dependencies and expected output artifacts

### 8. Post-Execution Status Management

After task completion, update the status based on execution outcome:

```bash
temp_file=$(mktemp)
awk '
    /^---$/ {
        if (++delim == 1) {
            print
            next
        } else if (delim == 2) {
            print "status: \"completed\""
            print
            next
        }
    }
    /^status:/ && delim == 1 {
        print "status: \"completed\""
        next
    }
    { print }
' "$task_file" > "$temp_file"

mv "$temp_file" "$task_file"

echo "✓ Task ${task_id} status updated to completed"
```

### 9. Noteworthy Events Documentation

After task execution (whether successful or failed), append a "Noteworthy Events" section to the task file body if anything noteworthy occurred during execution.

Append to the end of the task file:

```markdown
## Noteworthy Events
- [YYYY-MM-DD] [Event description with sufficient context for the orchestrator]
```

If no noteworthy events occurred, do not add the section.

## Error Handling

Read and execute $root/.ai/task-manager/config/hooks/POST_ERROR_DETECTION.md

On any error, ensure you still emit the structured output block (see Output Requirements) with `Exit Code: 1`.

## Output Requirements

**CRITICAL - Structured Output for Orchestrator Coordination:**

Always end your output with a standardized summary in this exact format:

```
---
Task Execution Result:
- Plan ID: [plan-id]
- Task ID: [task-id]
- Exit Code: [0 for success, 1 for failure]
```

This structured output enables automated orchestration pipelines to parse results and determine next steps. It MUST be included regardless of success or failure.

## Usage Examples

```bash
# Execute a specific task
/tasks:execute-task 16 1

# Execute task with zero-padded ID
/tasks:execute-task 16 03

# Execute task from archived plan
/tasks:execute-task 12 05
```

## Integration Notes

This command is designed for scripting contexts where an external orchestrator manages task sequencing, commits, feature branches, linting, test execution, and plan archival. It integrates with the task management system by:
- Using established plan and task location patterns
- Leveraging the dependency checking script for validation
- Following status management conventions (see Valid Status Transitions)
- Providing structured machine-parseable output for orchestrator pipelines
- Maintaining compatibility with execute-blueprint workflows
- Preserving task isolation and dependency order

The command complements execute-blueprint by providing granular single-task control while maintaining the same validation standards.