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

# AI Architect Plugin

Microsoft AI Solution Architect plugin for Claude Code.

## Hva denne pluginen gjør

Tilbyr strukturert arkitekturveiledning for Microsoft AI-stakken:
- Azure AI Foundry, Copilot Studio, M365 Copilot
- Power Platform AI (AI Builder, Power Automate)
- Microsoft Agent Framework
- Sikkerhet og compliance
- EU AI Act-klassifisering og compliance

## Regulatorisk arbeidsflyt

`/architect:classify` → `/architect:dpia` (Art. 13/14 input) → `/architect:ros` (dimensjon 6 input)

## Kommandoer

| Kommando | Beskrivelse |
|----------|-------------|
| `/architect` | Start en strukturert arkitekturrådgivning med Cosmo Skyberg |
| `/architect:help` | Vis oversikt over alle kommandoer, agenter og kunnskapsbaser |
| `/architect:compare` | Sammenlign Microsoft AI-plattformer for et gitt scenario |
| `/architect:security` | Sikkerhets- og compliance-vurdering (6 dimensjoner) |
| `/architect:cost` | Kostnadsestimat med konfidensgradering (NOK) |
| `/architect:adr` | Generer Architecture Decision Record (MADR v3.0) |
| `/architect:research` | Utforsk siste nytt for en Microsoft AI-plattform |
| `/architect:poc` | Generer POC-plan med suksesskriterier og risiko |
| `/architect:license` | Kartlegg AI-kapabiliteter per lisenstype |
| `/architect:migrate` | Planlegg migrasjon mellom plattformer |
| `/architect:utredning` | AI-arkitekturutredning for norsk offentlig sektor |
| `/architect:diagram` | Generer arkitekturdiagram med Imagen 3 (mcp-image) |
| `/architect:review` | Kjør arkitekturgjennomgang mot norske offentlig sektor-krav |
| `/architect:generate-skills` | Generer kunnskapsfiler med MCP-research (batch) |
| `/architect:ros` | Gjennomfør ROS-analyse (Risiko- og Sårbarhetsanalyse) for et AI-system |
| `/architect:dpia` | Gjennomfør DPIA/PVK for et AI-system |
| `/architect:summary` | Generer teknisk sammendrag og beslutningsnotat fra arkitekturvurderinger |
| `/architect:export` | Eksporter arkitekturdokument til PDF |
| `/architect:classify` | EU AI Act-klassifisering: risikonivå + rolle |
| `/architect:requirements` | Konkrete AI Act-krav basert på risikonivå og rolle |
| `/architect:transparency` | Generer Art. 13/50 transparensnotis på norsk |
| `/architect:frimpact` | FRIA (Art. 27) — obligatorisk for offentlig sektor |
| `/architect:conformity` | Samsvarsvurdering (Art. 43) — sjekkliste + erklæring |
| `/architect:onboard` | Onboard pluginen med virksomhetsspesifikk kontekst |
| `/architect:kb-update` | Manuell KB-refresh — poller sitemaps, oppdaterer endrede filer via `microsoft_docs_fetch`, committer |

## Agenter

| Agent | Formål | Modell |
|-------|--------|--------|
| `research-agent` | MCP-isolert research med microsoft-learn | opus |
| `security-assessment-agent` | 6-dimensjons sikkerhetsrammeverk med 1-5 scoring | opus |
| `cost-estimation-agent` | Kostnadsestimering i NOK med TCO-sammenligning | opus |
| `adr-writer-agent` | ADR-generering i MADR v3.0-format | opus |
| `license-mapper-agent` | Kryssreferering av lisenser mot plattformkapabiliteter | opus |
| `diagram-generation-agent` | Arkitekturdiagrammer med Imagen 3 via mcp-image | opus |
| `architecture-review-agent` | Arkitekturgjennomgang mot Digdir, AI Act, NSM, Schrems II | opus |
| `ros-analysis-agent` | ROS-analyse med 7 dimensjoner, NS 5814-metodikk og AI-trusselbibliotek | opus |
| `dpia-agent` | DPIA/PVK for AI-systemer med risikomatrise og tiltakstabell | opus |
| `summary-agent` | Teknisk sammendrag og beslutningsnotat fra arkitekturvurderinger | opus |
| `ai-act-assessor` | EU AI Act-klassifisering, forpliktelser og compliance-vurdering | opus |
| `onboarding-agent` | Strukturert onboarding-intervju for virksomhetstilpasning | opus |

