Agentic Loop Architecture

Four principles

1. 1
   Loops as first-class citizens.

   The agentic loop between systems is the unit of design. Design the loops, not just the boxes.

2. 2
   Loops run continuously.

   A loop is not a one-off. It keeps turning on its trigger, using systems and writing back again and again.

3. 3
   Loops are self-learning.

   Each turn learns from the last. The loop measures its effect and improves how it decides over time.

4. 4
   One file, real routines.

   The whole architecture is one reviewable YAML that publishes to runnable Claude Code routines.

Anatomy of a loop

id

Kebab-case identifier for the loop.

name

Human-readable name.

trigger

When it runs, a cron, an event, an ISO time, or manual. One or more.

model

The model the loop runs on.

observe

The systems the loop reads from (uses).

act

The systems the loop writes back to.

prompt

What the loop does each turn.

tools

The tools the loop is allowed to use.

Loop Storming

Loop Storming is a collaborative workshop for discovering loops, in the spirit of Event Storming. The team maps the systems, connects them into loops (what each loop uses and writes back to), names them, writes their prompts, and sets triggers. The messy wall is your initial map; you then refine it into a formal Loop Architecture YAML.

Read the Loop Storming guide →

The format

One plain YAML file with three top-level keys, id, systems, and loops. Each loop uses (observe) systems and writes back to (act) systems. A trigger is a 5-field cron, an ISO timestamp, a GitHub event, or manual.

id: your-org
systems:
  - id: dash0
    url: https://dash0.com            # favicon becomes the icon
    connector: dash0
  - id: code-repo
    repository: https://github.com/your-org/app
  - id: docs
    url: https://docs.your-org.com
loops:
  - id: triage-incidents
    name: Triage Incidents
    trigger: "*/5 * * * *"            # cron | ISO time | github event | manual
    model: claude-opus-4-8          # the model this loop runs on
    observe: [dash0]                # systems it uses
    act: [jira, slack]            # systems it writes back to
    prompt: Detect incidents; open a Jira ticket and post to Slack
  - id: sync-docs
    name: Sync Docs
    trigger:                        # one trigger, or several
      - "0 6 * * *"
      - pull_request.merged
    observe: [code-repo]
    act: [docs]
    prompt: >                     # what the loop does each turn
      Diff the docs against changes merged in the last 24h and open a PR.
    tools: [Read, Grep, Bash(gh pr *)]

Specification → JSON schema → Full example →

One file, one diagram

Because every loop names the systems it uses and writes back to, looparch renders the whole architecture as a single interactive diagram that flows left to right, sources on the left, loops in the middle, sinks on the right, a trigger icon (🕐 schedule · ⚡ event) on each. Click any system or loop for details.

looparch

A Python CLI (built with uv) to validate, visualize, and publish loops.

$ uv tool install looparch

$ looparch init your-org              # scaffold an architecture
$ looparch validate your-org.looparch.yaml    # schema + lint
$ looparch show your-org.looparch.yaml        # readable summary
$ looparch diagram your-org.looparch.yaml     # ALL loops → one diagram (SVG)
$ looparch export your-org.looparch.yaml      # → React Flow JSON (interactive)
$ looparch publish your-org.looparch.yaml     # → Claude Code routines
$ looparch import ./my-project                    # ← existing routines back to YAML

publish writes, for each loop, a slash command (.claude/commands/loop-<id>.md) and a routine descriptor (.claude/routines/<id>.json) with the loop's schedule/event, model, and repos.

CLI reference →

The example loops

The loops in the diagram above, from the example architecture:

• Triage Incidents, detect incidents from observability signals; ticket + Slack. dash0 → jira/slack
• Fix Errors, find recurring errors in the logs and open a fix PR. dash0 → code-repo
• Deploy Previews, on every commit, deploy a preview to Azure. ci-cd → app-azure
• Reconcile Infra Drift, reconcile Terraform state against running infra. infra → app-azure
• Sync Docs, keep the docs in sync with the code; daily PR. code-repo → docs
• Translate Docs, keep the German docs in sync with the English source. docs → docs-de
• Sync Confluence, keep internal runbooks in Confluence current. code-repo → confluence
• Sync Landing Page, keep landing-page copy consistent with the docs. docs → landing-page
• Answer Tickets, triage Jira tickets and draft answers from the docs. jira → jira
• Review Compliance, review ISO 27001 policies and vendor risks weekly. policies → onedrive