mi® Agentic OS — Architektur und Bedienung

Master-Dokument für das mi®-eigene KI-System in Claude Code.
Stand: 2026-07-04 · Plugin-Ära (Versionsnummer = Plugin-Semver, siehe CHANGELOG.md — ADR-022)
Release Notes: CHANGELOG.md · Lese-Ansicht: docs/site/index.html (Front-Door im Kit-Look) → docs/site/referenz.html (generierter Spiegel, ADR-022 §5)
Spiegel-Doku: ClickUp-Wiki qd2rx-31615
Maintainer-Liste: MAINTAINERS.md
Arbeitsstand-Historie: handoffs/SESSION_HANDOFF.md + Session-Logs in handoffs/.

1. TL;DR

mi® hat in Claude Code ein strukturiertes KI-System:

• 36 mi®-Skills (7 Architektur/Meta, 14 Operations, 14 Disziplin/Kreation, 1 Intern — Ground Truth: EXPECTED_SKILLS in verify.sh)
• 5 Tool-Wrapper-Skills ohne mi--Präfix (relume, greyd, design-system, claude-design-to-figma, copywriting)
• 17 mi®-Subagents als virtuelles Team (Phasen A–F)
• 3 Memory-Tiers (Team Git-versioniert, Personal lokal, Templates)
• Customer-Storage auf NAS-Master + lokalem Working-Buffer + Pending-Puffer (ADR-002)
• Distribution als 7 Plugins über den Claude-Code-Marketplace (ADR-020); Hooks leben in den Plugins
• mi-setup.sh idempotent, verify.sh mit Drift-Guards + Fehler-Exit (✗ ⇒ Exit 1, ADR-022)

Skills sagen WAS gemacht wird, Subagents WER es macht. Aktivierung: direkt (Slash/Phrase), orchestriert (Claude erkennt), autonom (Hooks).

2. Drei-Schichten-Architektur

                    USER · TEAM
                         │
                         ▼
              ┌─────────────────────┐
              │  CLAUDE             │
              │  Orchestrator       │
              │  (Hauptagent)       │
              └──────────┬──────────┘
                         │
              ┌──────────┴──────────┐
              ▼                     ▼
        ╔═════════╗           ╔═══════════╗
        ║ SKILLS  ║           ║ SUBAGENTS ║
        ║ (WAS)   ║           ║ (WER)     ║
        ╚═════════╝           ╚═══════════╝
        Workflows             Personen mit
        in meinem Kontext     eigenem Kontext

Skill-Schichten

┌─ Schicht 3 — KREATIV / STRATEGIE ─────────────────────┐
│ • mi-brand-strategy        • mi-pr-communication      │
│ • mi-brand-naming          • mi-digital-marketing     │
│ • mi-art-direction         • mi-ui-ux                 │
│ • mi-pitch-craft           • mi-client-consulting     │
│ • mi-ai-visual-production  • mi-workshop-facilitation │
│ • mi-video-motion          • mi-campaign              │
│ + Tool-Wrapper: relume, greyd, design-system,         │
│   claude-design-to-figma, copywriting                 │
└───────────────────────────────────────────────────────┘
                         ▲
┌─ Schicht 2 — QUALITÄT / GOVERNANCE ───────────────────┐
│ • mi-stresstest    (Substanz-Quality-Gate)            │
│ • mi-pitch-review  (Empfänger-Quality-Gate)           │
│ • Memory-System    (Konventionen, Regeln)             │
└───────────────────────────────────────────────────────┘
                         ▲
┌─ Schicht 1 — OPERATIONS / PLUMBING ───────────────────┐
│ • mi-customer-onboarding  (3 Angebote / Projekt-Build)│
│ • mi-customer-interview   (Pricing-Pfad, 3 Stufen)    │
│ • mi-customer-discovery   (IST-Aufnahme)              │
│ • mi-clickup              (ClickUp-Master, Workflows A–G) │
│ • mi-offer-sync           (Pipeline-Pull → History)   │
│ • mi-submit               (NAS-Submit)                │
│ • mi-test-cleanup         (Test-Folder-Aufräumen)     │
│ • mi-lead-cleanup         (dormante Leads → Warteliste)│
│ • mi-sales-log            (Nach-Versand-Log, ADR-019) │
└───────────────────────────────────────────────────────┘
                         ▲
                  ┌──────┴──────┐
                  │  mi-system  │  ← Master-Skill (meta)
                  └─────────────┘

3. Skill-Katalog

3.1 Architektur und Meta (6)

3.2 Operations (14)

3.3 Disziplin und Kreation (13 mi®-eigen + 1 generischer Wrapper)

Strategie und Konzeption:

Kreation und Text:

Digital und Performance:

3.4 Tool-Wrapper (6, ohne mi--Präfix)

3.5 Intern (1)

Skill-Speicherort: plugins/<plugin>/skills/{name}/SKILL.md im Repo, installiert als Claude-Code-Plugin (/plugin install …, siehe §13). Optional references/.

4. Subagent-Katalog

17 Custom Subagent Types in plugins/<plugin>/agents/mi-{name}.md, installiert über die Plugins (§13). Jeder hat eigene Persona, Tool-Whitelist und Kontextfenster.

Phase A — Spezialist:innen (4)

Phase B — Direktion und Steuerung (3)

Phase C — Kreativ-Direktion und Produktion (3)

Phase D — Operations (1)

Phase E — Empfänger-Personas für Pitch-Review (4)

Lesen Angebote aus Empfänger-Brille. Tool-Whitelist nur lesend. Output mit Originalzitaten + Ampel-Urteil. Keine Wahrscheinlichkeits-Scores.

Phase F — OS-Maintenance (2)

Visual-Trio — wer macht was

Standard-Pipeline für Markenlaunch

mi-clickup Workflow A (CRM + Customer-Folder + KI-Source)
    ↓
mi-customer-discovery → mi-customer-discoverer (Brand-Briefing IST)
    ↓ User-Verifikation
mi-customer-interview (Tier-Ableitung, drei Stufen-Vorschläge, Scoping-Daten)
    ↓
mi-angebot (drei Phasen-Angebots-Tasks in Finanzen-Liste + Sales-Felder am Lead-Task + sevdesk-Hinweis)
    ↓ parallel: mi-pitch-doc (verkaufendes Narrativ)
    ↓ Vertragsabschluss + „Verkaufte Stufe" + „€ Angebot" am Pipeline-Lead-Task gesetzt
mi-customer-onboarding (Single-Mode / Projekt-Build: Projekt-Container + Meilensteine + Module + NAS-Folder)
    ↓
    ↓ User-Verifikation
mi-brand-strategist (Positionierung — schreibt SOLL in Tasks 01–08)
    ↓
mi-creative-director (Big Idea + Briefings)
    ↓
mi-art-director (Bildsprache) ─→ mi-ai-visual-producer (Assets)
    ↓
mi-design-engineer (Layout, Komponenten, Prototyp)
    ↓
mi-copywriter (Copy in Slots)
    ↓
mi-reviewer (Stresstest)
    ↓
mi-pitch-review (Empfänger-Stresstest, vor Versand)
    ↓
mi-account-manager (Kundenpräsentation)

5. Aktivierungs-Modi

Direkt (User triggert)

Slash-Command oder Trigger-Phrase: /mi-clickup, „onboarde Kunde X", „stress test bitte". Subagents: „Brand-Strategist, prüf die Whitespace-These", „Researcher, finde mir 3 Wettbewerber".

Orchestriert (Claude erkennt Kontext)

„Ich kann das mit mi-stresstest machen — soll ich?" Bei eindeutigen Trigger-Phrasen aktiviere ich autonom, sonst frage ich.

Autonom (Hooks)

Default nach Plugin-Installation:

• SessionStart — sync-projekte-sidebar + auto-pull-repo + pending-submit-check
• Stop — customer-session-log-reminder + review-reminder + work-folder-cleanup
• PostToolUse auf clickup_update_document_page — Stresstest-Hint
• PostToolUse auf clickup_update_task — Brand-Brain-Promote-Gate-Hint

Details in §10.

6. Inter-Agent-Koordination — vier Muster

Subagents reden nicht direkt miteinander. Koordination läuft über:

1. Orchestrator-Mediated (Standard). Claude spawnt Subagents nacheinander, konsolidiert.

2. Shared State (asynchron). Strategist schreibt in ClickUp-Doc, Copywriter liest, Reviewer kritisiert. SSOT: ClickUp / Memory / Repo.

3. Sequential Hand-off (Pipeline). Researcher → Strategist → Copywriter → Reviewer.

mi-stresstest --pre-brief sitzt zwischen Briefing-Eingang und Disziplin-Subagent-Spawn als Orchestrator-Tool, nicht als Workflow-Schritt 0. Filter: ≥ 2 von 4 Brief-Klassen-Eigenschaften (schriftlich, kunden-adressiert, multi-disziplin, strategische Implikation). Details: feedback_pre_brief_review.

4. Parallel Critique (Triangulation). Briefing geht parallel an Strategist + Researcher + Reviewer. Claude konsolidiert die drei unabhängigen Sichten.

7. Stack-Pipelines

7.1 KI-Source pro Kunde

Die KI-Source ist der Marken-Wissensspeicher pro Kunde — die Quelle, aus der alle KI-Agenten markenkonform arbeiten. Pro Kunde liegt sie als Sub-Folder KI-Source im Customer-Folder (v2.27 1-Folder-Modell). Alt-Kunden bleiben auf paralleler Folder KI-Source [KUNDE] — koexistiert. Volle Konvention: feedback_ki_source_doc_pattern.

