ms-ai-architect/docs/development.md

ms-ai-architect — Development

Plugin development, testing, KB-refresh. Imported from CLAUDE.md via pointer.

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 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 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: ~73% av 1343 URLer matcher mot sitemaps (poll --force, juni 2026). Microsoft rebrandet «Azure AI Foundry» → «Microsoft Foundry» og flyttet /azure/ai-foundry/ → /azure/foundry/; Sesjon 2 remappet de 164 ai-foundry-URLene (migrate-ai-foundry.mjs), som løftet foundry fra 0 % → ~62 % tracked. Resten som ikke matcher er nesten utelukkende azure/foundry/openai/-stier (egen URL-struktur — ikke remappet, ingen verifiserte mål).

Taksonomi (lag 0): sitemap-prefikser, relevans (INCLUDE/EXCLUDE), category→skill og file-priority bor i scripts/kb-update/data/domain-taxonomy.json (eneste sannhetskilde, tracket). poll-sitemaps, discover-new-urls og report-changes leser den. category-skill-map.json er ukonsumert av kode (legacy doc) — ved divergens vinner taksonomien (disk-sann).

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

Kurs-deteksjon (Spor C / C3 — Learn Platform API, opt-in)

Et parallelt, uavhengig spor fra sitemap-discoveren: oppdage at Microsoft har publisert nye eller endrede treningskurs (modules + learning paths) i produktene KB-en dekker, slik at operatøren kan vurdere om temaet bør dekkes. Et kurs er et signal, ikke en doc-side — det auto-ingestes aldri. Full spec: c3-course-detection-plan.md.

To-stegs-mønster (samme invariant som discover-new-urls):

1. Deteksjon (Claude-fri, opt-in, Node-script). detect-courses.mjs leser tre Entra-creds fra macOS Keychain, henter token, paginerer Platform API (/api/v1/modules + /learning-paths) med produkt- og updatedAt.gt-filter, diff-er mot data/course-registry.json (detektorens egen sporings-state), og skriver kun to private filer: data/course-detection-report.json (kandidater) + oppdatert course-registry.json. Importerer aldri saveDecisions — skriver hverken skills/ eller decisions.json.

   node scripts/kb-update/detect-courses.mjs              # default data-dir
   node scripts/kb-update/detect-courses.mjs --data-dir DIR  # omdiriger IO (tester)
   

   Fail-soft: mangler creds → status:"skipped" + exit 0; vedvarende nettverksfeil → status:"error" + exit 0. Opt-in inni opt-in: steget kjøres kun av scheduleren når include_course_detection: true (default false) — sett nøkkelen manuelt i ~/.claude/ms-ai-architect/ms-ai-architect.local.md.

2. SessionStart-surfacing (read-only). session-start-context.mjs leser course-detection-report.json og viser en one-liner via summarizeCourses («Kurs-signaler: N nye / M endrede kurs i dekkede produkter. Kjør /architect:kb-update») — speiler skill-signaler-blokka. removed er kun et informasjonssignal i rapporten, aldri en surfacet lead (spec §4.2). Hooken spawner ingenting for kurs-sporet.

3. Gate (operatør, Claude-i-loop). /architect:kb-update §3c leser rapporten, presenterer nye/endrede leads, og skriver godkjente leads til den UID-nøklede courses-kolleksjonen i decisions.json (via recordCourseLead). --dry-run viser leads uten å skrive. Strukturell invariant: ingen apply-path leser courses → et godkjent kurs-lead trigger aldri fetch/transform/KB-skriving.

Slug→skill-mapping er config i domain-taxonomy.json (course_products), ikke hardkoding. last_full_enum-kadens (≥30 d) styrer når removed beregnes (kun full-enumerering — aldri inkrementelt).

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