Team Orchestrator

Break large goals into agent-sized tasks, wire up dependencies, and drive parallel execution across a team.

Core Concepts

Epic to Story to Task Decomposition

Every piece of work flows through three levels:

•Epic: A broad objective ("Build user authentication"). Too large for one agent.
•Story: A coherent slice of the epic ("Implement password hashing"). May still need splitting.
•Task: A single unit of work completable by one agent in one session. Has clear inputs, outputs, and acceptance criteria.

The rule of thumb: if you cannot describe the done state in one sentence, the task is too big. If the task takes under five minutes of thought to specify, you may have over-decomposed.

Dependency Management

Tasks declare two relationships:

•blockedBy: IDs of tasks that must complete before this task can start.
•blocks: IDs of tasks that cannot start until this task completes.

These are symmetric: if task B has blockedBy: ["A"], then task A should have blocks: ["B"].

Dependency rules:

•Minimize dependencies. Every edge you add constrains parallelism.
•Never create circular dependencies. If A blocks B and B blocks A, neither can start.
•Prefer thin interfaces. A task should depend on an output artifact, not on an entire body of work.
•Make dependencies explicit. Implicit ordering causes race conditions and wasted effort.

Workflow Patterns

Sequential -- Tasks run one after another. Use when each task consumes the prior task's output directly.

code

A --> B --> C --> D

Parallel -- Independent tasks run simultaneously. Use when tasks share no data dependencies.

code

A --> B
A --> C
A --> D

Diamond -- Parallel paths converge at a synchronization point. Use when independent work must merge before the next phase.

code

    B
   / \
  A   D
   \ /
    C

Pipeline -- Stages where multiple tasks feed into the next stage. Use for phased delivery with review gates.

code

[Design A, Design B] --> [Implement A, Implement B] --> [Integration Test]

Task Assignment Strategy

•Match skills to tasks. Assign code tasks to code-focused agents, documentation to writing agents.
•Balance load. Distribute tasks so no single agent becomes a bottleneck.
•Minimize handoffs. If one agent wrote the module, assign its tests to the same agent when possible.
•Separate concerns. The agent reviewing code should not be the agent who wrote it.
•Keep the critical path staffed. Never leave a critical-path task unassigned.

Execution Monitoring

Track workflow health by watching:

•Blocked count: How many tasks are waiting. A rising number signals a bottleneck.
•In-progress count: How many tasks are active. Should match your team size.
•Critical path progress: How many critical-path tasks remain. This determines your minimum completion time.
•Idle agents: Any agent with no assigned pending or in-progress task is wasted capacity.

Update task status as work proceeds. A task moves through: pending -> in_progress -> completed.

When a task completes, check whether it unblocks downstream tasks and notify those owners.

Example 1: Build REST API

Epic: Build a REST API for a task management application.

Decomposition:

code

Epic: REST API
  Story: Project Setup
    Task 1: Initialize project structure and dependencies
  Story: Data Layer
    Task 2: Define database schema and models
    Task 3: Write database migration scripts
  Story: API Endpoints
    Task 4: Implement CRUD endpoints for tasks
    Task 5: Implement CRUD endpoints for users
    Task 6: Add authentication middleware
  Story: Testing
    Task 7: Write unit tests for models
    Task 8: Write integration tests for endpoints
  Story: Documentation
    Task 9: Write API documentation with examples

Dependency graph:

code

Task 1 (setup)
  |
  +--> Task 2 (schema) --+--> Task 3 (migrations)
  |                       |
  |                       +--> Task 4 (task endpoints) --+--> Task 8 (integration tests)
  |                       |                              |
  |                       +--> Task 5 (user endpoints) --+
  |                       |
  |                       +--> Task 6 (auth middleware) --+
  |                       |
  |                       +--> Task 7 (unit tests)
  |
  +--> Task 9 (docs) -- depends on Tasks 4, 5, 6

TaskCreate calls:

code

TaskCreate: {
  subject: "Initialize project structure",
  description: "Create Python project with FastAPI, SQLAlchemy, Alembic. Set up pyproject.toml, directory layout (app/models, app/routes, app/tests), and dev dependencies.",
  owner: "backend-dev-1",
  blockedBy: [],
  blocks: ["task-2", "task-9"]
}

TaskCreate: {
  subject: "Define database schema and models",
  description: "Create SQLAlchemy models for User (id, email, password_hash, created_at) and Task (id, title, description, status, owner_id FK, created_at, updated_at). Include relationships.",
  owner: "backend-dev-1",
  blockedBy: ["task-1"],
  blocks: ["task-3", "task-4", "task-5", "task-6", "task-7"]
}