Customer-Folder „[Kunde]"
└─ Sub-Folder „KI-Source"
     ├─ Liste „Brand-Brain"     ← Status-Layer (8 Tasks 01–08)
     ├─ Doc „Brand-Briefing"    ← IST (Diagnose, Page pro Rev)
     ├─ Doc „Brand-Brain"       ← SOLL (8 Prosa-Pages 01–08)
     ├─ Doc „Brand-Tokens"      ← generierter Spiegel der NAS-tokens.json (v3.2)
     └─ Doc „Sessions-Archive"  ← Audit-Trail

Vier Doc-Artefakte:

Die 8 SOLL-Dimensionen (Brand-Brain Pages 01–08): 01 Brand & Base · 02 Tone of Voice & Personas · 03 CI & Visuals · 04 No-Gos & Compliance · 05 Golden Examples · 06 Stakeholder · 07 Quellen & Referenzen · 08 Markt & Wettbewerb.

Vier Regeln:

1. IST/SOLL-Override. Brand-Briefing ist Start-Input. Sobald eine SOLL-Page gefüllt und auf review/final ist, überstimmt sie die entsprechende IST-Sektion (Mapping A→01 … H→08). Details: feedback_ist_soll_workflow.
2. Prosa ≠ Tokens. Page 03 CI & Visuals trägt nur die Prosa der visuellen Identität. Die Werte (HEX, Gewichte, px, Dauern) leben im Brand-Tokens-Artefakt — kanonisch als versionierte tokens.json auf NAS. ClickUp-Doc ist generierter read-only Spiegel (mi-clickup Workflow G). Voice bleibt Prosa in Page 02. theme.json (greyd) + Figma-Variables sind abgeleitet. Details: feedback_brand_token_artifact + Schema brand-tokens-schema.md.
3. Status-Workflow (Brand-Brain-Tasks via mi-clickup Workflow C): backlog → in progress → review → final → outdated. Vor final: verpflichtender Stresstest via mi-reviewer.
4. Changelog-Pflicht. Jede Brand-Brain-Page-Änderung → Changelog-Eintrag in der Task-Description (feedback_brand_brain_task_changelog). Token-Änderung → Changelog + semver-Bump im tokens.json-_meta.

Konsumenten-Trennung: LLM-Agenten ziehen Prosa-Wissen aus den Docs. Tools/Pipelines ziehen Werte aus der tokens.json. Zwei Konsumenten, zwei Formate.

Brain-Pipeline (KI-Source → mi® Brain v3, geplant):

ClickUp `final` → GitHub repository_dispatch → Hetzner Self-Hosted Runner Frankfurt
  → Subagent mi-brain-promote (MAX_TURNS=15, 10min wallclock)
  → Supabase Pro EU (RLS, Temporal) + Google Drive EU Backup
  → HTTP REST → beliebiger KI-Agent

Spec eingefroren in ClickUp Page qd2rx-32835. Build pending — siehe SESSION_HANDOFF.md §10.

7.2 Website-Pipeline (Relume → Figma → Greyd)

KI-Source (mi-clickup Workflow B)
    ↓ relume Skill: Section-Prompts
Relume Site Builder (Wireframes + Content)
    ↓ Export nach Figma
Figma + design-system Skill (DESIGN.md) + Brand-Tokens (tokens.json)
    ↓ greyd Skill: theme.json (Build-Output aus tokens.json)
Greyd.Suite WordPress
    ↓
Go Live

Token-Naming Beispiele:

8. MCP-Server-Stack

9. Externe Community-Skills

Installation via npx skills add -y -g [repo]. Diese Skills tragen kein mi--Präfix, weil sie nicht mi®-eigen sind.

Marketing & Copy:

• coreyhaines31/marketingskills — 35 Skills
• boraoztunc/skills — Ogilvy Direct Response
• SHADOWPR0/beautiful_prose — AI-Tics entfernen
• blader/humanizer — KI-Text menschlicher

SEO / GEO:

• AgriciDaniel/claude-seo — 19 Skills
• aaron-he-zhu/seo-geo-claude-skills — 20 Skills

Design & Figma:

• nafiurrahmanniloy/figma-skill — Figma-to-Code
• shomtsm/figma-review-skill — Engineering Review
• albertzhangz10/design-system-skill — DESIGN.md Generator
• bergside/awesome-design-skills — 60+ Skills
• Owl-Listener/designer-skills — 63 Skills

Knowledge / Tools:

• safishamsi/graphify — Knowledge Graphs
• Lum1104/Understand-Anything — Karpathy-Pattern Wikis
• kepano/obsidian-skills — Obsidian Skills
• smixs/creative-director-skill — Cannes/D&AD Methoden

10. Memory-System

Drei-Tier-Modell

Team- und Personal-Memory werden in jeder Claude-Code-Conversation geladen via @-Import in ~/.claude/CLAUDE.md. Der Import-Block wird von mi-setup.sh idempotent gesetzt (zwischen Markern <!-- mi-agentic-os:memory-imports:start --> / :end -->).

Trennscharf-Test

„Würde ein anderes Teammitglied diese Erkenntnis lesen wollen, bevor es eine Aufgabe übernimmt?"
Ja → team/ · Nein → personal/${USER}/

Promotion (Personal → Team)

git -C <repo> mv memory/personal/${USER}/<datei>.md memory/team/<datei>.md
# Inhalt neutralisieren (keine user-spezifischen Bezüge)
git -C <repo> commit -m "memory: promote <kurzbeschreibung>"
git push

Vollständige Doku: memory/README.md.

11. Hooks

Default-Hooks

Konfiguriert in settings.template.json, übernommen via merge-settings.py. Stand: 4 Blöcke / 8 Commands.

Mechanik

Hooks sind keine Personen, sondern Reflexe. Sie feuern auf Events und injizieren Kontext-Hinweise in den Run des Hauptagenten. Zähl-Einheit ist der Block in hooks, nicht der Command. Ein Block kann mehrere Commands sequenziell enthalten.

12. Naming-Konvention

13. Setup und Onboarding

Vollständige Schritt-für-Schritt-Anleitung für neue Teammitglieder (Git-Zugang,
MCP-Auth inkl. Fehlerbilder, sevdesk-Token, NAS-Mount, lokale Marker-Dateien):
docs/ONBOARDING.md. Dieser Abschnitt ist die Kurzfassung.

Voraussetzungen

• Claude Pro oder höher (für Claude Code)
• Node.js → nodejs.org
• git → git-scm.com

Verifikation

bash <repo>/verify.sh

Prüft: Voraussetzungen, Plugin-Installation (mi-core Pflicht) + Doppel-Installations-Guard, Repo-Abdeckung (35 Skills + 17 Subagents, Single-Home), Plugin-Versions-Parität, settings.json (Permissions — Hooks leben in den Plugins), Memory-Pointer, Drift-Guards inkl. Doku-Disziplin (Block 6m, ADR-022). Endet mit Exit 1, sobald ein Check fehlschlägt.

Erstinstallation (Plugin-Ära, ADR-020)

git clone git@github.com:medienimpuls/mi-agentic-os.git ~/Projekte/mi-agentic-os
bash ~/Projekte/mi-agentic-os/mi-setup.sh [--modules=core,kreativ]
# dann in Claude Code:
#   /plugin marketplace add medienimpuls/mi-agentic-os
#   /plugin install mi-core   (+ weitere nach Rolle, modules/README.md)

Bestands-Installation (v1.0-Symlinks): einmalig bash mi-setup.sh --migrate-v1. Updates: Skills/Agents/Hooks via /plugin update (Kanal 1); memory/docs/verify zieht der SessionStart-Hook per git pull (Kanal 2). Maintainer-Release: scripts/release-plugins.sh <version> (bumpt alle sechs gemeinsam).

MCP-Authentifizierung

claude mcp add clickup --transport sse --url https://mcp.clickup.com/mcp
claude mcp add figma --transport sse --url https://mcp.figma.com/mcp \
  --header "Authorization: Bearer [DEIN_TOKEN]"
claude mcp add google-drive --transport sse --url https://drivemcp.googleapis.com/mcp/v1

Erste Test-Aufgaben

> /mi-system                                  # Architektur-Übersicht
> Project-Manager, wo stehen wir mit [Kunde]? # Subagent-Test
> Onboarde Kunden X mit Website Y             # Skill-Test
> Stress-Test auf den letzten Briefing-Doc    # Quality-Gate-Test

14. Pflichtartikel beim Erweitern

Wenn ein neuer mi®-Skill oder Subagent erstellt wird:

1. Trigger-Phrasen in der description — eindeutig, überschneidungsfrei.
2. Memory-Pointer anlegen (reference_{name}_skill.md für Skills).
3. MEMORY.md Index aktualisieren.
4. Master-Skill mi-system Skill-Katalog erweitern.
5. Diese Datei aktualisieren (Skill-Katalog, Subagent-Katalog).
6. verify.sh EXPECTED_SKILLS / EXPECTED_AGENTS aktualisieren.
7. Routing-Logik prüfen — Trigger-Konflikte mit existierenden Skills?
8. Bei Hook-Änderungen — Zähl-Einheit ist Block, nicht Command. Drei Stellen synchron halten: settings.template.json, §11, §16.
9. Bei Permission-Änderung — feedback_least_privilege_permissions konsultieren. verify.sh Block 6 Drift-Guard nach jeder Änderung. Lokale Migration via python3 scripts/cleanup-permissions-v2.24.py.
10. Bei Customer-Storage-Änderungen — feedback_nas_only_customer_storage + ADR-002. Master bleibt NAS, Submit bleibt explizit. Subagent-Tool-Frontmatter NICHT für Write/Edit erweitern.
11. Bei Skill-/Doku-Edits mit Erklärungs-Tiefe — feedback_skill_dokumentation_stil anwenden (klare 1-N Nummerierung, max. eine Unter-Ebene, Klartext-Erklärung, Fachbegriffe nur wenn nötig).

