Architect diagram

Skill: architect-diagram

Produce Mermaid diagrams that survive enterprise wiki rendering and stay readable at a glance. Structural discipline (boundaries, technology labels, trust zones) beats pretty.

Output rendering

Diagram / flow — For relationships or flow, emit a fenced ```mermaid block (it renders in chat and artifacts). If the surface is terminal-only, fall back to an ASCII box-and-arrow sketch.

Mode detection — pick one at entry

Read the user's message and route once. Don't ask the user to flag intent.

Signal	Mode
Vague idea, no code or paths in scope. "Draw me how a checkout flow could look."	design
Repo path, file list, or "the system as it is today" in scope.	document
Diagram pasted into the conversation + "is this ok / what's wrong".	review
Existing diagram + a diff request ("add a caching layer", "remove X").	update

If two modes plausibly fit, ask once which the user wants.

• design — generate from the user's words. Fabricate component names only where the user hasn't named one; flag fabrications.
• document — read the code or paths first; only diagram what is actually there. Never invent names.
• review — quick rubric pass against references/diagram-rubric.md; if the user wants severity-tagged findings, route to the architect-review skill (if installed) for the full critique.
• update — apply the requested diff. Surface side-effects the user didn't ask for (orphaned nodes, broken trust boundaries).

Procedure

1. Route by mode (above). For document mode, read before drawing.

2. In document or update mode — extend "read the repo" to "read the landscape." Only in these two modes, and only when the as-is system integrates beyond the repo boundary and an internal knowledge-retrieval surface is reachable this session (an enterprise-knowledge MCP tool, an internal CLI, an in-repo doc set — public web does not count), load references/knowledge-surfaces.md and consult the descriptive current-system facets (current landscape, interfaces, operational reality) to ground the beyond-repo boxes, arrows, and edge labels. Name what you drew from (the surface, or "repo only / none"). A node or edge you can't ground stays <unnamed> or becomes a question — never a guess (this strengthens the never-fabricate-names rule below); a surface-derived edge the repo contradicts is flagged, not silently drawn over. This step does not apply in design mode (you're drawing the user's hypothetical — fabrication is allowed-but-flagged) or review mode (route to architect-review).

3. Pick the notation from intent. Always load references/notation-routing.md — it carries the intent → notation decision table, the split-when-too-big rule, and the don't draw cases (comparison, checklist, two-component flow).

4. Load the syntax reference for the chosen notation — references/mermaid-{flowchart,sequence,c4,state,er,gitgraph,gantt}.md, one file per notation, on demand. For the three newer product/roadmap grammars, load references/mermaid-{timeline,quadrant,mindmap}.md — each carries the rendering caveat, the table/bullet-list fallback, and the per-type complexity budget. For C4 Container drafts, the starter shape is in assets/c4-container.mmd.

5. Load cross-cloud patterns for any cloud-aware diagram. Load references/cloud-patterns.md whenever the diagram crosses cloud boundaries — boundary stack, public-vs-private subnets, async vs. sync edges, trust-boundary labeling, storage shapes. Then layer the vendor-specific reference:

   • Any AWS / Azure / GCP service — or a primitives provider (Hetzner and its class) → load references/cloud-<cloud>.md (incl. cloud-primitives.md) for boundary vocabulary, subgraph nesting, and gotchas. Multi-cloud → load multiple references.
   • Agentic platform named → load references/agentic-<platform>.md (bedrock-agentcore, ai-foundry, vertex-agent-engine). A diagram of AgentCore is not "AWS with a Lambda in it".

6. Draft the diagram inline. Default to flowchart TB with subgraph nesting and emoji or text markers — renders cleanly in GitHub, Confluence, Azure DevOps Wiki, and GitLab. Only if the user's target renderer is known to support it, mention Mermaid's newer architecture-beta syntax as an alternative — load references/mermaid-architecture-beta.md for the trade-offs and skeleton before offering. Do not default to it; rendering is inconsistent across enterprise wikis. To apply a theme, layout, or look within the diagram itself, use Mermaid's YAML frontmatter block (Mermaid ≥ 10.5, mmdc v11+):

   ---
   config:
     theme: base        # default | forest | dark | neutral | base
     layout: elk        # dagre (default) | elk — see mermaid-flowchart.md for venue caveats
     look: handDrawn    # classic (default) | handDrawn
   ---
   

   look: handDrawn signals "draft / not final" — offer it for informal design artifacts, never default to it for documentation-grade diagrams. The frontmatter and %%{init}%% produce identical output; prefer frontmatter when setting two or more keys. When the diagram distinguishes more than one category of thing or relationship, load references/visual-encoding.md — map each visual channel (shape, grouping, position, edge style, marker) to meaning by data type, and keep colour as reinforcement only, never the sole carrier.

7. Self-check against references/diagram-rubric.md. Fix violations before showing the user. The non-negotiables: every Container has a technology label; no bare relation labels; fits one screen (≤15 nodes); document mode never fabricates names; trust boundaries are visible (dashed subgraph border or explicit comment). Also scan for {} in %% comment text — Mermaid silently breaks on curly braces inside comments. Verify no token is misspelled: the parser fails silently on unrecognised keywords, producing a blank diagram with no error.

8. Offer to save — config-driven. Resolve the output directory following the config-driven, two-branch elicitation procedure in references/agentbundle-layout.md. Resolution order: (1) repo-root ./agentbundle-layout.toml [architecture] output_dir — repo-scope takes priority; (2) user-profile ~/.agentbundle/agentbundle-layout.toml [architecture] output_dir; when neither resolves, two-branch elicitation runs — never a silent default: (a) Repo branch — suggest docs/design/ and offer to write output_dir to ./agentbundle-layout.toml [architecture]; (b) Personal/vault branch — ask for an absolute path (e.g. ~/Documents/<VaultName>/design/) and write to ~/.agentbundle/agentbundle-layout.toml [architecture]. Resolve to a full absolute path (~-expand, realpath-resolve, reject .. escapes); surface the resolved path before writing. Suggest a kebab-case .mmd filename inside the resolved directory. Saving is an offer, never automatic.

Anti-patterns to refuse

• Drawing without naming the trust boundary. A cross-account or cross-tenant arrow without a labeled boundary is a security hazard rendered as art. Add the boundary, then draw.
• Picking the notation the user named when the intent disagrees. If the user asks for a "sequence diagram" of what talks to what, the right answer is a Container view. Push back; offer both.
• Defaulting to architecture-beta because it looks nicer. Enterprise wikis render flowchart consistently; architecture-beta is uneven. Mention it as an option, not the default.
• Fabricating service or component names in document mode. Read the code; if a name isn't there, mark the node <unnamed> or ask.