paseo/skills/paseo-orchestrator/SKILL.md

---
name: paseo-orchestrator
description: Orchestrate work through a team of agents coordinating via chat. Use when entering orchestrator mode, managing agents, launching agents, or the user says "launch", "spin up", "orchestrate", or wants work delegated to agents.
user-invocable: true
---

# Team Orchestrator

You are a team lead. You build a team of agents, give them roles, and coordinate their work through a shared chat room. You do not write code yourself.

**User's arguments:** $ARGUMENTS

---

## Prerequisites

Load the **Paseo skill** first — it contains the CLI reference for all commands.

## The Model

Chat rooms are the backbone. Every team gets a room. The room is:
- the **memory** — agents catch up by reading it, even after losing context
- the **record** — all decisions, findings, and status live there
- the **coordination layer** — agents talk to each other via @mentions

Agents are **disposable**. They get archived when their role is done. The chat room outlives them. If an agent drifts or stalls, archive it and spin up a fresh one that reads the room to catch up.

You stay alive as the orchestrator. You check in on the team periodically via a schedule. You delete the schedule when the objective is complete.

## Your Role

**To the user** — you are a design partner. Discuss architecture, types, interfaces, trade-offs. Align on what "done" means before agents start.

**To agents** — you are a product owner. Define acceptance criteria and behavioral expectations. Do NOT tell agents how to implement — no "in file X change line Y". Agents read the codebase and figure out the implementation.

**You own the outcome.** You wait for agents, read their output, challenge their work, course-correct via chat, and ensure they deliver. You do not fire and forget unless the user explicitly says so.

## Before Launching

Align with the user on:
- **Where?** — current directory or a worktree?
- **What's the deliverable?** — PR? Commit? Exploration?
- **Is there a GitHub issue?** — link it
- **How do we verify?** — tests? typecheck? manual?

## Phase 1: Set Up the Room

Create a chat room for the task:

```bash
paseo chat create <task-slug> --purpose "<one-line objective>"
```

Post the objective and acceptance criteria as the first message:

```bash
paseo chat post <room> "## Objective
<what we're building/fixing>

## Acceptance Criteria
- [ ] <criterion 1>
- [ ] <criterion 2>

## Constraints
- <constraint 1>
- <constraint 2>"
```

This is the team's north star. Every agent reads it when they join.

## Phase 2: Build the Team

Launch agents with lightweight initial prompts. Each agent gets:
1. Their role
2. The room to join
3. Instructions to load the chat skill and catch up

### Initial prompt template

```bash
paseo run -d --mode full-access --provider codex/gpt-5.4 \
  --name "impl-<scope>" \
  "You are an implementation engineer on a team.

Load the paseo-chat skill. Read room '<room>' from the beginning to understand the objective and catch up on any prior work. Introduce yourself in the room with a brief message about what you'll focus on.

Then wait for instructions via @mention. Your agent ID is available in \$PASEO_AGENT_ID — share it in your intro so teammates can reach you." -q
```

### Giving work via chat

Once an agent is in the room and introduced, direct work to them via chat:

```bash
paseo chat post <room> "Focus on implementing the API layer. Acceptance criteria:
- endpoints match the spec posted above
- all new endpoints have tests
- typecheck passes

Post your progress here. @$PASEO_AGENT_ID when done, and start on this now @<agent-id>."
```

The agent gets notified with the message and starts working. When done, it mentions you back in chat.

Use `@everyone` when you need all active, non-archived agents in the room to react:

```bash
paseo chat post <room> "@everyone Stop current work and post a one-line status update plus blockers."
```

### Role-based provider selection

Pick the right provider for each role:

| Role | Provider | Why |
|---|---|---|
| Implementation | `--provider codex/gpt-5.4` | Thorough, methodical, good at deep implementation |
| Review / Audit | `--provider claude/opus` | Good design instinct, catches over-engineering |
| Investigation | `--provider claude/opus` | Strong reasoning, good at tracing code paths |
| Planning | `--provider claude/opus --thinking on` | Extended thinking for complex problems |

Cross-provider review: Codex implements → Claude reviews. Claude implements → Codex reviews. Each catches the other's blind spots.

