| name | agentic-workflow-guide |
| description | Design, review, and improve agent workflows & agent using SSOT, SRP, Fail Fast principles. Supports Prompt Chaining, Parallelization, Orchestrator-Workers patterns. |
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 for details
| Tier | Principles | Focus |
|---|
| Tier 1: Essential | SSOT, SRP, Simplicity First, Fail Fast, Iterative Refinement, Feedback Loop | Must-have for any workflow |
| Tier 2: Quality | Transparency, Gate/Checkpoint, DRY, ISP, Idempotency | Recommended for production |
| Tier 3: Scale | Human-in-the-Loop, KISS, Loose Coupling, Graceful Degradation | Advanced patterns |
Key insight:
- Start simple and only add multi-step agent patterns when the simpler approach stops working.
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
| Pattern | Use Case | Iterative Level |
|---|
| Prompt Chaining | Sequential with validation | ⭐⭐⭐ |
| Routing | Classify → route to specialists | ⭐⭐ |
| Parallelization | Execute independent tasks together | ⭐⭐ |
| Orchestrator-Workers | Dynamic decomposition → workers | ⭐⭐⭐ |
| Evaluator-Optimizer | Generate → evaluate → improve loop | ⭐⭐⭐⭐⭐ |
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:
| Condition | Recommended Pattern |
|---|
| Tasks have clear ordering | Prompt Chaining |
| Tasks are independent | Parallelization |
| Number of tasks is dynamic | Orchestrator-Workers |
| Repeat until quality criteria met | Evaluator-Optimizer |
| Processing varies by input type | Routing |
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 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 for details
For long-running agents, manage context as a finite resource:
| Technique | When to Use |
|---|
| Compaction | Context window 70%+ full |
| Structured Note-taking | Multi-hour tasks with milestones |
| Sub-agent Architectures | Complex research, parallel exploration |
| Just-in-Time Retrieval | Large codebases, dynamic data |
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
python scripts/scaffold_workflow.py my-workflow
python scripts/scaffold_workflow.py code-review --pattern evaluator-optimizer
python scripts/scaffold_workflow.py data-pipeline --pattern orchestrator-workers --path ./projects
python scripts/scaffold_workflow.py --list-patterns
Available Patterns
| Pattern | Description |
|---|
basic | Basic workflow structure |
prompt-chaining | Sequential processing pattern |
parallelization | Parallel processing pattern |
orchestrator-workers | Orchestrator + workers pattern |
evaluator-optimizer | Evaluation-improvement loop |
routing | Routing pattern |
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
