Agentic Workflow Guide

A comprehensive guide for designing, reviewing, and improving agent workflows based on proven design principles.

When to Use

• New Workflow Design - Define agent roles, responsibilities, and execution order
• Workflow Review - Detect issues by checking against design principles
• Pattern Selection - Choose the right workflow pattern for your task
• Quality Improvement - Iteratively refine workflows step by step
• Scaffolding - Generate workflow directory structures and templates
• Long-Horizon Tasks - Manage context for multi-hour agent sessions

Core Principles

→ See [references/design-principles.md](references/design-principles.md) for details

Key insight:

• Start simple and only add multi-step agent patterns when the simpler approach stops working.

Workflow Patterns

→ See [references/workflow-patterns.md](references/workflow-patterns.md) for details

Pattern Selection Guide

What's the nature of the task?
├─ Sequential processing needed ──→ Prompt Chaining
├─ Multiple independent tasks ────→ Parallelization
├─ Dynamic task decomposition ────→ Orchestrator-Workers
├─ Until quality criteria met ────→ Evaluator-Optimizer
└─ Processing varies by input ────→ Routing

Pattern Overview

Design Workflow

Step 1: Requirements Gathering

## Workflow Design Interview

1. **Goal**: What do you want to achieve?
2. **Task Decomposition**: What subtasks can this be broken into?
3. **Dependencies**: Are there ordering dependencies between tasks?
4. **Parallelism**: Which tasks can run independently?
5. **Quality Criteria**: What defines success/failure?
6. **Error Handling**: How should failures be handled?

Step 2: Pattern Selection

Choose the optimal pattern based on requirements:

Step 3: Create Design Diagram

Visualize with Mermaid:

graph TD
    A[Start] --> B{Task Classification}
    B -->|Type A| C[Agent 1]
    B -->|Type B| D[Agent 2]
    C --> E[Reviewer]
    D --> E
    E -->|OK| F[End]
    E -->|NG| G[Feedback]
    G --> C
    G --> D

Step 4: Principle Check

Validate design against principles (use review checklist)

Step 5: Implement & Iterate

Build small → verify → get feedback → improve

Review Checklist

→ See [references/review-checklist.md](references/review-checklist.md) for complete checklist (includes anti-patterns)

Quick Check (5 items)

- [ ] Is each agent focused on a single responsibility? (SRP)
- [ ] Can errors be detected and stopped immediately? (Fail Fast)
- [ ] Is it divided into small steps? (Iterative)
- [ ] Can results be verified at each step? (Feedback Loop)
- [ ] Are related files (references, scripts) simple and minimal? (DRY)

Context Engineering

→ See [references/context-engineering.md](references/context-engineering.md) for details

For long-running agents, manage context as a finite resource:

Key insight:

• Start with simple prompts/workflows and only add multi-step agent patterns when needed.
• Treat context as limited; keep the main instructions lean and move details into reference files.

Scaffold Workflow

Automatically generate workflow directory structures.

Usage

# Basic workflow
python scripts/scaffold_workflow.py my-workflow

# Specify pattern
python scripts/scaffold_workflow.py code-review --pattern evaluator-optimizer

# Specify output path
python scripts/scaffold_workflow.py data-pipeline --pattern orchestrator-workers --path ./projects

# List available patterns
python scripts/scaffold_workflow.py --list-patterns

Available Patterns

Generated Structure

my-workflow/
├── Agent.md                    # Workflow overview & agent list
├── README.md                   # Usage guide
├── .github/
│   ├── copilot-instructions.md # GitHub Copilot instructions
│   └── instructions/           # File-pattern-specific rules
│       ├── workflow.instructions.md
│       ├── agents.instructions.md
│       └── prompts.instructions.md
├── agents/                     # Agent definitions
├── prompts/                    # Prompt templates
│   ├── system_prompt.md
│   ├── task_prompt.md
│   └── error_handling_prompt.md
├── docs/                       # Design documentation
│   ├── design.md
│   └── review_notes.md
└── config/                     # Configuration files

Resources

References

• Building Effective Agents - Anthropic
• Effective Context Engineering - Anthropic
• Writing Tools for Agents - Anthropic
• Prompt Engineering Tutorial - Anthropic
• subagent-driven-development - obra/superpowers
• dispatching-parallel-agents - obra/superpowers