Pipeline Depth Levels

Start at Level 1. Move down as your confidence in the system grows. The only reason not to use adw_sdlc.py immediately is building trust one phase at a time.

The Five Levels

cd adws

# Level 1 — plan + build only, you handle testing and review
uv run adw_plan_build.py <issue>

# Level 2 — plan + build + run validation commands from spec
uv run adw_plan_build_test.py <issue>

# Level 3 — plan + build + review against spec (Playwright screenshots)
uv run adw_plan_build_review.py <issue>

# Level 4 — plan + build + test + review
uv run adw_plan_build_test_review.py <issue>

# Level 5 — full SDLC: plan + build + test + review + docs
uv run adw_sdlc.py <issue>

# Level 5 flags
uv run adw_sdlc.py <issue> --skip-e2e         # skip browser tests (faster)
uv run adw_sdlc.py <issue> --skip-resolution  # review only, no auto-patch loop

What Each Phase Does

flowchart TD
    PB[adw_plan_build.py] --> PLAN[1. Planning\nclassify → spec → branch → PR]
    PB --> BUILD[2. Building\nread spec → implement → commit]

    PBT[adw_plan_build_test.py] --> PLAN2[1. Planning]
    PBT --> BUILD2[2. Building]
    PBT --> TEST[3. Testing\nrun commands → auto-fix failures → report]

    PBTR[adw_plan_build_test_review.py] --> PLAN3[1. Planning]
    PBTR --> BUILD3[2. Building]
    PBTR --> TEST2[3. Testing]
    PBTR --> REVIEW[4. Review\nspec compliance → screenshots → auto-patch]

    SDLC[adw_sdlc.py] --> PLAN4[1. Planning]
    SDLC --> BUILD4[2. Building]
    SDLC --> TEST3[3. Testing]
    SDLC --> REVIEW2[4. Review]
    SDLC --> DOCS[5. Documentation\ngenerate app_docs/ from review artifacts]

Individual Phase Scripts

Each phase can also run standalone:

# Plan only — generates spec, creates branch, opens PR
uv run adw_plan.py <issue>

# Build from existing plan
uv run adw_build.py <issue> <adw-id>

# Test only — runs test suite, auto-fixes up to 3 times
uv run adw_test.py <issue> <adw-id>
uv run adw_test.py <issue> <adw-id> --skip-e2e

# Review only — spec compliance check + screenshots
uv run adw_review.py <issue> <adw-id>
uv run adw_review.py <issue> <adw-id> --skip-resolution

# Document only
uv run adw_document.py <issue> <adw-id>

Phase Chaining via Pipe

Scripts can be chained using pipes to pass state:

# Chain planning and building
uv run adw_plan.py 123 | uv run adw_build.py

# Chain full pipeline manually
uv run adw_plan.py 123 | uv run adw_build.py | uv run adw_test.py

State is automatically passed between scripts via JSON on stdout.

Test vs Review: Different Questions

These are not the same phase:

Phase	Question	Information Used
adw_test.py	"Does it work?"	Runs commands, checks exit codes
adw_review.py	"Is it what we asked for?"	Reads original spec, uses Playwright screenshots

Run both for full confidence. Skip review when you're tight on time; skip tests when the change is purely visual.

adw_sdlc.py Output Structure

agents/
└── {adw_id}/
    ├── adw_state.json
    ├── {adw_id}_plan_spec.md
    ├── planner/
    │   └── raw_output.jsonl
    ├── implementor/
    │   └── raw_output.jsonl
    ├── tester/
    │   └── raw_output.jsonl
    ├── reviewer/
    │   ├── raw_output.jsonl
    │   └── review_img/           # Playwright screenshots
    └── documenter/
        └── raw_output.jsonl

app_docs/
└── features/
    └── {feature_name}/
        ├── overview.md
        ├── technical-guide.md
        └── images/