ADW System Overview

Architecture

The ADW engine is composed of 8 Python modules plus a set of orchestrator scripts that chain them together.

flowchart TD
    subgraph Orchestrators
        PB[adw_plan_build.py]
        PBT[adw_plan_build_test.py]
        PBTR[adw_plan_build_test_review.py]
        SDLC[adw_sdlc.py]
    end

    subgraph Phase Scripts
        PLAN[adw_plan.py]
        BUILD[adw_build.py]
        TEST[adw_test.py]
        REVIEW[adw_review.py]
        DOC[adw_document.py]
        PATCH[adw_patch.py]
    end

    subgraph adw_modules
        AGENT[agent.py]
        GH[github.py]
        GIT[git_ops.py]
        STATE[state.py]
        WF[workflow_ops.py]
        DT[data_types.py]
        UTILS[utils.py]
    end

    subgraph Triggers
        CRON[trigger_cron.py]
        HOOK[trigger_webhook.py]
    end

    PB --> PLAN --> AGENT
    PB --> BUILD --> AGENT
    PLAN --> GH
    PLAN --> GIT
    PLAN --> STATE
    BUILD --> WF
    AGENT --> DT
    CRON --> PB
    HOOK --> SDLC

Core Modules

agent.py — Claude Code CLI Interface

The bridge between Python orchestrators and Claude Code CLI. Handles:

• Subprocess invocation with proper env and flags
• Raw output streaming to .jsonl files
• Session ID management
• Error handling and retries

# agent.py is how every ADW phase calls Claude
result = run_agent(
    prompt=spec_content,
    working_dir=project_dir,
    model="sonnet",  # or "opus"
    tools=["Bash", "Read", "Write", "Edit"]
)

github.py — GitHub API Wrapper

Wraps the GitHub REST API for all issue and PR operations:

• Fetch issue details and comments
• Post comments to issues
• Create and update pull requests
• Upload review artifacts

git_ops.py — Git Operations

Centralizes all git operations:

• Create feature branches (feat-{num}-{adw-id}-{slug})
• Stage and commit changes with semantic messages
• Push branches and create PRs
• Handle merge conflicts

state.py — ADW State Machine

Persistent state management for workflow chaining:

class ADWState:
    adw_id: str           # 8-char unique ID
    issue_number: int
    branch_name: str
    plan_file: str        # path to spec in specs/
    issue_class: str      # /chore, /bug, /feature

State writes to agents/{adw_id}/adw_state.json. Any phase can read or update it. Enables piping state between phases via stdout/stdin.

workflow_ops.py — Business Logic

Core orchestration logic:

• Issue classification via /classify_issue
• Spec generation via /feature, /bug, /chore
• Implementation via /implement
• Review via /review
• Document generation via /document

data_types.py — Pydantic Models

Typed contracts for agent communication:

• IssueClassification — type + reasoning
• SpecResult — plan file path + summary
• BuildResult — commit hash + files changed
• TestResult — pass/fail + output

utils.py — Shared Helpers

• ADW ID generation (8 random chars)
• Branch name slugification
• File path utilities
• Timestamp formatting

ADW ID System

Every workflow run gets a unique 8-character ID:

feat-42-a3f9k2m1-add-csv-export
      ^^ ^^^^^^^^
      |  ADW ID
      Issue number

The ID appears in:

• Branch name
• Spec filename: specs/issue-42-adw-a3f9k2m1-sdlc_planner-*.md
• Workspace: agents/a3f9k2m1/
• GitHub comments: a3f9k2m1_ops: ...
• All git commits

Issue Classification

The system auto-classifies issues into three types:

/chore  — maintenance, no user-facing change, no E2E tests needed
/bug    — something broken, needs repro steps in spec
/feature — net new capability, needs acceptance criteria + E2E test file

Force classification by including it in the issue body:

• "This is a chore to..." → /chore
• "This is a bug where..." → /bug
• (Default if neither) → /feature