diegosouzapw ADW Design
Guide for creating AI Developer Workflows - reusable agentic workflows that combine deterministic code with non-deterministic agents.
When to Use
- Building automated development pipelines
- Designing AFK (Away From Keyboard) agent systems
- Implementing the PITER framework
- Creating micro agent architectures
- Setting up GitHub issue → PR automation
What is an ADW?
An ADW is the highest composition level of agentic coding:
ADW = Orchestrator + Micro Agents + Triggers + Observability
Components:
- Orchestrator - Python/TypeScript code that coordinates the workflow
- Micro Agents - Specialized Claude Code invocations with single responsibilities
- Triggers - Webhooks, cron, or manual invocation
- Observability - Logging, issue comments, tracking
ADW Design Process
Step 1: Define the Workflow
Map out the phases:
Input → Classify → Branch → Plan → Implement → Review
Questions to answer:
- What's the input source? (GitHub issues, Notion, Slack)
- What are the phases? (classify, plan, implement, review)
- What's the output? (PR, deployment, report)
Step 2: Design Micro Agents
For each phase, define a specialized agent:
| Phase | Agent | Responsibility | Model |
|---|---|---|---|
| Classify | issue_classifier |
Determine work type | Haiku |
| Branch | branch_generator |
Create branch name | Haiku |
| Plan | sdlc_planner |
Generate implementation plan | Sonnet |
| Build | sdlc_implementer |
Implement the solution | Sonnet |
| Commit | committer |
Create semantic commits | Haiku |
| PR | pr_creator |
Create pull request | Haiku |
Step 3: Create Templates
Each agent needs a slash command:
/classify-issue- Classify issue type/generate-branch-name- Create branch name/chore,/bug,/feature- Generate plans/implement- Execute plans/commit-with-agent- Create commits/pull-request- Create PRs
Step 4: Build Orchestrator
The orchestrator coordinates everything:
# Pseudocode structure
def run_adw(issue_number, adw_id):
issue = fetch_issue(issue_number)
issue_type = execute_agent("classifier", issue)
branch = execute_agent("branch_generator", issue)
plan = execute_agent("planner", issue_type, issue)
execute_agent("implementer", plan)
execute_agent("pr_creator", branch, issue, plan)
Step 5: Add Observability
Track everything:
- ADW ID: 8-char UUID for correlation
- Issue comments: Progress updates
- Logs: Structured output per agent
- Metrics: Success rate, duration
ADW Directory Structure
adws/
├── main_workflow.py # Main orchestrator
├── agent.py # Claude Code integration
├── data_types.py # Type definitions
├── github.py # GitHub operations
├── trigger_cron.py # Cron trigger
├── trigger_webhook.py # Webhook trigger
├── health_check.py # Environment validation
└── README.md # Documentation
Model Selection Strategy
Match model to task:
| Task Complexity | Model | Examples |
|---|---|---|
| Simple decision | Haiku | Classification, branch naming |
| Formatting | Haiku | Commit messages, PR body |
| Reasoning | Sonnet | Plan generation |
| Complex coding | Sonnet/Opus | Implementation |
ADW Quality Checklist
Before deploying:
- Each agent has single responsibility
- Model selection matches task complexity
- ADW ID tracking implemented
- Issue comments posted at each phase
- Error handling with meaningful messages
- Logging captures all agent outputs
- Health check validates environment
- Templates tested independently
- End-to-end workflow tested
Common Patterns
Agent Executor Pattern
def execute_agent(agent_name, *args):
prompt = build_prompt(agent_name, args)
result = subprocess.run([
"claude", "-p", prompt,
"--model", get_model(agent_name),
"--output-format", "stream-json"
])
log_result(agent_name, result)
return parse_result(result)
Issue Comment Pattern
def update_issue(issue_number, adw_id, agent_name, message):
comment = f"[{adw_id}_{agent_name}] {message}"
gh_issue_comment(issue_number, comment)
Error Handling Pattern
def check_error(result, phase):
if not result.success:
update_issue(issue, adw_id, phase, f"ERROR: {result.error}")
sys.exit(1)
Anti-Patterns to Avoid
Monolithic Agent
Bad: One agent doing everything
Good: Micro agents with single responsibilities
Missing Observability
Bad: No logging, no issue comments
Good: ADW ID tracking, structured logs, progress comments
Wrong Model Selection
Bad: Using Opus for branch naming
Good: Match model to task complexity
No Error Handling
Bad: Silent failures
Good: Error comments, graceful degradation
Related Memory Files
- @piter-framework.md - PITER elements for AFK agents
- @adw-anatomy.md - ADW structure and patterns
- @outloop-checklist.md - Deployment readiness
- @inloop-vs-outloop.md - When to use ADWs
Version History
- v1.0.0 (2025-12-26): Initial release
Last Updated
Date: 2025-12-26 Model: claude-opus-4-5-20251101