Architecture overview
The loop is five layers. You author the first two; the engine owns the rest.
| Layer | What it is | Who authors it |
|---|---|---|
| Pipeline | One pipeline.yaml declaring the stage graph: agent steps, mechanical command gates, verdict routing, retry loops, and per-step isolation. |
You |
| Agent prompts | Markdown prompt files with YAML frontmatter (<name>.agent.md) defining each agent's role, rules, sandbox notes, and tools. |
You |
| Sandbox | Every agent shell and command step runs in a Docker container: no network access by default, writes only to declared mounts:, and no .git - steps run against a fresh export. If no sandbox is available, the run stops instead of degrading. |
Engine |
| Dev image | The digest-pinned dev image pulled on first run. The supply-chain check refuses to continue on a digest mismatch. | Engine |
| Extensions | Optional plugins: your own actions, tools, and document loaders, loaded from outside the workspace. | You (optional) |
Every run is crash-safe (interrupt and resume from the exact checkpoint), watchable in a live browser graph view with a browsable run history, and gated: nothing gets committed until every stage passes. The fixed policies are part of the product - fail fast on missing config or secrets, no silent fallbacks, verdicts only from artifacts, bounded retries, and a single clean-worktree-gated commit point.
What a run looks like
The shipped self-loop example is the canonical shape: an agent works, a mechanical gate verifies, two verdict agents review, and a single host-side action commits.
flowchart LR
dev["agent: dev"] --> test{{"test gate"}} --> review["agent: review"] --> qa["agent: qa"] --> commit["action: commit"]
test -- fail --> dev
review -- fail --> dev
qa -- fail --> dev
- dev - the dev agent works with full context (loaded docs + shared files).
Its edits are untracked; only declared
produces:files are hygiene-tracked. - test - a mechanical command step runs the suite inside the sandbox.
Exit 0 moves on; anything else rewinds to
devwith the failing output. - review / qa - verdict agents finish by calling the
record_verdicttool; the validated tool call routes the graph.failrewinds todevand consumes an attempt. - commit - the single commit point fires only when all gates passed and the worktree was clean at start.
- success - committed; or failure when attempts are exhausted.
Host boundary (security model)
The orchestrator, tool layer, and the commit action run in the host process
- they hold your credentials and your full user account, so the engine keeps
anything agent-writable out of that process:
- Consumer actions are sandbox-executed. An action you register via an
extension is a command-shaped script (
script + params), run through the same sandbox path as command steps. Only the engine's trusted built-ins (commit, document loaders) run host-side. - Extensions load from outside the workspace. Any extension or tool module whose file resolves under the workspace is refused before import, naming the file.
- The engine installs outside the workspace. Install with pipx so the
venv is unmounted from the sandbox; a startup self-check refuses to run if
agentic_dev_loopresolves under the workspace. - Tooling is read-only by the loop. At run start the pipeline file,
agents_dir,additional_files,aidlc-docs/, andtools/must be git-clean relative to HEAD, and thecommitaction excludes those paths from its sweep, so the loop never commits its own tooling. commitstays host-side, deliberately. It holds push credentials and runs argv-style with a scrubbed child env and a hooks override, so repo hooks never execute.
Net: the host executes nothing from the workspace, reads only git-clean control files, and the only agent-writable host-consumed thing left is the code the loop is building.