---
name: skill-orchestrate
description: /orchestrate skill — checks agent task state, launches container agents in git worktrees, updates .agent-tasks.json. Use with /loop 2m /orchestrate for auto-polling.
type: reference
---

# /orchestrate Skill

## Purpose

Poll `.agent-tasks.json`, check container statuses, and launch container agents for tasks whose dependencies are met. Each task runs in its own git worktree for isolation. Designed for repeated invocation via `/loop`.

## Usage

```
/orchestrate                    # one-shot check and dispatch
/loop 2m /orchestrate           # auto-poll every 2 minutes
```

## How It Works

Each invocation:

1. **Check running containers** — `docker inspect` each running task's container. Mark completed (exit 0) or failed (non-zero). Capture logs on failure.
2. **Identify ready tasks** — pending tasks whose dependencies are all completed. Mark tasks as `blocked` if a dependency failed.
3. **Launch ready tasks** (up to `max_concurrent`):
   - Create a git worktree: `git worktree add .worktrees/<task-id> -b agent/<task-id>` (branches from dependency branch if applicable)
   - Launch container: `docker run -d` with worktree mounted at `/project`
   - Record container ID, host, branch, worktree path in task state
4. **Report status** — concise table showing all task statuses
5. **Update `.agent-tasks.json`**

When all tasks are resolved, suggests branch review and merge. Does NOT auto-merge.

## Git Worktree Isolation

- Each task gets its own branch (`agent/<task-id>`) and worktree (`.worktrees/<task-id>`)
- Tasks with no dependencies branch from HEAD
- Tasks depending on one completed task branch from that task's branch
- Tasks with multiple dependencies get an octopus merge base branch
- Worktrees share the `.git` object store — fast creation, minimal disk

## Gotchas

- Uses `docker run -d` (no `--rm`) so container logs survive for inspection after exit
- `CLAUDE_CODE_OAUTH_TOKEN` must be in the environment or readable from `~/dev/claude/secrets/claude/long_lived_oauth_token`
- Containers mount the worktree path, not the main project — the absolute path must be correct
- `Bash(git *)` in allowed-tools is broad (validator warns) but necessary for worktree/branch/merge operations
- Stale containers (running > 30 minutes) are flagged but not killed automatically

## Used By

- `agent-runtimes` — M3 harness implementation
- Any project using `/decompose` for parallel container agent work