## Skills (5 domenespesifikke)

| Skill | Formål | Referansefiler | BrukerIntent |
|-------|--------|----------------|--------------|
| `ms-ai-advisor` | Cosmo Skyberg-persona, 7-fase arbeidsflyt, plattformvalg | 62 | "Hjelp meg velge" |
| `ms-ai-governance` | Norsk offentlig sektor-styring, EU-regelverk, ansvarlig AI | 78 | "Er dette lovlig?" |
| `ms-ai-security` | Sikkerhetsscoring (6x5), kostnadsestimering (P10/P50/P90) | 60 | "Er dette trygt?" |
| `ms-ai-engineering` | RAG, agenter, Azure AI Services, data, MLOps, multimodal | 153 | "Hvordan bygger jeg dette?" |
| `ms-ai-infrastructure` | BCDR, hybrid/edge, suveren sky | 34 | "Hvordan drifter jeg dette?" |

### Kunnskapsbase-routing i agenter (max 3 filer per invokasjon)

Agenter leser navngitte kjernefiler, ikke hele kataloger:
- **security-assessment-agent**: security-scoring-rubrics-6x5.md, ai-security-scoring-framework.md, ai-threat-modeling-stride.md
- **cost-estimation-agent**: deterministic-cost-calculation-model.md, azure-ai-foundry-cost-governance.md, cost-models.md
- **architecture-review-agent**: decision-trees.md, security.md, public-sector-checklist.md + domene-spesifikke ved behov
- **ros-analysis-agent**: ros-ai-threat-library.md, ros-scoring-rubrics-7x5.md, ros-methodology-ns5814-iso31000.md
- **dpia-agent**: dpia-norwegian-methodology-ai.md, gdpr-compliance-ai-systems.md, ai-impact-assessment-framework.md
- **ai-act-assessor**: ai-act-classification-methodology.md + relevante ai-act-*.md filer (maks 3 per fase)
- **summary-agent**: Leser assessment-outputs fra sesjon, ikke KB-filer

## MCP-servere

- `microsoft-learn` — Offisiell Microsoft dokumentasjon (search, fetch, code samples)
- `mcp-image` — Bildegenerering med Imagen 3 for arkitekturdiagrammer (via diagram-generation-agent)

### Anbefalte MCP-servere (ikke påkrevd)

- `azure-mcp-server` (microsoft/azure-mcp-server) — Live Azure-infrastrukturinspeksjon (Storage, Key Vault, Monitor, AI Search, RBAC)
- `bicep-mcp-server` — IaC-generering for Azure-ressurser
- `azure-devops-mcp` (microsoft/azure-devops-mcp) — Work items, pipelines, repos

Se `references/architecture/recommended-mcp-servers.md` for detaljer.

## Utvikling

### Legge til ny kunnskapsbase
1. Opprett `.md`-fil i riktig undermappe under den relevante skillens `references/`-mappe (f.eks. `skills/ms-ai-engineering/references/`)
2. Følg format fra eksisterende filer (header, dato, seksjoner, "For Cosmo"-seksjon)
3. Oppdater relevant SKILL.md med referanse

### Legge til ny kommando
1. Opprett `commands/navn.md` med frontmatter (`description`, `argument-hint`)
2. Følg mønster fra eksisterende kommandoer
3. Oppdater `commands/help.md` med ny kommando
4. Oppdater denne CLAUDE.md

### Legge til ny agent
1. Opprett `agents/navn-agent.md` med frontmatter (`name`, `description`, `model`, `color`, `tools`)
2. Inkluder tydelig "triggers on" i description
3. Oppdater denne CLAUDE.md

### Testing

#### Statisk validering
```bash
# Kjør plugin-validering (frontmatter, encoding, KB-referanser)
bash tests/validate-plugin.sh
```

#### KB-ferskhet (sitemap-basert, manuell drift)

**Apply-fasen kjøres via slash-kommandoen** (krever aktiv Claude Code-sesjon, holder oss innenfor Anthropic Consumer Terms § 3):

```text
/architect:kb-update                          # default: critical + high
/architect:kb-update --priorities critical    # bare critical
/architect:kb-update --skip-discover          # hopp over new-URL discovery
/architect:kb-update --dry-run                # rapport uten apply
```

