adw-design

# 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:

```text
ADW = Orchestrator + Micro Agents + Triggers + Observability
```

Components:

1. **Orchestrator** - Python/TypeScript code that coordinates the workflow
2. **Micro Agents** - Specialized Claude Code invocations with single responsibilities
3. **Triggers** - Webhooks, cron, or manual invocation
4. **Observability** - Logging, issue comments, tracking

## ADW Design Process

### Step 1: Define the Workflow

Map out the phases:

```text
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

Th