15. FAQ

Q: Wann nutze ich einen Skill, wann einen Subagent? A: Workflow / Quality-Gate / Routing → Skill. Person mit eigener Stimme → Subagent.

Q: Können Subagents miteinander reden? A: Nein, nicht direkt. Koordination über Claude (Orchestrator) oder Shared State.

Q: Was kostet ein Subagent-Run? A: Eigene Tokens — typischerweise 30k–100k pro substantieller Aufgabe.

Q: Warum tragen relume, greyd, design-system keinen mi--Präfix? A: Weil sie über externe Tools handeln, nicht über mi-internal Workflows. Der Name reflektiert das Tool.

Q: mi® Brain — ist das live? A: Nein. Architektur v3 eingefroren (Supabase EU + Hetzner Runner). Heute zieht Claude direkt aus ClickUp via MCP. Build-Plan in SESSION_HANDOFF.md §10.

Q: Wie erweitere ich das System um eine neue Rolle? A: Siehe §14.

16. Inventar (Stand 2026-07-04)

<!-- adr-count: 22 -->

17. Plugin-Distribution & Marketplace

Das OS wird nicht als Monolith installiert, sondern als sieben Plugins über einen Marketplace-Katalog verteilt (ADR-020). Zwei Begriffe, zwei Ebenen:

• Plugin = Distributions-Einheit. Bündelt zusammengehörige Skills, Subagents und Hooks unter plugins/<name>/ mit Manifest .claude-plugin/plugin.json. Installiert via /plugin install <name>.
• Marketplace = Katalog. Die Datei .claude-plugin/marketplace.json listet alle Plugins mit Quelle, Beschreibung, Kategorie. Einmal hinzufügen (/plugin marketplace add medienimpuls/mi-agentic-os), dann rollenweise installieren.

17.1 Die sieben Plugins

Rollen-Zuschnitt: mi-setup.sh --modules=core,kreativ filtert Setup + Rechte passend. Detail-Matrix in modules/README.md.

17.2 Plugin ≠ Autorisierung

Das Plugin-Bündel ist eine Discovery-/Distributions-Grenze, keine Sicherheitsgrenze. Ein Skill ist eine Instruktions-Datei — „Plugin nicht installiert" verhindert keinen Tool-Aufruf. Wer real in sevdesk schreiben darf, entscheidet sich an MCP-Verbindung + Permissions, nicht am Plugin-Zuschnitt: Faktura-Berechtigte verbinden das sevdesk-MCP, alle anderen nicht (optional zusätzlich mcp__sevdesk__* in deny). Folgt der Layer-Regel → feedback_layer_separation.

17.3 Zwei Update-Kanäle

Plugins und Repo werden getrennt aktuell gehalten (ADR-020 §6):

1. Plugins (Skills/Agents/Hooks) — claude plugin marketplace update mi-agentic-os (Cache), dann claude plugin update <name>@mi-agentic-os, dann Claude Code neu starten (Plugins laden erst beim Start).
2. Repo (Memory/Docs/verify.sh) — SessionStart-Hook per git pull; verify.sh warnt bei Versions-Drift zwischen installierten Plugins und Repo-Stand.

Alle sechs Plugin-Versionen werden gemeinsam gebumpt (scripts/release-plugins.sh) — Plugin-Semver ist der Update-Cache-Key und die einzige OS-Versionsnummer (ADR-022 §1). Lese-Ansicht dieser Ebene: Front-Door docs/site/index.html im Kit-Look, Deep-Dive im generierten Spiegel docs/site/referenz.html.

18. Roadmap

19. Versionshistorie

Ab v1.0.0 (2026-07-03) ist CHANGELOG.md die Release-Historie — Plugin-Semver ist die einzige OS-Versionsnummer (ADR-022 §1). Die Tabelle unten ist Geschichtsschreibung der Wellen-Ära davor; die Wellen-Zählung wird nicht fortgeführt.

Wellen-Detail liegt in den Session-Logs. Diese Übersicht verweist nur.

20. Quellen-Pointer

• Aktueller Stand: handoffs/SESSION_HANDOFF.md
• Leistungskatalog-SSOT: ab v5 (ADR-013) eine ClickUp-Liste Module v2 (901523964518) im Folder _Vorlagen (Space mi® Operations). Meilenstein-Liste 901523776742 + Alt-Modul-Liste 901523776746 abgeschafft, Folder Leistungsübersicht stillgelegt — Gruppierung via Service-Linie. skills/mi-leistungsportfolio/bundles.yaml = generierter Spiegel (Re-Sync von 901523964518 offen; Reihenfolge Repoint → Resync → Delete). skills/mi-leistungsportfolio/SKILL.md = SSOT für die Pricing-Logik (Modul-Tier-Preise, Komplexitäts-Aufschläge, Cluster-Heuristiken). Quelle: ADR-013 (teil-supersedet ADR-004 §Entscheidung). Pricing-Architektur v3.4: ADR-005.
• Brand-Speicher-Pattern: feedback_ki_source_doc_pattern + feedback_ist_soll_workflow
• Schreibstil-Konvention: feedback_skill_dokumentation_stil
• Release Notes: CHANGELOG.md (SSOT, ADR-022) · Lese-Ansicht: Front-Door docs/site/index.html (Kit-Look, von Hand gepflegt) → generierter Spiegel docs/site/referenz.html (via scripts/build-docs-site.sh, nie von Hand editieren)
• Kaufmännisches Modell (Ist-Spec): docs/spec/kaufmaennisches-modell.md — EIN Dokument für Typ-Progression, Topologie, Owner-Matrix, Trigger-Tupel und ID-Registry (Stand heute); die ADRs bleiben die Warum-Historie. Pflege-Regel: Jeder ADR im Controlling-Umfeld aktualisiert die Spec (ADR-022-Gate).
• ADRs: docs/adr/ — Zählung siehe Inventar §16 (Drift-Guard 6m-3). Pricing/Angebot: ADR-005, ADR-006, ADR-007, ADR-008. v5-ClickUp-Reform (accepted 2026-07-05, gebündelter mi-reviewer-Lauf): ADR-009, ADR-010, ADR-011, ADR-012, ADR-013. Onboarding-Topologie (accepted 2026-07-05): ADR-014. Controlling-Vorgang als multifunktionaler Träger (accepted 2026-07-05, präzisiert + teilkorrigiert ADR-009/010/011): ADR-015. Struktur-Schicht / Task-Typen Service-Linie + Leistungsziel (accepted 2026-07-05, verfeinert ADR-015 §2/§3, realisiert ADR-011 §5): ADR-016. Projektaufbau-Modus / Entkopplung CORE-STACK-EPIC (proposed, modus-konditionalisiert ADR-006 §2 + ADR-007 §1/§4): ADR-017. Design-System-Kit + Deck-Generator (proposed): ADR-018. Pitch-Prozess-Härtung (accepted): ADR-019. Plugin-Distribution (accepted): ADR-020. Claude-Design-Direktverbindung (accepted): ADR-021. Doku- + Release-Notes-Disziplin (accepted): ADR-022. Migration: docs/migrations/v5-controlling-modell.md
• Team-Memory: memory/team/MEMORY.md (auto-loaded)
• Repo: github.com/medienimpuls/mi-agentic-os
• ClickUp-Wiki-Spiegel: Master-Doc qd2rx-31615
• Kundenspezifische Daten: Vault + ClickUp-Customer-Folder (nicht im OS-Repo)

Team-Onboarding — mi® Agentic OS auf einem frischen Rechner

Diese Anleitung führt ein neues Teammitglied von null zu einem lauffähigen OS. Die technische Installation selbst machen mi-setup.sh + die Plugin-Installation (siehe README) — hier steht alles, was drumherum nötig ist: Zugänge, Authentifizierung, lokale Dateien.

Grundregel: Zugangsdaten (Tokens, Passwörter, VPN-Profile) leben NIE im Repo. Alles, was hier mit „beim Maintainer anfragen" markiert ist, wird persönlich übergeben (siehe MAINTAINERS.md).

Checkliste (Reihenfolge einhalten)

1. Git-Zugang zum OS-Repo
2. Basis-Werkzeuge installieren
3. OS installieren (Setup + Plugins)
4. MCP-Server verbinden (ClickUp, Figma, Google Drive)
5. sevdesk-Zugang (nur Faktura-Arbeit)
6. NAS-Zugang (Kunden-Ablage)
7. Lokale Dateien anlegen (Kundendaten-Marker)
8. Verifizieren + erste Test-Aufgaben

1. Git-Zugang zum OS-Repo

Das Repo liegt unter github.com/medienimpuls/mi-agentic-os (privat).

1. GitHub-Account an den Maintainer melden → Einladung in die Organisation.
2. Zugang einrichten — einer der beiden Wege:
• SSH (empfohlen): SSH-Key erzeugen (ssh-keygen -t ed25519), Public Key

bei GitHub hinterlegen (Settings → SSH Keys).

beim ersten git clone als Passwort verwenden.

