§ Methodology

Four-Layer Architecture

Every project passes through all four layers in strict order. Skipping layers means failures in production.

§ Overview

Most agent failures come from rushing to implementation. We solve this by forcing every project through four sequential layers: visual architecture, operational contracts, technical diagrams, and only then — implementation.

Layer I

Miro

Layer II

Notion

Layer III

Mermaid

Layer IV

Hermes

§ The Four Layers

Inside Each Stage

Layer I

› Miro

Visual Architecture

Every agent begins as a visual system on a Miro board. 10 standardized frames cover identity, triggers, workflow, tools, permissions, retrieval logic, failure handling, approval gates, metrics, and Hermes file mapping. Nothing moves forward until the flow is absolutely clear.

Produces ◆ Agent identity, workflow flow, decision points, approval gates, tool overview, permission boundaries

── Contents ──

  • 01Agent Brief
  • 02Trigger & Input Map
  • 03Core Workflow
  • 04Tools & Contracts Overview
  • 05Data, Memory & Permissions Map
  • 06Retrieval & Evidence Flow
  • 07Failure, Retry & Fallback Map
  • 08Human Approval & Risk Gates
  • 09Metrics, Logs & Testability
  • 10Hermes File Mapping

Layer II

› Notion

Contracts & Documentation

Once the visual architecture is locked, we translate it into precise operational rules. Four databases work together: Agent Registry (command table), Agent Spec Database with Master Template (full specification), Tool Contract Library (standardized tool rules), and Test & Incident Database (quality history).

Produces ◆ Detailed agent specification, tool contracts, permission matrices, test scenarios, incident tracking

── Contents ──

  • 01Agent Registry — 13 columns, high-level overview
  • 02Agent Spec + Master Template — 18 columns + 10 detailed sections
  • 03Tool Contract Library — 15 columns, one row per tool
  • 04Test & Incident Database — 11 columns, quality tracking

Layer III

› Mermaid

Technical Diagrams

Mermaid diagrams formalize and verify consistency between visual architecture and operational documentation. Three mandatory diagrams for every agent ensure no logical gaps survive into implementation.

Produces ◆ Workflow diagram, sequence diagram, state diagram, consistency verification

── Contents ──

  • 01Workflow — what the agent does step by step
  • 02Sequence — who communicates with whom and in what order
  • 03State — run lifecycle (queued → running → completed / failed / partial_success / no_results / needs_approval)

Layer IV

› Hermes

Implementation

Only after three layers of design, documentation, and verification do we write implementation files. Nothing is invented from scratch — every file is derived from the previous three layers.

Produces ◆ SOUL.md, AGENTS.md, USER.md, MEMORY.md, skill files, prompt files, .env, config.yaml

── Contents ──

  • 01SOUL.md — identity, tone, boundaries
  • 02AGENTS.md — project context, roles, handoff logic
  • 03USER.md — user preferences, output style
  • 04MEMORY.md — memory rules, what to store/forget
  • 05skills/ — procedural skill modules
  • 06.env — API keys, secrets
  • 07config.yaml — model, provider, runtime settings

§ Disciplines

Seven Non-Negotiable Checks

Every design must satisfy all seven. If one is weak — the design is not ready.

№ 01

System Design

Is the architecture clear and scalable?

№ 02

Tool & Contract Design

Are inputs and outputs explicit?

№ 03

Retrieval Engineering

How does the agent find information?

№ 04

Reliability Engineering

What happens when something fails?

№ 05

Security & Safety

Does it have only the permissions it needs?

№ 06

Evaluation & Observability

Can behavior be measured and diagnosed?

№ 07

Product Thinking

Does it solve a real problem?

§ Next Step

Want to see this methodology applied to your business?

Book an Architecture AuditRead the Lab