Humans own the specification. Agents own the execution and the evidence.
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.
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.
Pipeline Metadata
- Target Environment
- Orbit Sandbox (Isolated)
- Validation Suite
- playwright-validator agent
- Artifact
- RESULTS.md + chaptered recording
Architectural warning: 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.
Trigger the loop yourself
A faithful mock of the Orbit orchestrator. Pick a feature request or type your own, then trigger the agentic loop. Watch the five stages transition, then stall deliberately at the human gate. The agents never promote on their own.
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 |
Design invariant: 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 expand resolves 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 search does semantic lookup and lat check validates every link, so the working context stays small and provably correct.
Context Injection Properties
Design properties of the injection step, not benchmarked metrics.
-
lat expand
resolves [[refs]] to only the sections a task touches
-
lat search
semantic lookup finds the same sections for the same request
-
lat check
validates every wiki link and code ref before injection
Why it matters: 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
Click any node to read its full document card. Use the scenario buttons below the graph to watch the resolver in action: each scenario highlights the exact node set the orchestrator would inject for that task.
Graph Composition
Node Types
Context Injection Simulator
Select a real task from the platform. The resolver highlights exactly which nodes it would inject and shows the token cost reduction versus injecting the full graph.
D. Sandbox Lifecycle: Reset to Promote-Gate
The sandbox is a shared, always-on environment made disposable by deterministic reset rather than reprovisioning. It is reset + reseeded to identical state per run, driven through an agent session, and gated by a human at the end. 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.
Each phase below has a hard infrastructure contract. Clicking any stage shows the contract and the orbit command that verifies it. Agents call the same commands an operator would run by hand, which is what makes each phase independently auditable.
Environment Resources
-
orbit-backend-sandbox - agent-operated container app
-
orbit_sandbox @ pg-wasteology - reset + reseeded per run
-
orbitsandboxsa - compliance docs storage (SAS)
-
wg-pg-orbit-prod - separate prod server, Entra-only, unreachable with sandbox creds
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. The ontology gate deterministically catches a class of “impossible-in-our-domain” errors — dangling references and duplicate aliases — that are hard to catch by prompt or LLM review alone.
Constraints Enforced
-
C1 · alias-uniqueness - no project id/alias claimed by two projects
-
C3 · edge-referential integrity - every DEPENDS_ON / FEEDS_INTO target is a registered project
Ontology constraint gate
A deterministic, closed-world validator (ops ontology check) runs over the portfolio knowledge graph and enforces C1 and C3. A blocking violation escalates the work item to needs_human and is never committed or turned into a PR.
Maker-checker verifier
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.
Live vs. dark: 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.
F. Database Access Matrix
| Environment | Server | Schema | Auth Method | Credential Holder |
|---|---|---|---|---|
| Dev | pg-wasteology | orbit_dev | password | Developer, local .env |
| Sandbox | pg-wasteology | orbit_sandbox | password env-scoped | Agents + CI; reset per run |
| Production | wg-pg-orbit-prod | orbit_prod | Entra-only, managed identity (orbit_rw) | CI/CD service principal; human-approved merge only |
| Prod (operator) | wg-pg-orbit-prod | orbit_prod | Entra token via az account get-access-token | Named human operator; no stored passwords |
Defense in depth: 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.
The agents run a real binary
Agents do not improvise infrastructure. Every step of the loop shells out to orbit, the Typer 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. Try it below.
try a command:
The terminal is a faithful simulation of the operator surface. Agents call these exact versioned commands, which is why a run is reproducible: the same task resolves to the same context set, and the promotion gate rejects any actor that is not an authenticated human merging on GitHub.
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 entry points. Label a GitHub issue adw in mars_workorder_system — the issue-trigger workflow authors the spec, self-reviews against the 7-dimension gate, implements, and opens a draft PR. Or run /adw "<request>" in Claude Code from the repo. Either way, agents own execution and recorded evidence; a human owns the merge.
Domain
Work-order operations platform (Orbit)
Proof of work
Recorded evidence gate + live spec tracker
Discipline
Spec-first, evidence-gated delivery
Automation
Claude Code multi-agent orchestration
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