TaskCreate: {
  subject: "Write database migration scripts",
  description: "Create Alembic migration for initial schema. Verify upgrade and downgrade paths. Seed script for dev data.",
  owner: "backend-dev-2",
  blockedBy: ["task-2"],
  blocks: []
}

TaskCreate: {
  subject: "Implement CRUD endpoints for tasks",
  description: "POST /tasks, GET /tasks, GET /tasks/{id}, PUT /tasks/{id}, DELETE /tasks/{id}. Use Pydantic schemas for validation. Return appropriate HTTP status codes.",
  owner: "backend-dev-1",
  blockedBy: ["task-2"],
  blocks: ["task-8", "task-9"]
}

TaskCreate: {
  subject: "Implement CRUD endpoints for users",
  description: "POST /users (register), GET /users/me, PUT /users/me. Hash passwords with bcrypt. Pydantic schemas for input/output.",
  owner: "backend-dev-2",
  blockedBy: ["task-2"],
  blocks: ["task-8", "task-9"]
}

TaskCreate: {
  subject: "Add authentication middleware",
  description: "JWT-based auth. POST /auth/login returns access token. Middleware validates token on protected routes. Token expiry 24h.",
  owner: "backend-dev-2",
  blockedBy: ["task-2"],
  blocks: ["task-8", "task-9"]
}

TaskCreate: {
  subject: "Write unit tests for models",
  description: "Test User and Task model creation, validation, relationships. Test password hashing. Use pytest with in-memory SQLite. Target 95% model coverage.",
  owner: "tester",
  blockedBy: ["task-2"],
  blocks: []
}

TaskCreate: {
  subject: "Write integration tests for endpoints",
  description: "Test all endpoints with httpx AsyncClient. Cover auth flow, CRUD operations, error cases (404, 422, 401). Use test database with fixtures.",
  owner: "tester",
  blockedBy: ["task-4", "task-5", "task-6"],
  blocks: []
}

TaskCreate: {
  subject: "Write API documentation",
  description: "Document all endpoints with request/response examples. Include auth flow walkthrough. Add OpenAPI schema customizations. Write getting-started guide.",
  owner: "tech-writer",
  blockedBy: ["task-4", "task-5", "task-6"],
  blocks: []
}

Execution order:

•Task 1 starts immediately (no blockers).
•Task 2 starts when Task 1 completes.
•Tasks 3, 4, 5, 6, 7 all start in parallel when Task 2 completes.
•Tasks 8 and 9 start when Tasks 4, 5, and 6 all complete.

Critical path: Task 1 -> Task 2 -> Task 4 (or 5 or 6, whichever is slowest) -> Task 8.

Parallelism: After Task 2, five tasks can run simultaneously. Assign each to a different agent if available.

Example 2: Write Technical Documentation

Epic: Create comprehensive technical documentation for an existing library.

Decomposition:

code

Epic: Technical Documentation
  Story: Audit and Plan
    Task 1: Audit existing code and identify public API surface
    Task 2: Create documentation outline and style guide
  Story: Core Documentation
    Task 3: Write getting-started guide
    Task 4: Write API reference for core module
    Task 5: Write API reference for utilities module
  Story: Advanced Content
    Task 6: Write tutorial: common workflows
    Task 7: Write migration guide from v1 to v2
  Story: Review and Polish
    Task 8: Technical review of all documentation
    Task 9: Copy-edit and format final output

Dependency graph:

code

Task 1 (audit) ---+--> Task 2 (outline)
                  |        |
                  |        +--> Task 3 (getting started)
                  |        +--> Task 4 (core API ref) ----+--> Task 8 (tech review)
                  |        +--> Task 5 (utils API ref) ---+        |
                  |                                       |        v
                  +--> Task 6 (tutorials) ----------------+   Task 9 (copy-edit)
                  |
                  +--> Task 7 (migration guide) ----------+

TaskCreate calls:

code

TaskCreate: {
  subject: "Audit public API surface",
  description: "Read all source files. List every public class, function, and constant. Note which have docstrings and which do not. Output: api-surface.md with name, signature, and docstring status for each symbol.",
  owner: "researcher",
  blockedBy: [],
  blocks: ["task-2", "task-6", "task-7"]
}

