ads-copilot: Skill for Claude Code

Architecture Diagramming Skill

This skill provides diagram generation conventions and patterns for Architecture Design Sessions. It is domain-agnostic — the domain skill (e.g., Databricks, Fabric, AWS) supplies the domain-specific components, while this skill supplies the diagramming methodology, style guide, and generic architecture patterns.

Dual-Diagram Workflow

Every ADS session produces two architecture diagrams:

1. Current State Diagram (after Phase 2 — Current Landscape)

Purpose: Capture the existing environment as-is so both parties share a common baseline.

What to include:

• All systems, services, and platforms mentioned by the user
• Integrations and data flows between systems
• Pain points annotated as comments or styled nodes
• Team/ownership boundaries (if discussed)

Template structure:

---
title: Current State Architecture
---
flowchart LR
  subgraph EXT["External Systems"]
    %% Sources, SaaS, partners
  end

  subgraph CURRENT["Current Platform"]
    %% Existing systems, databases, compute
  end

  subgraph CONSUME["Consumers"]
    %% BI tools, applications, users
  end

  %% Data flows between subgraphs
  EXT --> CURRENT --> CONSUME

Rules:

• Label the diagram clearly as "Current State Architecture" in the title.
• Do NOT include future-state components — this is a snapshot of today.
• Present to the user and explicitly ask: "Does this accurately capture your current environment? Anything missing or incorrect?"
• Do NOT proceed to Phase 3 until the user confirms the current state.

2. Future State Diagram (Phase 5 — Future State Diagram Generation)

Purpose: The recommended target architecture based on all gathered requirements.

Template structure:

---
title: Future State Architecture
---
flowchart LR
  subgraph SRC["Data Sources"]
    %% Sources identified in discovery
  end

  subgraph PLATFORM["Target Platform"]
    %% Core platform components
    %% Grouped by layer: ingestion, processing, storage, serving
  end

  subgraph SEC["Security & Identity"]
    %% Security components
  end

  subgraph CONSUME["Consumers"]
    %% BI, applications, APIs
  end

  %% Data flows
  SRC --> PLATFORM --> CONSUME
  SEC -.->|governs| PLATFORM