orchestration

What this skill does

# Orchestration Skill

> **Version:** 2.2.0
> **Framework:** Jerry Orchestration (ORCH)
> **Constitutional Compliance:** Jerry Constitution v1.0
> **Industry References:** [Anthropic Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills), [Microsoft AI Agent Patterns](https://learn.microsoft.com/en-us/azure/architecture/ai-ml/guide/ai-agent-design-patterns), [LangGraph](https://langchain-ai.github.io/langgraph/), [CrewAI Flows](https://docs.crewai.com/concepts/flows)

---

## Document Audience (Triple-Lens)

This SKILL.md serves multiple audiences:

| Level | Audience | Sections to Focus On |
|-------|----------|---------------------|
| **L0 (ELI5)** | Project stakeholders, new users | Purpose, When to Use, [Routing Disambiguation](#routing-disambiguation), Core Artifacts |
| **L1 (Engineer)** | Developers executing workflows | Quick Start, State Schema |
| **L2 (Architect)** | Workflow designers | Workflow Patterns, Adversarial Quality Mode, Constitutional Compliance |

---

## Purpose

The Orchestration skill provides a structured framework for managing **multi-agent workflows** that require:

- **Parallel Pipeline Execution** - Multiple agent pipelines running concurrently
- **Sync Barriers** - Cross-pollination points between pipelines
- **State Tracking** - Persistent execution state across sessions
- **Checkpointing** - Recovery points for long-running workflows
- **Progress Visibility** - Clear dashboards and metrics

### Key Capabilities

- **Cross-Pollinated Pipelines** - Bidirectional agent pipelines with barrier synchronization
- **State Management** - YAML-based machine-readable state (SSOT)
- **Checkpoint Recovery** - Resume workflows from any checkpoint
- **Execution Queues** - Priority-ordered agent execution with dependencies
- **Metrics Tracking** - Progress percentages, success rates, timing

---

## When to Use This Skill

Activate when:

- Coordinating **3+ agents** in a structured workflow
- Running **parallel pipelines** that need synchronization
- Workflow spans **multiple sessions** and needs state persistence
- Need **checkpointing** for long-running processes
- Require **visibility** into complex workflow progress

NEVER invoke this skill when:
- Task requires a single agent only -- Consequence: Orchestration overhead (barrier sync, quality gates, ORCHESTRATION.yaml state tracking) applied to single-step task wastes significant context budget on unnecessary coordination infrastructure; use `/problem-solving` instead
- Flow is simple and sequential without parallel pipelines -- Consequence: Three artifacts created (ORCHESTRATION_PLAN.md, ORCHESTRATION_WORKTRACKER.md, ORCHESTRATION.yaml) for a workflow that needs none; artifact overhead exceeds task complexity; use direct agent invocation
- No cross-session state persistence is needed -- Consequence: YAML state management and checkpointing infrastructure adds complexity without value for ephemeral single-session work

See [Routing Disambiguation](#routing-disambiguation) for full exclusion conditions with consequences.

---

## Core Artifacts

Every orchestrated workflow creates three artifacts:

| Artifact | Format | Purpose | Audience |
|----------|--------|---------|----------|
| `ORCHESTRATION_PLAN.md` | Markdown | Strategic context, workflow diagram | Humans |
| `ORCHESTRATION_WORKTRACKER.md` | Markdown | Tactical execution documentation | Humans |
| `ORCHESTRATION.yaml` | YAML | Machine-readable state (SSOT) | Claude/Automation |

**Location:** `projects/{project_id}/`

---

## Available Agents

| Agent | Role | Output |
|-------|------|--------|
| `orch-planner` | Creates orchestration plan with workflow diagram | `ORCHESTRATION_PLAN.md` |
| `orch-tracker` | Updates execution state after agent completion | `ORCHESTRATION.yaml`, `ORCHESTRATION_WORKTRACKER.md` |
| `orch-synthesizer` | Creates final workflow synthesis | `synthesis/workflow-synthesis.md` |

### Important: P-003 Compliance

These agents are **workers invoked by the main context**. They do NOT spawn other agents.

```
MAIN CONTEXT (Claude) ← Orchestrator
    │
    ├──► orch-planner      (creates plan)
    ├──► ps-d-001          (Phase work)
    ├──► nse-f-001         (Phase work)
    ├──► orch-tracker      (updates state)
    └──► orch-synthesizer  (final synthesis)

Each is a WORKER. None spawn other agents.
```

---

## Workflow Patterns

### Pattern 1: Cross-Pollinated Pipeline

Two or more pipelines running in parallel with synchronization barriers.

```
Pipeline A                    Pipeline B
    │                              │
    ▼                              ▼
┌─────────┐                  ┌─────────┐
│ Phase 1 │                  │ Phase 1 │
└────┬────┘                  └────┬────┘
     │                            │
     └──────────┬─────────────────┘
                ▼
        ╔═══════════════╗
        ║   BARRIER 1   ║  ← Cross-pollination
        ╚═══════════════╝
                │
     ┌──────────┴─────────────────┐
     │                            │
     ▼                            ▼
┌─────────┐                  ┌─────────┐
│ Phase 2 │                  │ Phase 2 │
└─────────┘                  └─────────┘
```

### Pattern 2: Sequential with Checkpoints

Single pipeline with checkpoints for recovery.

```
┌─────────┐     ┌─────────┐     ┌─────────┐
│ Phase 1 │────►│ Phase 2 │────►│ Phase 3 │
└─────────┘     └─────────┘     └─────────┘
     │               │               │
     ▼               ▼               ▼
   CP-001          CP-002          CP-003
```

### Pattern 3: Fan-Out/Fan-In

Parallel execution with synthesis.

```
              ┌─────────┐
              │  Start  │
              └────┬────┘
        ┌──────────┼──────────┐
        ▼          ▼          ▼
   ┌────────┐ ┌────────┐ ┌────────┐
   │Agent A │ │Agent B │ │Agent C │
   └────┬───┘ └────┬───┘ └────┬───┘
        └──────────┼──────────┘
                   ▼
            ┌────────────┐
            │ Synthesize │
            └────────────┘
```

---

## Quick Start

### Step 1: Create Orchestration Artifacts

```
# Copy templates to your project
cp skills/orchestration/templates/ORCHESTRATION_PLAN.template.md \
   projects/{PROJECT}/ORCHESTRATION_PLAN.md

cp skills/orchestration/templates/ORCHESTRATION_WORKTRACKER.template.md \
   projects/{PROJECT}/ORCHESTRATION_WORKTRACKER.md

cp skills/orchestration/templates/ORCHESTRATION.template.yaml \
   projects/{PROJECT}/ORCHESTRATION.yaml
```

Or use the `orch-planner` agent:

```
"Create an orchestration plan for a cross-pollinated pipeline
 using problem-solving and nasa-systems-engineering skills"
```

The planner will automatically:
1. Generate a workflow ID (or use your specified ID)
2. Resolve pipeline aliases from skill defaults
3. Create dynamic path structure

### Step 2: Update State After Each Agent

After each agent completes, update the state. Reference artifacts using the dynamic path scheme:

```
"Update ORCHESTRATION.yaml: agent-a-001 complete,
 artifact at orchestration/{workflow_id}/{pipeline_alias}/phase-1/research.md"
```

The orch-tracker agent will resolve placeholders to actual paths.

### Step 3: Track Progress

Check workflow status:

```
"Show orchestration status for PROJ-002"
```

---

## State Schema

### ORCHESTRATION.yaml Structure

```yaml
workflow:
  id: string                    # Unique workflow identifier
  name: string                  # Human-readable name
  project_id: string            # Project identifier
  status: ACTIVE|PAUSED|COMPLETE|FAILED

pipelines:
  {pipeline_id}:
    current_phase: number
    phases:
      - id: number
        name: string
        status: PENDING|IN_PROGRESS|COMPLETE|BLOCKED
        agents:
          - id: string
            status: PENDING|IN_PROGRESS|COMPLETE|FAILED
            artifact: string    # Path to output artifact

barriers:
  - id: string
    status: PENDING|COMPLETE
    artifacts:
      a_to_b: {path, status}   # {pipeline_a_alias}-to-{pipeline_b_alias}