Run Your First Orchestration

April 7, 2026 · View on GitHub

This tutorial walks through running a batch with /orch, reading the execution plan, and controlling batch lifecycle with pause/resume/abort commands.

Before You Start

Complete this first:

Install Taskplane

You should already have:

.pi/taskplane-config.json
default example tasks:
- taskplane-tasks/EXAMPLE-001-hello-world/
- taskplane-tasks/EXAMPLE-002-parallel-smoke/

New project? If you haven't set up Taskplane yet, just run /orch with no arguments. The supervisor detects that no configuration exists and walks you through onboarding — project assessment, task area design, git branching, and config generation. See Commands Reference: /orch for details.

Step 1: Understand Task Areas

The orchestrator discovers tasks from task areas defined in .pi/taskplane-config.json:

{
  "taskRunner": {
    "taskAreas": {
      "general": {
        "path": "taskplane-tasks",
        "prefix": "TP",
        "context": "taskplane-tasks/CONTEXT.md"
      }
    }
  }
}

Each area points to a directory containing task folders (for example TP-001-...).

Step 2: Preview the Plan

Start pi:

pi

Inside pi, run:

/orch-plan all

This shows:

discovery results (pending/completed tasks)
dependency graph
computed waves
lane assignment preview

Use refresh mode to bypass dependency cache:

/orch-plan all --refresh

Step 3: Launch the Dashboard

In a separate terminal:

taskplane dashboard

Keep it open while running /orch so you can watch lanes and task progress live.

Step 4: Start the Batch

The simplest way to start is:

/orch

When you have pending tasks and a valid configuration, /orch with no arguments detects this state and offers to start a batch. You can confirm and the supervisor takes care of the rest.

Alternatively, start directly with explicit arguments:

/orch all

or explicit task paths:

/orch taskplane-tasks/EXAMPLE-001-hello-world/PROMPT.md taskplane-tasks/EXAMPLE-002-parallel-smoke/PROMPT.md

You can also orchestrate a single task path for worktree isolation:

/orch taskplane-tasks/EXAMPLE-001-hello-world/PROMPT.md

What happens:

Task discovery and dependency analysis
Wave computation (topological ordering)
Lane allocation up to maxLanes
Per-lane execution in isolated git worktrees
Each lane executes its assigned task in an isolated worktree with the worker/reviewer pipeline
Merge of successful lane branches into integration branch