ktg-plugin-marketplace/plugins/ms-ai-architect/README.md

# AI Architect Plugin for Claude Code

> Your virtual Microsoft AI solution architect — meet **Cosmo Skyberg**.

![Version](https://img.shields.io/badge/version-1.7.0-blue)
![Platform](https://img.shields.io/badge/platform-Claude_Code_Plugin-purple)
![Docs](https://img.shields.io/badge/reference_docs-387-green)
![Agents](https://img.shields.io/badge/agents-12-orange)
![License](https://img.shields.io/badge/license-MIT-lightgrey)

A Claude Code plugin that provides structured architecture guidance across the full Microsoft AI stack. Cosmo Skyberg is a methodical, opinionated architect persona who understands the problem before recommending technology, verifies claims against live Microsoft Learn documentation via MCP, and delivers assessments calibrated for Norwegian public sector governance — while remaining useful for any enterprise context.

---

## Table of Contents

- [What Is This?](#what-is-this)
- [Quick Start](#quick-start)
- [Commands](#commands)
- [Agent Architecture](#agent-architecture)
- [Knowledge Base](#knowledge-base)
- [Workflow Examples](#workflow-examples)
- [Norwegian Public Sector Features](#norwegian-public-sector-features)
- [MCP Integrations](#mcp-integrations)
- [Hooks & Safety](#hooks--safety)
- [Technology Coverage](#technology-coverage)
- [Enterprise Onboarding](#enterprise-onboarding)
- [Related Plugins](#related-plugins)
- [Version History](#version-history)
- [License & Attribution](#license--attribution)

---

## What Is This?

This plugin gives you access to **Cosmo Skyberg**, a virtual Microsoft AI solution architect who guides you through structured decision-making across Azure AI Foundry, Copilot Studio, Power Platform AI, Microsoft 365 Copilot, and the broader Microsoft agent ecosystem.

Unlike a chatbot that answers questions, Cosmo follows a **7-phase advisory methodology**: understand the business need, map the technical context, assess team capability, validate against live documentation, integrate domain knowledge from 380 reference documents, deliver a concrete architecture recommendation, and optionally visualize it.

Key capabilities:

- **ROS analysis** (Risk and Vulnerability Analysis) with 7 dimensions, 49-threat AI threat library, and NS 5814/ISO 31000 methodology
- **Security assessments** with a 6-dimension × 5-level scoring rubric
- **Cost estimation** in NOK with P10/P50/P90 confidence ranges and TCO comparison
- **DPIA/PVK** aligned with Datatilsynet methodology and Norwegian regulations
- **Architecture reviews** against Digdir, EU AI Act, NSM, and Schrems II requirements
- **Full public sector utredning** (investigation report) following Utredningsinstruksen
- **ADR generation** in MADR v3.0 format
- **Live MCP verification** of all technical claims against Microsoft Learn
- **Enterprise onboarding** that tailors all recommendations to your organization

> [!TIP]
> Start with `/architect:onboard` to customize for your organization, then `/architect` for guided advisory.

---

## Quick Start

### Prerequisites

- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed
- Python with [uv](https://github.com/astral-sh/uv) (for the microsoft-learn MCP server)
- Network access to `learn.microsoft.com`

### Installation

```bash
claude plugin marketplace add https://git.fromaitochitta.com/open/ktg-plugin-marketplace.git
```

Or add to your `~/.claude/settings.json`:

```json
{
  "enabledPlugins": {
    "ms-ai-architect@ktg-plugin-marketplace": true
  }
}
```

### First Conversation

```
> /architect

Hei! Jeg er Cosmo Skyberg, løsningsarkitekt for Microsoft AI-økosystemet.

For å gi deg en god anbefaling, trenger jeg å forstå situasjonen din.
Kan du beskrive forretningsproblemet eller behovet dere ønsker å løse?
```

Cosmo will ask clarifying questions about your business need, licenses, data sources, and team capability before making any recommendations. Every recommendation is grounded in the 380-document knowledge base and verified against live Microsoft Learn documentation.

> [!NOTE]
> Run `/architect:onboard` first for organization-specific customization (~5 minutes). This is optional but makes all subsequent assessments more relevant.

---

## Commands

### Core Advisory

| Command | Description |
|---------|-------------|
| `/architect` | Start a structured architecture advisory session with Cosmo Skyberg |
| `/architect:help` | Show all commands, agents, and knowledge bases |
| `/architect:compare` | Compare Microsoft AI platforms for a given scenario |
| `/architect:research` | Explore latest updates for a Microsoft AI platform via MCP |

### Assessment & Review

| Command | Description |
|---------|-------------|
| `/architect:ros` | Risk and Vulnerability Analysis (ROS) with 7 dimensions and AI threat library |
| `/architect:security` | Security and compliance assessment (6-dimension scoring) |
| `/architect:cost` | Cost estimate with confidence grading in NOK |
| `/architect:review` | Architecture review against Norwegian public sector requirements |
| `/architect:dpia` | DPIA/PVK for an AI system with risk matrix and mitigation table |
| `/architect:license` | Map AI capabilities per license type (E3, E5, F1, G5, etc.) |

### Documentation & Output

| Command | Description |
|---------|-------------|
| `/architect:adr` | Generate Architecture Decision Record (MADR v3.0) |
| `/architect:summary` | Generate executive summary and decision memo from assessments |
| `/architect:diagram` | Generate architecture diagram with Imagen 3 or Mermaid |
| `/architect:export` | Export architecture document to PDF |

### Planning & Migration

| Command | Description |
|---------|-------------|
| `/architect:utredning` | Full AI architecture investigation for Norwegian public sector |
| `/architect:poc` | Generate POC plan with success criteria and risk assessment |
| `/architect:migrate` | Plan migration between Microsoft AI platforms |

### Setup & Maintenance

| Command | Description |
|---------|-------------|
| `/architect:onboard` | Onboard with organization-specific context (~5 min interview) |
| `/architect:generate-skills` | Regenerate knowledge base files via MCP research |

---

## Agent Architecture

The plugin delegates specialized work to 12 purpose-built agents. Each agent has its own knowledge base routing, model assignment, and tool access.

| Agent | Role | KB Sources | Triggered By |
|-------|------|------------|--------------|
| `research-agent` | MCP-isolated Microsoft Learn research | Live MCP queries | `/architect:research`, any verification need |
| `security-assessment-agent` | 6-dimension security scoring (1–5 per dimension) | ms-ai-security, ms-ai-governance | `/architect:security` |
| `cost-estimation-agent` | Cost estimation in NOK with P10/P50/P90 ranges | ms-ai-security (cost), ms-ai-advisor (cost models) | `/architect:cost` |
| `architecture-review-agent` | Review against Digdir, AI Act, NSM, Schrems II | ms-ai-governance | `/architect:review` |
| `ros-analysis-agent` | ROS analysis with 7 dimensions, NS 5814 methodology, 49-threat AI library | ms-ai-governance (ros-*), ms-ai-security | `/architect:ros` |
| `dpia-agent` | DPIA/PVK with risk matrix and mitigation table | ms-ai-governance, ms-ai-security | `/architect:dpia` |
| `adr-writer-agent` | ADR generation in MADR v3.0 format | Assessment outputs | `/architect:adr` |
| `license-mapper-agent` | Cross-reference licenses vs. platform capabilities | ms-ai-advisor | `/architect:license` |
| `diagram-generation-agent` | Architecture diagrams via Imagen 3 / Mermaid | Prompt templates | `/architect:diagram` |
| `summary-agent` | Executive summary and decision memo synthesis | All assessment outputs (incl. ROS) | `/architect:summary` |
| `onboarding-agent` | 5-phase structured org interview | Writes org/*.md | `/architect:onboard` |
| `ai-act-assessor` | EU AI Act classification, obligations, and compliance assessment | ms-ai-governance (ai-act-*) | `/architect:classify`, `/architect:requirements`, `/architect:transparency`, `/architect:frimpact`, `/architect:conformity` |

### Orchestration Pattern

For complex workflows like `/architect:utredning`, the plugin orchestrates multiple agents in parallel:

```
                    ┌─────────────┐
                    │ Orchestrator│
                    │ (utredning) │
                    └──────┬──────┘
                           │
              ┌────────────┼────────────┐
              ▼            ▼            ▼
     ┌────────────┐ ┌───────────┐ ┌──────────┐
     │  Security  │ │   Cost    │ │ Research │
     │ Assessment │ │ Estimation│ │  (MCP)   │
     └─────┬──────┘ └─────┬─────┘ └────┬─────┘
           │              │             │
           └──────────────┼─────────────┘
                          ▼
                  ┌───────────────┐
                  │   Summary +   │
                  │  Quality Check│
                  └───────────────┘
```

The orchestrator creates a `.work/` directory for intermediate results, delegates sections to specialized agents, and runs a quality check before assembling the final document.

---

## Knowledge Base

The plugin includes **387 reference documents** organized across 5 domain-specific skills:

| Skill | Domain | Refs | User Intent |
|-------|--------|------|-------------|
| `ms-ai-advisor` | Cosmo persona, 7-phase workflow, platform selection | 62 | "Help me choose" |
| `ms-ai-engineering` | RAG, agents, Azure AI Services, data, MLOps, multimodal | 153 | "How do I build this?" |
| `ms-ai-governance` | Norwegian public sector governance, EU regulations, responsible AI, ROS | 78 | "Is this legal/safe?" |
| `ms-ai-security` | Security scoring (6×5), cost estimation (P10/P50/P90) | 60 | "Is this safe?" |
| `ms-ai-infrastructure` | BCDR, hybrid/edge, sovereign cloud | 34 | "How do I operate this?" |

### ms-ai-advisor (62 refs)

Architecture decision trees, platform comparison matrices, Cosmo persona definition, cost models, migration patterns.

### ms-ai-engineering (153 refs)

RAG implementation patterns, agent orchestration, Azure AI Foundry, Copilot Studio extensibility, AI Builder, multimodal processing, Semantic Kernel, MLOps pipelines.

### ms-ai-governance (78 refs)

Norwegian public sector governance (Digdir, DFØ), EU AI Act (Annex III checklist), responsible AI frameworks, GDPR/Schrems II compliance, Utredningsinstruksen alignment. Includes a comprehensive **ROS analysis framework** with 7 new reference documents: AI threat library (49 threats across 7 categories), NS 5814/ISO 31000 methodology guide, 7×5 scoring rubrics, sector-specific checklists (health, transport, finance, justice, education), report templates, DPIA/security integration patterns, and MAESTRO multi-agent security model.

### ms-ai-security (60 refs)

6×5 security scoring rubrics, threat modeling for AI systems, content safety, cost optimization, deterministic cost calculation model, data residency patterns.

### ms-ai-infrastructure (34 refs)

BCDR planning, hybrid and edge deployment, sovereign cloud (Norway regions), network architecture, monitoring and observability.

> [!NOTE]
> All reference documents were generated and verified via the Microsoft Learn MCP server. Regenerate with `/architect:generate-skills` to refresh against current documentation. Check freshness with `bash scripts/kb-staleness-check.sh`.

---

## Workflow Examples

### 1. First-Time Setup → Platform Selection → ADR

```
/architect:onboard           # 5-min interview to capture org context
/architect                   # Guided advisory with Cosmo Skyberg
/architect:compare           # Side-by-side platform comparison
/architect:adr               # Formalize the decision as an ADR
```

### 2. Full Public Sector Investigation → Export

```
/architect:utredning         # Multi-section investigation report
                             # (orchestrates security, cost, research agents in parallel)
/architect:export            # Export to PDF with Norwegian formatting
```

### 3. ROS Analysis → Security → DPIA → Summary

```
/architect:ros               # 7-dimension risk and vulnerability analysis (NS 5814)
/architect:security          # 6-dimension security deep-dive
/architect:dpia              # DPIA/PVK for privacy risks identified in ROS
/architect:summary           # Executive summary synthesizing all findings
/architect:export            # PDF for stakeholders
```

### 4. Security Review → DPIA → Summary → Export

```
/architect:security          # 6-dimension security assessment
/architect:dpia              # DPIA/PVK with risk matrix
/architect:summary           # Executive summary synthesizing findings
/architect:export            # PDF for stakeholders
```

---

## Norwegian Public Sector Features

This plugin is specifically designed for Norwegian public sector governance requirements:

### Regulatory Frameworks

| Framework | Coverage |
|-----------|----------|
| NS 5814 / ISO 31000 | ROS analysis methodology with AI-specific extensions (7 dimensions, 49-threat library) |
| EU AI Act | Annex III high-risk checklist, conformity assessment guidance |
| GDPR / Personopplysningsloven | Data processing, DPIA alignment, Datatilsynet methodology |
| Schrems II | Data residency requirements, EU/EEA transfer assessment |
| NSM Grunnprinsipper | Security baseline for government IT systems |
| Utredningsinstruksen | Structure and methodology for public sector investigations |
| Digdir | Architecture principles, reference frameworks, digital strategy |
| Sikkerhetsloven | Classification levels and handling requirements |

### Localization

- **Cost estimates** in NOK with Norwegian tax and procurement context
- **DPIA** aligned with Datatilsynet's recommended methodology
- **Prose** in Norwegian with English technical terms where natural
- **All agents** have explicit Norwegian encoding instructions (æ, ø, å)

---

## MCP Integrations

### Required

**microsoft-learn** — Official Microsoft documentation search, fetch, and code samples.

```json
{
  "mcpServers": {
    "microsoft-learn": {
      "command": "uvx",
      "args": ["--from", "microsoft-learn-mcp", "microsoft_learn_mcp"]
    }
  }
}
```

### Optional

**mcp-image** — Imagen 3 image generation for architecture diagrams (used by `diagram-generation-agent`).

### Recommended

These MCP servers enhance the plugin's capabilities but are not required:

| Server | Purpose |
|--------|---------|
| [azure-mcp-server](https://github.com/microsoft/azure-mcp-server) | Live Azure infrastructure inspection (Storage, Key Vault, AI Search, RBAC) |
| bicep-mcp-server | Infrastructure-as-Code generation for Azure resources |
| [azure-devops-mcp](https://github.com/microsoft/azure-devops-mcp) | Work items, pipelines, repos integration |

---

## Hooks & Safety

Two runtime hooks provide session context and safety guardrails:

| Event | Script | Purpose | Behavior |
|-------|--------|---------|----------|
| `SessionStart` | `session-start-context.mjs` | Show active investigations + KB freshness | Advisory — displays context |
| `Stop` | `stop-assessment-reminder.mjs` | Remind about uncommitted assessments and next steps | Advisory — displays reminder |

> [!TIP]
> For secrets scanning across all plugins, use the [llm-security plugin](https://git.fromaitochitta.com/open/ktg-plugin-marketplace) which provides byte-level secrets detection as a blocking PreToolUse hook.

---

## Technology Coverage

| Domain | Technologies |
|--------|-------------|
| Copilot Family | Microsoft 365 Copilot, Copilot Studio, Sales Copilot, Service Copilot |
| Power Platform | Power Automate, Power Apps, AI Builder |
| Azure AI Foundry | Agent Service, Model Router, Prompt Flow, Model Catalog |
| Azure AI Services | Azure OpenAI, AI Search, Document Intelligence, Speech, Vision |
| Development | Microsoft Agent Framework, Semantic Kernel, AutoGen |
| Security | Microsoft Purview, Defender for Cloud, Content Safety |
| Infrastructure | Azure Norway regions, sovereign cloud, hybrid/edge |
| Governance | EU AI Act, GDPR, NSM, Digdir, Utredningsinstruksen |

---

## Enterprise Onboarding

### The Onboarding Agent

Run `/architect:onboard` to start a **5-phase structured interview** (~5 minutes) that captures your organization's context. The `onboarding-agent` asks targeted questions using interactive prompts and writes the answers to `org/` files that all 11 agents read automatically.

This means every subsequent command — security assessments, cost estimates, architecture reviews, DPIAs — is calibrated to your specific organization without repeating context.

### The 5 Phases

#### Phase 1: Organization Profile

Captures sector (government, healthcare, education, etc.), organization name and description, size, and applicable regulations (GDPR, Sikkerhetsloven, Arkivloven, Forvaltningsloven, etc.).

#### Phase 2: Technology Stack

Maps your cloud platforms (Azure, M365, Power Platform, hybrid), license type (E3, E5, G3, G5, etc.), and AI services currently in use.

#### Phase 3: Security & Compliance

Records data classification levels, data residency requirements (Norway, Nordics, EU/EEA), DPIA practice maturity, and security certifications/frameworks in place.

#### Phase 4: Architecture Decisions

Captures preferred AI platform, integration targets (M365, SharePoint, Dynamics, SAP, custom APIs), and annual AI budget range.

#### Phase 5: Business References

Documents AI governance model (centralized, decentralized, hybrid CoE), preferred document formats, and existing reference architecture or strategy documents.

### How It Works

```
/architect:onboard              # Start the interview
                                # Agent asks questions with interactive prompts
                                # Answers are saved to org/*.md files (gitignored)
                                # Resume anytime — completed phases are skipped

/architect:onboard --status     # Check which phases are completed
```

The `org/` directory is in `.gitignore` — your organizational context stays local and is never committed to the repository.

**Automatic detection:** The plugin automatically checks onboarding status at session start and displays a reminder if setup is missing or incomplete. No configuration needed — the check runs via the SessionStart hook.

### Deployment Patterns

| Pattern | Description |
|---------|-------------|
| **Individual** | Developer installs plugin, runs onboarding, uses for personal advisory |
| **Team** | Shared `org/` files (copy between machines or use shared config) |
| **Organization-wide** | Pre-populated `org/` files distributed as part of standard developer setup |

### Knowledge Base Customization

For organizations that need deeper customization beyond what onboarding provides:

| What to Customize | Where | How |
|-------------------|-------|-----|
| Security scoring thresholds | `skills/ms-ai-security/references/` | Edit scoring rubric files |
| Regulatory requirements | `skills/ms-ai-governance/references/` | Add org-specific governance docs |
| Cost models / pricing | `skills/ms-ai-security/references/cost-optimization/` | Update NOK rates and assumptions |
| Architecture patterns | `skills/ms-ai-engineering/references/` | Add org reference architectures |
| Platform preferences | `skills/ms-ai-advisor/references/` | Adjust decision tree weights |

### Requirements & Constraints

- **Platform:** macOS and Linux. Windows support planned.
- **MCP dependency:** The `microsoft-learn` MCP server must be configured for live documentation verification.
- **KB freshness:** Reference documents reflect Microsoft Learn state at time of generation. Regenerate with `/architect:generate-skills` periodically.

---

## Related Plugins

### LLM Security Plugin

The **[LLM Security Plugin](../llm-security)** is a companion plugin that covers the agentic AI attack surface — the runtime security dimension that complements this plugin's architecture-level assessments.

While **ms-ai-architect** evaluates *what to build* (platform selection, compliance, cost, risk), the LLM Security Plugin evaluates *whether what you built is safe to deploy* by scanning Claude Code plugins, MCP servers, and AI agent configurations against the OWASP LLM Top 10.

| Capability | ms-ai-architect | llm-security |
|------------|----------------|--------------|
| Architecture guidance | `/architect` | — |
| Security assessment (6-dimension) | `/architect:security` | — |
| ROS analysis (NS 5814) | `/architect:ros` | — |
| DPIA/PVK | `/architect:dpia` | — |
| Plugin/agent supply chain scan | — | `/security scan` |
| MCP server audit | — | `/security audit --mcp` |
| Pre-deploy security gate | — | `/security posture` |
| Deep-scan (7 deterministic scanners) | — | `/security deep-scan` |
| Runtime hook protection | — | Automated via hooks |

> [!TIP]
> A recommended workflow: use `/architect:security` for architecture-level risk assessment, then `/security scan` on the implemented solution to catch supply chain and runtime vulnerabilities before deployment.

---

## Testing

Three levels of automated testing ensure plugin integrity:

| Suite | Command | Checks |
|-------|---------|--------|
| **Static validation** | `bash tests/validate-plugin.sh` | Frontmatter, encoding, KB references (176 checks) |
| **KB freshness** | `bash scripts/kb-staleness-check.sh` | Stale reference documents by age |
| **E2E regression** | `bash tests/run-e2e.sh` | Agent output structure, encoding, domain validation (4 suites) |

### E2E Regression Tests

Fixture-based structural validation of agent outputs without invoking Claude. Tests verify that generated assessments have correct markdown structure, valid scores, proper encoding (UTF-8 with Norwegian characters), and domain-specific content.

```bash
# Run all E2E suites
bash tests/run-e2e.sh

# Run individual suites
bash tests/run-e2e.sh --security    # Security assessment agent (17 checks)
bash tests/run-e2e.sh --cost        # Cost estimation agent (13 checks)
bash tests/run-e2e.sh --summary     # Summary agent (13 checks)
bash tests/run-e2e.sh --ros         # ROS analysis agent (24 checks)

# Capture new fixtures from a completed investigation
bash tests/capture-fixture.sh <source-file> <section-header> <output-dir>
```

### Knowledge Base Maintenance

The plugin includes a systematic process for keeping reference documents current. See `docs/kb-update-policy.md` for the full policy (update frequencies per domain, procedures, quality gates).

**Staleness checking:**

```bash
# Human-readable report
bash scripts/kb-staleness-check.sh

# Machine-readable JSON output
bash scripts/kb-staleness-check.sh --json

# Write report to file
bash scripts/kb-staleness-check.sh --json --output report.json
```

**Knowledge base regeneration:**

```bash
# Full regeneration via MCP research
/architect:generate-skills

# Incremental update (Edit existing files instead of rewriting)
/architect:generate-skills --update
```

Category-to-skill routing is defined in `scripts/skill-gen/category-skill-map.json` (20 categories mapped to 5 skills), used by the generate-skills workflow to place new reference documents in the correct skill directory.

---

## Version History

| Version | Date | Highlights |
|---------|------|-----------|
| **1.6.0** | 2026-02-19 | ROS analysis command and agent (`/architect:ros`) — 7-dimension risk assessment with NS 5814/ISO 31000 methodology, 49-threat AI threat library, sector-specific checklists (health, transport, finance, justice, education), MAESTRO multi-agent security model, 7 new KB reference documents (3,131 lines), E2E test suite (24 checks), summary-agent integration |
| **1.5.0** | 2025-02-13 | E2E regression tests (43 checks across 3 suites), auto onboarding detection at session start, systematic KB update process with staleness policy and `--json` output |
| **1.4.0** | 2025-02-13 | Onboarding agent (5-phase structured interview), README rewrite to English |
| **1.3.0** | 2025-02-13 | 5-skill migration (1 monolithic skill → 5 domain-specific with 364 refs), 13 broken KB reference fixes, encoding fixes |
| **1.2.0** | 2025-02-13 | Runtime hooks (secrets detection, session context, stop reminders), test infrastructure (hook tests, KB integrity, plugin discovery), PDF export command |
| **1.1.0** | 2025-02-13 | Summary agent, DPIA agent, utredning orchestrator v2, production readiness (21 fixes) |
| **1.0.0** | 2025-02-12 | Initial release — 20 knowledge bases, 8 agents, architecture-review-agent, Cosmo Skyberg persona |

---

## License & Attribution

This project is licensed under the [MIT License](LICENSE).

Reference material in `skills/*/references/` is adapted from [Microsoft Learn](https://learn.microsoft.com) documentation, licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). Content has been translated to Norwegian, reorganized, and augmented with original analysis for Norwegian public sector context.

Code samples from Microsoft Learn are used under the [MIT License](https://opensource.org/licenses/MIT).

The plugin architecture, Cosmo Skyberg persona, decision methodology, and governance analysis are original work.

See [NOTICE.md](NOTICE.md) for full attribution details.

> Microsoft product names are trademarks of Microsoft Corporation. This project is not endorsed by or affiliated with Microsoft.