**Endringsrapport-fasen kan kjøres som rent Node-script (ingen LLM-kostnad):**

```bash
# Poll sitemaps → endringsrapport (ingen filendringer)
node scripts/kb-update/run-weekly-update.mjs --force

# Med discovery av nye relevante sider
node scripts/kb-update/run-weekly-update.mjs --force --discover

# Vis rapport på nytt etter polling
node scripts/kb-update/report-changes.mjs

# Bygg/oppdater URL-registry fra referansefiler
node scripts/kb-update/build-registry.mjs [--merge]
```

Systemet sammenligner Microsoft Learn sitemap-`<lastmod>` med filenes `Last updated:` header, og genererer en prioritert endringsrapport (critical/high/medium/low).

**Match rate:** ~69% av 1342 URLer matche mot sitemaps. ~31% (mest `azure/ai-foundry/openai/`-stier) finnes ikke i sitemaps pga. Microsofts URL-restrukturering.

**Schedulering:** Pluginen schedulerer ingenting. Bruker som vil ha periodisk varsling kan sette opp egen cron / launchd / systemd / GitHub Actions som kjører `node scripts/kb-update/run-weekly-update.mjs --force --discover` (rapport-fasen, ikke apply). Apply-fasen er bevisst manuell — den krever LLM-resonnering på diff og kjører fra en åpen Claude Code-sesjon.

Legacy (deprecated):
```bash
bash scripts/kb-staleness-check.sh  # mtime-basert, upålitelig etter git clone
```

#### E2E-regresjonstester
```bash
# Kjør alle E2E-suiter
bash tests/run-e2e.sh

# Kjør enkeltsuiter
bash tests/run-e2e.sh --security
bash tests/run-e2e.sh --cost
bash tests/run-e2e.sh --summary
bash tests/run-e2e.sh --ai-act
```

Fixture-basert validering av agent-output (sikkerhet, kostnad, sammendrag). Tester struktur, encoding, og domene-spesifikke krav uten å invokere Claude.

#### Manuell test
```bash
# Test at plugin registreres
cd <plugin-root>
claude --plugin ./plugins/ms-ai-architect

# Kjør hovedcommand
/architect

# Vis alle kommandoer
/architect:help
```

## Playground (v3 / v1.14.0)

Interaktiv decision-builder + rapport-viewer for Microsoft AI-beslutninger. Erstatter v2 5-stegs-pipelinen med en multi-surface-app som persisterer state og visualiserer importerte rapporter inline. Spec: v3-arkitektur dokumentert under `.claude/projects/2026-05-03-playground-v3-architecture/`. v1.10.0-utvidelser dokumentert under `.claude/projects/2026-05-03-ms-ai-architect-v1-10-playground/`. v1.11.0 leverer design-system 100%-adoption (PARALLEL-CSS-migrasjon til DS-konvensjon, inline `<style>`-trim 37%, severity-coded card borders, app-header-restruktur, `.stack-lg` body spacing, AI Act-pyramide bredde-fix). v1.13.0/.1 patchet 10+ symptomatiske visuelle bugs. v1.14.0 leverer root-cause refaktor over 6 sesjoner: B-DS-1/2/3 fikset i shared/ DS v0.4.0 (kanban-card word-break, expansion title-block, matrix-bubble cursor); 3 risk-renderere (renderDpia/Security/Ros) til DS-summary-grid + ros-layout; 6 compliance/govern-renderere bytter lokal `.report-meta`-wrapper mot DS-konvensjon; renderMigrate + renderPoc til expansion-list per fase (slett `.phase-detail`-CSS); 5b-fixes: renderCost p50/p90-objekter ekstrahert via `.monthly` (var "[object Object]"), renderCompare distinctive-token-matching erstatter firstWord-heuristikk, renderUtredning droppet misvisende `role="tab"`. Lokal `<style>`-blokk: 191 → 122 effektive linjer (~36% reduksjon). Alle 17 renderere PASS visuell QA.

