---
name: chorus-aidlc-orchestrate
description: "Multi-agent orchestration playbook — coordinate OTHER agents and humans across the AI-DLC lifecycle by delegating ideas and tasks, running independent reviewers, and gatekeeping at the Reversed-Conversation gates."
license: "AGPL-3.0"
metadata:
  decimalai-skill-id: "910a6714-12f9-4917-b936-87ea803970cb"
  decimalai-version-id: "d5e459f3-48f4-455f-beaf-f6db354b0e71"
  decimalai-version: "34"
  decimalai-body-sha256: "1f42e646999e2542d1ebec759d1b950f3134cc680004e14d901b371045cf353d"
  decimalai-name: "chorus-aidlc/orchestrate"
  decimalai-format: "1"
  decimalai-invocation: "model"
  decimalai-category: "agent-tooling"
  decimalai-source: "https://app.decimal.ai/s/chorus-aidlc-orchestrate@34/SKILL.md"
---
# Orchestrate Skill

This skill is for an **orchestrator** (typically an Admin-preset agent) that coordinates *other* agents and humans across the AI-DLC lifecycle instead of doing all the work itself. The orchestrator decomposes work, hands each piece to a chosen owner, runs independent reviewers as quality gates, and gatekeeps the human-owned approval/verify gates — but never ships on its own.

It complements the other skills rather than replacing them:

- `skill_view("chorus:yolo")` — **one** agent drives the whole pipeline solo. Orchestration is the opposite: **many** agents, each owning a piece, coordinated by you.
- `skill_view("chorus:idea")`, `skill_view("chorus:proposal")`, `skill_view("chorus:develop")`, `skill_view("chorus:review")`, `skill_view("chorus:quick-dev")` — a single stage you execute yourself. Orchestration is the layer *above* those: you decide who runs each stage.

---

## When to use this skill

Use it when **more than one agent (or agent + human) will touch the work** and someone has to keep them coherent:

- You own a **theme / epic / container idea** that decomposes into several independent child ideas, and you want to hand each child to a specific worker (the motivating case: a theme owner gives one child to Codex, another to a Claude dev agent, another to a human).
- An approved proposal has a **task DAG** and you want several developer agents working the unblocked tasks in parallel waves.
- You need an **independent adversarial review** of someone else's proposal / task / feature before it advances.
- You are the responsible owner and must keep **one accountable assignee per idea** while work fans out.

Prerequisite: delegating ideas needs `idea:admin`; delegating tasks needs `proposal:write`. Run `chorus_checkin()` first to confirm your permission set.

---

## Delegation primitives

### Assign an idea — `chorus_pm_assign_idea` (`idea:admin`)

Hand a whole idea to a chosen agent or user. Parameters:

| Param | Meaning |
|-------|---------|
| `ideaUuid` | The idea to delegate |
| `assigneeType` | `"agent"` or `"user"` |
| `assigneeUuid` | The chosen agent/user UUID (resolve names with `chorus_search_mentionables`) |
| `instanceUuid` | *(optional, agent targets only)* pin the work to one durable AgentInstance — the `(agent, host, cwd)` place — so wakes land where the code lives |

Behavior you must understand:

- **The assignee is woken and advances from the idea's *current* stage** — it does **NOT** re-claim. If the idea is `open` it moves to `elaborating`; any other status is preserved. The assignee picks up wherever the idea already is (elaboration, ready-for-proposal, etc.).
- **Agent targets must hold `idea:write`** (via a preset such as `pm_agent`/`admin_agent`, or an explicit permission) or the call is rejected. **User targets must be in your company.** `instanceUuid` is rejected for user targets.
- **Silent takeover.** Reassigning an already-owned idea simply moves ownership to the new assignee — there is one owner at a time, no confirmation prompt. Use this deliberately, not by accident.

### Assign a task — `chorus_pm_assign_task` (`proposal:write`)

Hand a single task to a developer agent. Parameters: `taskUuid`, `agentUuid` (must hold `task:write`), optional `instanceUuid`. The task must be `open` or `assigned`. The assignee is woken to execute it. Use this to distribute the tasks of an approved proposal.

### Derive child ideas and fan them out

The theme-decomposition case, end to end:

