A tech-stack-agnostic reference architecture and machine-enforced harness for building reliable AI agent loops.
Loop Engineering Architecture is a blueprint for agentic loops that keep working — an autonomous plan → execute → verify → stop cycle where a deterministic orchestrator owns control flow and an LLM worker (Codex, Claude, or any CLI) only makes judgments. It synthesizes the community consensus around 12-Factor Agents, LangChain's Loop Engineering, and Harness Engineering into one runnable repo.
The single source of truth for design principles, mechanics, and the growth path is docs/architecture.md — this README is the folder map and the front door.
In-depth docs (architecture, ADRs, phases) are currently written in Korean; this English README is the entry point for international readers.
LLM agents drift, loop forever, and silently skip verification. This repo makes the control loop itself the engineered artifact rather than an afterthought:
- Deterministic orchestrator, not a prompt.
loop/run.shis a state machine (PLAN → EXECUTE → VERIFY → STOP). It handles state transitions, retries, escalation, and stop conditions in code — the LLM decides only what to do next (12-Factor #8: own your control flow). - Machine-verifiable stop conditions. Turn/token budgets and timeouts live in
config/limits.yamland are enforced, not suggested. - Maker/checker separation. Every ticket carries a deterministic
verifycommand; a VERIFY gate runs it before any work is accepted. Failures are fed back as context and retried within a bounded limit, then escalated to a human handoff. - File-based state bus. All cross-session and cross-agent state lives in the repo (
state/) — survives context compaction and restarts, stays human-inspectable, and turns git history into an audit log. No database, no queue. - Contract enforcement via hooks. A Stop hook (
scripts/check-loop-contract.sh) mechanically rejects turns that change files without updating progress, mutate append-only decision records, or touch the human-gated objective function. - Portable by design.
dist/loop-bootstrap.mdis a self-contained instruction file that installs this whole architecture into any project.
The VERIFY gate treats worker-authored verify commands as untrusted input: by default it blocks
shell control characters (chaining, pipes, command substitution, redirection) so a prompt-injected or
untrusted ticket cannot escape the worker sandbox into host code execution
(ADR-012). Opt back into raw shell with verify_allow_shell: true.
| Folder | Purpose |
|---|---|
config/ |
Model parameters and loop limits (turn/token budgets, timeouts = stop conditions) |
prompts/ |
System prompts and reusable fragments. Version-controlled artifacts |
agents/<name>/ |
Agent definitions: prompt + config + responsibility doc |
tools/<name>/ |
Tools: I/O schema (contract) + implementation + tests. Schema and impl kept separate |
loop/ |
Core loop control: cycle, stop conditions, state serialization, error compaction |
state/ |
Shared runtime state: PLAN.md, PROGRESS.md, task queue, handoffs, checkpoints |
context/ |
Context engineering: retrieval, compaction, cross-session memory |
verification/ |
Runtime verification loop: rubrics + graders. Feedback re-injected on miss |
evals/ |
Offline evaluation: datasets + graders + run results |
traces/ |
Execution transcripts (gitignored, only representative samples committed) |
triggers/ |
Entry points: CLI, cron, webhook |
skills/<name>/ |
Reusable procedural knowledge (SKILL.md pattern) |
scripts/ |
Helpers: trace analysis, eval runners, contract checks |
docs/PRD.md |
Why it's built — the longest-lived intent context |
docs/architecture.md |
Structure and mechanics (living doc) — the detailed explanation |
docs/phases/ |
Milestone contracts: per-phase scope + completion criteria |
docs/decisions/ADR.md |
Decision records — decision/rationale/tradeoff, append-only |
docs/specs/ |
Feature specifications |
tests/ |
Unit/integration tests for the harness itself |
bootstrap/ · dist/ |
Bootstrap instruction source · build output dist/loop-bootstrap.md — installs this architecture into any project |
- docs/architecture.md — design principles, doc hierarchy, orchestration, the loop contract, and the growth path.
- AGENTS.md — working instructions for agents (and humans); the session startup procedure.
- docs/decisions/ADR.md — why each decision was made, with tradeoffs.
loop/run.sh drives an autonomous cycle; the worker CLI is injectable
(WORKER_CMD / worker_cmd, defaults to codex exec). See triggers/cli.md for
the unattended loop vs. interactive session split.
# preview resolved config and the next action, no side effects
loop/run.sh --dry-run
# run the loop (bounded by config/limits.yaml)
loop/run.sh --max-turns 30MIT © hhamja