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

# 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):

/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):

# 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 scripts/kb-staleness-check.sh  # mtime-basert, upålitelig etter git clone

E2E-regresjonstester

# 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

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