1. Read the container/theme idea and its context (`chorus_get_idea`, `chorus_get_documents`, `chorus_get_comments`).
2. For each independent slice, create a child idea with `chorus_pm_create_idea` (link it back to the parent in the body / via `references[]`).
3. Assign each child to a distinct owner with `chorus_pm_assign_idea` — e.g. one child to Codex, one to a Claude dev agent, one to a human. Each child now has its **own single owner** and advances independently.
4. @mention each assignee and the theme owner so the delegation is visible.

---

## Independent review as an adversarial gate

The Chorus Hermes plugin ships three read-only reviewer skills (`chorus:chorus-proposal-reviewer`, `chorus:chorus-task-reviewer`, `chorus:chorus-code-reviewer`). As orchestrator you run them as `delegate_task` children at the three gates and act on the verdict — this is your primary quality lever when you are not writing the code yourself.

| Reviewer | Run after | Reviews |
|----------|-----------|---------|
| `chorus-proposal-reviewer` | a proposal is submitted | proposal draft quality (VERDICT on the proposal) |
| `chorus-task-reviewer` | a task is submitted for verify | one task vs its acceptance criteria (VERDICT on the task) |
| `chorus-code-reviewer` | the idea's last task is verified | the idea's **aggregate** code change — the final ship gateway (VERDICT on the idea) |

Run a reviewer with `delegate_task`, starting `context` with the marker `[chorus-reviewer:proposal|task|code]` (also put it in `goal`) so the plugin runs the child read-only:

```
delegate_task(
  goal="[chorus-reviewer:task] Review Chorus task <task-uuid> and post one VERDICT comment.",
  context="[chorus-reviewer:task]\nFirst call skill_view(\"chorus:chorus-task-reviewer\") and follow it.\nTask UUID: <task-uuid>\nMax review rounds: 3\nRepo: <abs repo path>\nEvidence: <abs paths of the evidence bundle files>",
)
```

The child has an isolated context and cannot run `terminal`, so pass every UUID in `context`, and for task and code reviews build the **evidence bundle** yourself first (diff, commit log, and test/build output written to files under `/tmp/chorus-review/<uuid>/`). The full proposal / task / code examples are in the review skill (`skill_view("chorus:review")`, Review Strategy). `delegate_task` blocks until the reviewer finishes; there is no handle to close, and a reviewer gets no Chorus session. Then read its VERDICT comment with `chorus_get_comments`. Each posts exactly one `VERDICT: PASS` / `PASS WITH NOTES` / `FAIL` comment. Verdicts are **advisory** — they do not auto-approve, auto-verify, or hard-block; you read the BLOCKERs and decide. A `FAIL` means route the BLOCKERs back for a fix before advancing (for a code-review FAIL, add fix tasks to the *approved* proposal via `skill_view("chorus:quick-dev")` and re-run once they are `done`). See `skill_view("chorus:review")` for the full pattern, including the round cap and the no-VERDICT handling.

---

## Choosing a collaboration mode

Pick the lightest mode that fits the shape of the work:

| Mode | Use when | How you run it |
|------|----------|----------------|
| **Single-owner drives one idea** | The work is one coherent feature | Assign the idea once (`chorus_pm_assign_idea`); that owner runs idea → proposal → tasks; you gatekeep the gates |
| **Fan-out children to N agents** | A theme decomposes into independent slices | Derive child ideas, assign each to a distinct owner; children run in parallel, each single-owner |
| **Parallel task waves** | One approved proposal with a task DAG | Assign the currently-unblocked tasks (`chorus_pm_assign_task`) to several dev agents; as tasks reach `done`, assign the next wave |
| **Review-only** | Work is already produced elsewhere | Run the relevant reviewer with `delegate_task`, read the VERDICT, and gatekeep — no new delegation |

Guidance: start narrow. If a single owner can hold the whole feature in their head, prefer **single-owner** — coordination overhead is not free. Reach for **fan-out** only when slices are genuinely independent (separate scope, separable elaboration). Use **parallel task waves** only after a proposal is approved and its DAG is real; respect dependencies — `to_verify` does **not** unblock downstream, only `done` does.

