# Orchestrate

`vp orchestrate` is an Agent-to-Agent (A2A) orchestration system. A controller agent breaks a task into sub-tasks, assigns each to a persona (preferred agent + fallback), runs worker agents in isolated git worktrees in parallel, and synthesises the results.

## Workflow

```
vp orchestrate plan <task>    # controller agent generates PLAN.md
vp orchestrate execute        # spawn workers per PLAN.md, monitor to completion
vp orchestrate merge          # controller agent synthesises worktree results
```

Each phase is independently runnable so you can review and edit between steps.

## Quick start

**1. Initialise orchestrate config in your project:**

```bash
vp orchestrate init
```

This creates `.vibepod/config.yaml` (or updates it if it already exists) with four starter personas — `frontend`, `backend`, `security`, `testing` — each with a preferred agent and fallback. Edit the file to match your project and the agents you have configured.

**2. Generate a plan:**

```bash
vp orchestrate plan "Add JWT authentication with a React login page and integration tests"
```

The controller agent analyses the task, assigns sub-tasks to personas, and writes:
- `.vibepod/PLAN.md` — human-readable orchestration plan
- `.vibepod/tasks/task-N.md` — detailed prompt for each worker agent

**3. Review and optionally edit the plan:**

```bash
cat .vibepod/PLAN.md
```

The plan looks like this:

```markdown
## Sub-tasks

### [TASK-1] Set up authentication module
- **persona**: backend
- **agent**: codex (fallback: claude)
- **worktree**: .vibepod/worktrees/task-1
- **prompt-file**: .vibepod/tasks/task-1.md
- **depends-on**: none
- **status**: pending

### [TASK-2] Build login UI components
- **persona**: frontend
- **agent**: claude (fallback: codex)
- **worktree**: .vibepod/worktrees/task-2
- **prompt-file**: .vibepod/tasks/task-2.md
- **depends-on**: none
- **status**: pending

### [TASK-3] Write integration tests
- **persona**: testing
- **agent**: claude (fallback: gemini)
- **worktree**: .vibepod/worktrees/task-3
- **prompt-file**: .vibepod/tasks/task-3.md
- **depends-on**: TASK-1, TASK-2
- **status**: pending
```

Edit PLAN.md or the individual task files before proceeding.

**4. Execute:**

```bash
vp orchestrate execute
```

VibePod spawns worker containers (up to `max_parallel` at a time), monitors their completion signals, and updates PLAN.md live. Tasks with dependencies start automatically once their prerequisites are done.

**5. Merge:**

```bash
vp orchestrate merge
```

The controller agent merges all completed worktree branches, resolves conflicts, and reports any that need manual attention.

---

## How it works

### Worker communication

Each worker agent receives:
- A task prompt file mounted read-only at `/vibepod-prompt.md`
- A `VP_STATUS_FILE` environment variable pointing to `/vibepod-status/task-N.json`

When finished, the worker writes a JSON signal to `VP_STATUS_FILE`:

```json
{"status": "done", "summary": "Implemented JWT auth with refresh tokens", "files_changed": ["src/auth/jwt.ts"]}
```

or on failure:

```json
{"status": "failed", "reason": "Could not resolve dependency conflict"}
```

VibePod reads this file to detect completion without polling container logs.

### Git worktrees

Each task runs in an isolated git worktree at `.vibepod/worktrees/task-N` on branch `orchestrate/task-N-<run-id>`. Workers commit their changes there; the merge phase brings everything back together.

### Fallback agents

If a worker signals failure (or the container exits without writing a status file), VibePod resets the worktree to its base commit and retries the task with the persona's `fallback` agent. A task without a `fallback` fails immediately.

### Task statuses

| Status | Meaning |
|---|---|
| `pending` | Ready to run (no unmet dependencies) |
| `waiting` | Queued — dependencies not yet done |
| `running` | Container active |
| `done` | Worker signalled success |
| `failed` | Worker signalled failure (and fallback also failed, if any) |
| `blocked` | A dependency failed — task will not run |

### Re-entrancy

If `vp orchestrate execute` is interrupted and re-run:
- `done` tasks are skipped
- `running` tasks whose containers are gone are reset to `pending` and re-queued
- `failed` tasks are retried from scratch
- `blocked` tasks can be unblocked by editing the failed dependency's status back to `pending` in PLAN.md

---

## Command reference

### `vp orchestrate init`

```
vp orchestrate init [OPTIONS]
```

| Option | Default | Description |
|---|---|---|
| `-w / --workspace` | `.` | Workspace directory |
| `--force` | — | Overwrite existing `orchestrate:` config without prompting |

### `vp orchestrate plan`

```
vp orchestrate plan <task> [OPTIONS]
```

| Option | Default | Description |
|---|---|---|
| `-w / --workspace` | `.` | Workspace directory |
| `--plan-file` | `.vibepod/PLAN.md` | Override plan file location |
| `--force` | — | Overwrite existing PLAN.md without prompting |

### `vp orchestrate execute`

```
vp orchestrate execute [OPTIONS]
```

| Option | Default | Description |
|---|---|---|
| `-w / --workspace` | `.` | Workspace directory |
| `--plan-file` | `.vibepod/PLAN.md` | Override plan file location |

### `vp orchestrate merge`

```
vp orchestrate merge [OPTIONS]
```

| Option | Default | Description |
|---|---|---|
| `-w / --workspace` | `.` | Workspace directory |
| `--plan-file` | `.vibepod/PLAN.md` | Override plan file location |
| `--force` | — | Skip warning when tasks are `failed`/`blocked` |
| `--merge-strategy` | *(from config)* | Override merge strategy: `auto` or `review` |

---

## `.vibepod/` layout

```
.vibepod/
  config.yaml           # project config (unchanged)
  PLAN.md               # orchestration plan (human-editable)
  planning-prompt.md    # generated prompt used by the plan phase
  merge-prompt.md       # generated prompt used by the merge phase
  merge-conflicts.md    # written by agent when a conflict cannot be resolved
  tasks/
    task-1.md           # agent prompt for TASK-1
    task-2.md           # agent prompt for TASK-2
  worktrees/
    task-1/             # git worktree for TASK-1
    task-2/             # git worktree for TASK-2
  status/
    task-1.json         # completion signal written by worker
    task-2.json         # completion signal written by worker
```

PLAN.md and task files are always retained after a merge. Worktrees and status files are removed automatically when `orchestrate.cleanup: true` (default) and the merge completes without unresolved conflicts.