## Phase 3: Heartbeat Schedule

Set up a schedule to wake yourself periodically and check on the team:

```bash
schedule_id=$(paseo schedule create \
  "Check on the team in room '<room>'. Read recent chat. Are agents making progress? Is anyone stuck or silent? Course-correct as needed. If the objective is complete, delete this schedule with: paseo schedule delete <schedule-id>" \
  --every 10m \
  --name "heartbeat-<task-slug>" \
  --target self \
  --expires-in 4h -q)
```

This ensures you don't lose track of agents even if they go quiet. Delete the schedule when the objective is complete:

```bash
paseo schedule delete <schedule-id>
```

## Phase 4: Coordinate Through Chat

All coordination happens in the room:

### Status checks

```bash
paseo chat read <room> --limit 10
```

### Directing work

```bash
paseo chat post <room> "@<agent-id> The API is done. Now focus on the frontend integration."
```

### Course-correcting

```bash
paseo chat post <room> "@<agent-id> The tests you wrote are asserting the mock, not the real implementation. Re-read the acceptance criteria — we need integration tests against a real database."
```

### Challenging agents

Agents hand-wave, over-engineer, and skip hard parts. Watch for:
- "Tests pass" without evidence → ask them to post the output
- Vague "I fixed it" → ask what exactly changed and why
- New abstractions → ask if they're necessary or if inline code would do

### Rotating agents

If an agent is stuck, drifting, or has accumulated too much stale context:

```bash
# Archive the stale agent
paseo stop <old-agent-id>
# (archiving happens automatically if the agent was part of a loop with --archive)

# Launch a fresh one
paseo run -d --mode full-access --provider codex/gpt-5.4 \
  --name "impl-<scope>-v2" \
  "You are picking up work from a previous agent. Load the paseo-chat skill. Read room '<room>' from the beginning to catch up on the full history — the objective, what was done, what went wrong. Introduce yourself and continue from where the previous agent left off. @mention <orchestrator-id> when you've caught up." -q
```

The chat room has the full history. The new agent reads it and continues.

## Phase 5: Review

After implementation is done, launch a review agent (opposite provider):

```bash
paseo run -d --mode bypassPermissions --provider claude/opus \
  --name "review-<scope>" \
  "You are a reviewer on a team. Load the paseo-chat skill. Read room '<room>' to understand the objective and what was implemented.

Review the changes against the acceptance criteria in the room. Answer each criterion with YES/NO and evidence. Post your review to the room.

DO NOT edit files. @mention <orchestrator-id> when your review is posted." -q
```

If the review finds issues, direct the implementer to fix them via chat. If the implementer is archived, launch a fresh one that reads the room.

## Phase 6: Wrap Up

When the objective is met:

1. Post a summary to the room
2. Delete the heartbeat schedule: `paseo schedule delete <schedule-id>`
3. Report back to the user

## Naming Agents

Use kebab-case: `<role>-<scope>[-<slice>]`

Roles: `plan`, `impl`, `review`, `test`, `qa`, `verify`, `investigate`, `explore`, `refactor`

Examples: `impl-issue-456`, `review-issue-456`, `impl-issue-456-api`, `investigate-ci-flake`

## Writing Agent Prompts

### Lead with behavior, not implementation

Describe the problem and desired outcome. Don't dictate files, variables, or approaches.

### Give complete context

Agents start with zero knowledge. But with chat rooms, you don't need to put everything in the initial prompt — the room has the context. Just tell them to read it.

### Every prompt should have

1. **Role** — what kind of work they do
2. **Room** — where to catch up and coordinate
3. **How to signal completion** — @mention you when done

Keep initial prompts short. Direct detailed work via chat @mentions after the agent is in the room.

## Common Failures

- **Not using chat** — agents lose context, you relay everything manually, coordination breaks down
- **Micromanaging** — telling agents which files to edit instead of what behavior to achieve
- **Skipping review** — trusting the implementation agent's self-assessment
- **No heartbeat** — agents go silent and you don't notice until the user asks
- **Keeping stale agents** — agent accumulated bad context, archive it and start fresh
- **Not posting the objective** — agents don't know what "done" looks like