/workflow-orchestration

name: workflow-orchestration
description: "Написание и запуск Claude Code dynamic workflows (JS-оркестратор субагентов). Use when user просит workflow своими словами или включает ultracode, нужен fan-out на десятки-сотни агентов, codebase-wide аудит/миграция, cross-checked research, competency-review, batch-обработка списка элементов через стадии. Покрывает: примитивы phase/agent/parallel/pipeline/workflow, pipeline vs parallel, schema, budget, resume, quality-паттерны (adversarial verify, judge panel, loop-until-dry), и наши добавки к платформе (accounting, bounded retry, error policy, .runs observability, eval-harness, billing-дисциплина). Триггеры: явная просьба «use/run a workflow» или «запусти воркфлоу», оркестратор, fan-out, ultracode, deep-research, 1000 агентов, скрипт агентов. Do NOT use to design the agent/Generator-Evaluator architecture itself (use harness-design) or for a single one-shot subagent/review where no deterministic multi-stage script is needed; this writes the JS orchestrator, it is not for ad-hoc one-off agent calls."
metadata:
  version: "1.0.0"
  source: "code.claude.com/docs/en/workflows + Workflow tool spec + deksden lessons (4 оркестратора)"
  created: "2026-05-30"

Workflow Orchestration

Claude Code **dynamic workflows** - JS-скрипт, который оркестрирует недетерминированных субагентов. Скрипт = «рельсы» (loop, branching, промежуточные результаты в переменных); агенты = «поезда». Надёжность даёт код вокруг агентов, а не агенты сами. Доступность зависит от плана, текущей конфигурации и runtime: на Pro включи Dynamic workflows в `/config`; перед запуском проверь доступность в текущей сессии.

Этот skill - наш свод поверх официального API: что платформа уже даёт, и что мы добавляем сами для задач, где нужна доказуемая полнота batch-результата.

**Текущая опора (проверено 2026-09-06):** [официальная документация](https://code.claude.com/docs/en/workflows), [официальный разбор](https://claude.com/blog/a-harness-for-every-task-dynamic-workflows-in-claude-code) и [официальный cookbook](https://platform.claude.com/cookbook/claude-agent-sdk-08-dynamic-workflows). Дата обновления docs/cookbook на странице не указана; blog датирован 2026-06-02.

Когда workflow, а когда нет

| | Subagent | Skill | Agent Team | **Workflow** | |---|---|---|---|---| | Что | воркер, спавнится разово | инструкции для Claude | сварм, коллаборация | **скрипт, исполняет runtime** | | Кто решает что дальше | Claude, ход за ходом | Claude по промпту | Claude + обмен между агентами | **скрипт (детерминизм)** | | Где промежуточные результаты | контекст Claude | контекст Claude | контекст Claude | **переменные скрипта** | | Масштаб | пара задач/ход | как subagent | х2-х10 агентов | **десятки-сотни, лимит 1000** | | Прерывание | рестарт хода | рестарт хода | рестарт хода | **resumable в той же сессии** |

**Бери workflow когда:** задаче нужно больше агентов, чем удержит один контекст; нужна повторяемая оркестрация как читаемый скрипт; нужен repeatable quality-паттерн (агенты adversarially проверяют находки друг друга перед тем как их вернуть).

**Практический тест:** бери workflow, когда работа больше контекста одного агента или один и тот же шаг надо повторить по множеству независимых элементов, а orchestration полезно сохранить и повторить. Для 1--3 одноразовых делегаций бери subagent. Это не правило «все три условия», а выбор масштаба и повторяемости.

**НЕ бери workflow когда:** хватает 1-3 субагентов на ход (бери subagent); задача - следование инструкции (skill); нужен интерактивный sign-off в середине (кроме permission prompts, run не принимает mid-run input; каждый этап с sign-off = свой workflow).

**Opt-in обязателен.** Workflow tool вызывается, когда user прямо просит workflow своими словами, использует keyword `ultracode`, или в сессии включён Ultracode. После v2.1.160 literal `workflow` больше не является trigger keyword (до этой версии он был им); обычная явная просьба работает в обеих версиях. Иначе — обычные субагенты. Это и наше правило, и поведение платформы.

Анатомия (точный API)

export const meta = {                       // ПЕРВЫМ. Pure literal — без переменных,
  name: 'my-flow',                          // вызовов функций, спредов, интерполяции.
  description: 'one-liner для диалога approve',
  phases: [{ title: 'Scan', detail: '...' }, { title: 'Fix' }],  // = phase() вызовам
  whenToUse: '...',                         // опц., в списке /workflows
}
// тело — обычный async JS + примитивы:
phase('Scan')                               // группа прогресса; agent() ниже в неё
const r = await agent('prompt', {schema: S, label, phase, model, isolation, agentType})
const all = await parallel(items.map(x => () => agent(...)))   // БАРЬЕР, ждёт всех
const out = await pipeline(items, stageA, stageB)              // fan-out, БЕЗ барьера
const sub = await workflow('deep-research', {question})        // суб-воркфлоу, вложен. 1
log('сообщение пользователю')

• **`agent(prompt, opts?)`** → без `schema` возвращает финальный текст (string); со `schema`

(JSON Schema) форсит StructuredOutput tool и возвращает **валидированный объект** (модель ретраит при mismatch); `null`, если агент остановлен в ходе run или случилась невосстановимая API-ошибка. opts: `label`, `phase` (явная группа - юзать внутри parallel/pipeline, не глобальный phase()), `model` (опускать - наследует модель сессии; ставить только когда уверен), `isolation:'worktree'` (дорого - только когда агенты параллельно мутируют файлы), `agentType` ('Explore', 'code-reviewer'...).

• **`parallel(thunks)`** - массив **функций** `()=>Promise`, барьер. Результат агента может

быть `null`. `.filter(Boolean)` допустим только для представления уже учтённых результатов; для явного batch сначала свяжи каждый `null` с исходным item и верни его как pending.

• **`pipeline(items, ...stages)`** - каждый item независимо через все стадии, БЕЗ барьера

между ними (item 2 на стадии 3, item 4 ещё на стадии 1). Если