# SOP: Multi-Agent Orchestration (PM + Workers)

When you ask “Hey Veritas, can you be the PM for this sprint and assign sub-agents?”, this is the playbook. One agent (usually Claude/Opus) acts as the project manager, spawns worker agents (Codex, Gemini, etc.), and reports back.

---

## Roles

| Role             | Description                                                                                 |
| ---------------- | ------------------------------------------------------------------------------------------- |
| **PM Agent**     | Owns the sprint, breaks work into tasks/subtasks, assigns/monitors workers, posts progress. |
| **Worker Agent** | Executes a single task end-to-end following the Agent Task SOP.                             |
| **Human Lead**   | Creates the sprint, reviews PM outputs, handles escalations.                                |

---

## PM Agent Checklist

1. **Read context**: AGENTS.md, sprint description, active tasks.
2. **Plan**: If tasks missing, create them (see Sprint Planning SOP).
3. **Assign**: For each task, either:
   - Self-assign if it’s planning/reporting work.
   - Spawn worker agent with clear instructions + acceptance criteria.
4. **Track**:
   - Update Agent Status panel using `vk agent sub-agent <count>`.
   - Managed workers rely on VK-owned attempt timing. Only human or external
     self-reporting workers use `vk begin`/`vk done`.
5. **Review**:
   - Run independent or cross-model review only when required by the task or
     configured governance policy.
   - Request fixes via subtasks or comments.
6. **Report**:
   - Post updates in task comments and daily standups (`vk summary standup --text`).
   - Ping human lead when blockers persist > 30 minutes.

---

## Worker Handoff Template

```
Task: <ID> — <Title>
Context: <link to research/requirements>
Deliverable: <clear definition of done>
Steps:
1. Treat the Veritas task envelope as authoritative.
2. Complete subtasks in order. Leave notes if deviations occur.
3. If blocked, report the blocker through an available VK tool or final output.
4. Return a concise completion summary through the native harness result.
5. Request an independent review only when the task or policy requires it.
Uploads: <where to store artifacts>
```

Store under `prompt-registry/worker-handoff.md`.

---

## Status Reporting Expectations

| Cadence                     | Mechanism                                            | Owner       |
| --------------------------- | ---------------------------------------------------- | ----------- |
| Start of day                | Comment on sprint tracker task summarizing plan.     | PM          |
| After each worker completes | Worker comment + PM reaction (✅/request changes).   | Worker + PM |
| Daily standup               | `vk summary standup --text` posted to comms channel. | PM          |
| Sprint end                  | Archive tasks, write lessons learned, close sprint.  | PM          |

Use emojis/reactions sparingly; detailed summaries live in comments.

---

## Error Escalation

| Issue                      | PM action                                                  |
| -------------------------- | ---------------------------------------------------------- |
| Worker exceeds time budget | Stop timer, leave comment, ping human.                     |
| Tooling failure (API down) | Run `pnpm dev:clean`, file issue, reassign.                |
| Reviewer rejects work      | Re-open task, create fix subtasks, keep reviewer looped.   |
| PM stuck                   | Escalate immediately — PMs should not be blocked > 15 min. |

---

## Squad Chat Protocol

All agents — PM and workers — must post to squad chat. This is the glass box.

**PM (orchestrator) responsibilities:**

```bash
# Before spawning each worker (include --model to show which AI is working):
./scripts/squad-event.sh --model gpt-5.1 spawned WORKER_NAME "Task Title"

# When worker completes:
./scripts/squad-event.sh completed WORKER_NAME "Task Title" "duration"

# When worker fails:
./scripts/squad-event.sh failed WORKER_NAME "Task Title" "duration"

# Coordination updates (regular messages):
./scripts/squad-post.sh --model claude-opus-4-6 PM_NAME "Dispatching 3 workers for sprint" coordination
```

**Worker responsibilities:**

```bash
# Post progress throughout work — include model so humans see which AI is behind each agent:
./scripts/squad-post.sh --model gpt-5.1 WORKER_NAME "Starting code review" review
./scripts/squad-post.sh --model gpt-5.1 WORKER_NAME "Found 3 issues, fixing" fix
./scripts/squad-post.sh --model gpt-5.1 WORKER_NAME "Complete — 10/10" review complete
```

The `--model` flag is optional but recommended. It shows which AI model is behind each agent in the squad chat UI — part of the glass box transparency.

See [SQUAD-CHAT-PROTOCOL.md](SQUAD-CHAT-PROTOCOL.md) for full details.

---

## Example: Opus PM orchestrating Codex workers

1. **Human**: `sessions_spawn` Opus with task “Be PM for US-1600”.
2. **Opus (PM)**: Reads sprint tasks, assigns `US-1601` to itself (docs) and `US-1602` to Codex.
3. **Opus**: Runs `vk agent sub-agent 1` to show a worker is active.
4. **Opus**: Spawns the Codex worker with the managed-run handoff template.
5. **Codex**: Executes and returns its completion summary through the managed run.
6. **Opus**: Reviews, marks done, updates sprint recap comment.
7. **Opus**: Sets agent status back to idle once all workers complete (`vk agent idle`).

---

## Workflow Engine

For repeatable multi-agent pipelines, consider using the **Workflow Engine** instead of manual orchestration:

- Define pipelines as YAML with sequential, loop, gate, and parallel steps.
- Tool policies restrict what each agent role can do.
- Session isolation prevents context bleed between steps.
- Real-time dashboard shows active runs, success rates, and per-workflow health.

See [WORKFLOW-GUIDE.md](WORKFLOW-GUIDE.md) for full details and example workflows.

**When to use Workflows vs. Manual Orchestration:**

- **Workflows:** Repeatable pipelines you run more than once (feature dev, security audits, release processes).
- **Manual orchestration:** One-off sprint management, ad-hoc task assignment, exploratory work.

Following this SOP keeps human oversight minimal while preserving accountability.
