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

Core Principles

→ See references/design-principles.md for details

Tier 1: Essential Principles

Tier 2: Quality Principles

Workflow Patterns

→ See 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 for details

Quick Check

## Workflow Review Checklist

### Core Principles

- [ ] **SSOT**: Is the same info defined in multiple places?
- [ ] **SRP**: Is each agent focused on a single responsibility?
- [ ] **Simplicity**: Is this the simplest possible solution?
- [ ] **Fail Fast**: Can errors be detected and stopped immediately?
- [ ] **Iterative**: Is it broken into small steps?
- [ ] **Feedback Loop**: Can results be verified at each step?

### Quality Principles

- [ ] **Transparency**: Are plans and progress visible?
- [ ] **Gate/Checkpoint**: Is validation done at each step?
- [ ] **DRY**: Are common processes reused?
- [ ] **ISP**: Is only necessary info being passed?
- [ ] **Idempotency**: Is it safe to retry?

### Anti-Pattern Detection

- [ ] Is too much responsibility packed into one agent?
- [ ] Is excessive context being passed?
- [ ] Is error handling missing?
- [ ] Is there potential for infinite loops?
- [ ] Are there points where human-in-the-loop is needed?

Anti-Patterns

→ See references/anti-patterns.md for details

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
• Workflows and Agents - LangChain
• subagent-driven-development - obra/superpowers
• dispatching-parallel-agents - obra/superpowers