1. Test: git clone git@github.com:medienimpuls/mi-agentic-os.git ~/Projekte/mi-agentic-os

2. Basis-Werkzeuge

• Claude Code CLI — npm install -g @anthropic-ai/claude-code (braucht Claude Pro oder höher)
• Node.js — nodejs.org
• Python 3 — auf macOS vorhanden (python3 --version)
• PyYAML — pip3 install pyyaml (brauchen die YAML-Drift-Guards in verify.sh)
• git — auf macOS vorhanden

Das OS ist auf macOS ausgelegt (Symlinks, NAS-Mounts unter /Volumes/).

3. OS installieren (Setup + Plugins)

# Setup: Memory-Imports, Permissions, lokale Marker
bash ~/Projekte/mi-agentic-os/mi-setup.sh
# Oder mit Modul-Filter (z. B. Kreativ ohne Faktura — filtert auch die Rechte):
bash ~/Projekte/mi-agentic-os/mi-setup.sh --modules=core,kreativ

Dann in Claude Code die Plugins installieren:

/plugin marketplace add medienimpuls/mi-agentic-os
/plugin install mi-core          ← Pflicht
/plugin install mi-kreativ       ← nach Rolle

Welche Plugins es gibt und was sie enthalten: modules/README.md. Danach einmal Claude Code neu starten, damit Team-Memory + Plugins geladen sind. Updates: Skills/Agents via /plugin update; Memory/Docs zieht ein SessionStart-Hook automatisch per git pull nach. Wer noch eine v1.0-Bootstrap-Installation hat: einmalig bash mi-setup.sh --migrate-v1 (räumt Symlinks + alte Hooks auf, mit Backup).

4. MCP-Server verbinden

Ohne diese Verbindungen laufen die meisten Skills nicht. Reihenfolge egal.

ClickUp (Pflicht — fast alle Operations-Skills):

claude mcp add claude_ai_ClickUp --transport sse --url https://mcp.clickup.com/mcp

Der Server-Name claude_ai_ClickUp ist Pflicht, kein Vorschlag. Hook-Matcher und Permissions im OS binden an die kanonische Tool-ID mcp__claude_ai_ClickUp__* (Konvention feedback_mcp_canonical_id_only). Unter anderem Namen (z. B. clickup oder ein claude.ai-Connector mit UUID-ID) laufen die Tools zwar, aber die Autonomie-Hooks feuern nie und jede MCP-Aktion erzeugt Permission-Prompts. verify.sh warnt bei falscher Registrierung.

Beim ersten Aufruf öffnet sich der Browser-Login. Mit dem mi®-ClickUp-Account anmelden (Einladung in den Workspace beim Maintainer anfragen). Danach in Claude Code testen: „Zeig mir die ClickUp-Workspace-Hierarchie" — es muss der Workspace medienimpuls mit dem Space mi® Operations erscheinen. Siehst du einen leeren oder fremden Workspace, bist du mit dem falschen Account angemeldet.

Figma (Pflicht für Kreativ-/Design-Arbeit):

claude mcp add claude_ai_Figma --transport sse --url https://mcp.figma.com/mcp \
  --header "Authorization: Bearer [DEIN_TOKEN]"

Auch hier gilt: Server-Name claude_ai_Figma — die Subagent-Tool-Listen binden an mcp__claude_ai_Figma__*.

Personal Access Token in Figma erzeugen (Settings → Security → Personal access tokens). Zugriff aufs mi®-Team-Projekt beim Maintainer anfragen.

Claude Design (nur kreativ/vertrieb — Werkbank-Sync + Deck-/DS-Publish, ADR-021):

Einmalig in einer Terminal-Session claude starten und /design-login ausführen — autorisiert den Design-System-Zugriff an deinem claude.ai-Login. Danach können Skills Decks und Kunden-Design-Systeme direkt nach claude.ai/design publizieren.

Google Drive (optional — Asset-/Doc-Zugriff):

claude mcp add google-drive --transport sse --url https://drivemcp.googleapis.com/mcp/v1

Mit dem mi®-Google-Account anmelden.

Bekannte Fehler:

• 502 bei ClickUp-Calls: Backend-Last, einfach erneut versuchen (Retry ist normal,

Quirks siehe mi-clickup-Skill).

• Skills schlagen „stumm" fehl / Tool nicht gefunden: MCP-Verbindung prüfen mit

claude mcp list — der Server muss als verbunden gelistet sein.

• Hooks feuern nicht / ständige Permission-Prompts bei ClickUp: Server läuft unter

falschem Namen. claude mcp list muss claude_ai_ClickUp zeigen — sonst entfernen und unter dem kanonischen Namen neu verbinden (siehe oben).

5. sevdesk-Zugang (nur wer Faktura macht)

Angebots-/Rechnungs-Skills (mi-abrechnung-sevdesk, mi-angebot, mi-controlling) sprechen sevdesk über die API an.

1. sevdesk-Benutzer + API-Token beim Maintainer anfragen.
2. Token NIE ins Repo oder in settings.json committen — nur in die lokale

MCP-/Env-Konfiguration.

1. Sicherheits-Konvention: Skills erzeugen ausschließlich Entwürfe (Status 100).

Festschreiben + Versand ist immer ein Mensch-Schritt.

Wer keine Faktura-Arbeit macht, überspringt diesen Schritt — die übrigen Skills funktionieren ohne sevdesk.

6. NAS-Zugang (Kunden-Ablage)

Master-Ablage für Kundendaten ist das NAS (ADR-002):

• /Volumes/impuls/mi® Kunden/<Kunde>/ — Kunden-Master
• /Volumes/impuls-1/medienimpuls®/ — u. a. Design-System-Exporte und Fonts

1. NAS-Benutzerkonto + Verbindungsdaten beim Maintainer anfragen.
2. Im Büro-Netz: Finder → „Gehe zu" → „Mit Server verbinden" → Server-Adresse

eintragen, mit dem NAS-Konto anmelden. Außerhalb des Büros ist ein VPN nötig — Profil beim Maintainer anfragen.

1. Test: ls "/Volumes/impuls/mi® Kunden/" zeigt die Kundenordner.

Ohne NAS funktioniert das OS trotzdem: mi-submit puffert Abgaben in ~/.claude/pending-submit/ und trägt sie nach, sobald das NAS erreichbar ist. Die SMB-Verbindung ist zeitweise unzuverlässig — vor Lösch-Operationen auf dem NAS immer absichern.

7. Lokale Dateien anlegen

Kundendaten-Marker (Pflicht für Design-System-Sync und Drift-Guards):

cp scripts/customer-markers.local.example scripts/customer-markers.local

Dann die aktuelle Kundennamen-Liste beim Maintainer anfragen und eintragen (eine Zeile pro Name). Die Datei ist gitignored — Kundennamen gehören nie ins Repo. Optional analog: customer-neutralize.local.sed (Vorlage daneben).

8. Verifizieren + erste Tests

bash ~/Projekte/mi-agentic-os/verify.sh

Muss ohne Fehler durchlaufen (Warnungen zu optionalen Teilen sind okay). Danach in Claude Code:

> /mi-system                                  # Architektur-Übersicht lädt
> Zeig mir die ClickUp-Workspace-Hierarchie   # MCP-Test
> Stress-Test auf [beliebiges Test-Dokument]  # Quality-Gate-Test

Wenn alles läuft: Willkommen im Team. Konventionen und Arbeitsweise stehen in MI_AGENTIC_OS.md und im Team-Memory (memory/team/MEMORY.md — wird automatisch in jede Session geladen).

Bequemer Lese-Einstieg: docs/site/index.html im Browser öffnen — Architektur-Referenz, dieses Onboarding und die Release Notes als eine durchsuchbare Seite. Was sich pro Version ändert: CHANGELOG.md — nach jedem git pull bzw. Plugin-Update der schnellste Überblick.

Plugins aktuell halten (zwei Kanäle, ADR-020 §6). Der Marketplace ist eine Git-Quelle mit lokalem Cache — ein Release im Repo landet NICHT automatisch in deiner Installation. verify.sh warnt (⚠), wenn deine Plugins hinter dem Repo zurückhängen; der Session-Start-Toast ebenso. Update in dieser Reihenfolge:

claude plugin marketplace update mi-agentic-os          # 1. Cache von GitHub auffrischen
for p in mi-core mi-design-extras mi-discovery mi-faktura mi-kreativ mi-vertrieb; do
  claude plugin update "${p}@mi-agentic-os"             # 2. Plugins aktualisieren
done
# 3. Claude Code neu starten — Plugins laden erst beim Start.

Schritt 1 nicht überspringen: Ohne Cache-Refresh meldet plugin update fälschlich „aktuell". Diagnose + Details im Skill mi-update (Kanal 1).

Changelog — mi® Agentic OS

Alle nennenswerten Änderungen am OS, pro Release, für Team-Leser geschrieben: was ist neu, was ändert sich an deiner Arbeit. Begründungen stehen in den ADRs, Arbeitsprotokolle in handoffs/.

Format angelehnt an Keep a Changelog, Versionierung = Plugin-Semver (alle Plugins tragen dieselbe Version, ADR-020 §6). Die Plugin-Version ist die einzige OS-Versionsnummer (ADR-022 §1) — die interne Wellen-Zählung (v2.x/v3.x/v5) endete mit der Plugin-Ära, siehe Vorgeschichte unten.

Dieses Dokument beschreibt den Repo-Stand. Welche Version bei dir installiert ist, sagt /plugin bzw. mi-update — nach einem Repo-Pull kann der CHANGELOG neuer sein als deine installierten Plugins.

