microsoft / microsoft/hve-core

feat(agents): C4 Notation Builder — author and maintain C4 model diagrams as notation-as-code

Open
#2,523 6 comments 0 reactions 1 assignee Claimed by @Salazander View on GitHub
needs-triage
Dominant language
Python
Stars
1.5k
Forks
301
Avg merge
3d 3h
Merged PRs (30d)
92

Description

### Custom Agent Name

/c4-notation-builder

### Type

Custom Agent

### Purpose

Architects need to produce and keep C4 model diagrams (Context, Container,
Component, Code) in sync with architecture decisions as a system evolves.
Today this requires manually applying C4 conventions, picking a notation,
and keeping each level consistent with the others and with recorded ADRs —
there is no guided, notation-aware workflow for this in the
`project-planning` collection.

This agent would be used whenever an architect needs to author or update a
C4-levelled diagram from architectural intent (a conversation, an ADR, a
requirement) rather than from static analysis of deployed infrastructure.

Open question for maintainers: this collection already ships an
`architecture-diagrams` skill (referenced in the reuse map discussed in
#2041) and a `system-architecture-reviewer` agent. Before this is
implemented, I'd like confirmation on how much C4-specific coverage those
already provide, so this either fills a genuine gap or becomes an extension
of the existing skill instead of a new agent — happy to be redirected if
it's the latter.

### Requirements

- Support all four C4 levels (Context, Container, Component, Code) with
level-appropriate guidance (e.g., flagging that Code-level diagrams go
stale quickly).
- Support authoring in Structurizr DSL, C4-PlantUML, or Mermaid C4,
defaulting to whichever notation is already used in the repository.
- Edit existing diagrams in place, preserving unrelated elements and
relationships, rather than regenerating from scratch.
- Cross-check generated/edited diagrams against existing ADRs and surface
conflicts instead of silently resolving them.
- Clearly differentiated from (or merged into) `architecture-diagrams` and
`system-architecture-reviewer`, per maintainer feedback.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.