- **Fil:** `playground/ms-ai-architect-playground.html` (~3870+ linjer, single-file v3-arkitektur)
- **4 surfaces:** Onboarding (18 felles felt — 4 strukturerte / 14 fritekst etter v1.10.0) → Home (prosjekt-liste + 3 entry-tracks) → Catalog (25 commands gruppert i 5 expansion-grupper med søk) → Project (per-prosjekt tabs, command-form-prefill fra felles state, paste-back-import med rapport-visualisering)
- **Persistens:** IndexedDB-primær med localStorage-fallback. Schema-versjonert (`STATE_KEY = 'ms-ai-architect-state-v1'`) med eager `MIGRATIONS`-pipeline. v1.10.0 introduserer `dataVersion v1→v2`-migrasjon (idempotent) som backfill-er `verdict`+`keyStats`.
- **17 rapport-renderers (felles grunnskjelett):** Alle wrapper output via `renderPageShell()` med eyebrow + h1 + valgfri verdict-pill + valgfri key-stats-grid + arketype-spesifikk body. Parser → struktur → HTML rutet via kanonisk archetype-routing-tabell.
- **Foundation-helpers:** `renderPageShell`, `renderVerdictPill`, `renderKeyStatsGrid`, `inferVerdict`, `inferKeyStats`, `KEY_STATS_CONFIG`.
- **Tier 3-adopsjon:** 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).
- **Theme:** Mørk default + lys theme-toggle med Aksel-tokens i begge moduser (lagt til i v1.10.0). Persistert i `localStorage('ms-ai-architect-theme')`. Theme-bootstrap-script i `<head>` unngår FOUC.
- **Eksport/import:** JSON Decision Record-envelope (Blob + FileReader), schema-versjon-bevisst på import.

### Validering (v1.14.0-tall)

| Test | Kommando | Dekning |
|------|----------|---------|
| Statisk struktur | `bash tests/test-playground-v3.sh` | 202 PASS — vendored CSS, surfaces, 25 commands, 14 parsere, 17 renderers (felles grunnskjelett), design-system-klasser, action-handlers, Tier 3-bruk, onboarding field-distribution |
| Parser-fixtures | `bash tests/test-playground-parsers.sh` | 70 PASS — 17 fixtures × parser-routing |
| Migrasjon | `bash tests/test-playground-migrations.sh` | 7 PASS — v1→v2 idempotent migrasjon |
| Kombinert (E2E) | `bash tests/run-e2e.sh --playground` | 272 PASS — statisk + parser-suiter |
| Plugin-validering | `bash tests/validate-plugin.sh` | 219 PASS |
| Manuell A11Y QA | Se `playground/MANUAL-CHECKLIST.md` | 10 seksjoner inkl. axe-core-kjøring per surface |
| A11Y-rapport | `playground/A11Y-RAPPORT.md` | Statisk vurdering klar — browser-axe-kjøring pending |

### Demo system (v1.11.0)

`scripts/build-demo-state.mjs` leser alle 17 fixture-filer fra `playground/test-fixtures/` og injiserer dem som en `<script type="application/json" id="demo-state-v1">`-blokk i playground HTML (idempotent — erstatter eksisterende blokk). "Last inn demo-data"-knappen på onboarding-overflaten kaller `ACTIONS['load-demo']` som leser blokken, erstatter alle state-grener via Proxy-mutasjon, og navigerer til project-surface med 17 pre-importerte rapporter. `rehydratePasteImports()` kjøres via `queueMicrotask` etter project-surface render — fyller textareas fra `project.reports[id].raw_markdown` og kaller `handlePasteImport` for hver. `handlePasteImport` har equal-value-guard for å unngå render-loop.

`tests/screenshot/` inneholder en frittstående Playwright-runner med egen `package.json` (gitignored `node_modules`). `node run.mjs` produserer 24 PNG-er (12 surfaces × 2 tema, retina, fullPage) under `playground/screenshots/v1.14.0/` (v1.10.0 + v1.11.0 beholdt som historisk referanse). Disse committes så forkere ser pluginen uten å installere noe. Demo-org er "Acme Kommune" og demo-prosjekt er "Acme: Kunde-chatbot" — konsistente navn på tvers av alle 17 fixtures (etter v1.11.0 rename fra "Acme AS" / "Demosystem").

### Design-system 100%-adoption (v1.11.0 → v1.14.0)