[Unreleased]

_Sammelstelle: Jeder OS-Arbeitsblock trägt hier ein, bevor die Session endet (ADR-022 §2). Beim Release wandern die Einträge in einen Versions-Abschnitt._

[2.6.0] — 2026-07-09

Neu

• Neues Plugin mi-intern (interne Team-/Org-Ops) + Skill mi-rollenprofil. Das OS hat jetzt eine siebte Distributions-Einheit für interne Deliverables — bewusst getrennt vom bisherigen, durchgehend kundenbezogenen Plugin-Zuschnitt (neue Marketplace-Kategorie internal). Erster Skill: mi-rollenprofil führt ein qualifiziertes Interview mit einem Senior/der GF (nicht dem Mitarbeiter selbst) in sechs Blöcken durch und produziert daraus reproduzierbar eine Rollen-/Stellenbeschreibung als ClickUp-Doc (Übersicht + „Stellenprofil auf einen Blick" + fünf Prosa-Unterseiten). Nutzt die Doc-Konventionen von mi-clickup (Pre-Read-Pflicht, Präfix-Reihenfolge, kein Löschen, Connector-Fallback), erfindet keine eigene ClickUp-Logik; optionaler Word-Export via docx. Registriert in marketplace.json, modules/intern.module, verify.sh (36 Skills, 7 Plugins), MI_AGENTIC_OS.md, modules/README.md, README.md. Migrations-Naht bewusst dokumentiert: sobald ein zweiter interner Skill entsteht, bleibt mi-intern der Home — keine Rückverlagerung nach mi-core.
• Doku-Front-Door im Website-UI-Kit-Look + Plugin-/Marketplace-Erklärung. Die Doku-Site ist jetzt zweiteilig (ADR-022 §5): docs/site/index.html ist eine von Hand gepflegte Front-Door im Look des Website-UI-Kits (ui_kits/website/ aus mi-design-system, V6) — Hero, mi-pillar-Card je Plugin, Marketplace-Panel, Update-Kanäle; der generierte Referenz-Spiegel wanderte nach docs/site/referenz.html. Neuer Abschnitt §17 „Plugin-Distribution & Marketplace" in MI_AGENTIC_OS.md (bisherige §17–19 → §18–20) erklärt Plugin vs. Marketplace, den 6-Plugin-Zuschnitt samt Abhängigkeiten, die Regel Plugin ≠ Autorisierung (sevdesk-Recht hängt an MCP-Verbindung + Permissions, nicht am Plugin) und die zwei Update-Kanäle. build-docs-site.sh, verify.sh (Versions-Gate auf referenz.html, Existenz-Check Front-Door), release-plugins.sh (Sichttest beider Dateien) und README nachgezogen.
• Front-Door und Referenz-Spiegel visuell zusammengeführt (kein „Schnitt"). Beide Seiten teilen dieselbe Header-Komponente (mi-header + mi-btn): Logo · Haupt-Navigation · Akzent-CTA, gleiches Verhalten. Im Spiegel liegen die drei Haupt-Themen (Architektur-Referenz · Onboarding · Release Notes) im Kopf, die Subpunkte in der linken Navigation — komplett auf Weiß, großzügigerer Weißraum, linksbündig zum Logo, ohne senkrechte Trennlinie. Content-Band beidseitig = Footer-Breite (--content:1200px); Link-Look/Typo angeglichen; Akzent-CTA als Pill mit korrigiertem Hover.
• Doku-Look in Claude Design editierbar (self-contained Karte + verlustfreier Round-Trip). In V6 liegt eine Karte preview/doku-site.html (Gruppe „Doku-Site") nach dem bewiesenen Muster der Komponenten-Karten — CSS inline, Tokens/Fonts via globalCssPaths, kein cross-Ordner-<link> — so rendert und editiert sie garantiert. scripts/build-doku-card.sh erzeugt sie driftfrei aus components.css + frontdoor.css (zwei data-doku-Blöcke); scripts/pull-doku-card.sh schreibt Edits verlustfrei zurück (Round-Trip verifiziert). Loop: in Claude Design editieren → Karte pullen → pull-doku-card.sh → build-docs-site.sh → Doku-Site trägt den Look. Keine eigene Projekt-Karte, kein Token-Drift.
• Doku-Site self-contained + auf Vercel deploybar (Static-Deploy, kein Build). Die Look-Schicht liegt jetzt NEBEN den HTML-Seiten in docs/site/site-theme/ (per git mv aus docs/site-theme/ gezogen), sodass docs/site ein self-contained Static-Root ist. vercel.json am Repo-Root setzt outputDirectory: docs/site → Vercel liefert nur diesen Ordner aus (kein Build, restliches Repo bleibt privat). Beide Seiten laden die geteilte Look-Schicht per <link>: site.css @importt den Kit-Token-Snapshot colors_and_type.css (lokale Kopie) + components.css + Seiten-CSS (frontdoor.css / theme.css). Kit-Kopplung: build-time statt live — build-docs-site.sh kopiert colors_and_type.css bei jedem Lauf frisch aus dem Kit (driftfrei, aber Token ziehen erst beim nächsten Build nach, nicht mehr live-on-reload; bewusste Aufweichung der 2026-07-06-Entscheidung, ADR-022 §5). verify.sh 6m-5 prüft die Look-Schicht am neuen Pfad inkl. Snapshot; Werkbank-Skripte (build-doku-card.sh/pull-doku-card.sh) und mi-design-system-SKILL nachgezogen. Hinweis: die ../../-Quell-Links in referenz.html (README, Handoffs, Memory, Skills) zeigen im Deploy ins Leere — bewusst außen vor gelassen.
• Doku-Site auf helles Schema gepinnt (Dark-Mode-Bug behoben). Der Kit-Snapshot flippt per prefers-color-scheme: dark, aber die Doku-Site ist nur hell designt und halb-adaptiv (muted-Textfarben hart Tinte-auf-Weiß) → auf einem Dark-Mode-OS war Fließ-/Karten-Text unsichtbar (Front-Door) bzw. ausgewaschen (Referenz). site.css pinnt jetzt fest das helle Schema (color-scheme: light + Kit-Semantik-Tokens im Dark-@media auf Licht-Werte). Verifiziert in beiden OS-Modi (Preview mit prefers-color-scheme-Emulation): Body weiß, Text dunkel, Tabellen/Code-Chips lesbar. Details ADR-022 §5.
• Verdrahtete Editier-Oberfläche in Claude Design (Werkbank). docs/site/site-theme/preview.html ist eine Kitchen-Sink-Galerie aller index/frontdoor-Elemente (Header, Buttons, Cards, Divider, Hero, Marketplace-Panel, Kanäle, Footer, Token-Swatches), die die echten CSS-Dateien lädt — lokal an die Kit-Tokens gebunden. Die gesamte Look-Schicht wurde als Komponente docs-theme/ nach V6 gepusht (@dsCard-Karte „Doku-Site / Komponenten-Vorschau"); dort rendert sie voll (Kit-Tokens + echte Fonts am Projekt-Wurzel) und ist visuell editierbar. Pull-Vertrag (ADR-022 §5 / SKILL): nur components.css + frontdoor.css + theme.css zurück — site.css (Pfad-Divergenz) und preview.html (Scaffold) bleiben Werkbank-seitig.

[2.5.0] — 2026-07-05

Entfernt

• Obsidian-Anbindung komplett ausgebaut (Live-Kosten-Analyse, negativer ROI): Eine Auswertung der Token-Kosten zeigte, dass ~89 % der Kosten aus Cache-Write/Read (Kontext × Turns) stammen, nicht aus Output — und dass die Obsidian-Anbindung eine Write-only-Schleife war: der MCP-Server wurde in 13.424 Sessions 0-mal aufgerufen, der Read-Hook (obsidian-context.py, feuerte bei jedem Prompt) injizierte in der gesamten Historie 12-mal Kontext, während der Write-Hook (save-to-obsidian.py + Haiku-Summary) jede Session automatisch dumpte und den Vault 22:1 mit Session-Müll gegenüber kuratierten Topics flutete. Entfernt: MCP-Server obsidian (aus ~/.claude.json), beide Hooks (aus ~/.claude/settings.json), die Skripte obsidian-context.py/save-to-obsidian.py/generate-summary.py/enable-obsidian-hooks.sh, sowie alle Opt-in-Verweise in MI_AGENTIC_OS.md, README.md, docs/ONBOARDING.md, mi-setup.sh, settings.template.json. Der Vault selbst (Nutzerdaten) bleibt unangetastet. Falls das Cross-Session-Memory-Konzept später gebraucht wird, wird es sauber neu aufgesetzt.

Neu

• Stop-Hook context-budget-reminder.sh (Token-Kosten-Hygiene): Erinnert bei großem Kontext (≥200k/400k/600k/800k Tokens) oder ≥120 Assistant-Turns an /compact bzw. einen sauberen SESSION_HANDOFF-Schnitt. Feuert in eskalierenden Bändern (nur beim Sprung in ein höheres Band, kein Spam), idempotent pro Session. Opt-in via ~/.claude/settings.json (Repo-Hook unter scripts/hooks/, nicht Plugin-verteilt). Hintergrund: eine einzelne Marathon-Session lief auf ~996k Tokens Kontext × 1.371 Turns.
• Konvention feedback_session_hygiene_token_cost: Token-Kosten ≈ Kontextgröße × Turns (nicht Output). Regel: eine Session = eine Aufgabe, /compact an Schwelle statt am Limit, 1-Mio-Fenster nur bei Bedarf, große Lese-Arbeit an Subagents auslagern, nur benötigte MCP-Server/Skills verbunden lassen.

[2.4.0] — 2026-07-05

Behoben

• Plugin-Update-Kanal gehärtet (Live-Befund: drei Releases kamen nie an): Die lokale Installation hing auf 2.0.0, während das Repo bei 2.3.0 stand — der Git-Marketplace-Cache refresht nicht automatisch, claude plugin update allein vergleicht gegen den veralteten Cache und meldet fälschlich „aktuell" (genau das Szenario, das ADR-020 §6 vermeiden wollte). Drei Gegenmaßnahmen: (1) mi-update Kanal 1 dokumentiert jetzt den Pflicht-Zweischritt claude plugin marketplace update mi-agentic-os → claude plugin update <plugin>@mi-agentic-os → Neustart; (2) der SessionStart-Auto-Pull-Hook vergleicht nach dem Pull die installierte Version (~/.claude/plugins/installed_plugins.json) gegen den Repo-Soll (plugins/mi-core/.claude-plugin/plugin.json) und gibt bei Rückstand einen Toast aus (rein lesend, fail-open); (3) verify.sh Block 5 + docs/ONBOARDING.md §8 zeigen den Drift als ⚠ (nur lokal, in CI übersprungen).

Neu (Review-Restliste C/D + Konzept-Lücken, 2026-07-05)

• mi-clickup Workflow I — KI-Source-NAS-Export: Alle vier KI-Source-Docs eines Kunden (Brand-Briefing, Brand-Brain, Brand-Tokens, Sessions-Archive) als Markdown-Snapshot auf den NAS-Master (001 - KI-SOURCE/_ClickUp-Export/<Datum>/), on-demand + Empfehlung nach jedem final-Promote. Schließt die Backup-Lücke: bis Brain v3 live ist, lebt Marken-Wissen nur in ClickUp ohne Recovery-Pfad. Schreib-Mechanik über mi-submit (kein Reimport — reiner Datenverlust-Schutz). Voller Ablauf in references/ki-source-nas-export.md.
• mi-clickup Workflow J — Live-Schema-Check: Liest den Workspace und vergleicht Task-Typ-IDs (numerisch), Listen/Spaces und Pflicht-Feld-Namen gegen die Registry — fängt ClickUp-UI-Umbenennungen, bevor Reasoning still bricht. Reine Diagnose, on-demand + vor jeder Migration. references/live-schema-check.md.
• Dry-Run + Test-Kunden-Fixture als Konvention (feedback_dry_run_und_test_fixture): Schreibende Operations-Skills sollen einen Dry-Run (Write-Plan als Text, keine Writes) unterstützen und gegen einen Test-Kunden-Folder laufen, bevor sie einen echten Kunden anfassen — bislang waren Live-Kunden das Testfeld (ADR-016/019 entstanden aus genau solchen Defekten). Verankert in mi-test-cleanup (Aufräum-Partner). Folge-Welle: Dry-Run pro Skill implementieren (Start: mi-angebot).
• Trigger-Runner ehrlich dokumentiert: docs/spec/kaufmaennisches-modell.md §4 + feedback_layer_separation stellen klar — der Trigger-Layer ist NICHT automatisiert; die (Typ ∧ Status)-Tupel sind Erkennungs-Regeln für Mensch/Session, Runner = der Senior. Beseitigt die Fehlannahme einer laufenden Automatik.

Geändert (P5-Mini-Welle — Mehrphasen-Verkauf, 2026-07-05)

• P5 aufgelöst (mi-os-architect-Vorlauf + gezielter mi-reviewer-Lauf, kein neuer ADR): Die drei seit ADR-015 offenen Fragen zum Mehrphasen-Modell sind geklärt — drei ADR-/Spec-Präzisierungen, mi-offer-sync code-seitig unangetastet.
• Frage 1 (Sales-Feldsatz beim Anschluss-Auftrag): Feld-Trennung eingeführt — Abschluss-Fakten (Verkaufte Stufe, Tier, Verkaufte Module, € Angebot) leben am jeweils gewonnenen Vorgang (beim STACK/EPIC-Anschluss am Geschwister, nicht am Spine — der behält CORE), Lern-Loop-Felder (Umsatztyp, Phase-2-Entscheidung, Verkaufsphase, …) exklusiv am Spine. Schützt die Erst-Auftrags-Wahrheit am Spine vor Überschreiben. docs/spec §5.1 + ADR-015 §5. Freeze-Gate (mi-reviewer) hat eine falsche KPI-Begründung im ersten Entwurf gefangen: die Anschluss-Quote läuft unverändert über Phase-2-Entscheidung am Spine, NICHT über eine confirmed-Paar-Zählung über den Kunden-Key (dieser Mechanismus existiert im Sync nicht) — Formulierung in allen drei Trägern korrigiert, mi-offer-sync bleibt code-seitig unberührt. Die confirmed-Paar-KPI ist als eigene Welle vermerkt (Spec §10 Punkt 8).
• Frage 2 (Service-Linien an der Schlussrechnung): Owner = mi-controlling, aber on-demand statt mechanisch — heute kein Konsument (sevdesk-Beleg spiegelt den Auftrag), daher nur dokumentiert. ADR-016 §8 Owner-Matrix-Zeile.
• Frage 3 (Rechnungs-Spiegelungs-Tiefe): war kein echtes Loch — ADR-016 §2 hatte es bereits entschieden (Abschläge = Ausschnitt via Leistungsziele). ADR-015-Annahme als aufgelöst markiert (Supersede-Hygiene).
• Drei [offen — Review-Record P5]-Marker in mi-controlling aufgelöst.

Geändert (Hygiene-Batch, 2026-07-05)

• mi-design-extras als opt-in deklariert: ~40 vendored Craft-Skills nicht mehr im Standard-Set — nur installieren, wer Design-/Craft-Arbeit macht (wird von mi-kreativ als Abhängigkeit gezogen). Verhindert, dass ~28 ungenutzte Skills das Skill-Listing jeder Session aufblähen. Vermerkt in marketplace.json + modules/README.md.
• Least-Privilege der Nur-Leser-Agents: Die 4 Empfänger-Personas + mi-project-manager + mi-brand-strategist tragen statt mcp__claude_ai_ClickUp__* (inkl. delete/merge/update) eine explizite Read-Toolliste (get/filter/search/document) — Umsetzung der eigenen Konvention feedback_least_privilege_permissions.
• Home-Blanket-Read verengt: Read(${HOME}/**) im settings-Template (und live) auf Read(${HOME}/.claude/**) + Read(${HOME}/Documents/**) reduziert — kein Zugriff mehr auf Browser-Profile, ~/Library, fremde Repos. verify.sh-Guard fängt den Blanket jetzt zusätzlich zu Read(*).
• mi-system-Katalogtabelle durch Pointer ersetzt: Die gespiegelte Skill-Tabelle (driftete auf „30 Skills" + alte Workflow-Namen) ist raus; MI_AGENTIC_OS.md §3 bleibt der einzige Katalog. Ein Träger weniger.
• Gelöscht: docs/wiki-migration/ (self-declared löschbar) + .archive/old-memories/ (Git ist das Archiv, erzeugte tote [[Links]]).

[2.3.0] — 2026-07-05

Behoben

• OS-Review-Welle A (2026-07-05) — Korrektur-Sammelblock aus dem Vier-Prüfer-Gesamt-Review:
• Plugin-Split-Link-Sweep: ~25 tote relative Pfade in 13 Skill-Dateien repariert, die seit dem Plugin-Umzug (ADR-020) ins Leere zeigten — v. a. die mi-leistungsportfolio-YAMLs (Daten-Layer der Pricing-Kette) aus mi-faktura/mi-vertrieb/mi-discovery heraus, dazu Repo-Root-Ziele (MI_AGENTIC_OS.md, scripts/…) und Cross-Plugin-Agents.
• bootstrap.sh-Sweep: 18 Referenzen in 14 Dateien auf mi-setup.sh bzw. Plugin-Mechanik umgestellt (u. a. CLAUDE.md, docs/ONBOARDING.md, MI_AGENTIC_OS.md Skill-/Agent-Speicherorte, mi-os-project-lead-Report-Template). Historie (ADRs, Session-Logs, CHANGELOG) unangetastet.
• mi-angebot auf ADR-015 angeglichen (Selbstwiderspruch beseitigt): Schritt 3 baut jetzt explizit Promotion (1022 → 1012 am Anfrage-Vorgang, KEIN neuer Task) + STACK/EPIC-Geschwister statt „drei Phasen-Angebots-Tasks anlegen"; Frontmatter, Schritt 6/7, sevdesk-Hinweis und Anti-Patterns nachgezogen. Gleiche Alt-Formulierung in mi-leistungsportfolio und mi-customer-interview 8.3 korrigiert.
• LAB-Tagessatz korrigiert: 1.225 € → 1.575 € (225 €/h × 7, Rechenfehler in der Pricing-SSOT; Senior-Entscheid).
• Tote Memory-Referenzen aufgelöst: mi-angebot-Gate 1.1 zeigt auf feedback_projekt_onboarding_flow (Brand-Brief-Gate) statt auf die nie existente feedback_kein_angebot_ohne_brand_brief; feedback_folder_naming_convention kundenneutral ins Team-Memory promotet (war nur im gitignorten Personal-Memory, wurde aber von mi-customer-discovery referenziert).
• verify.sh 6f-3 prüfte den falschen Ort: Controlling-Schreibweisen-Guard lief gegen ~/.claude/skills/ (v1-Ort, fremde Community-Skills) statt gegen plugins/*/skills/ — repariert. scripts/stats/skill_inventory.py von v1-Symlink-Inventar auf Plugin-Inventar umgestellt.
• Frontmatter-Defekt in 9 Subagents: YAML-Schließer --- klebte ohne Zeilenumbruch an der tools-Zeile (…ClickUp__*---) — behoben; neuer Guard verify.sh 6f-4.
• Kundenname aus mi-clickup-Beispiel entfernt (→ „Musterkunde GmbH & Co. KG", Konvention feedback_os_kundenneutral).
• Doku-Spiegel-Render-Bruch behoben: Das roh inline eingebettete logo-circles.svg enthält ein <image>-Element, das der HTML-Parser als Void-Element liest — die komplette Seite kippte in sichtbaren Base64-Text. Der Generator bindet das Logo jetzt als Data-URI-<img> (Original-Datei unverändert, weiterhin self-contained).

Behoben (P-Fix-Welle — Reviewer-Folge-Punkte, 2026-07-05)

• P1 — Verkaufsphase-Kanon (Inhaber-Entscheid): EIN Options-Set Verhandlung · Absage · Abgebrochen, sonst leer (Makro-Stufe trägt der Task-Typ, ADR-014 §5) — vorher schrieben drei Skills drei verschiedene Wertemengen und der Sync erkannte negotiating nie. Kanon-Träger offer-history.yaml; mi-angebot schreibt das Feld gar nicht mehr; mi-offer-sync liest Verhandlung + neu loss_kind (Absage vs. Abgebrochen) für die Verlust-Statistik. UI-Schritt offen: Dropdown-Optionen in ClickUp umbenennen.
• P2 — Verlust-Pfad hat einen Owner (Inhaber-Entscheid): mi-sales-log bekommt die einzige, eng gefasste Status-Schreibbefugnis — bei absage/abgebrochen Task-Status → verloren (+ Gegen-Read). Vorher blieb jede geloggte Absage auf offer-sent, die Hit-Rate war systematisch geschönt.
• P3 — mi-customer-onboarding auf ADR-015/017: Ein-Task-Lesart (kein „verknüpfter 1022" mehr — derselbe fortgeschriebene Task), 1-stufig-Pfad im Build-Gate (leere Verkaufte Stufe ist dort kein Abbruch mehr; Modul-Quelle = Verkaufte Module/Positions-Subtasks), 5-IDs-Marker statt 3-Folder-Marker.
• P4 — Owner-Zirkel Verkaufte Module aufgelöst: mi-controlling leitet das Feld bei der Auftrag-Übernahme (1012 → 1005) aus den Positions-Subtasks ab; der Projekt-Build ist reiner Leser. Zahlungsplan-[zu klären] geschlossen: Laufzeit = Senior-Input, Monatsbetrag = (Summe − Anzahlung − Schlussrate) / Laufzeit.
• P6 — Grenzfälle dokumentiert: Storno nach 1005 = bewusst nicht gebaut (Senior-Handarbeit, kein Typ-Rückweg); zurückgestellt (operatives Parken) vs. dormant/Warteliste (Lead-Lebenszyklus) sauber getrennt.
• P7 — reference_angebots_task_template neu gezogen: alle sechs Drift-Stellen (Akquise-Fallback, Legacy-Verkaufsphasen, Feld-Trigger statt Tupel, Block-3, Beträge im Body, Subtask-Naming) behoben; Spiegel kompakt, Skill = Schema-SSOT. feedback_offer_tracking + reference_clickup_custom_field_ids + Spec auf den Kanon nachgezogen.
• P9 — Field-ID-Cache-Invalidierung: Gegen-Read-Fail → Cache-Eintrag verwerfen + Probe-Task-Re-Resolve (in mi-angebot + mi-offer-sync); fehlender negotiating-Zweig im Sync-Pseudocode ergänzt.
• Offen bleibt P5 (Mehrphasen-Sales-Feldsatz + Service-Linien an der Schlussrechnung) als markierte Mini-Welle — [offen]-Marker in mi-controlling.

Neu (Welle B13–B15 — ADR-Konsolidierung, Spec, CI)

• ADR-009–016 auf accepted (gebündelter mi-reviewer-Stresstest, 2026-07-05): Das v5-Gesamtmodell wurde als EIN Modell geprüft — kein Blocker, Kern-Topologie dreifach konsistent (ADRs ↔ Skills ↔ verify-Guards). Neun Folge-Punkte (P1–P9, u. a. Verkaufsphase-Vokabular-Drift über drei Skills, Verlust-Pfad ohne Status-Owner, mi-customer-onboarding ohne 1-stufig-Pfad) sind im neuen Review-Record festgehalten. ADR-006/007 bekommen eine Fälligkeits-Mechanik (ADR-Validierungs-Gate-Sektion im mi-offer-sync-Bericht + Time-Box 2026-12-22), ADR-017 ist vom ADR-006-Kriterium entkoppelt (validiert am ersten 1-stufig-Durchlauf). Supersede-Note ADR-014→ADR-012 §2 nachgezogen, ADR-021-Status in MI_AGENTIC_OS.md korrigiert (war fälschlich proposed).
• Domänen-Spec docs/spec/kaufmaennisches-modell.md: Das kaufmännische Modell als EIN Ist-Dokument (Objekt-Modell, Topologie-Regeln, Lebenszyklus + Trigger mit ehrlicher Runner-Klausel, Owner-Matrix, Daten-Träger, ID-Registry mit 23 IDs, Modi, Abgeschafft-Liste, ADR-Landkarte) — löst die 7-ADR-Archäologie für Leser ab, ADRs bleiben Warum-Historie. Pflege-Regel unterm ADR-022-Gate. 7 erkannte Widersprüche als „Offene Klärungen" ausgewiesen.
• verify.sh gehärtet + GitHub-Actions-CI: 4 ungeschützte Command-Substitutions abgesichert (set -e-Abbruch mitten im Lauf mit irreführender Diagnose), Wrapper meldet interne Abbrüche jetzt explizit. Neuer CI-Modus MI_VERIFY_CI=1 (überspringt lokale Install-Checks, alle Repo-Drift-Guards laufen voll) + .github/workflows/verify.yml (push/PR auf main) — damit ist das ADR-022-Release-Gate erstmals maschinell erzwungen, nicht nur lokal. Zwei Repo-Guards aus dem settings.json-Block herausgelöst (liefen vorher nur, wenn lokal eine settings.json existierte).

Geändert (Welle B — Doku-Träger-Diät)

• SESSION_HANDOFF.md radikal geschnitten (411 → 186 Zeilen): Der Körper beschrieb eingefrorenen v3.4-Stand (abgeschaffte Listen als aktiv, Pipeline-Liste, altes Inventar) und widersprach dem eigenen Wellen-Kopf. Der Handoff trägt jetzt nur noch, was nirgends sonst lebt: aktive Welle, offene Folge-Punkte, Sackgassen (vollständig erhalten, um ADR-018/019/020-Verwerfungen ergänzt), Lessons, Brain-v3-Stand, Wellen-Historie-Tabelle. System-Stand ist an MI_AGENTIC_OS.md + CHANGELOG delegiert.
• Memory-Index-Diät (memory/team/MEMORY.md 25 → 11 KB, ~3–4k Tokens pro Session gespart): Jede Index-Zeile ist jetzt ein echter Einzeiler (Detail lebt in der Datei), 69 → 62 Einträge durch fünf Merges: no_generic_marketing_words→anti_ki_sprech · klardeutsch_entwicklung→skill_dokumentation_stil · pitch_doc_naming→pitch_doc_standard · project_brain_v3_status→reference_brain_v3 · vier Angebots-Regeln→NEU feedback_angebot_artefakt_regeln. Alle eingehenden Referenzen repo-weit umgebogen (ADR-Historie bewusst unangetastet), 29 tote [[Links]] normalisiert, reference_mi_catalog entzahlt.

Neu (Welle A)

• MCP-ID-Guard in verify.sh (⚠, informativ): warnt, wenn der ClickUp-Server lokal nicht unter der kanonischen ID claude_ai_ClickUp verbunden ist — dann feuern die Hook-Matcher nie und MCP-Allows greifen nicht. docs/ONBOARDING.md §4 registriert ClickUp/Figma jetzt verbindlich unter den kanonischen Server-Namen.

Geändert

• Sichttest als Pflicht-Schritt im Release-Hinweis: release-plugins.sh weist nach dem Spiegel-Build explizit an, docs/site/index.html einmal zu öffnen, bevor committet wird — Render-Brüche fallen nur visuell auf, kein Guard fängt sie (Live-Befund des Logo-Bruchs).
• Obsidian-Summary-Pfad DSGVO-konform umgebaut: generate-summary.py erzeugt Session-Zusammenfassungen jetzt lokal via Claude Code CLI headless (claude -p … --model haiku, bestehende Anmeldung — kein API-Key) statt über die Gemini-API (Google US-Compute, verletzte feedback_dsgvo_eu_only). Fail-open: ohne claude-Binary wird die Summary übersprungen, die Session blockiert nie. save-to-obsidian.py spawnt wieder das Repo-Skript statt des Gemini-basierten v1-Rests ~/.claude/scripts/cli/obsidian-synth.py; GEMINI_API_KEY und ~/.claude/scripts/.env sind aus dem OS raus.

Neu

• Erster Werkbank-Pull durchlaufen: Layout-Politur des Doku-Spiegels aus Claude Design kuratiert zurückgeholt (breitere Sidebar, Vollbreiten-Layout, großzügigere Abstände) — der docs-theme-Loop ist damit end-to-end verifiziert.
• Doku-Theme an die Claude-Design-Werkbank verdrahtet (ADR-022 §5 Nachzug): Die Design-Schicht des Doku-Spiegels ist in docs/site-theme/theme.css ausgelagert (mi®-Design-Tokens, offizielles Logo statt Typo-Annäherung) und als Komponente docs-theme/ im V6-Projekt visuell pflegbar — Workflow im Skill mi-design-system: an preview.html gestalten, Pull holt kuratiert nur die theme.css zurück, danach build-docs-site.sh. Show-Case für die Trennung Inhalt (Markdown) / Look (Theme) / Struktur (Generator).

[2.2.0] — 2026-07-04

Neu

• Doku- und Release-Notes-Disziplin (ADR-022, accepted nach mi-os-architect-Stresstest): CHANGELOG.md (dieses Dokument) ist die Release-Notes-SSOT; Plugin-Semver ist die einzige OS-Versionsnummer, die interne Wellen-Zählung endet. scripts/release-plugins.sh verweigert Versions-Bumps ohne Changelog-Abschnitt oder mit gestrandeten [Unreleased]-Einträgen.
• HTML-Doku-Spiegel: scripts/build-docs-site.sh generiert docs/site/index.html — Architektur-Referenz, Onboarding und Release Notes als eine offline lesbare Seite im mi®-Look (self-contained, keine externen Requests). Wird beim Release automatisch mitgebaut und committed; Änderungen gehören in die Markdown-Quellen, nie ins HTML.
• verify.sh Block 6m (Doku-Disziplin): prüft Changelog-Abschnitt für die Repo-Version, ADR-Referenz + ADR-Zähler-Marker in MI_AGENTIC_OS.md, Versions-Stempel des Doku-Spiegels.
• Team-Memory feedback_doku_release_disziplin: Jede OS-Session endet mit einem [Unreleased]-Eintrag; Owner der Release-Abschnitte ist mi-os-project-lead (Charter um CHANGELOG.md + docs/ONBOARDING.md erweitert).

Geändert

• verify.sh endet jetzt mit Exit 1, sobald ein Check fehlschlägt (vorher rein informativ, „✓ abgeschlossen" auch bei ✗). Aufrufer, die den Exit-Code auswerten, sehen Fehler ab sofort — verify ist damit CI-tauglich.
• MI_AGENTIC_OS.md auf Ist-Stand gezogen: Stand-Datum (war 2026-06-07), Inventar-Zähler (35 Skills / 17 Subagents), ADR-Tabelle bis ADR-022, Plugin-Ära im TL;DR (mi-setup.sh statt bootstrap.sh), Versionslogik-Klarstellung.
• README + ONBOARDING verweisen auf CHANGELOG und Doku-Spiegel als Lese-Einstieg.
• Deck-Ordner-Naming festgelegt: mi-pitch-slides benennt Deck-Ordner nach dem Schema <kundenname>-<art>-<datum> (ADR-021-Nachzug).

Behoben

• mi-abrechnung-sevdesk war „dunkel": existierte im mi-faktura-Plugin, fehlte aber in der EXPECTED_SKILLS-Prüfliste von verify.sh — nachgezogen (35 statt 34 Skills).

[2.1.2] — 2026-07-04

Behoben

• Deck-Publish landet im richtigen Projekt-Typ: mi-pitch-slides publiziert Decks in ein normales Claude-Design-Projekt (vom User in der claude.ai/design-UI angelegt, UUID an den Skill übergeben) statt via create_project — das erzeugt ausschließlich Design-System-Projekte (ADR-021 Live-Test-Befund, Sammel-Projekt-Konvention).

[2.1.1] — 2026-07-04

Behoben

• Deck-Bau nach Plugin-Umzug repariert: mi-pitch-slides löst das Design-Kit jetzt über den Plugin-Pfad auf (Single-Home, ADR-020). Vorher schlug der Deck-Bau auf frisch installierten Maschinen fehl, weil der Runner noch den alten skills/-Pfad suchte.
• Kundenname aus ADR-021 neutralisiert (Kundenneutralitäts-Guard 6l).

[2.1.0] — 2026-07-04

Neu

• Claude-Design-Direktverbindung (ADR-021): Der Abgleich zwischen Repo-Design-Kit und der Claude-Design-Werkbank läuft jetzt über das native DesignSync-Tool statt über manuelle ZIP-Exporte. Einmalig /design-login in einer Terminal-Session nötig.
• mi-design-system: Werkbank-Sync (Pull kuratiert mit Kundendaten-Guard, Push nach Kit-Änderungen). Projekt V6 ist das einzige mi®-DS-Projekt — Alt-Stände (V3 u. a.) nicht mehr benutzen.
• mi-pitch-slides: neues Ausgabe-Profil DESIGN-PROJEKT — Decks können als editierbare Claude-Design-Projekte ausgeliefert werden (Projekt in der claude.ai/design-UI anlegen, UUID an den Skill übergeben). PDF/NAS bleibt der Standard-Kanal.
• mi-creative-pipeline: Kunden-Design-Systeme können nach Claude Design publiziert werden (ADR-021 §4).

Behoben

• Hook-Guard präzisiert + Obsidian-Opt-in nutzt Repo-Pfade (v2.0-Nachzügler).

[2.0.0] — 2026-07-03

Geändert — Breaking

• Plugin-Distribution (ADR-020): Das OS wird nicht mehr über bootstrap.sh-Symlinks installiert, sondern als sechs Claude-Code-Plugins über den Marketplace (/plugin marketplace add medienimpuls/mi-agentic-os, dann /plugin install mi-core + Module nach Rolle).
• Skills und Agents leben jetzt genau einmal unter plugins/<modul>/ (Single-Home): mi-core · mi-faktura · mi-vertrieb · mi-kreativ · mi-discovery · mi-design-extras.
• Hooks leben in den Plugins, nicht mehr in settings.template.json.
• mi-setup.sh ersetzt bootstrap.sh (Memory-Imports, Permissions, lokale Marker; --modules-Filter bleibt).
• verify.sh v3.0 ist plugin-bewusst (Installation, Single-Home, Versions-Parität).
• Updates erreichen das Team über den Plugin-Update-Mechanismus; mi-update fährt zweigleisig (Repo-Pull für Maintainer, Plugin-Update fürs Team).
• Release-Disziplin: scripts/release-plugins.sh bumpt alle sechs Plugin-Versionen gemeinsam — nie einzeln bumpen, sonst bekommen Teammitglieder still keine Updates mehr.

[1.0.0] — 2026-07-03

Neu

• Team-Rollout: Erstes versioniertes Release. Das Repo ist team-tauglich:
• Kundennamen aus skills/, agents/, memory/team/ und Migrations-Doku neutralisiert; neuer verify-Block 6l erzwingt Kundenneutralität + Portabilität dauerhaft.
• Team-Onboarding-Doku docs/ONBOARDING.md: Zugänge, MCP-Auth (ClickUp, Figma, Drive), sevdesk, NAS — der Weg von null zum lauffähigen OS.
• Modul-Manifeste (modules/): Installation nach Rolle filterbar (z. B. Kreativ ohne Faktura), inklusive gefilterter Permissions.
• PyYAML als dokumentierte Abhängigkeit (YAML-Drift-Guards in verify.sh).

Vorgeschichte — Wellen-Ära (2026-05-05 bis 2026-07-02)

Vor der Plugin-Ära lief die Entwicklung in intern nummerierten „Wellen" (v2.6 … v3.7 plus v5-ClickUp-Reform — die Zählungen sind historisch gewachsen und nicht mit der heutigen Plugin-Semver vergleichbar). Die Substanz dieser Ära, grob chronologisch:

• OS-Grundgerüst (Mai): Skills/Subagents/Hooks/Memory-Konventionen, Team-Memory, Least-Privilege-Permissions, NAS-only Customer-Storage (ADR-002), mi®-Designsystem, Empfänger-Personas + mi-pitch-review.
• Brand-Speicher-Modell (Anfang Juni): 1-Folder-Customer-Modell, KI-Source-Artefakte (Brand-Briefing/Brand-Brain/Brand-Tokens/Sessions-Archive), Brand-Tokens als eigenes Artefakt (ADR-003).
• Pricing-Architektur (Juni): Leistungskatalog-SSOT (ADR-004/013), Tier-Stufen-Trennung (ADR-005), Phasen-Pfad CORE/STACK/EPIC (ADR-006), Projektaufbau-Modus 1-/3-stufig (ADR-017).
• v5-ClickUp-Reform (Mitte/Ende Juni): Customer-Folder v5, Controlling-Lebenszyklus als Typ-Progression, Rechnungs-Schicht, Space-Ansicht statt Pipeline-Liste, Onboarding-Topologie, Struktur-Schicht (ADR-009 bis ADR-016).
• Pitch-Strecke (Ende Juni/Anfang Juli): Pitch-Doc-Standard v3.7, Angebots-Skill mi-angebot, Pitch-Prozess-Härtung mit Kommentar-Log und mi-sales-log (ADR-007/008/019), Design-System-Deck-Generator (ADR-018).

Details: Session-Logs und ADR-001 … ADR-019.