Agentic Developer Workflow

Agentic Developer Workflow (ADW)

**English** | [Deutsch](README.de.md)

A Python orchestrator that takes an issue fully automatically through **seven phases**:

Spec → Plan + Contract → Build (Lanes) → Integration/E2E → Codex Review → final Review + Triage → Push/CI/Staging

Guiding principle: **Control flow is code, not prompt.** Loops, Gates, merges, dispatch, triage, limits, and CI polling are deterministic Python code (0 tokens). Agents (Claude Agent SDK + Codex CLI) run only where judgment is needed — and reviewers never fix: every fix goes through the build agents and again through all Gates.

**Billing:** ADW talks to Claude exclusively via the **Claude Code CLI** (the Agent SDK spawns it headless) with stored login — usage runs against the Claude plan, never token-by-token against the API (API key env variables are actively blanked). An exhausted plan limit stops the run at the checkpoint; `adw resume` continues after the reset.

References: [`docs/SPEC.md`](docs/SPEC.md) (target behavior, interfaces, DoD) and [`docs/PLAN.md`](docs/PLAN.md) (implementation plan).

**Claude skill:** [agentic-developer-workflow-skill](https://github.com/sostrowsk/agentic-developer-workflow-skill) — packages the operation of this orchestrator as an installable Claude skill (preflight check, workflow guide, config template, troubleshooting).

Quickstart

# Dependencies (uv, Python >= 3.12)
uv sync

# Prepare the target repo: create .adw/config.yaml (see examples/config.yaml)
mkdir -p /path/to/repo/.adw
cp examples/config.yaml /path/to/repo/.adw/config.yaml   # and adjust

# Dry run: complete control flow with mocks — 0 tokens, no network
uv run adw run --repo /path/to/repo --issue "Demo feature" --dry-run --no-approval
uv run adw run --repo /path/to/repo --issue "Demo feature" --dry-run --parallel --no-approval

# Real run (tokens!): issue text directly, GitLab issue (glab) or GitHub issue (gh)
uv run adw run --repo /path/to/repo --issue "Bug: login aborts when .