architect-diagram

name	architect-diagram
description	Generate an interactive HTML architecture diagram (`diagram.html`) with drill-down navigation and Comment Mode. If architecture artifacts already exist, render from them; if not, first run architect-init to discover the repo and create the artifacts.

Use this skill to render diagram.html from architecture artifacts. Before rendering, always check whether the required artifacts already exist. If they do not exist, hand off to architect-init first, using the same output root and repo scope, then resume rendering after architect-init produces the artifacts.

Inputs

• output root path, usually the current repo root
• generated architecture artifacts, when present:
  • architecture/manifest.yaml
  • architecture/model.yaml
  • architecture/views/*.yaml
  • architecture/summary.md
  • optional architecture/diff.yaml

Outputs

Required:

• <output-root>/architecture/diagram.html (primary)

Recommended intermediate output:

• <output-root>/architecture/.out/diagram-svg/<view-id>.svg (one per non-sequence view)

Optional debug output:

• <output-root>/architecture/.out/diagram-data.json (when --write-data-json is enabled)

Runtime state (managed by the bridge):

• <output-root>/architecture/.out/claude-comments.json — persisted Claude-authored comment threads. Source of truth for the bidirectional comments surface. Read by render-diagram-html.py at render time and embedded into the diagram handoff; mutated only by the bridge in response to channel tool calls or user reply POSTs.

Channel surface (architect-comments)

The architect-comments MCP channel exposes these tools:

• update_feedback_status — progress updates for user-submitted feedback batches.
• finalize_feedback_update — validate artifacts + rerender after Claude-authored edits.
• post_claude_comment — open a new Claude-authored thread anchored to a specific view/element/relationship. Use during plan mode for genuine design questions.
• post_claude_reply — reply into an existing thread, optionally with resolves=true to close on reply or silent_resolve=true to resolve without writing a message.
• resolve_thread — silently resolve a thread without posting a reply.

The channel delivers two event types to Claude:

• architect_feedback_batch — user submitted a batch of comments. May include open_thread_ids + open_thread_summary for threads the user did not reply to in this batch. Claude must not act on those threads this turn.
• architect_thread_user_reply — the user replied into a specific Claude-authored thread. Claude should use post_claude_reply (not finalize_feedback_update) to respond.

Hard Rules

• Do not invent architecture facts.
• Source all content from provided artifacts.
• Do not generate architecture artifacts directly in this skill. If artifacts are missing or incomplete, invoke architect-init; architect-diagram only resumes once artifacts exist.
• Preserve exact IDs and paths from source artifacts.
• diagram.html must remain a single-file artifact with inline CSS/JS; external assets are disallowed except for the approved Instrument Sans Google Fonts links when that typography path is intentionally used.
• diagram.html must implement drill-down + breadcrumb navigation.
• diagram.html must implement Comment Mode (Comment toggle + C shortcut + queued comments + JSON submit modal).
• Do not render confidence labels directly on canvas/SVG; show confidence in details sidebar only.
• Details sidebar behavior:
  • collapsed by default
  • auto-expands on node click
  • manual collapse control in sidebar
• By default, do not generate diagram-prompt.md in this skill.
• If user asks for upload bundle generation, use architect-diagram-prompt.
• Sequence diagrams are disabled by default. Include sequence only when explicitly requested.
• Person/actor nodes must render as the same rectangular card family used by other nodes, with sufficient padding for label text.
• Do not render person nodes as oversized head-and-body pictograms or circle-over-rectangle figures.
• When a person/actor subtype label is shown inside a node, prefer compact inline copy like [👤 User].
• Visible relationship arrows should use lighter strokes than node borders; keep the visual stroke subtle while preserving large invisible hit targets for comment-mode interaction.
• Header-band geometry and person-card header positioning currently have two owners: authored SVG output in scripts/generate-svg-fragments.py and browser-side normalization in templates/diagram-app.html. If you adjust header band size, label alignment, or person-card header placement, update both paths.

Rendering approach

Primary path (preferred):

1. Generate styled SVG fragments from architecture artifacts:
   • python3 ${CLAUDE_PLUGIN_ROOT}/scripts/generate-svg-fragments.py --output-root <output-root>
2. Inject fragments into template app:
   • python3 ${CLAUDE_PLUGIN_ROOT}/scripts/render-diagram-html.py --output-root <output-root> --demo-mode

Fallback/testing path:

• If explicitly requested for quick iteration, allow fallback renderer:
  • python3 ${CLAUDE_PLUGIN_ROOT}/scripts/render-diagram-html.py --output-root <output-root> --mode fast

Sequence behavior

Default:

• sequence views are excluded from render payload/tabs.

Opt-in (explicit request only):

• pass --include-sequence to render-diagram-html.py

Workflow

1. Resolve <output-root>:
   • use the user-provided output root when supplied
   • otherwise use the current repository/workspace root
2. Run artifact preflight before rendering:
   • check for <output-root>/architecture/manifest.yaml
   • check for <output-root>/architecture/model.yaml
   • check for at least one <output-root>/architecture/views/*.yaml
   • check for <output-root>/architecture/summary.md
3. If any required artifact is missing:
   • invoke architect-init against the same repo/output root
   • if some artifacts exist, tell architect-init to treat this as update/recovery mode and preserve stable IDs where concepts are unchanged
   • after architect-init finishes, restart this workflow from artifact preflight
   • if the repo/output root cannot be inferred, ask one focused question for the repo path instead of guessing
4. Read contracts/specs:
   • references/diagram-output-contract.md
   • references/html-diagram-spec.md
   • references/svg-fragment-spec.md
5. Load architecture artifacts under <output-root>/architecture/.
6. Generate SVG fragments under <output-root>/architecture/.out/diagram-svg/.
7. Render architecture/diagram.html via template injection.
8. Validate:
   • ${CLAUDE_PLUGIN_ROOT}/scripts/validate-diagram-html.sh <output-root>/architecture/diagram.html
9. Return path and summary of what was rendered.

Completion Standard

Complete only when architecture/diagram.html exists, is grounded in artifacts, and passes validation.