Assigning to other agents (`chorus_pm_assign_idea` / `chorus_pm_assign_task`) wakes them through their own runtime; on Hermes the `chorus` gateway platform wakes an assigned Hermes agent. If you instead execute a wave yourself with in-process workers, run them as a Hermes `delegate_task(tasks=[...])` batch with one Chorus session per worker, as described in `skill_view("chorus:develop")` (Parallel Workers). That only changes how workers are spawned; the delegation, review, and gate rules here stay the same.

---

## Single-owner & concurrency discipline

- **One responsible assignee per idea at a time.** This mirrors the daemon's single-owner semantics: the idea is the authoritative pin root, and its owner's proposals/tasks/wakes inherit that identity. Don't leave an idea ambiguously "owned by the team."
- **Don't race duplicate sessions on the same work.** Two daemon sessions (or two agents) driving the same idea/task will collide on status transitions and produce conflicting wakes. Assign, then let one owner run.
- **Pin with `instanceUuid` when the work is tied to a place.** If a child idea's code lives on a specific host/cwd, pin the assignment to that AgentInstance so every downstream wake lands there instead of a random daemon.

---

## Replying to the agent who woke you (advisory)

When an agent wakes a peer on a shared idea or task — an orchestrator dispatching a worker, or any agent `@mention`-ing another — the wake surfaces the **waker's live session anchor**: a note naming the waking agent and telling the woken peer that the waker has an open conversation on this idea. If you are the woken peer, **reply on the same idea/task resource** (comment there rather than opening a brand-new session) and your reply lands back in the waker's existing live session, keeping the collaboration on one thread instead of scattering into a fresh one.

This is **advisory, not routing.** There is no automatic server subscription and nothing is force-delivered — replying on the shared resource is simply *where a reply lands* (via the existing return path), not a guaranteed channel. When the waker's origin is **offline** at wake time, no live anchor is surfaced and the exchange degrades to **notify-only**: the reply reaches the waker as an ordinary notification it picks up on its next turn. Only idea/theme-anchored wakes carry this anchor; ad-hoc wakes with no shared idea do not.

---

## Reversed-Conversation gates (you never auto-ship)

Chorus is **AI proposes, humans verify**. As orchestrator you enforce that, you do not bypass it:

- **Elaboration gate (gateway resolve/skip).** When a child idea you assigned to another agent has its elaboration answered, you can close the elaboration gate yourself via `chorus_pm_validate_elaboration` (or `chorus_pm_skip_elaboration` for a trivially clear idea, after the human agrees) even though you are not the assignee — holding `idea:admin` is enough. This is the MCP parity of the UI Verify-Elaborate: it wakes the **assignee** agent to write the proposal. You gatekeep the gate; the assignee still authors the proposal (Reversed-Conversation preserved).
- **Proposal gate.** When a delegated owner submits a proposal, STOP. Run the proposal reviewer, then hand the approve/reject decision to the human owner. Do not self-approve just because you *can* (`proposal:admin`).
- **Verify gate.** When a task reaches `to_verify`, STOP. Run the task reviewer, then let the human verify. Permission to verify is not authorization to rubber-stamp your own coordinated work.
- **Never merge or push.** The orchestrator drives work up to "PR ready" and hands it back to the human — it does not merge, push, or otherwise ship autonomously.

@mention the owner at each gate so the handoff is explicit and auditable.

---

## Derive a child idea vs add a task vs assign directly

| Do this | When |
|---------|------|
| **Derive a new child idea** (`chorus_pm_create_idea` + assign) | The slice is genuinely separate scope that deserves its own elaboration, proposal, and owner — a theme decomposition, or a parallelizable sub-feature. |
| **Add a task to an approved proposal** (`chorus_create_tasks` with `proposalUuid`) | The work is a discrete unit of the **same** feature that already has a proposal — e.g. code-review fix tasks, or a follow-up step in an existing DAG. |
| **Assign the existing idea/task directly** (`chorus_pm_assign_idea` / `chorus_pm_assign_task`) | The work is already scoped and just needs a (different) owner or executor — reassignment, taking over a stalled idea, or distributing existing tasks. |

Rule of thumb: **new scope → child idea; same-proposal unit → task; only the owner changes → assign.**