Lesson 1: From Conversation to Workflow: Why Orchestration Exists

Learning goals:

• Understand the fundamental difference between a single conversation and a workflow
• Recognize the traits of a task that fits a workflow
• Grasp the core value of workflow orchestration

Prerequisites: You've used Claude Code or a similar AI tool | Next: Lesson 2 >>

Your Agent Hits a Wall

You ask Claude Code to refactor a large codebase: "Split this 5,000-line monolith into microservices."

Claude gets to work. It reads files, identifies module boundaries, pulls out dependencies, and then, somewhere around file 47, the context window fills up. It forgets what it did earlier, starts over, and gets stuck in a loop.¹

Or you ask it to "review every open PR and write this week's release notes." Claude can only handle one PR at a time, so you run it 20 times by hand, re-explaining the formatting rules on every pass.

That's the ceiling of a single conversation: one conversation, one context window, one chain of reasoning. For complex tasks, this pattern breaks down.²

What a Workflow Is

A workflow is an executable script that breaks a complex task into steps, delegates each step to a fresh agent, and coordinates the whole thing itself.³

The key differences:

For example, a refactoring workflow might look like this:

The script holds the loops, the branches, and the intermediate results; Claude's context only ever sees the final answer. The orchestration is deterministic, and only the work inside each step is model-driven.³

When a Workflow Fits

Four traits mark a task that fits a workflow:

1. More agents than one conversation can coordinate. A single conversation can manage 3-5 subagents; past that, you need a workflow.
2. You want the orchestration codified as a readable, reusable script. Write it once, rerun it whenever.
3. The task splits into clear phases. Analyze, plan, implement, verify.
4. You need parallel execution or cross-checking. Independent subtasks, adversarial validation, tournament-style comparison.

The official docs put it plainly: "Reach for a workflow when a task needs more agents than one conversation can coordinate, or when you want the orchestration codified as a script you can read and rerun."²

Typical scenarios:

• Codebase audit. Scan 500 files, one agent per file checking for security issues, then aggregate the results.
• Large-scale migration. Upgrade 200 components from Vue 2 to Vue 3 in parallel, then verify the integration at the end.
• Cross-checked research. Have 5 agents research the same question independently, cross-check the facts, and produce a consistency report.
• Multi-angle design review. Evaluate a design from three angles (architecture, performance, cost) independently, then merge.²

When a workflow is the wrong tool:

• Simple single-file edits or code reviews, where a direct conversation is enough.
• Open-ended work like creative writing or brainstorming.
• Tasks that need a lot of human judgment and can't be reduced to steps.

How Workflows Evolved

Workflows didn't appear out of nowhere. They're the fourth stage of Claude Code's orchestration capability:¹

Stage 1: Monolithic agent

┌─────────┐│ Claude  │  One context window does everything:└─────────┘  read, plan, edit, test

Stage 2: Subagent fan-out (the Agent tool)

┌─────────┐│ Claude  │──→ agent: "search the codebase"│ (main)  │──→ agent: "read these 40 files"└─────────┘  results return to the parent agent

Stage 3: Agent teams

┌─────────┐    ┌─────────┐    ┌─────────┐│ Planner │───→│ Coder   │───→│ Tester  │└─────────┘    └─────────┘    └─────────┘     each agent keeps its own role and context

Stage 4: Workflow orchestration

    ┌─────────────────┐    │ Workflow Script │  holds loops, branches, state    └────────┬────────┘         ┌───┴───┬───────┬───────┐         ↓       ↓       ↓       ↓    agent()  agent() agent() agent()    each call launches an independent subagent

The core innovation of a workflow is inverted control flow: instead of letting the agent decide "what do I do next," the script decides "which agent do I call next."³

What Orchestration Really Is

Orchestration is exactly what it sounds like: "one score, many musicians. A script deciding it — for loop, if statement — is orchestration."¹

In a workflow:

• The score = the JavaScript/TypeScript script you write, with its for loops, if statements, and Promise.all calls.
• The musicians = the subagents each agent() call launches.
• The conductor = the script's execution engine, coordinating the agents according to the score.

Here's the distinction, in the words of the guide that named it: "A normal agent decides the control flow as it goes. A workflow inverts that. You write the control flow as plain code, and each individual step is delegated to a fresh subagent."

A normal agent improvises at runtime: "do A first, then decide whether to do B or C." A workflow pins the control flow down in code: "run A1-A10 in parallel, then do B once they all finish; if B returns score > 0.8, do C, otherwise D."

What deterministic orchestration buys you:

• Predictable. Same input, same execution path.
• Debuggable. Which step failed is obvious.
• Rerunnable. The script lives in .claude/workflows/ and can be called by name.
• Scalable. Going from 10 agents to 100 is just a change to the loop count.³

Your First Workflow Scenario: A Code-Review Pipeline

Let's look at a real case. Your team has 15 PRs waiting for review, and each PR needs four checks:

1. Does the code follow the style guide?
2. Are there any obvious bugs?
3. Is test coverage sufficient?
4. Were the relevant docs updated?

With a single conversation, you run it 15 times, switching PRs by hand each time.

With a workflow:

What this workflow gets you:

• 15 PRs reviewed in parallel, 15x faster than sequential.
• Consistent review standards (every PR uses the same prompt).
• It can run automatically every week, no manual steps.
• The script commits to Git and gets shared across the team.

Next: Lesson 2 >> — Workflow Building Blocks: Steps, State, Branches, Loops