Orchestration

Complex work rarely fits into a single task for a single agent. Orchestration lets you decompose large initiatives into coordinated work items that are dispatched in the right order, run in parallel where possible, and roll up into a unified result when complete.

The supervisor pattern

Large pieces of work — an epic that spans multiple repositories, a feature that requires database changes, backend API work, and frontend updates — are handled by a supervisor agent. The supervisor does not write code. Instead, it analyses the epic description and creates child work items, each assigned to the appropriate role and target repository.

How it works

1. Supervisor dispatched — the poller finds an epic work item assigned to the SUPERVISOR role and dispatches it like any other work item.
2. Supervisor analyses the epic — the supervisor agent reads the epic description and determines what child tasks are needed, which roles should handle them, which repositories they target, and what dependencies exist between them.
3. Supervisor creates children — using PPM tools, the supervisor creates child work items with appropriate roles, target repositories, and descriptions. It also creates dependency links between children (e.g. the backend task depends on the database migration finishing first).
4. Supervisor exits — the supervisor's own run completes. It does not wait for children to finish — this is a fire-and-forget pattern.
5. Children enter the queue — the newly created work items become eligible for dispatch through the normal scheduling process, subject to their dependencies.

The supervisor has access to PPM authoring tools (creating work items, setting dependencies, logging activities) but does not have code editing tools. Its job is decomposition and coordination, not implementation.

tip

The supervisor role can use a different model than implementation agents. A model with strong reasoning capabilities (such as Opus) can be used for work decomposition, while faster or cheaper models handle the implementation tasks.

DAG-aware parallel dispatch

Work items have dependencies — a backend API change might depend on a database migration completing first. The dispatch scheduler respects these dependencies using a DAG (directed acyclic graph) model to determine which items are ready to run.

How scheduling works

The scheduler evaluates the work item queue on each cycle:

Three conditions must be met before a work item is dispatched:

Condition	What it checks
Dependencies resolved	All predecessor work items have reached a completed status
Concurrent slots	The number of currently running agents is below the configured maximum
Same-repo serialization	No other agent run is currently active for the same target repository

Items that pass all three checks are dispatched in priority order. Items that fail any check are skipped and re-evaluated on the next cycle.

Same-repo serialization

Only one agent can work on a given repository at a time. This prevents merge conflicts and race conditions that would arise from multiple agents editing the same codebase simultaneously.

If two work items target the same repository and have no dependency between them, they run sequentially — the scheduler dispatches one, and the other waits until the first completes.

important

Same-repo serialization applies to the target repository, not the work item's parent epic. Two unrelated work items targeting the same repository will still be serialized, even if they belong to different epics.

Parallel execution across repositories

Work items targeting different repositories can run in parallel, up to the configured concurrency limit. For a multi-repo epic, this means independent tasks (such as documentation and backend work in separate repositories) proceed simultaneously while dependent tasks wait their turn.

Epic auto-completion

When a supervisor creates an epic with multiple child work items, the system automatically tracks whether all children have completed. You do not need to manually close the epic.

The check runs periodically:

1. Find epics with status IN_PROGRESS where the supervisor role has completed
2. Check whether all child work items have reached a completed status
3. When all children are done, create an aggregation task

The aggregation task is a final supervisor dispatch that reviews the results of all child work items — their merge request URLs, summaries, and eval scores. It produces a roll-up activity on the epic summarising what was accomplished across all children, then marks the epic as DONE.

Cross-repo coordination

When an epic spans multiple repositories, the child work items need to be consistent with each other — a database column name must match between the migration and the backend code that references it, an API response shape must match between the backend and the frontend that consumes it.

The supervisor handles this by writing explicit cross-references into each child work item's description:

• A backend work item might reference: "The DB migration in WI-XXXX adds column new_field — your handler must use this exact column name"
• A frontend work item might reference: "The API endpoint created in WI-YYYY returns {field: value} — your component must consume this response shape"

This makes dependencies and contracts visible in the work item itself, so the implementation agent has the context it needs without querying other repositories or work items.

Sequencing for consistency

The supervisor uses PPM dependency links to enforce correct ordering:

Dependency type	Meaning	Typical use
FS	Finish-to-start: B cannot start until A finishes	DB migration before backend code
SS	Start-to-start: B cannot start until A starts	Parallel tasks that should begin together
FF	Finish-to-finish: B cannot finish until A finishes	Tasks that must complete in sync
SF	Start-to-finish: B cannot finish until A starts	Handoff patterns

The most common pattern is finish-to-start (FS): the database migration must complete before the backend work begins, and the backend work must complete before the frontend update starts. This ensures each layer builds on verified, merged changes from the previous layer.

How orchestration connects to other modules

• PPM — work item dependencies, status transitions, and activity records are all PPM concepts. Orchestration builds on PPM's dependency model to schedule work. The supervisor creates work items and dependencies using PPM tools.
• FND — concurrency control is managed through FND's job system. The concurrent slot limit is the max_processes value on the FND worker manager record. See the Foundation job scheduling documentation for details.
• Agent runs — each dispatched child creates an agent run. The aggregation task reviews agent run data (MR URLs, eval scores, cost) to produce the epic summary. See Agent Runs for details.
• Human-in-the-loop — a work item in NEEDS_APPROVAL status blocks its dependents from starting. This means a high-risk database migration that requires approval will hold up the backend work that depends on it until a human approves. See Human-in-the-Loop for details.
• Guardrails — each child work item runs through its own guardrail checks independently. The supervisor's aggregation task can review guardrail results across all children. See Guardrails for details.