meta-diagram-triangulation

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: meta-diagram-triangulation
description: "Scan a target codebase path, classify the most informative diagram kind, then render it as BOTH a PlantUML source file AND a draw.io XML in parallel, and compose them into a single architecture doc. Use when writing an RFC or onboarding doc and you want a text-friendly (PlantUML) and an editable (drawio) view of the same architecture."
kind: meta
meta_priority: 55
always: false
triggers:
  - "diagram triangulation"
  - "triangulate diagrams"
  - "架构三视图"
  - "出双视图架构图"
provenance:
  origin: opensquilla-original
  license: Apache-2.0
composition:
  steps:
    - id: scan_repo
      kind: agent
      skill: history-explorer
      with:
        task: |
          Scan the target path identified in the user's invocation for
          architectural structure. Extract:
            * Top-level modules / packages under the target path
            * Inter-module import dependencies (who imports who)
            * Hotspot files (most-changed in the last 90 days)
            * Public surface: classes, functions, protocols exported via __init__.py

          User invocation (target path is somewhere in this string):
          {{ inputs.user_message | xml_escape | truncate(400) }}

          Reply with a structured summary, max 1500 chars:
            ## Target path
            <resolved absolute path>

            ## Modules (top-level)
            - <module/>: <one-line description>

            ## Dependencies
            <module> → <module>
            ...

            ## Hotspots
            - <file>: <commit count last 90d>

            ## Public surface
            - <ClassName>: <one-line role>
    - id: classify_kind
      kind: llm_classify
      depends_on: [scan_repo]
      output_choices:
        - class
        - sequence
        - component
        - deploy
        - flow
      with:
        task: |
          Based on this codebase scan, which diagram kind is most informative
          for an architecture doc? Pick ONE of:
            - class: data structures / OO hierarchy dominant
            - sequence: cross-module call flows dominant
            - component: module-level boxes + arrows dominant
            - deploy: infra / process layout dominant
            - flow: data pipeline / staged processing dominant

          Scan output:
          {{ outputs.scan_repo | truncate(1500) }}
    - id: render_plantuml
      kind: agent
      skill: sub-agent
      depends_on: [scan_repo, classify_kind]
      with:
        task: |
          Generate a PlantUML diagram source of kind `{{ outputs.classify_kind }}`
          from this codebase scan. Use idiomatic PlantUML syntax bracketed by
          `@startuml` ... `@enduml`. Aim for 10-20 boxes/arrows; do not over-render.

          Scan output:
          ---
          {{ outputs.scan_repo | truncate(2000) }}
          ---

          Write the source to: `{{ inputs.workspace_dir }}/diagrams/arch.puml`
          (create parent dir if missing; overwrite OK).

          Reply with the absolute output path on a single line, no preamble.
    - id: render_drawio
      kind: agent
      skill: sub-agent
      depends_on: [scan_repo, classify_kind]
      with:
        task: |
          Generate a draw.io XML diagram of kind `{{ outputs.classify_kind }}`
          from this codebase scan. Use valid draw.io XML:
            <mxfile><diagram><mxGraphModel><root>
              <mxCell id="0"/><mxCell id="1" parent="0"/>
              <mxCell id="N" value="..." style="..." vertex="1" parent="1">
                <mxGeometry .../>
              </mxCell>
              <mxCell ... edge="1" source="..." target="..." parent="1">
                <mxGeometry .../>
              </mxCell>
            </root></mxGraphModel></diagram></mxfile>

          Aim for 10-20 boxes/edges to mirror the PlantUML side; layout can be
          simple grid since the user is expected to re-arrange in draw.io.

          Scan output:
          ---
          {{ outputs.sca