ADW: Agentic Development Workflows
An Agentic Development Workflow is a closed loop with a hard boundary. A human authors the specification — a self-contained HTML document in specs/ — and holds the only promotion gate: merging the PR to main. Agents run everything between those points: architect-review the spec against a 7-dimension gate, implement on a spec/NN-slug branch, open the PR that is the sandbox deploy, validate with Playwright against the live sandbox, and produce a mandatory evidence package (RESULTS.md + screenshots + chaptered recording).
No code reaches production until a human reads the spec, watches the evidence, and clicks merge. Fast because the loop is automated end to end; safe because the promotion boundary is fixed.
This page is the maintained, auto-updating source of truth for the ADW deep-dive. A fully interactive version — with a live sandbox-loop simulator, a draggable lat.md knowledge-graph canvas, and an orbit CLI terminal emulator — is preserved as a static experience at /orbit/adw-interactive.html. The narrative, architecture, and tables below are the canonical reference.
Production stack: FastAPI · React · PostgreSQL · Azure Container Apps · Azure SWA · Playwright · Claude Code agents · lat.md graphs · orbit CLI
Evidence Gate — every run ships with recorded proof
The loop does not report success in prose. /spec-validate runs every Playwright scenario from the spec against the live sandbox preview, saves before/after screenshots, records a chaptered video, and writes RESULTS.md. /spec-promote greps that file for Overall: PASS before the gate opens. The reviewer watches what the agent actually did before the merge gate.
artifact://specs/screenshots/adw-pipeline-demo/adw-pipeline-demo.mp4 · ~138s · Playwright MCP video + Azure TTS narration
| Pipeline metadata | Value |
|---|---|
| Target environment | Orbit Sandbox (isolated) |
| Validation suite | playwright-validator agent |
| Artifact | RESULTS.md + chaptered recording |
| Recorder | Playwright MCP video |
| Narration | Azure TTS |
| Gate | human-required |
RESULTS.md claiming PASS is written by the validator, not the implementer. If RESULTS.md is missing or reports FAIL, /spec-promote refuses to run and the PR stays draft. Absence of proof is treated as failure, not as a pass.
The Five Commands
Every step of the loop shells out to a deterministic command. Agents call the same commands an operator would run by hand, which is what makes each run reproducible and auditable.
| Step | Command | What it does |
|---|---|---|
| 1 | /spec-create <description> | Drafts a new HTML spec in specs/, creates a spec/NN-slug branch, updates roadmap.html + the lat.md spec directory, runs lat check, commits and pushes. The spec number is assigned automatically. |
| 2 | /spec-review | Spawns an AI Architect agent to critique the spec against a 7-dimension gate before any code is written; self-revises up to three times before escalating to a human. |
| 3 | /spec-implement | Resets the sandbox, delegates code authorship to executor-high (specs read-only), commits per phase, and opens the PR to main — which is the sandbox deploy trigger. |
| 4 | /spec-validate | Runs orbit health + smoke as a baseline, then executes every Playwright scenario against the live sandbox, captures mandatory evidence screenshots, writes RESULTS.md, and posts the verdict as a PR comment. |
| 5 | /spec-dispatch | Convenience command that runs the full end-to-end loop: sandbox reset → implement → validate. Use this for a clean run from scratch. |
/spec-promote is the final step — it verifies RESULTS.md reports Overall: PASS, flips the spec badge to Validated, and moves the PR from draft to ready-for-review. It never merges. Merge is a deliberate human action.
Live Sandbox — trigger the loop yourself
The ADW orchestrator drives a faithful, disposable Orbit sandbox. Pick a feature request, trigger the agentic loop, and watch the five stages transition — then stall deliberately at the human gate. The agents never promote on their own.
A representative run, stage by stage:
| Stage | Status | What completes |
|---|---|---|
1 · spec-create | ✅ SUCCESS | branch spec/NN-slug + spec HTML stub, roadmap + lat.md updated, lat check green |
2 · spec-review | ✅ SUCCESS | architect agent, 7-dimension gate (summary, criteria, plan, validation, scenarios, scope, questions) → PASS |
3 · spec-implement | ✅ SUCCESS | orbit sandbox reset (ACA restart → alembic base→head → seed 21 WOs), executor commits per phase, PR opened to main |
4 · spec-validate | ✅ SUCCESS | orbit health + smoke ok, playwright-validator ran scenarios, RESULTS.md → Overall: PASS, PR comment posted |
5 · human-gate | ⏸ GATED | spec badge Validated, PR draft → ready-for-review; waiting for human merge — agents never promote |
The interactive companion ships a real terminal emulator where you can type your own feature request and watch the orchestrator narrate each stage in real time.
Architecture — isolation and context, engineered
Two design decisions keep the loop trustworthy at speed: a strict three-tier environment boundary, and deterministic context injection from a lat.md knowledge graph.
A. Three-tier environment isolation matrix
| Dimension | Dev | Sandbox | Production |
|---|---|---|---|
| Operated by | Humans | Agents only | CI/CD, human-approved merge |
| Data seeding | Manual, developer-driven | Deterministically reset + seeded per run via orbit sandbox reset (21 canonical WOs, two Mars sites) | Live PostgreSQL, governed; empty-by-design at launch |
| Auth & network | Password auth, orbit_dev | Password auth scoped to orbit_sandbox; prod DB is a different server — unreachable with sandbox credentials | Entra-only (wg-pg-orbit-prod); password auth does not exist |
| Write scope | Feature branch | spec/NN-slug branch + sandbox ACA + per-PR SWA preview | Merged main, tagged image |
| Promotion path | Opens a spec | Produces RESULTS.md evidence; cannot merge | Requires human merge to main |
| Lifetime | Persistent | Reset to identical seed state per run | Durable |
orbit sandbox reset restarts the ACA revision, rolls the schema base → head via alembic, and reseeds the same 21 work orders. Two identical runs start from an identical state. The prod database lives on a separate server (wg-pg-orbit-prod) with Entra-only auth, so sandbox credentials cannot reach it even if misconfigured.
B. Context engineering — the lat.md knowledge graph
Agents drift when context is dumped in as unstructured prose. Orbit instead reads from its lat.md/ directory (operations.md, overview.md, infrastructure.md, tests.md): every section carries a stable id, cross-links to related sections via [[wiki links]], and code carries # @lat: refs back to spec sections.
- Progressive disclosure —
lat expandresolves the[[refs]]in a request, injecting only the sections a task touches, never the whole repository. - Deterministic resolution — because each section is addressed by a stable id, the same request resolves to the same section set every run.
- Token economics —
lat searchdoes semantic lookup andlat checkvalidates every link, so the working context stays small and provably correct.
These are design properties of the injection step, not benchmarked metrics:
lat expandresolves[[refs]]to only the sections a task touches;lat searchfinds the same sections for the same request;lat checkvalidates every wiki link and code ref before injection.
Context drift is the quiet failure mode of agentic systems. An addressable lat.md graph turns context from a liability into an interface: versioned, reviewable, and cheap to inject.
C. The lat.md graph, live
The interactive companion renders the full Orbit lat.md graph as a draggable canvas — click any node to read its document card, and use the context-injection simulator to watch the resolver highlight exactly which nodes it would inject for a given task (versus injecting the full graph). The graph spans eight node types:
| Node type | What it represents |
|---|---|
| Architecture | Hub/overview nodes: the Orbit domain model, spec directory, cross-cutting design |
| API Endpoint | FastAPI routes serving the backend, exercised by the frontend, orbit CLI, and Playwright |
| Frontend View | React views in the dispatcher or hauler surface, deployed as per-PR SWA previews |
| Database | A PostgreSQL DB, migration chain, seed script, or data-integration surface |
| Infrastructure | An ACA app, deploy workflow, managed identity, storage account, or ACS resource |
| Agent Command | A slash command or orbit CLI operation agents invoke to drive the loop deterministically |
| Governance | A gate, policy, or branch-protection rule defining who may promote and what evidence is required |
| Test Spec | A test spec, Playwright scenario set, or smoke check that produces the required evidence |
Context injection simulator — worked examples. For a real task, the resolver injects only the relevant node set:
| Task | Injected nodes |
|---|---|
| Add compliance-doc expiry warnings to the hauler portal | Compliance Docs API · Hauler Portal · Compliance Drawer · orbitsandboxsa Storage · Playwright Scenarios · /spec-validate |
| Wire bounce notifications through ACS email | Notifications Dispatch API · orbit-acs Email · Auth & Personas · Managed Identities · /spec-implement |
| Sync CieTrade dispatch jobs into work orders | CieTrade Sync · Work-Orders API · orbit_sandbox DB · Alembic Migrations · Work-Order State Machine · /spec-create |
D. Sandbox lifecycle — reset to promote-gate
The sandbox is a shared, always-on environment made disposable by deterministic reset rather than reprovisioning. Every guarantee in the loop — reproducibility, blast-radius containment, production data isolation — is a property of the reset + separate-server design, not a policy document.
Environment resources:
orbit-backend-sandbox— agent-operated container apporbit_sandbox @ pg-wasteology— reset + reseeded per runorbitsandboxsa— compliance docs storage (SAS)wg-pg-orbit-prod— separate prod server, Entra-only, unreachable with sandbox creds
Each phase has a hard infrastructure contract, and agents call the same orbit commands an operator would run by hand — which is what makes each phase independently auditable. The interactive companion ships a clickable lifecycle stepper mapping each phase to its contract and verifying orbit command.
E. Quality gates — symbolic + probabilistic
During spec-implement, after the agent has written the code and it has been formatted and linted — but before the commit — the ADW build runs two automated gates in order. Neither a dangling reference nor an unverified diff becomes a commit or a PR. They are a neuro-symbolic pairing: a deterministic symbolic guardrail in front of a probabilistic LLM reviewer. "Pydantic at the door, ontology at the ledger."
Step 6.6 symbolic
A deterministic, closed-world validator (ops ontology check) runs over the portfolio knowledge graph and enforces C1 · alias-uniqueness (no project id/alias claimed by two projects) and C3 · edge-referential integrity (every DEPENDS_ON / FEEDS_INTO target is a registered project). A blocking violation escalates the work item to needs_human and is never committed or turned into a PR.
Step 6.7 probabilistic
The independent Opus adversarial reviewer reads the spec, the actual diff, and the test evidence, and refuses to let unfinished or unverified work reach a PR — the maker never grades its own homework. It runs after the ontology gate passes, on Opus (never tiered below), and fails closed on any doubt.
The same ontology check is live and blocking on every pull request (not env-gated there), so violations can't merge to main even outside the ADW loop. Inside the ADW build the gate defaults OFF under ADW_ONTOLOGY_CHECK while it is dark-launched. Both gates record their catches to a metrics surface (the ontology_violations table plus an ontology_catch flag) that surfaces in the Command Center "Ontology Guardrail" Governance tab.
F. Database access matrix
| Column | Type | Purpose |
|---|---|---|
Dev | pg-wasteology / orbit_dev | Password auth · held by developer in local .env |
Sandbox | pg-wasteology / orbit_sandbox | Password auth, env-scoped · agents + CI, reset per run |
Productionrequired | wg-pg-orbit-prod / orbit_prod | Entra-only, managed identity (orbit_rw) · CI/CD SP, human-approved merge only |
Prod (operator)required | wg-pg-orbit-prod / orbit_prod | Entra token via az account get-access-token · named human operator, no stored passwords |
Prod is a physically separate PostgreSQL server (wg-pg-orbit-prod) with password auth disabled entirely (Entra-only); plus RLS policies and ORM guards inside the schema. Isolation is enforced at server, identity, and row level simultaneously.
CLI Layer — the agents run a real binary
Agents do not improvise infrastructure. Every step of the loop shells out to orbit, the Typer-based operations CLI (Spec 24) that operators run by hand: uv run orbit …. Deterministic commands in, versioned JSON out — that is what makes agent runs reproducible, auditable, and cheap to optimize.
The CLI has seven command groups — token, health, smoke, db, digest, sandbox, deploy — with global --env, --json, --yes, and --dry-run flags. Representative operations:
| Command | Purpose |
|---|---|
orbit token | Mint a persona-scoped JWT and exercise the auth round-trip |
orbit health | Assert the content-aware /health JSON status (guards against the ACA "Welcome" 200 placeholder) |
orbit smoke | Mint a token, list work orders, report counts + status breakdown as a fast baseline |
orbit db status / orbit db migrate | Report the current alembic revision / apply pending migrations (prod requires an interactive TTY confirmation) |
orbit sandbox reset | Restart the ACA revision, roll alembic base→head, seed 21 WOs. Refuses --env prod unconditionally; requires --yes to mutate; prints the plan under --dry-run |
The interactive companion ships a terminal emulator that runs these exact commands against a simulated operator surface.
Background — who runs this, and how to trigger it
Built and operated by the Wasteology platform team on the Orbit work-order system (Mars pilot). The methodology on this page is the one in daily use for shipping features to the dispatcher queue, hauler portal, and compliance workflows.
There are two primary entry points:
- GitHub issue +
adwlabel — label an issue inmars_workorder_systemand the issue-trigger workflow authors the spec, self-reviews against the 7-dimension gate, implements, and opens a draft PR. Zero local setup; a human still runs/spec-validateand reviews the sandbox before merge. /adw "<request>"in Claude Code — run from themars_workorder_systemrepo for the full-powered local loop: 7-dimension architect review with revision loops, executor implementation, and Playwright validation with video. Needsgh+azauthenticated,~/.sling/.env, Node/Python/uv, the Playwright MCP server,oh-my-claudecode, and thelatCLI.
Either way, agents own execution and recorded evidence; a human owns the merge.
Core stack: FastAPI backend · React + Vite frontend · PostgreSQL (Azure Flexible Server) · Azure Container Apps · Azure Static Web Apps · Playwright evidence capture · lat.md knowledge graphs · Claude Code agents.
See Also
- ADW Workflow — the command reference and stage-by-stage walkthrough
- Interactive ADW deep-dive — the full interactive experience (sandbox simulator, live knowledge graph, CLI emulator)
- ADW Workflow (company-wide) — the general ADW guide on the AI Tools page