dynamic-workflows

name	dynamic-workflows
description	Orchestrate dozens-to-hundreds of subagents from a script Claude writes (Claude Code Dynamic Workflows, trigger `ultracode`). Use when a task exceeds a single agent's context or needs more than ~4 concurrent workers — large audits, migrations, multi-source research, fan-out reviews. Distinct from Agent Teams (synchronous, ≤4 workers) and ralph-run (sequential single-context loop).
context	fork

Dynamic Workflows — orchestration multi-agents scriptée

Dynamic Workflows (Claude Code 2.1.154+, mot-clé déclencheur ultracode) laissent Claude écrire un script JavaScript qui orchestre des sous-agents de façon déterministe (boucles, conditions, fan-out). Le script tourne en arrière-plan ; on suit l'exécution via /workflows.

⚠️ Opt-in coûteux : un workflow peut lancer des dizaines à centaines de sous-agents. Ne l'utiliser que sur demande explicite (mot « ultracode », « use a workflow », « fan out agents ») ou quand le palier de complexité ci-dessous est franchi.

Quand l'utiliser — les 3 paliers d'orchestration

Palier	Outil	Concurrence	Quand
1	Sub-agent simple (Task/Agent)	1	Une investigation isolée, garder le contexte principal propre
2	Agent Teams (/team:audit, /team:sprint, /team:security)	1 leader + ~3 workers	Travail parallèle borné, synchrone, qui tient en un round
3	Dynamic Workflows (ultracode)	jusqu'à ~1000 sous-agents (cap concurrent ~16)	La tâche dépasse le contexte d'un agent OU exige >4 workers OU une boucle/pipeline déterministe

Heuristique break-even : dès que tu écrirais « lance N agents, puis pour chacun fais X, puis agrège » — c'est un workflow. Si N ≤ 4 et une seule passe suffit, reste sur Agent Teams.

Patterns composables (prompts minimaux)

• Fan-out & synthesize — N lecteurs en parallèle sur des sous-systèmes disjoints → un agent synthétise. (audit, cartographie de code)
• Adversarial verification — chaque finding passé à ≥1 sceptique chargé de le réfuter ; ne garder que les CONFIRMED. Le pattern qualité le plus important pour la génération autonome.
• Generate-and-filter — générer large (idées, candidats), puis filtrer par un juge.
• Classify-and-act — un classifieur route chaque item vers le traitement adapté.
• Pipeline — chaque item traverse toutes les étapes sans barrière (latence = pire chaîne, pas somme des étapes). C'est le défaut multi-étapes.
• Loop-until-done / loop-until-dry — relancer des chercheurs jusqu'à K rounds sans nouveauté (découverte de taille inconnue : bugs, edge cases).

Squelette type (review → verify)

const results = await pipeline(
  DIMENSIONS,
  d => agent(d.prompt, { phase: 'Review', schema: FINDINGS }),
  review => parallel(review.findings.map(f => () =>
    agent(`Adversarially verify: ${f.title}. Default refuted=true if unsure.`,
          { phase: 'Verify', schema: VERDICT }).then(v => ({ ...f, verdict: v }))))
)
const confirmed = results.flat().filter(Boolean).filter(f => f.verdict?.isReal)

pipeline() par défaut (pas de barrière) ; parallel() seulement quand l'étape N a besoin de TOUS les résultats de N-1 (dédup, early-exit, comparaison croisée). schema force une sortie structurée validée. Pour des éditions concurrentes de fichiers, isolation: 'worktree'.

Monitoring

• /workflows : progression live (phases, agents, tokens).
• Le script revient avec un résultat agrégé ; lire ce résultat, décider la suite (souvent plusieurs workflows en séquence : comprendre → concevoir → implémenter → revoir).

À ne pas confondre

• ralph-run (/common:ralph-run) : boucle séquentielle mono-contexte jusqu'à une DoD — pas de parallélisme. Pour une tâche qui dépasse ce modèle, basculer sur un Dynamic Workflow.
• /effort ultracode : palier d'effort CLI (débit code max sur Opus 4.8) — orthogonal au déclencheur ultracode des workflows, même si souvent utilisés ensemble.

Réutilisation & garde-fous (v2.1.166+)

• Essayer d'abord le workflow intégré /deep-research (recherche multi-sources vérifiée) avant d'en écrire un : beaucoup de besoins « fan-out web + synthèse » y sont déjà couverts.
• Sauvegarder un run éprouvé : dans /workflows, presser s enregistre le script comme commande réutilisable — projet (.claude/workflows/) ou perso (~/.claude/workflows/). Un paramètre args permet de le rejouer avec une entrée différente (question de recherche, chemin cible…).
• ⚠️ Sécurité — acceptEdits implicite : les sous-agents lancés par un workflow tournent toujours en mode acceptEdits et héritent de ton allowlist, quel que soit le mode de la session (y compris plan ou default). Les éditions de fichiers sont auto-approuvées. Ne fan-out des agents qui écrivent qu'en zone maîtrisée (worktree isolé, cf. règle 11 sur l'hygiène des permissions).
• Coupe-circuit & coût : disableWorkflows (settings.json) ou CLAUDE_CODE_DISABLE_WORKFLOWS=1 désactivent la fonctionnalité ; /workflows affiche la consommation de tokens en direct (un workflow coûte significativement plus qu'un contexte unique — piloter avec un budget explicite).

Référence : Claude Code Workflows · voir aussi @.claude/commands/common/sub-agents-patterns.md (tableau comparatif des orchestrations).