# AI Architect Plugin for Claude Code

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

> **Solo-maintained, fork-and-own.** This plugin is a starting point, not a vendor product. Issues are welcome as signals; pull requests are not accepted. See [GOVERNANCE.md](GOVERNANCE.md) for the full model and what upstream provides.

*AI-generated: all code produced by Claude Code through dialog-driven development. [Full disclosure →](../../README.md#ai-generated-code-disclosure)*

![Version](https://img.shields.io/badge/version-1.11.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

Add the marketplace and browse plugins with `/plugin`:

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

Or enable directly in `~/.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 are generated and verified via the Microsoft Learn MCP server. A weekly cron job (`scripts/kb-update/weekly-kb-cron.mjs`) automatically polls Microsoft Learn sitemaps for changes, updates stale files via MCP research, and commits to the repository. Last full update: April 2026. Manual refresh: `/architect:generate-skills --update`.

---

## 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.

---

## Playground (v3)

Interactive **decision-builder + report viewer** for Microsoft AI architecture decisions, runnable from `file://` without a server. Replaces the v2 5-step pipeline with a multi-surface app that persists state across sessions and visualizes parsed reports inline.

- **File:** `playground/ms-ai-architect-playground.html` (~3870 lines, single-file v3 architecture)
- **4 surfaces:** Onboarding (18 shared fields) → Home (project list + 3 entry tracks) → Catalog (24 commands grouped by 5 expansion categories with search) → Project (per-project tabs, command form prefill, paste-back report import + visualization)
- **Persistent state:** IndexedDB primary store with localStorage fallback. Schema-versioned (`STATE_KEY = 'ms-ai-architect-state-v1'`) with eager `MIGRATIONS` pipeline.
- **17 report renderers:** Each report-producing command has a parser (markdown → structured) and renderer (structured → HTML visualization: pyramid, matrix, radar, findings, distribution, capability-matrix, etc.) wired through a canonical archetype-routing table.
- **Theme:** Dark default + light mode toggle, persisted in `localStorage('ms-ai-architect-theme')`. Both themes ship Aksel-aligned tokens (full WCAG AA contrast) as of v1.10.0; theme-bootstrap script in `<head>` prevents FOUC.
- **Export/import:** JSON Decision Record envelope (Blob + FileReader), schema-version-aware on import.

### v1.10.0 — Foundation refactor (felles grunnskjelett)

All 17 report renderers now wrap output through `renderPageShell()` for a consistent visual signature:

- **Foundation helpers** — `renderPageShell()`, `renderVerdictPill()`, `renderKeyStatsGrid()`, `inferVerdict()`, `inferKeyStats()` provide the shared header/eyebrow/h1, optional 5-band verdict-pill, and 3-5 key-stats grid that every renderer can opt into.
- **Schema v1→v2 migration** — eager `MIGRATIONS` pipeline (idempotent via `dataVersion=2` guard) backfills `verdict` and `keyStats` on existing reports without disrupting existing user state.
- **Tier 3 component adoption** — kanban (conformity, review), mat-ladder (migrate, poc), screen-tabs (utredning, project surface), scenario-card-grid (license, compare), residual-pair (dpia, ros), top-risks (ros), recommendation-card (security, ros), suppressed-panel (review), critique-card (adr), read-more (utredning, summary), traffic-light (poc).
- **Parser extensions** — `parsePhasedPlan` adds `phases[].status` + `currentPhaseIndex` + `pocVerdict`; `parseComparison` adds `winner` field; `parseMatrixRisk` is shared across dpia + ros via `_consumer` discriminator (Strategy A).
- **Onboarding redesign** — exactly 4 structured fields (select / multiSelect for sector, regulations, license, scenarios) + 14 free-text fields with placeholder hints. Improves prefill flexibility while keeping enum-driven fields where they matter.
- **Theme tokens** — `[data-theme="light"]`-block added to `shared/playground-design-system/tokens.css` (and re-synced to vendored copy) with verbatim Aksel values. WCAG AA contrast in both themes.

```bash
# Run playground locally
open plugins/ms-ai-architect/playground/ms-ai-architect-playground.html
```

### v1.11.0 — Design-system 100%-adoption

The playground now consumes the shared `playground-design-system` v0.3.0 end-to-end — no parallel CSS, minimal inline overrides, visual upgrade benchmarked against the showcase scenarios:

- **Hoisted to shared DS (v0.3.0)** — 13 generic components moved from inline `<style>` to `shared/playground-design-system/components-tier3-supplement.css`: `.eyebrow`, `.page__*`, `.key-stats`/`.key-stat`, `.verdict-pill-lg`, `.tab-list`/`.tab`/`.tab-panel`, `.top-risks`/`.top-risk[data-severity]`, `.recommendation-card`, `.card__*` subcomponents, `.card--severity-{level}`, form-patterns, `.stack-lg/-md/-sm`, `.pyramide-tier-detail`, `.scenario-card-grid`/`.scenario-card[data-status="winner"]`, `.app-shell` variants. Re-synced to vendored DS via `scripts/sync-design-system.mjs ms-ai-architect`.
- **PARALLEL CSS migration** — all 6 plugin-local naming groups renamed to DS conventions: `.topbar* → .app-header*`, `.residual-pair* → .pair-before-after*`, `.command-card*` / `.catalog-card* → .card + .card__*`, `.screen-tabs/-tab/screen → .tab-list/.tab/.tab-panel`, `.pyramide-desc* → .pyramide-tier-detail*`. ~50 markup occurrences updated across CSS + JS strings.
- **Inline `<style>` trim** — block reduced 202 → 127 lines (~37%). `renderPageShell` + `renderKeyStatsGrid` refactored to DS markup (`.page__header-main` + `.page__header-aside`, `.key-stat--{level}` BEM modifiers).
- **Visual upgrade (benchmarked against showcase)** — AI Act pyramid width fix (min-width 480px, font-size-md, responsive breakpoint), severity-coded left border on report cards in project surface based on `parsed.verdict`, app-header restructure (brand + breadcrumb + spacer + actions), eyebrow-label "PROSJEKTER · X av X" on home, `.stack-lg` vertical rhythm on home/project/catalog body.
- **Plugin-local survivors (intentional)** — `.verdict-pill` (domain go/block semantics, distinct from DS `.verdict-pill-lg` severity bands), `.scenario-card[data-status="met/partial/missing"]` (DS only ships "winner"), `.read-more-block` + `.suppressed-panel` (native `<details>`; DS uses JS-toggled `aria-expanded`), surface-specific layouts (`.onboarding-*`, `.home-*`, `.project-*`, `.modal*`, `.command-form*`).

### Demo data (one-click)

Click **"Last inn demo-data"** on the onboarding screen to bootstrap a complete demo:

- 18 onboarding fields prefilled for "Acme Kommune" (Norwegian municipality, deployer, high-risk AI Act)
- One demo project ("Acme: Kunde-chatbot") with all 17 reports pre-imported as `raw_markdown`
- Visualizations rehydrate automatically when the project surface mounts

This lets you explore every renderer, theme, and surface without any setup. The inline demo state is built by `scripts/build-demo-state.mjs` from `playground/test-fixtures/*.md`. To regenerate after fixture changes:

```bash
node scripts/build-demo-state.mjs
```

### Screenshot gallery

Screenshots of every surface in both themes live in `playground/screenshots/v1.11.0/` (the v1.10.0 set is preserved as historical reference). They are committed so forkers see what the plugin produces without running anything:

| # | File | What you see |
|---|------|--------------|
| 01 | `01-onboarding-empty-{dark,light}.png` | Onboarding surface, empty state |
| 02 | `02-project-rapporter-regulatory-{dark,light}.png` | All 6 regulatory renderers (classify pyramid, requirements, transparency, FRIA, conformity kanban, DPIA matrix) |
| 03 | `03-project-rapporter-security-{dark,light}.png` | 6×5 + 7×5 risk matrices, radar, top-risks, residual-pair, recommendation-card, review kanban |
| 03 | `03-project-rapporter-economy-{dark,light}.png` | Cost distribution P10/P50/P90, license capability matrix |
| 03 | `03-project-rapporter-documentation-{dark,light}.png` | Migrate mat-ladder, ADR critique-card, summary read-more, POC traffic-light, utredning screen-tabs, compare scenario-cards |
| 03 | `03-project-rapporter-tool-{dark,light}.png` | 7 tool commands (no report — pipeline-string builders) |
| 04-06 | `04-project-oversikt-{dark,light}.png` etc. | Project screen-tabs (oversikt / kontekst / eksport) |
| 07 | `07-home-{dark,light}.png` | Home with project list + 3 entry tracks |
| 08 | `08-catalog-{dark,light}.png` | Catalog with 24 commands in 5 expansion-grupper |
| 09 | `09-onboarding-prefilled-{dark,light}.png` | Onboarding with state from demo |

Regenerate via `cd tests/screenshot && npm install && npx playwright install chromium && node run.mjs`.

### Validation

| Test | Command | Coverage |
|------|---------|----------|
| Static structure | `bash tests/test-playground-v3.sh` | 201 PASS — vendored CSS, surfaces, 24 commands, 14 parsers, 17 renderers (felles grunnskjelett), design-system classes, action handlers, Tier 3-bruk, onboarding field-distribution |
| Parser fixtures | `bash tests/test-playground-parsers.sh` | 70 PASS — 17 fixtures × parser routing |
| Migrations | `bash tests/test-playground-migrations.sh` | 7 PASS — v1→v2 idempotent migration |
| Combined (E2E) | `bash tests/run-e2e.sh --playground` | static + parser suites |
| Manual a11y QA | See `playground/MANUAL-CHECKLIST.md` + `playground/A11Y-RAPPORT.md` | 10 sections incl. axe-core run per surface |

### Vendored design-system

The playground loads CSS from `playground/vendor/playground-design-system/` — a vendored copy of the marketplace-root `shared/playground-design-system/`. This keeps the plugin **standalone**: copy the plugin folder anywhere and the playground still works.

- **Sync:** `node scripts/sync-design-system.mjs ms-ai-architect` (run from marketplace root)
- **Drift detection:** `MANIFEST.json` records SHA-256 per file. Re-sync refuses to overwrite files modified locally — pass `--force` to override.
- **Generated header:** Each vendored CSS file is prefixed with `/* Code generated by sync-design-system.mjs; DO NOT EDIT. */`. Edit `shared/`, then re-sync.

---

## 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 387 reference documents are actively maintained by the plugin author. Updated reference files are published as regular commits to the marketplace repository. If you installed via `claude plugin marketplace add`, updates are pulled automatically — no manual action needed.

The plugin includes a sitemap-based change detection system that tracks when Microsoft Learn source pages are updated, ensuring the author is always aware of which reference files need refreshing.

**Automated change detection (sitemap-based):**

```bash
# Weekly update: poll sitemaps → compare → generate change report
node scripts/kb-update/run-weekly-update.mjs --force

# Include discovery of new relevant pages
node scripts/kb-update/run-weekly-update.mjs --force --discover

# View change report only (after polling)
node scripts/kb-update/report-changes.mjs
```

The session-start hook automatically triggers a background poll if >7 days since the last check.

**How it works:**
1. `build-registry.mjs` extracts 1342 unique `learn.microsoft.com` URLs from reference files
2. `poll-sitemaps.mjs` fetches Microsoft Learn sitemaps and compares `<lastmod>` dates
3. `report-changes.mjs` generates a prioritized list of files needing update
4. `discover-new-urls.mjs` finds relevant new pages not yet covered

**Knowledge base update:**

```bash
# Incremental update based on change report (targets changed sources via MCP)
/architect:generate-skills --update

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

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.11.0** | 2026-05-04 | Design-system 100%-adoption — 13 generic components hoisted to shared playground-design-system v0.3.0, all PARALLEL CSS names migrated to DS conventions, inline `<style>` block trimmed 37% (202 → 127 lines), severity-coded card borders on report cards, app-header restructure with breadcrumb, `.stack-lg` body spacing across home/project/catalog, AI Act pyramide width fix. Demo state renamed to "Acme Kommune" + "Acme: Kunde-chatbot" for cross-fixture consistency. 24 v1.11.0 screenshots regenerated. 278/278 playground E2E PASS. |
| **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.
