Agentic Development Workflow (ADW)
The ADW is Wasteology's AI-powered development pipeline. Instead of a human developer writing every line of code, AI agents implement features from a written specification — then a human reviews what was built in a safe sandbox environment before it ever reaches production.
The core principle: humans own sign-off, not authorship.
Read the ADW Translation Matrix ↗ — a leadership-facing breakdown of six pillars of this platform (the spec-first pipeline, the knowledge graph, the evidence gate, 24/7 monitoring, access governance, and unified intake), each translated from technical reality into business argument.
This page is the quick-start. For the step-by-step curriculum — install Claude Code, ground an agent with lat.md, write a spec, run the local loop, scale to the cloud, and onboard your own project — take the ADW Track in Wasteology Academy ↗ (labs + knowledge checks + a capstone).
The Five-Step Pipeline
Every piece of work — bug fixes, new features, chores — follows the same five steps:
| Step | Who does it | What happens |
|---|---|---|
| Identify & Classify | Human or automated trigger | Issue is categorized — bug, feature, or chore |
| Draft Specification | Human (with AI assist) | A spec document is written describing exactly what to build and how to verify it |
| Review Specification | AI architect agent | The spec is checked for completeness, clarity, and technical soundness |
| Implement in Sandbox | AI agents | Code is written and deployed to the sandbox environment |
| Validate | AI Playwright agent | The implementation is tested against the spec's acceptance criteria |
| Human Approval | You | You review the working feature in sandbox and decide whether it's ready |
| Promote to Production | CI/CD pipeline | Approved code goes live automatically |
The Three Environments
Work moves through three isolated environments. Each has a distinct owner and purpose.
Key rule: Nothing reaches production until a human has reviewed the working feature in sandbox. There is no shortcut path.
What "sandbox" means
Sandbox is not a mock environment — it's a complete, running copy of the application with a real database and real API. AI agents deploy their implementation there automatically. You review actual behavior (not code) before approving.
The Spec Lifecycle
Every work item is anchored to a specification document. The spec drives everything: what gets built, how it's tested, and when it's done.
Spec files live in the project's specs/ directory as self-contained HTML documents. Open any .html file in a browser to read it.
What You Do as a Human Reviewer
Your role in the ADW pipeline is to:
- Review the spec before agents start — does it describe the right behavior? Is anything missing?
- Review sandbox output — navigate to the sandbox URL and use the feature as a real user would
- Approve or request changes — if the feature works correctly, approve it; if not, describe what's wrong and the cycle repeats
You do not need to read code, write tests, or understand implementation details. Your input is behavioral: does the feature do what was specified?
How to Trigger Work
All ADW work is initiated from the wg-orchestration project with Claude Code:
# Create a new specification (starts the pipeline)
/spec-create "description of the feature or change"
# Implement immediately in the current Claude session
/task <spec-id>
# Dispatch to overnight ADW pipeline
/dispatch --go
If you're working in any other project directory, cd ~/projects/wg-orchestration first — spec creation and dispatch always run from there.
Mars / Orbit Platform Example
The Mars work order platform (mars_workorder_system) uses a refined version of this workflow:
- Specs live in
mars_workorder_system/specs/as numbered HTML documents (01-adw-workflow-init.html,02-backend-skeleton.html, etc.) - The sandbox environment is
orbit-backend-sandboxon Azure - Playwright validation automatically tests scenarios listed in each spec
- The roadmap (
specs/roadmap.html) tracks the status of all specs
See it in action: Watch a 2-minute narrated replay of a real run on the Orbit ADW Workflow page.
📽 Executive briefing deck: Open an 11-slide interactive briefing on ADW governance and adoption, for leadership audiences (opens full-screen; arrow keys to navigate).
Newer Projects: Self-Updating Roadmaps
The newest ADW projects (starting with the Avalara tax commit & reconciler) add three refinements that make the roadmap trustworthy without extra bookkeeping:
- Specs are drafted with OpenSpec — an open spec-driven-development standard. You and the AI agree on what to build before any code is written, and the specification lives in the repo as the source of truth.
- The roadmap updates itself. It's a single structured file where every deliverable moves through
planned → implemented → validated → deployedautomatically — flipping to implemented when its spec merges and to validated when its test/Playwright evidence is on file. No one hand-maintains status. - A CI gate makes "done" mean proven. Every pull request is checked automatically; a deliverable cannot be marked validated without its validation evidence, and the check blocks the merge otherwise. The check is plain, deterministic tooling — no AI cost.
The result: at any moment the roadmap reflects reality, and nothing is called finished until it's been demonstrated.
For the engineering detail (the TOML source of truth, the roadmap.py tool, and the exact status transitions), see the Orbit ADW Workflow page.
Known Gotcha: CLI Version Drift Breaks Headless Slash Commands
Applies to: any repo whose ADW pipeline shells out to the bare headless Claude Code CLI on the shared ADW-Agents self-hosted pool (Azure Container Apps, image built from wg-orchestration's adw-agent Dockerfile) and drives its loop through a repo-local slash command like /adw.
Not applicable to Pipeline 9's Anthropic-SDK tool-loop, which never invokes the CLI product and so is immune to CLI-version drift.
What happened (2026-09-09, portal-reconciliation — build 8796, work item #516). The pool image is rebuilt independently of the repos that use it, and its pre-installed Claude Code CLI jumped 2.1.63 → 2.1.197 between two pipeline runs. The pipeline's /adw <id> invocation was then parsed as a literal unrecognized command, Claude replied "Unknown command: /adw", and the run exited reporting success with zero real work done.
The dangerous part: claude --print exits 0 regardless. A pipeline that trusts the exit code alone reports a false-green build that built nothing — and the requester waits on a PR that will never appear.
Two distinct causes — don't stop at the first one
Workspace trust was the first hypothesis, and a fix based on it alone still failed identically on retry (build 8808, same work item). Local repro isolated two separate effects of the version jump.
1. The actual blocker: CLAUDE_CODE_SIMPLE=1 changed meaning across CLI versions. The pipeline had set this env var since its creation, to "reinforce headless/simple mode." On 2.1.63 it only trims the tool list. On 2.1.197 it also unconditionally strips every project-level slash command — including the repo's own /adw — regardless of workspace trust. Confirmed locally: 2.1.197 + CLAUDE_CODE_SIMPLE=1 drops /adw even with trust accepted; the same binary loads /adw fine once trusted if CLAUDE_CODE_SIMPLE is unset.
2. A separate, genuinely real issue: a workspace-trust gate that --dangerously-skip-permissions does not bypass. In an untrusted cwd, 2.1.197 ignores .claude/settings.json permissions.allow and logs a warning. Worth fixing on its own merits — but fixing only this does not restore /adw while CLAUDE_CODE_SIMPLE=1 is set on a newer CLI.
The four-part fix
Applied and verified in portal-reconciliation's azure-pipelines-adw.yml (PR #1376, branch fix/adw-pipeline-cli-trust-regression). Port all four to any ADW pipeline on this pool.
| # | Fix | Why |
|---|---|---|
| 1 | Pin the CLI to a known-good version via a local npm prefix — npm install --prefix $HOME/.adw-claude-pin @anthropic-ai/claude-code@<version> | Don't trust whatever a shared pool image happens to ship. A local prefix needs no root and won't collide with the root-owned pre-installed copy. Make it best-effort: fall back to the pre-installed CLI if the install fails, so a network hiccup never hard-fails the step. This is what actually keeps the pipeline working. |
| 2 | Make the pinned binary survive the step boundary — symlink it into $HOME/.local/bin/claude rather than relying on export PATH= | Each Azure Pipelines script: block is a fresh shell, so a PATH-prepend is step-local and silently no-ops by the time a later step runs claude. See the callout below — this is a general ADO lesson, not a CLI-specific one. |
| 3 | Stamp workspace trust on every run — merge projects["<cwd>"].hasTrustDialogAccepted = true into ~/.claude.json before invoking claude | Fixes cause (2) above; not sufficient on its own. A one-time interactive trust accept does not stick, because the self-hosted agent's checkout path varies per run (/azp/_work/N/s). Merge, don't overwrite — preserve the file's other keys. |
| 4 | Never treat exit 0 as proof of work — gate the build on a concrete downstream artifact | Confirm a PR was actually opened and linked to the originating work item before marking the build green. In portal-reconciliation this existing silent-empty-run guard is what caught both failed attempts instead of publishing a false green. |
The first fix attempt (build 8808) installed the pinned CLI correctly and logged the right version in its own step — then the ADW step still launched the old pre-installed one. Every script: block gets a fresh shell, so export PATH=... never reaches the next step. Hand a tool install across steps via a disk-backed location already on PATH (here $HOME/.local/bin, which later steps add for uv). This applies to any multi-step ADO pipeline chaining tool installs — not just this CLI pin.
An ADW build that succeeds in minutes with no spec, no branch, and no PR. Search the run log for Unknown command: — that string plus a green build is this exact failure. If you've already stamped trust and the warning is gone but the symptom persists, check for CLAUDE_CODE_SIMPLE (or any similar mode-forcing env var) in the pipeline.
This is a shared-infrastructure lesson, not a portal-reconciliation one. The canonical cross-project write-up is recorded in wg-orchestration's lat.md/operations.md — check there first for the current pinned version and the exact pipeline snippets. The portal-reconciliation specifics are in that repo's lat.md/operations.md.
Any new repo adopting this pattern — especially any repo copying a CLAUDE_CODE_SIMPLE=1-style env var into a headless pipeline — should port the pin, the cross-step PATH fix, and the trust-stamp up front rather than rediscovering them the hard way.
Frequently Asked Questions
Q: What if the agents build the wrong thing?
The spec is the contract. If agents misimplement it, they fix it. If the spec was wrong, the spec is updated and the cycle repeats. Either way, nothing incorrect reaches production.
Q: Can I still write code myself?
Yes. The ADW pipeline is the standard path, but developers can implement directly on feature branches. The spec still exists — it just gets implemented manually instead of by agents.
Q: How long does a typical cycle take?
Simple features: a few minutes to a few hours. The agents work continuously; the bottleneck is human review time.
Q: What's the overnight ADW pipeline?
Specs dispatched with /dispatch --go are picked up by an automated pipeline that runs outside business hours. You find the results in sandbox the next morning, ready to review.