orchestrate

Orchestrate — Full Lifecycle Execution

Execute a complete DDD plan from decomposition through validation and merge, managing the entire lifecycle automatically.

Command

/orchestrate <plan-path> [--phase <N>] [--continue] [--dry-run]

Arguments

Argument	Required	Description
<plan-path>	Yes	Path to DDD plan file
--phase <N>	No	Execute only phase N (skip earlier completed phases)
--continue	No	Resume from existing manifest (skip decomposition)
--dry-run	No	Decompose and plan but do not execute

Execution Modes

The orchestrator supports two execution modes, selected automatically at runtime:

Sequential Mode (default)

When CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS is not set, tasks within a phase execute sequentially via /spawn. This is the proven, stable execution path.

Agent Teams Mode (opt-in)

When CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 is set, independent tasks within a phase execute concurrently via agent teams. The orchestrator becomes the team lead, spawning one teammate per independent task.

Dual state model: The agent teams task list drives coordination (claiming, dependencies, completion), while .impl/manifest.json remains the persistent record. The lead synchronizes between the two.

See ADR-016 for the architectural decision and orchestration-guide.md for detailed documentation.

Workflow

Stage 1: Decomposition

1. Check for existing manifest. If --continue and .impl/manifest.json exists, load it and skip to Stage 2. Report: "Resuming from existing manifest."

2. Verify the plan. Read <plan-path> and confirm status is active.

3. Extract plan metadata and tasks. Run:

   bash scripts/parse-plan.sh --file <plan-path> --metadata
   bash scripts/parse-plan.sh --file <plan-path> --tasks
   

4. Initialize manifest.

   mkdir -p .impl
   bash scripts/task-manifest.sh --init \
     --plan-path <plan-path> \
     --plan-number <number> \
     --plan-title "<title>"
   

5. Populate all tasks. For each extracted task:

   bash scripts/task-manifest.sh --add-task \
     --task-id <id> --phase <N> --description "<desc>" \
     --depends-on "<deps>" --bounded-contexts "<BCs>"
   

6. Report decomposition. Display phase/task summary. If --dry-run, stop here.

Stage 2: Phase Iteration

For each phase (in numerical order, or just --phase <N> if specified):

1. Check phase readiness. A phase is ready when all tasks in its dependency phases have status merged or abandoned. Run:

   bash scripts/task-manifest.sh --phase-status --phase <dep>
   

   If any dependency phase has non-terminal tasks, wait or report the blocker.

2. Identify pending tasks in the current phase:

   bash scripts/task-manifest.sh --list-tasks --phase <N> --status pending
   

Stage 3: Task Execution

Sequential Mode (default)

For each task in the phase:

1. Update manifest to in_progress.

   bash scripts/task-manifest.sh --update-status \
     --task-id <id> --status in_progress
   

2. Invoke /spawn <task-id>. This forks to the impl-worker agent in an isolated worktree. The agent:

   • Creates a named branch (impl/<plan-number>/<task-id>)
   • Implements the task
   • Commits changes
   • Returns a summary

3. Parse agent output. Extract:

   • Branch name created
   • Files changed
   • Any blockers or errors

4. Update manifest to validating.

   bash scripts/task-manifest.sh --update-status \
     --task-id <id> --status validating \
     --branch <branch-name>
   

5. Run validation. Discover the worktree path and run checks:

   bash scripts/run-checks.sh --discover --cwd <worktree-path>
   bash scripts/run-checks.sh --execute --cwd <worktree-path>
   

6. If checks pass:

   • Update manifest to passed
   • Invoke /merge-work <task-id> to merge branch and clean up worktree
   • Manifest updates to merged

7. If checks fail: Decide based on failure type:

   • Retryable (test/lint failure, retries < 2): Update manifest to failed, increment retries, re-spawn with failure context appended
   • Non-retryable (max retries reached): Mark abandoned, continue with remaining tasks
   • Critical (blocks dependent phases): Pause and report to user with --continue instructions

Agent Teams Mode (when CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1)

1. Detect agent teams. Check if CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS is set. If not, fall back to sequential mode above.

2. Populate task list. For each pending task in the current phase, add it to the agent teams task list with dependency information from the manifest.

3. Spawn teammates. The orchestrator (team lead) spawns one teammate per independent task. Teammates self-claim tasks via the task list's file-lock mechanism.

4. Each teammate executes. Same as sequential steps 1-6, but running concurrently in separate context windows. The TaskCompleted hook (gate-task-completion.sh) enforces quality checks.

5. Handle idle teammates. When a teammate finishes and others are still running, reassign to review or cleanup work via TeammateIdle handling.

6. Synchronize state. As teammates complete tasks, the lead synchronizes the agent teams task list with the .impl/manifest.json. Team task completion triggers manifest updates.

7. Merge sequentially. After all tasks in the phase complete, the lead merges branches sequentially (same as sequential mode) to avoid complex conflict resolution.

Stage 4: Phase Completion

1. Check phase status. After all tasks in the phase are processed:

   bash scripts/task-manifest.sh --phase-status --phase <N>
   

2. Report phase results. Display: tasks merged, failed, abandoned.

3. Advance to next phase. Return to Stage 2 for the next phase.

Stage 5: Completion

1. Final summary. Run:

   bash scripts/task-manifest.sh --summary
   

   Report:

   • Total tasks: N
   • Merged: M
   • Failed/abandoned: F
   • Phases completed: P/T
   • If all merged: "Plan <number> implementation complete."
   • If some failed: list failed/abandoned tasks with details

2. Clean up remaining worktrees. For any worktrees still present:

   git worktree list
   

   Remove worktrees for merged or abandoned tasks.

Error Recovery

• Merge conflicts: Pause orchestration, report conflicting files. Re-run with --continue after manual resolution.
• Sub-agent failure: Retry up to 2 times with failure context appended to the agent prompt. After exhausting retries, mark abandoned.
• Interrupted orchestration: Re-run with --continue to resume from the last known manifest state.
• All tasks in phase failed: Pause and report. The plan may need re-decomposition.

Scripts

• scripts/parse-plan.sh — Plan parsing (copy from decompose)
• scripts/task-manifest.sh — Manifest CRUD (copy from decompose)
• scripts/run-checks.sh — Check runner (copy from check-impl)

Templates

• templates/claude-task.md — Sub-agent instructions (copy from spawn)