lyther/agent-surface/arch-diagram

Objective

Build or refresh one evidence-backed architecture model, expressed through the smallest set of views that answers the audience's questions. Leaders should grasp purpose, shape, differentiators, scale, and material risks without reading the repository; developers should navigate from a system view to deployable units, runtime and data paths, source symbols, failure behavior, and operational boundaries; reviewers should tell observed, implemented, inferred, proposed, and unknown apart. Keep editable source in the repository and render and inspect what people consume: invented architecture fails, and so does correct source that renders as an unreadable wall. Rationale and sources: references/research-basis.md.

Input

Scope (whole system, subsystem, service, feature, journey, incident path, proposed change); audience (leadership, engineering, operations, security, combined); focus (landscape, runtime, data, deployment, dependency, trace, all); state (as-is, to-be, delta); delivery (docs, presentation, interactive, combined); tool (auto or a named available renderer).

Defaults: whole system, as-is, leadership plus engineering, all, docs plus presentation, auto, output in docs/diagrams/ (preserve an existing diagrams-as-code layout). Answer from repository evidence; ask only when audience, scope, or current-versus-proposed state is ambiguous and a wrong choice would materially change the result.

Evidence

Never put credentials or unrelated private repository content in a diagram or ledger. Re-ground on the live checkout. Treat the canonical architecture and concept docs, existing diagrams, and prose as claims, and verify them against runtime traces, service catalogs, deployment inventory, or a reproducible probe; entry points, module boundaries, API contracts, schemas, migrations, event definitions, configuration, and IaC; tests that exercise real paths; and runbooks.

Before laying out views, record a ledger in the repository's existing architecture model, else in docs/diagrams/evidence.md (no bespoke format unless it drives generation or validation). Per important element and relationship: stable ID reused across views; kind (person, system, container, component, process, datastore, queue/topic, deployment node, code symbol); short responsibility; technology when relevant; status; evidence (file and line, symbol, contract, IaC resource, sanitized trace or span, command, environment observation); freshness (Git revision, observation date, environment for runtime evidence); notes (assumption, contradiction, owner, proof limit).

Statuses: OBSERVED (current runtime trace, inventory, or reproducible probe), IMPLEMENTED (current source, config, contract, schema, or IaC), INFERRED (reasoned, not established; give the reasoning), PROPOSED (future design, never styled as current), UNKNOWN (missing or contradictory evidence). Static evidence proves structure, not runtime frequency, latency, reachability, or end-to-end success. Sanitize runtime evidence: no secrets, tokens, personal data, or private endpoints in diagrams.

Views

Draw what exists unless the state is to-be or delta. Derive every view, leadership and engineering alike, from one model: reuse IDs, names, relationship semantics, and evidence; prefer the repository's modelling source when it can derive views, and with a diagram-oriented tool keep one shared terminology and ledger. Move from orientation to selected detail; never mix abstraction levels in one view or draw a giant graph. A delta uses paired or filtered views with stable placement and explicit added, changed, removed, and unchanged marks; never imply proposed components exist.

Before authoring, write a view plan and delete or merge any view without a distinct question:

A whole-system atlas needs at least an orientation view, a representative value trace, and enough runtime, data, and deployment detail to substantiate the story; omit categories that do not exist and say why in the index.

Leadership storyboard, when leadership or presentation delivery is in scope, using only frames that advance the story: orientation (users, boundary, ecosystem, owned outcome); value path (one defining journey across the architecture); why this shape (decision, leverage, scale mechanism, or differentiator); trust and resilience (material boundary, failure containment, recovery, ownership); change, only when requested (truthful as-is/to-be delta with trade-offs and open decisions). Each frame states a sentence-length takeaway readable without narration, fits the target slide without zooming, pushes detail to notes or a linked engineering view, and keeps its traceability and uncertainty.

Engineering views, chosen by question: landscape/context (actors, boundary, external systems, ownership, relationship intent); runtime/container topology (deployable units, stateful resources, async infrastructure, protocols, ownership); journey trace; data lifecycle (origin, validation, transformation, storage, publication, retention or deletion, trust boundaries); deployment/resilience (environments, zones, routing, scaling units, single points of failure, failover, rollback, observability); dependency/blast radius (generated or filtered when large). Add a state machine only for a lifecycle whose invalid transitions, retries, or terminal states matter, and a component/code view only for a complex, risky, or decision-relevant boundary it explains better than source navigation, preferably generated and linked to symbols. Security and operations audiences get a perspective or filtered overlay on the same base view (trust zones, sensitive data, controls, ownership, health, SLOs, failure domains), never a second model.