Sesjon 3-5 la til inline CSS i `playground/ms-ai-architect-playground.html`. v1.11.0 hoisted alle generiske komponenter til `shared/playground-design-system/components-tier3-supplement.css` (DS v0.3.0):
- `.pyramide-desc` / `.pyramide-desc__item`
- `.scenario-card-grid` / `.scenario-card`
- `.residual-pair` / `__cell` / `__cell-label/__cell-value/__cell-meta` / `__arrow`
- `.read-more` / `.read-more__trigger` / `.read-more__chev` / `.read-more__body`
- `.top-risks` / `.top-risk[data-severity]`
- `.recommendation-card`
- `.suppressed-panel`
- `.screen-tabs` / `.screen-tab` / `.screen[data-active]`

v1.14.0 (DS v0.4.0): root-cause fix for tre DS-bugs som tidligere ble symptomatisk patchet i lokal CSS — `.kanban-card__name` (break-word + overflow-wrap; var break-all), `.expansion__title-main/sub` (display: block), `.matrix__bubble` (cursor + hover/focus). Fix-en re-syncet til vendored DS, og tilsvarende lokal-overrides slettet. Plus: 14 renderere refaktorert til DS-konvensjon (3 risk-renderere → DS-summary-grid + ros-layout, 6 compliance/govern-renderere → DS-konvensjon, renderMigrate + renderPoc → expansion-list per fase). Lokal `<style>`-blokk: 191 → 122 effektive linjer (~36% reduksjon siden v1.13.1).

Alle PARALLEL-CSS-navngrupper migrert til DS-konvensjon. `renderPageShell` + `renderKeyStatsGrid` refaktorert til DS markup. Severity-coded card-borders på rapport-cards, app-header-restruktur, `.stack-lg` body spacing på home/project/catalog, AI Act-pyramide bredde-fix, eyebrow-label på home-projects.

Ved videre hoisting: re-sync via `node scripts/sync-design-system.mjs ms-ai-architect`. Dette er endringer i delt asset — krever drift-deteksjon-handling per `MANIFEST.json`.

### Vendored design-system

Playground laster CSS fra `playground/vendor/playground-design-system/` — en vendored
kopi av marketplace-rotens `shared/playground-design-system/`. Dette holder pluginen
**standalone**: HTML-filen kan åpnes fra `file://` uavhengig av marketplace-roten.

- **Sync-skript:** `node scripts/sync-design-system.mjs ms-ai-architect` (ved marketplace-rot)
- **Drift-deteksjon:** `MANIFEST.json` lagrer SHA-256 per fil. Re-sync feiler hvis
  vendored fil er endret lokalt — `--force` overstyrer.
- **Lastes i HTML:** `<link>`-tags til `fonts.css`, `tokens.css`, `base.css`,
  `components.css`, `components-tier2.css`, `components-tier3.css`,
  `components-tier3-supplement.css` (i den rekkefølgen).
- **Aldri rediger** filer under `vendor/playground-design-system/` direkte —
  endringer går i `shared/`, deretter re-sync.

> v2-spec under `docs/playground-v2-spec.md` er beholdt som historisk
> referanse, men er IKKE gjeldende kontrakt. v3-arkitekturen er
> dokumentert i `.claude/projects/2026-05-03-playground-v3-architecture/`.

## Relaterte plugins (fremtidig)

- `ms-rag-architect` — RAG-spesialist (egen plugin)
- `ms-power-automate-architect` — Power Automate deep-dive
- `ms-azure-ai-architect` — Azure AI Services deep-dive
- `ms-foundry-architect` — Azure AI Foundry spesialist
- `ms-copilot-studio-architect` — Copilot Studio spesialist

## Hooks (2)

| Event | Script | Formål |
|-------|--------|--------|
| SessionStart | `session-start-context.mjs` | Viser aktive utredninger, KB-ferskhet, onboarding-status + AI Act-frister |
| Stop | `stop-assessment-reminder.mjs` | Påminnelse om ucommittede vurderinger, neste steg |

> Secrets scanning consolidated to llm-security plugin.

## Viktige frister (EU AI Act)

| Frist | Krav | Status |
|-------|------|--------|
| 2025-02-02 | Forbudte AI-praksiser (Art. 5) | Gjeldende |
| 2025-08-02 | Governance og sanksjoner (Art. 99) | Gjeldende |
| 2026-08-02 | GPAI-krav + Annex III høyrisiko | 161 dager |
| 2027-08-02 | Alle høyrisiko-krav (full compliance) | 527 dager |

**Tilsynsmyndigheter:** Datatilsynet (personvern), nasjonal AI-tilsynsmyndighet (under etablering), sektortilsyn.