Adaptive Experience Architecture (AEA)
The Plain-English Visual Guide to Harness Engineering applied to Zorg's Dungeon Maker. Canonical Reference: aea.artof.link.
"The engineers who thrive in the AI era are not the ones who write the most code. They are the ones who build the best environments for AI agents and human teams to stay honest."
1. The Core Formula in Everyday Terms
Adaptive Experience = Shared Understanding + Domain Services + Outer Harness
┌────────────────────────────────────────────────────────────────────────┐
│ 1. THE CUSTOMER / PLAYER INTERACTS │
│ Player lays out dungeon rooms, casts spells, inspects solvability │
└───────────────────────────────────┬────────────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────────────────────────┐
│ 2. THE AI INTERPRETER & LIVE NOTEPAD (Shared Understanding) │
│ • Multi-Agent Team (Claude, Gemini, OpenAI, Grok, Copilot, Kimi) │
│ • Shared Memory: Committed docs, GAME_SPEC.md, Status Ledger │
└───────────────────────────────────┬────────────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────────────────────────┐
│ 3. THE REAL-WORLD SERVICES (The Source of Truth) │
│ • Simulation Engine (@zorg/engine): Pure TS rules, 100% deterministic│
│ • Geometry & Border Validation: Side-adjacency, wall-hatch alignment│
│ • Turn Scheduler & Pathfinding: Fail-closed verification │
└───────────────────────────────────┬────────────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────────────────────────┐
│ 4. THE OUTER HARNESS (The Factory & Quality Inspectors) │
│ • Automated Governance Gates: Trace, Ledger, Findings, Docs-Graph │
│ • Independent Gatekeeper: No self-approval, required peer review │
└────────────────────────────────────────────────────────────────────────┘
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+governancechecks and an independent review.
2. The 5 Concentric Floors (Why AI Apps Break)
┌────────────────────────────────────────────────────────────────────────┐
│ 🏢 FLOOR 05: THE AGENT TEAM & GOVERNANCE (Graph Engineering) │
│ Specialized human/agent roles + Independent Reviewer (AGENTS.md §5) │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ 🔄 FLOOR 04: THE GOAL RUN & RETRIES (Loop Engineering) │ │
│ │ 1 Issue → 1 Branch → 1 Pull Request with clean budgets │ │
│ │ ┌────────────────────────────────────────────────────────────┐ │ │
│ │ │ ⚙️ FLOOR 03: THE MACHINE & TESTS (Harness Engineering) │ │ │
│ │ │ Real tools (Vitest, pnpm) + automated quality guards │ │ │
│ │ │ ┌──────────────────────────────────────────────────────┐ │ │ │
│ │ │ │ 🧠 FLOOR 02: THE MEMORY CURATOR (Context Engineering) │ │ │ │
│ │ │ │ Filters noise, preserves lessons in 4 clean vaults│ │ │ │
│ │ │ │ ┌────────────────────────────────────────────────┐ │ │ │ │
│ │ │ │ │ 💬 FLOOR 01: THE MESSAGE (Prompt Engineering) │ │ │ │ │
│ │ │ │ │ Single objective, strict pointers to AGENTS.md│ │ │ │ │
│ │ │ │ └────────────────────────────────────────────────┘ │ │ │ │
│ │ │ └──────────────────────────────────────────────────────┘ │ │ │
│ │ └────────────────────────────────────────────────────────────┘ │ │
│ └──────────────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────────┘
│
▼ Built On Real Infrastructure
┌────────────────────────────────────────────────────────────────────────┐
│ 🏛️ SOLID FOUNDATION: AWS Lightsail, Route 53, Docker, Prometheus & Grafana│
└────────────────────────────────────────────────────────────────────────┘
- 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
📖 1. Procedure Memory (Skills)
Step-by-step playbooks for repeatable workflows: build scripts, governance validation gates, and Docker launch commands.
🚫 2. Correction Memory (Constraints)
Hard rules learned from past mistakes: docs/FINDINGS.md logs every miss (CF-NNN). Upon recurrence ≥ 2, an automated sensor in CI or tests is mandatory.
🕸️ 3. Relationship Memory (Graph)
Bidirectional traceability linking GAME_SPEC.md requirement IDs (FR-xx) to engine code, Vitest suites, and docs/STATUS_LEDGER.md via [[wikilinks]].
📅 4. Daily Brief (Handoff)
A clean 1-page summary of exactly where the team left off: docs/journal/YYYY-MM-DD.md records shipped changes, probes, and pending decisions.
4. The Six Layers of the Outer Harness in Practice
1. Guides (The Rulebook)
AGENTS.md and GAME_SPEC.md loaded before any agent writes code.
2. Sensors (The Smoke Alarms)
Automated Vitest suites and 4 governance scripts catching regressions before production.
3. The Loop (The Factory Line)
Disciplined workflow: 1 task → agent/<family>/<slug> branch → PR template.
4. Memory (The Vault)
Honesty ledger, findings ledger, ADRs, and dev journal preserving institutional knowledge.
5. Permissions (The Keycard)
Branch protection on main, IAM scoped credentials, and fail-closed checks.
6. Observability (The Dashboard)
Real-time Prometheus + Grafana telemetry proving the entire system is healthy at zorg.artof.link/grafana/.