Adaptive Experience Architecture (AEA)

The Plain-English Visual Guide to Harness Engineering applied to Zorg's Dungeon Maker. Canonical Reference: aea.artof.link.

Same split as the architecture page: spec and docs are shared memory; packages/engine decides outcomes ([[NFR-1]]); apps/web is the Maker; this site explains.

flowchart LR
  spec["GAME_SPEC + docs"]
  engine["packages/engine"]
  maker["apps/web — Maker"]
  site["apps/knowledge — this site"]
  spec --> engine
  spec --> site
  engine --> maker

1. The Core Formula in Everyday Terms

flowchart TB
  player["Layer 1 — Player interacts<br/>Places rooms, casts spells, inspects solvability"]
  shared["Layer 2 — Shared Understanding<br/>Multi-agent team + committed docs, GAME_SPEC, Status Ledger"]
  domain["Layer 3 — Domain Services<br/>@zorg/engine decides — geometry, scheduler, fail-closed checks"]
  harness["Layer 4 — Outer Harness<br/>Governance gates + independent peer review, no self-approval"]
  player --> shared --> domain --> harness

The Three Golden Rules

• AI Interprets, Domain Services Decide: AI agents suggest room placements and spell tactics, but only @zorg/engine's deterministic rules engine decides path validity, damage, and victory conditions.
• Fail-Closed Availability: If solvability or layout verification cannot be proven, the engine reports unverified (Unknown) rather than claiming success. It is far better to fail closed than to promise an invalid dungeon.
• No Self-Approval: The agent or human that writes code is never the one who signs off on pushing it to production. Every PR requires passing ci + governance checks and an independent review.

2. The 5 Concentric Floors (Why AI Apps Break)

flowchart TB
  subgraph f05["05 Graph — agent team and governance"]
    subgraph f04["04 Loop — 1 issue, 1 branch, 1 PR"]
      subgraph f03["03 Harness — Vitest, pnpm, quality guards"]
        subgraph f02["02 Context — memory curator, 4 vaults"]
          f01["01 Prompt — the message<br/>One objective, pointers to AGENTS.md"]
        end
      end
    end
  end
  found["Foundation — Lightsail, Route 53, Docker, Prometheus and Grafana"]
  f05 -->|"built on"| found

Outer floors wrap inner ones: graph roles and independent review, then the 1-issue / 1-branch / 1-PR loop, then Vitest and pnpm guards, then the four memory vaults, then a single AGENTS.md-pointed prompt. The stack sits on the live host.

• The Dependency Law: If your multi-agent team keeps failing, don't blame the agents—check your memory filter. Bad input on Floor 2 ruins everything above it.
• The Economic Law: Swapping the AI model (switching between Claude, Gemini, DeepSeek, or OpenAI) takes 1 afternoon. Rebuilding your 5-floor operational harness takes 3 months. The harness is your real intellectual property.

3. The "Second Brain": 4 Clean Memory Vaults

4. The Six Layers of the Outer Harness in Practice