distributed-task-orchestrator

# Distributed Task Orchestrator

Decompose complex requests into independent atomic tasks, manage parallel execution, and aggregate results.

## Quick Decision

```
Is task complex? (3+ independent steps, multiple files, parallel benefit)
├── NO → Execute directly, skip orchestration
└── YES → Use orchestration
    ├── Simulated mode (default) → Present as parallel batches
    └── CLI mode (user requests) → Launch real Claude CLI sub-agents
```

**Skip orchestration for:** single-file ops, simple queries, < 3 steps, purely sequential tasks.

## Core Workflow

### Phase 1: Decompose

Analyze request → Break into atomic tasks → Map dependencies → Create `.orchestrator/master_plan.md`

```markdown
# Task Plan

## Request
> [Original request]

## Tasks
| ID | Task | Deps | Status |
|----|------|------|--------|
| T-01 | [Description] | None | 🟡 |
| T-02 | [Description] | T-01 | ⏸️ |
```

**Status:** 🟡 Pending · 🔵 Running · ✅ Done · ❌ Failed · ⏸️ Waiting

### Phase 2: Assign Agents

Create `.orchestrator/agent_tasks/agent-XX.md` for each task:

```markdown
# Agent-XX: [Task Name]
**Input:** [parameters]
**Do:** [specific instructions]
**Output:** [expected format]
```

### Phase 3: Execute

**Simulated Mode (Default):**

```
═══ Batch #1 (No Dependencies) ═══
🤖 Agent-01 [T-01: Task Name]
   ⚙️ [Execution steps...]
   ✅ Completed

═══ Batch #2 (After Batch #1) ═══
🤖 Agent-02 [T-02: Task Name]
   ⚙️ [Execution steps...]
   ✅ Completed
```

**CLI Mode (When Requested):** See [cli-integration.md](references/cli-integration.md)

### Phase 4: Aggregate

Collect results → Merge by dependency order → Generate `.orchestrator/final_output.md`

## Dependency Patterns

- **Parallel:** T-01, T-02, T-03 → T-04 (first three run together)
- **Serial:** T-01 → T-02 → T-03 (each waits for previous)
- **DAG:** Complex graphs use topological sort

## Error Handling

| Strategy | When to Use |
|----------|-------------|
| Retry (3x, exponential backoff) | Timeouts, transient failures |