TaskCreate: {
  subject: "Create documentation outline and style guide",
  description: "Define doc structure (sections, ordering). Write style guide: voice (active, second person), code example format (runnable snippets), heading conventions. Output: outline.md, style-guide.md.",
  owner: "tech-writer-1",
  blockedBy: ["task-1"],
  blocks: ["task-3", "task-4", "task-5"]
}

TaskCreate: {
  subject: "Write getting-started guide",
  description: "Cover installation (pip, conda), first script (10 lines), key concepts (3-4 paragraphs). Include a working code example that the reader can copy-paste and run.",
  owner: "tech-writer-1",
  blockedBy: ["task-2"],
  blocks: ["task-8"]
}

TaskCreate: {
  subject: "Write API reference for core module",
  description: "Document every public symbol in the core module. For each: signature, parameters with types, return value, exceptions raised, one usage example. Follow style guide from Task 2.",
  owner: "tech-writer-2",
  blockedBy: ["task-2"],
  blocks: ["task-8"]
}

TaskCreate: {
  subject: "Write API reference for utilities module",
  description: "Document every public symbol in the utilities module. Same format as Task 4. Cross-link to core module where utilities wrap core functionality.",
  owner: "tech-writer-2",
  blockedBy: ["task-2"],
  blocks: ["task-8"]
}

TaskCreate: {
  subject: "Write tutorial: common workflows",
  description: "Three tutorials: data loading, transformation pipeline, export to multiple formats. Each tutorial is a standalone page with full code and expected output.",
  owner: "tech-writer-1",
  blockedBy: ["task-1"],
  blocks: ["task-8"]
}

TaskCreate: {
  subject: "Write migration guide from v1 to v2",
  description: "List every breaking change. For each: what changed, why, before/after code snippets, automated migration steps if any. Include a checklist for migrating a project.",
  owner: "researcher",
  blockedBy: ["task-1"],
  blocks: ["task-8"]
}

TaskCreate: {
  subject: "Technical review of all documentation",
  description: "Verify every code example runs. Check accuracy of parameter descriptions against source. Flag inconsistencies with style guide. Output: review-notes.md with file, line, issue, suggestion.",
  owner: "reviewer",
  blockedBy: ["task-3", "task-4", "task-5", "task-6", "task-7"],
  blocks: ["task-9"]
}

TaskCreate: {
  subject: "Copy-edit and format final output",
  description: "Apply review fixes. Check grammar, spelling, formatting. Ensure consistent heading levels, link validity, and code block language tags. Final output: publishable documentation set.",
  owner: "tech-writer-1",
  blockedBy: ["task-8"],
  blocks: []
}

Execution order:

•Task 1 starts immediately.
•Tasks 2, 6, 7 start when Task 1 completes (parallel).
•Tasks 3, 4, 5 start when Task 2 completes (parallel, also parallel with 6 and 7).
•Task 8 starts when Tasks 3, 4, 5, 6, 7 all complete.
•Task 9 starts when Task 8 completes.

Critical path: Task 1 -> Task 2 -> Task 4 (longest API ref) -> Task 8 -> Task 9.

Parallelism peak: Up to five tasks (3, 4, 5, 6, 7) can run simultaneously after Task 2 completes. With three writers and one researcher, assign: writer-1 gets Tasks 3 and 6, writer-2 gets Tasks 4 and 5, researcher gets Task 7.

Monitoring Checklist

After creating all tasks:

•Run scripts/dependency_graph.py {team-name} to visualize the graph and confirm no cycles.
•Identify the critical path. Ensure every task on it has an owner.
•Count maximum parallelism. Ensure you have enough agents to exploit it.
•Set up a check-in cadence: after each critical-path task completes, review the remaining graph.
•When a task completes, use TaskUpdate to set status: "completed" and check what it unblocks.
•If a blocked task has all its blockers completed, set it to in_progress and notify the owner.
•If an agent finishes early, assign them the next available task from the ready queue (pending tasks with all blockers completed).

Common TaskUpdate Patterns

Starting a task:

code

TaskUpdate: { id: "task-4", status: "in_progress" }

Completing a task and checking downstream:

code

TaskUpdate: { id: "task-4", status: "completed" }
TaskList: { filter: { blockedBy: "task-4" } }
-- For each downstream task, check if all blockers are now completed.
-- If yes, notify the owner and set status to in_progress.

Reassigning a stuck task:

code

TaskUpdate: { id: "task-6", owner: "tech-writer-2", description: "..." }

Related Skills

•team-communicator -- Communication protocols for coordinating agents during workflow execution
•team-monitor -- Track task progress and detect bottlenecks in the workflow
•team-builder -- Create the team and initial tasks before orchestration begins