16 — Workflow Playbooks

Workflows are just primitives chained in the right order. The interesting part is knowing which order.

The composition idea

Every workflow you'll build is a sequence of the things covered in earlier sections: agents, skills, MCPs, commands, hooks. The pattern is always the same:

1. Gather context — what does Claude need to know to act well here?
2. Narrow scope — one task per agent call, not "do everything"
3. Verify output — check before moving on, not after the whole chain
4. Codify the repeat — when you run the same sequence three times, make it a command

The mistake is treating workflows as one big prompt. Break them up.

Example: ship a feature

This isn't code to copy — it's the pattern to adapt.

1. spec        → Write a short spec doc: what it does, what it doesn't do
2. plan        → Ask Claude to generate an implementation plan from the spec
3. implement   → Run parallel agent calls for independent parts (frontend / backend / tests)
4. review      → Run a reviewer agent on the diff
5. commit      → Commit with a generated message; push only after review passes

Each step is a discrete call. The output of one is the input to the next. If step 3 fails, you fix it before running step 4 — you don't let errors compound.

Example: research → write

1. research    → Use an MCP (search, scraper, docs) to gather raw material
2. distill     → Ask Claude to extract the 5 most relevant points
3. draft       → Write the piece using the distilled points as structure
4. edit        → One more pass: tighten, cut what doesn't earn its place

The research step is where most people shortcut and then wonder why the output is generic. Garbage in, garbage out.

When to make it a command

A workflow becomes a custom command when:

• You've run the same sequence 3+ times
• The steps don't change between runs — only the inputs do
• You want it to be available to others (team) or in future sessions

Commands live in .claude/commands/. Each is a markdown file with the prompt template and any parameters. Claude picks them up automatically.

# Run a custom command
/your-command-name

What makes a playbook fail

• Context gaps: Claude doesn't know something it needed. Fix with better CLAUDE.md or explicit context at the start of the chain.
• Scope creep: one agent call does too much. Break it up.
• Skipped verification: you moved on before confirming the last step was correct.
• No handoff format: agent A produces output, agent B can't parse it. Define the format explicitly.

Start small

Pick one workflow you run manually today. Map the steps. Run them as discrete Claude calls this week. If it saves time, codify it as a command. That's the whole loop.