Traces

A trace answers a concrete question ("How does a submitted order become a durable, externally visible result?"), not a call transcript. For each journey:

1. Name the trigger, actor, preconditions, expected outcome, and completion evidence.
2. Follow the real entry point to durable state or an external effect, reusing model IDs and linking developer-facing nodes to source files, symbols, API or event schemas, or infrastructure definitions.
3. Label each hop with operation plus protocol or invocation type; for data, the payload or entity and meaningful transformations.
4. Show authentication and authorization, trust-boundary crossings, transaction boundaries, and ownership changes when relevant, and async causality (producer, topic, consumer, correlation, delivery semantics, idempotency, retry, dead-letter) only where evidence supports it.
5. Include the highest-value failure or recovery branch: timeout, partial write, duplicate delivery, dependency failure, rollback, compensation, or degraded mode.
6. Mark the observability anchors (span, metric, log or event, alert, audit record) that prove or diagnose the path.
7. State whether the trace is OBSERVED, reconstructed from IMPLEMENTED evidence, or partly INFERRED; a static call graph, mocked run, fixture, or diagram name is not runtime proof.

Prefer one representative happy path plus one critical exception; split long journeys at meaningful boundaries and link the continuation.

For each important data flow, distinguish source, process, store, queue, stream, or sink, named data on every directed edge, validation and transformation, owner and system of record, sensitivity, trust, network, tenant, or privilege boundaries, retention, deletion, replication, and backup when material, and failure, replay, deduplication, reconciliation, and consistency behavior. Never hide topic-level coupling, ownership, or distinct data paths behind a generic bus or database box, and never mix dependency and data-flow arrows unless they look distinct and the legend explains them.

Tools

Use the repository's established, reproducible toolchain when it can produce the artifact; otherwise pick the simplest available tool that meets the model, view, and rendering needs (auto does not mean Mermaid):

Use one primary renderer; add a second only for a specialized view it materially improves, and record why. When the optional archify skill is installed and delivery is interactive or presentation-grade, use its renderer and validation commands, but keep architecture discovery and evidence classification here. Never add an unreviewed hosted dependency or upload private architecture; use an external renderer only when the workflow requires it, sending the minimum input and no credentials. Follow the project's dependency-risk policy and pin the rendering version. Mermaid-only: explicit frontmatter or config, a consistent theme, and ELK for non-trivial layered flow when supported. With no suitable renderer, finish the source and report rendered acceptance BLOCKED.

Visual Rules

• One visual grammar: stable shapes per element type, a restrained semantic palette (owned, external, stateful, proposed/unknown, risk), and text, shape, or line pattern carrying meaning so color is never the only carrier; contrast sufficient for the rendered target.
• One direction per view: left-to-right for journeys, top-to-bottom for hierarchy.
• Direct relationship labels matching arrow direction, protocols on inter-process edges; short responsibility text in nodes, details in notes or the ledger.
• Consistent names and positions across related views, especially as-is/to-be pairs; labeled official icons only when they aid recognition, never icon-only nodes.
• Every standalone view has a legend, diagram type, scope, state, and expanded acronyms.
• Icons, gradients, animation, and specialized renderers are conditional tools, never a substitute for content.
• Keep important paths continuous and minimize crossings, bends, and reverse-flow edges; when routing tangles, labels must shrink, or the primary path stops dominating, filter or split instead of enlarging the canvas.
• Presentation frames are 16:9 unless the user names another target, with title, takeaway, and primary path legible at final size; engineering views may be large or interactive but need a clear start point and navigable links.

Output

Adapt to an existing layout. For a new atlas:

docs/diagrams/
  README.md                 # audience routes, view catalog, freshness, known gaps
  evidence.md               # model/evidence ledger and contradictions
  source/                   # editable .dsl/.d2/.dot/.puml/.mmd sources and shared style/config
  rendered/                 # reviewed SVGs; PNG/PDF only where the consumer needs them
  presentation/             # optional storyboard, notes, PPTX/PDF, or progressive frames