orchestrator-complete-task

This skill provides the workflow for parent agents to properly complete and integrate work from child/worker tasks.

When to Use This Skill

Load this skill when:

• •You spawned a subtask via a2a_spawn_subtask or a2a_spawn_parallel_subtasks
• •You receive a completion notification from your child/worker
• •The notification says: [SUBTASK UPDATE] Task "task-name" completed successfully
• •Your child called a2a_reportCompletion

Applies to:

• •Orchestrators managing plan tasks
• •Parent agents coordinating child workers
• •Any agent that spawned subtasks and needs to integrate their work

Critical Understanding

Child task completion is a MULTI-STEP process that YOU (the parent) control!

When a child worker calls a2a_reportCompletion, this does NOT:

• •Automatically integrate their changes into your work
• •Mark the task as complete (for orchestrators)
• •Deploy dependent tasks

You must: Review, integrate, and explicitly complete the task following the steps below.

Step-by-Step Completion Process

1. Child Reports Completion

What happens:

• •Child worker commits their changes to their worktree branch
• •Child calls a2a_reportCompletion (NOT orchestrator_completeTask)
• •You receive: [SUBTASK UPDATE] Task "implement-core" completed successfully

What this means:

• •The child has finished their work
• •Changes are committed in their branch
• •Work is isolated in their worktree until you integrate it
• •For orchestrators: Task is still "running" in the plan until you complete it

2. Review Child's Output

Actions:

• •Read the completion message carefully
• •Verify the child accomplished the task goals
• •Check if there are obvious issues or concerns

Red flags:

• •Child mentions failures or partial completion
• •Error messages in the completion note
• •Child indicates uncertainty about their work
• •Output doesn't match what you requested

3. Pull Child's Changes

Use a2a_pull_subtask_changes to fetch the child's changes into your worktree:

{
  "subtaskWorktree": "/path/to/child/worktree"
}

Note: This pulls their branch into your worktree but doesn't merge it yet. You can review the changes before merging.

4. Review Code & Provide Feedback (CRITICAL)

Before merging, you MUST review the code:

• •Inspect the files changed by the worker.
• •Does the code meet the requirements?
• •Is it clean and idiomatic?
• •If you are unsure: Spawn a @reviewer subtask to review the changes for you.

Decision Point:

A. If work is SUBSTANDARD:

• •DO NOT proceed to merge or complete.
• •Send feedback to the worker:
  json

  // a2a_send_message_to_worker
  {
    "workerId": "worker-id",
    "message": "I reviewed your changes. The error handling in `api.ts` is missing. Please add try/catch blocks and retry."
  }
  

• •The worker will continue working. Wait for their next completion report.

B. If work is GOOD:

• •Proceed to Step 5 (Merge to Main).

5. Merge to Main

Decision point: Do dependent tasks need this code?

If merging:

# Switch to main branch
git checkout main

# Merge the worker's branch
git merge <worker-branch-name>

# If conflicts occur:
git status
git checkout --theirs <file>  # Accept worker's version (common pattern)
# OR manually resolve conflicts
git add .
git commit -m "Integrate task: implement-core"

Why merge before completing:

• •Workers operate in isolated worktrees from main
• •If Task B depends on Task A's code, A MUST be merged before B starts
• •Otherwise B works on stale code → conflicts, duplicates, errors

6. Delete the Child's Branch

CRITICAL STEP - Always delete after integrating:

# Delete the child's branch after merging
git branch -d <child-branch-name>

# If branch wasn't merged and you want to force delete:
git branch -D <child-branch-name>

Why this is mandatory:

• •Proves you've "folded" the worktree back into your work
• •For orchestrators: orchestrator_completeTask will FAIL if branch still exists
• •Prevents accumulation of stale branches
• •Signals that the child's work is fully integrated

7. Mark Task Complete in Plan (Orchestrators Only)

⚠️ This step only applies if you are an orchestrator managing a plan!

If you're a regular parent agent (not managing an orchestrator plan), skip to step 8.

For orchestrators only - after reviewing, merging, and deleting branch:

{
  "taskId": "implement-core"
}

Tool: orchestrator_completeTask

What this does:

• •Marks task as "completed" in the plan
• •Removes the worker
• •Fires completion event
• •Triggers deployment of dependent tasks

Important: This tool verifies the branch was deleted. If you get an error about the branch still existing, go back to step 6.

8. Continue Your Work

For orchestrators:

• •The orchestrator service automatically deploys any tasks whose dependencies are now satisfied
• •Dependent tasks will start with merged changes from main
• •Wait for health monitoring to inject updates about new workers
• •Monitor progress of newly deployed tasks
• •Continue the cycle for each completion

For regular parent agents:

• •You can now use the integrated code in your work
• •Continue executing your own task with the child's changes available
• •If you spawned multiple children, repeat this process for each completion
• •When all your children are integrated, you can complete your own task

Common Mistakes to Avoid

❌ DON'T:

• •Assume task is complete when you receive the notification
• •Call orchestrator_completeTask before pulling and reviewing changes
• •Forget to delete the branch before marking complete
• •Skip merging when dependent tasks need the code
• •Accept substandard work without review

✅ DO:

• •Follow all 8 steps in order
• •Review completion messages carefully
• •Review the actual code changes
• •Provide feedback if work is not good enough
• •Merge to main when tasks have dependencies
• •Delete branches after merging
• •Verify branch deletion before calling orchestrator_completeTask

Quick Reference

Orchestrator Flow:

Child calls a2a_reportCompletion
    ↓
You receive notification
    ↓
Review output
    ↓
Pull changes (a2a_pull_subtask_changes)
    ↓
Merge to main (if needed)
    ↓
Delete branch (git branch -d)
    ↓
Mark complete (orchestrator_completeTask) ← Orchestrator only
    ↓
Dependent tasks auto-deploy

Regular Parent Agent Flow:

Child calls a2a_reportCompletion
    ↓
You receive notification
    ↓
Review output
    ↓
Pull changes (a2a_pull_subtask_changes)
    ↓
Merge to your branch (if needed)
    ↓
Delete child's branch (git branch -d)
    ↓
Continue your work with integrated changes

Error Recovery

If orchestrator_completeTask fails:

Error: "Worker branch still exists"

• •Check: git branch --list <branch-name>
• •Fix: git branch -d <branch-name>
• •Retry: Call orchestrator_completeTask again

If merge conflicts occur:

• •Use git status to see conflicted files
• •Common pattern: git checkout --theirs <file> (accept worker's version)
• •Or manually resolve conflicts in files
• •git add . and git commit to complete merge

If child reported partial completion:

• •Don't complete the task yet
• •Send feedback via a2a_send_message_to_worker with guidance
• •For orchestrators: Retry the task with orchestrator_retryTask
• •Or spawn a new child to finish remaining work
• •Review what was completed vs what's still needed