feat(agents): add visual-communicator persona for technical mermaid diagrams#897
feat(agents): add visual-communicator persona for technical mermaid diagrams#897danielmeppiel wants to merge 4 commits intomainfrom
Conversation
…iagrams Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
danielmeppiel
force-pushed
the
feat/visual-communicator-agent
branch
from
cbd487b to
27357a2
Compare
There was a problem hiding this comment.
Pull request overview
Adds a new reusable visual-communicator persona to the APM agent catalog, intended to standardize creation and critique of technical Mermaid diagrams (including an ASCII-only constraint for labels).
Changes:
- Add new
visual-communicatoragent definition under.apm/agents/and its generated mirror under.github/agents/. - Update
apm.lock.yamlto include the new deployed agent and its content hash. - Add an Unreleased changelog entry for the new agent.
Show a summary per file
| File | Description |
|---|---|
apm.lock.yaml |
Adds the new .github/agents/visual-communicator.agent.md to deployed files and updates hashes. |
CHANGELOG.md |
Adds an Unreleased/Added entry for the new agent. |
.github/agents/visual-communicator.agent.md |
Generated agent persona content for Mermaid diagram design/review. |
.apm/agents/visual-communicator.agent.md |
Source-of-truth agent persona content (mirrored into .github/). |
Copilot's findings
- Files reviewed: 4/4 changed files
- Comments generated: 1
| - `visual-communicator` agent: world-class technical visual communication persona specialized in Mermaid diagrams. (#897) | ||
| - CI: add `APM Self-Check` to `ci.yml` for `apm audit --ci`, regeneration-drift validation, and `merge-gate.yml` `EXPECTED_CHECKS` coverage. (#885) |
There was a problem hiding this comment.
Changelog entries must end with a real PR number. Please replace the placeholder (#TBD) with the actual PR number before merge to match the repo's Keep a Changelog + SemVer rules.
| existing diagram for clarity, fidelity, or chartjunk. | ||
| model: claude-opus-4.6 | ||
| --- | ||
|
|
There was a problem hiding this comment.
Too verbose, leverage the PROSE principles to refactor wisely (mainly reduce the length smartly) with apm's primitive architect skill that you must use. Pin to opus 4.7, not 4.6.
There was a problem hiding this comment.
Done in 12b8ba8. Applied PROSE principles via the primitives-architect agent -- reduced from 218 to 117 lines (46%): removed the redundant "When to activate" section (duplicated frontmatter), collapsed the self-check checklist (every item already in "Communication discipline"), and folded the ASCII rule into the discipline bullet list. Model is now claude-opus-4.7. The .github/agents/ mirror and apm.lock.yaml hash are updated; apm audit --ci passes clean.
Agent-Logs-Url: https://github.com/microsoft/apm/sessions/44054472-be12-47b0-b45b-f5002575bf54 Co-authored-by: danielmeppiel <51440732+danielmeppiel@users.noreply.github.com>
…ciples Apply Reduced Scope, Progressive Disclosure, and Explicit Hierarchy to cut the agent definition from 218 to 117 lines (46% reduction) while preserving all meaningful semantic content. Key changes: - Remove 'When to activate' section (duplicates frontmatter description) - Remove 'Self-check before you ship' (restates discipline rules) - Merge 'ASCII-only inside diagrams' into Communication discipline - Compress 'Composition with apm-review-panel' into Boundaries - Tighten Mermaid type list and anti-patterns - Drop sankey-beta (unstable GitHub support) - Update model from claude-opus-4.6 to claude-opus-4.7 - Sync .github/agents/ generated copy Co-authored-by: danielmeppiel <51440732+danielmeppiel@users.noreply.github.com>
… to opus-4.7 Agent-Logs-Url: https://github.com/microsoft/apm/sessions/44054472-be12-47b0-b45b-f5002575bf54 Co-authored-by: danielmeppiel <51440732+danielmeppiel@users.noreply.github.com>
Summary
Adds a new reusable APM persona,
visual-communicator, specialized in producing Mermaid diagrams for technical audiences. The persona is anchored on the official Mermaid documentation and Edward Tufte's principles of graphical excellence; it cites PROSE constraints (Reduced Scope, Progressive Disclosure, Explicit Hierarchy) and follows APM's ASCII-only encoding rule inside diagram syntax and label text.The persona is NOT added to the apm-review-panel roster in this PR; it is available as a standalone agent invokable on demand. A future change may promote it to a conditional panelist if visual-review demand justifies it.
Scope
.apm/agents/visual-communicator.agent.md.github/agents/visual-communicator.agent.md(byte-identical mirror viaapm install --target copilot)apm.lock.yaml(new agent entry + hash)Why
Forthcoming Epic on drift detection / lockfile per-asset granularity needs first-class Mermaid diagrams (producer-produced map, drift-detection architecture, PR landscape, design-phase workflow). Hand-rolling diagrams ad hoc loses consistency. Promoting this expertise to a reusable persona makes future architectural narratives composable.
Verification
apm install --target copilotproduces clean mirror.apm audit --cipasses (run after install).