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

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 for the full model and what upstream provides.

AI-generated: all code produced by Claude Code through dialog-driven development. Full disclosure →

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?
• Quick Start
• Commands
• Agent Architecture
• Knowledge Base
• Workflow Examples
• Norwegian Public Sector Features
• MCP Integrations
• Hooks & Safety
• Technology Coverage
• Enterprise Onboarding
• Related Plugins
• Version History
• 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 installed
• Python with uv (for the microsoft-learn MCP server)
• Network access to learn.microsoft.com

Installation

Add the marketplace and browse plugins with /plugin:

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

Or enable directly in ~/.claude/settings.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.

{
  "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	Live Azure infrastructure inspection (Storage, Key Vault, AI Search, RBAC)
bicep-mcp-server	Infrastructure-as-Code generation for Azure resources
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 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'). Light-mode tokens are pending in the shared design-system; the toggle works but currently only swaps the label.
• Export/import: JSON Decision Record envelope (Blob + FileReader), schema-version-aware on import.

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

Validation

Test	Command	Coverage
Static structure	bash tests/test-playground-v3.sh	170 PASS — vendored CSS, surfaces, 24 commands, 14 parsers, 17 renderers, design-system classes, action handlers
Parser fixtures	bash tests/test-playground-parsers.sh	70 PASS — 17 fixtures × parser routing
Combined (E2E)	bash tests/run-e2e.sh --playground	both above
Manual a11y QA	See playground/MANUAL-CHECKLIST.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 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.

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

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

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

Reference material in skills/*/references/ is adapted from Microsoft Learn documentation, licensed under CC 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.

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

See NOTICE.md for full attribution details.

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