Kjell Tore Guttormsen
e57dee5a03
Removes:
- All 6 PNG screenshots (playground/screenshots/) and the capture script
(scripts/screenshots/capture-playground.py).
- "Screenshots" section from plugin README.
- "Screenshot-suite" section from plugin CLAUDE.md.
- Screenshots bullet from marketplace root README's ms-ai-architect listing.
Scrubs the 17 synthetic fixtures + CHANGELOG/CLAUDE/README of identifying
references: organization names, government-agency names, agency-specific
terminology, sector-specific use cases. Replaced with generic placeholder
data ("Acme AS" / "Demosystem") that exercises the same parser archetypes.
Plugin's domain-target wording (Datatilsynet, offentlig sektor, offentlig
myndighet, rettshåndhevelse, NS 5814, Utredningsinstruksen, EU AI Act
Annex III categories) is intact — those describe the plugin's intended
audience, not any specific entity.
This is a cleanup commit. Earlier git history still contains the prior
references; force-push or rebase is required if scrubbing the history is
desired. That decision is out of scope here — please run it separately
if needed.
Verified post-scrub:
- bash tests/validate-plugin.sh -> 215/215 PASS
- bash tests/run-e2e.sh --playground -> 240/240 PASS (170 + 70)
242 lines
12 KiB
Markdown
242 lines
12 KiB
Markdown
# 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 |
|
||
|
||
## 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)
|
||
```bash
|
||
# Ukentlig oppdatering: poll sitemaps → endringsrapport
|
||
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
|
||
|
||
# Kun endringsrapport (etter polling)
|
||
node scripts/kb-update/report-changes.mjs
|
||
|
||
# Bygg/oppdater URL-registry fra referansefiler
|
||
node scripts/kb-update/build-registry.mjs [--merge]
|
||
```
|
||
|
||
Systemet poller Microsoft Learn sitemaps ukentlig, sammenligner `<lastmod>` med filenes `Last updated:` header, og genererer en prioritert endringsrapport. Session-start hook trigger bakgrunns-poll automatisk hvis >7 dager siden siste.
|
||
|
||
**Match rate:** ~69% av 1342 URLer matche mot sitemaps. ~31% (mest `azure/ai-foundry/openai/`-stier) finnes ikke i sitemaps pga. Microsofts URL-restrukturering.
|
||
|
||
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)
|
||
|
||
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/`.
|
||
|
||
- **Fil:** `playground/ms-ai-architect-playground.html` (~3870 linjer, single-file v3-arkitektur)
|
||
- **4 surfaces:** Onboarding (18 felles felt fra `/architect:onboard`) → Home (prosjekt-liste + 3 entry-tracks) → Catalog (24 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 for fremtidige skjema-endringer.
|
||
- **17 rapport-renderers:** Hver rapport-produserende command har én markdown-parser (markdown → struktur) og én renderer (struktur → HTML-visualisering: pyramide, matrix, radar, findings, distribution, capability-matrix, m.fl.) rutet via en kanonisk archetype-routing-tabell.
|
||
- **Theme:** Mørk default + lys theme-toggle, 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
|
||
|
||
| Test | Kommando | Dekning |
|
||
|------|----------|---------|
|
||
| Statisk struktur | `bash tests/test-playground-v3.sh` | 170 PASS — vendored CSS, surfaces, 24 commands, 14 parsere, 17 renderers, design-system-klasser, action-handlers |
|
||
| Parser-fixtures | `bash tests/test-playground-parsers.sh` | 70 PASS — 17 fixtures × parser-routing |
|
||
| Kombinert (E2E) | `bash tests/run-e2e.sh --playground` | begge over |
|
||
| Manuell A11Y QA | Se `playground/MANUAL-CHECKLIST.md` | 10 seksjoner inkl. axe-core-kjøring per surface |
|
||
| A11Y-rapport | `playground/A11Y-RAPPORT.md` | Skjelett — fylles ut etter kjøring |
|
||
|
||
### 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.
|
||
|