MakerOS, der Architektur-BauplanMakerOS, the architecture blueprint

Was MakerOS istWhat MakerOS is

MakerOS ist ein Betriebssystem fürs Bauen von Software. Es richtet sich an Maker: Designer, Gründerinnen, Kreative und alle, die eine Idee bauen wollen, ohne klassischen Entwickler-Hintergrund. Statt eines einzelnen Chat-Assistenten bekommst du ein kuratiertes Team aus spezialisierten KI-Buddies, die ein gemeinsames Gedächtnis teilen, sich Arbeit gegenseitig übergeben und dich mit Schutzschichten begleiten.MakerOS is an operating system for building software. It is made for Makers: designers, founders, creatives, and anyone who wants to build an idea without a traditional developer background. Instead of a single chat assistant, you get a curated team of specialized AI buddies that share one memory, hand work to each other, and guide you with protective layers.

Der rote Faden dieser Seite: Wir starten bei der Leitidee, gehen dann durch die Architektur von oben nach unten, und zeigen am Ende an einem konkreten Beispiel, wie alle Teile bei einem echten Build ineinandergreifen.The thread of this page: we start with the core idea, then walk the architecture top to bottom, and close with a concrete example of how every part meshes during a real build.

Die Werte dahinter stehen in der Identitätsdatei des Systems: Befähigung statt Abhängigkeit, Sicherheit durch Struktur, keine Scham und kein Fachjargon, Plan vor Bau, ein Team mit einem Gehirn, und Fortschritt feiern. Jede Aktion kommt mit einer Erklärung.The values behind it live in the system's identity file: empowerment over dependency, safety through structure, no shame and no jargon, plan before build, one team with one brain, and celebrate progress. Every action comes with an explanation.

Die Highlights: was das für dich heißtThe highlights: what this means for you

Wenn du nur eine Sache mitnimmst: MakerOS lässt dich eigene Software bauen, ohne selbst zu programmieren, und hält dich dabei sicher. Du beschreibst, das System baut, prüft und sichert ab. Diese sechs Punkte sind der Kern.If you take away just one thing: MakerOS lets you build your own software without writing code yourself, and keeps you safe while you do. You describe, the system builds, checks, and secures. These six points are the core.

Die nächsten Abschnitte zeigen, wie jeder dieser Punkte technisch zustande kommt. Wir folgen dem Weg von der Idee bis zum fertigen, geprüften Commit.The next sections show how each of these points comes about technically. We follow the path from idea to a finished, checked commit.

Die Leitidee: das System komponiert, der Maker beschreibtThe core idea: the system composes, the Maker describes

Das wichtigste Prinzip vorweg, weil alles andere daraus folgt: Der Maker schreibt keine Skills, keine Workflows und keine Buddies, und er klickt sie auch nicht selbst zusammen. Er beschreibt seine Idee, bestätigt an klaren Kontrollpunkten, und das System übernimmt die Komposition im Hintergrund.The key principle first, because everything else follows from it: the Maker does not write skills, workflows, or buddies, and does not assemble them by hand either. The Maker describes the idea, confirms at clear checkpoints, and the system handles composition in the background.

Konkret heißt das: Du sagst, was du bauen willst. MakerOS routet zum passenden Buddy, der zieht den passenden Workflow, der ruft die passenden Skills auf. Du bleibst der oberste Dirigent, denn die Gates verlangen deine Zustimmung und jede Übergabe zwischen Buddies wird dir transparent angekündigt.In practice: you say what you want to build. MakerOS routes to the right buddy, which pulls the right workflow, which calls the right skills. You stay the top conductor, because the gates require your approval and every handover between buddies is announced to you transparently.

Sieben Layer auf einen BlickSeven layers at a glance

Die Architektur ist ein Stapel aus sieben Layern. Ganz oben steht der Maker, der nur in Alltagssprache spricht. Ganz unten sprechen die LLM-Schnittstellen. Dazwischen übersetzt jede Schicht ein Stück weiter ins Technische. Eine einzige kanonische Datei, AGENTS.md, ist die Single Source of Truth für alle Regeln; werkzeugspezifische Wrapper wie CLAUDE.md importieren sie nur.The architecture is a stack of seven layers. At the top sits the Maker, speaking only plain language. At the bottom the LLM interfaces speak. In between, each layer translates a bit further toward the technical. One canonical file, AGENTS.md, is the single source of truth for all rules; tool-specific wrappers like CLAUDE.md only import it.

Drei Dinge stehen nicht im Stapel, sondern daneben oder quer: das Memory, das jede Schicht anzapfen kann, die acht Guard-Rails, die auf jeder Ebene greifen, und die kanonische Regel-Quelle ganz oben. Genau diese Trennung macht das System austauschbar nach unten (mehrere LLM-Anbieter) und stabil nach oben (eine Regelquelle).Three things sit beside or across the stack rather than inside it: the memory that every layer can tap, the eight guard rails that apply at every level, and the canonical rule source at the very top. This separation is what makes the system swappable below (several LLM providers) and stable above (one rule source).

Die drei LibrariesThe three libraries

Die mittleren Layer sind in Wahrheit drei kuratierte Bibliotheken. Sie beantworten drei Fragen: wer arbeitet, was wird getan, und wie genau. Das System wählt aus diesen Bibliotheken aus, nicht der Maker.The middle layers are really three curated libraries. They answer three questions: who works, what gets done, and how exactly. The system picks from these libraries, not the Maker.

Zwei Sorten SkillsTwo kinds of skills

Skills gibt es in zwei Geschmacksrichtungen. Ein Atom-Skill ist deterministisch, maximal achtzig Zeilen, mit festem JSON-Schema für Ein- und Ausgabe, etwa der code-health-check. Ein Smart-Skill ist ein begrenzter Mini-Agent mit Ziel, einer Toolbox aus Atom-Skills und einem Iterations-Limit, etwa der findings-classifier im Security-Audit. Manche Schritte sind also schnell und dumm, manche flexibel und schlau.Skills come in two flavors. An atom skill is deterministic, at most eighty lines, with a fixed JSON schema for input and output, like the code-health-check. A smart skill is a bounded mini-agent with a goal, a toolbox of atom skills, and an iteration limit, like the findings-classifier in the security audit. So some steps are fast and dumb, some are flexible and smart.

Referenzen: die Wissensbasis der BuddiesReferences: the knowledge base of the buddies

Kurz: Referenzen sind keine vierte Library, sondern die Wissenstiefe der Persona-Library. Jeder Buddy trägt einen eigenen Ordner mit Domänen-Wissen in .claude/skills/<buddy>/references/. Wichtig ist die Abgrenzung zu den Skills: ein Skill tut etwas (ausführbarer Baustein), eine Referenz ist Wissen, das der Buddy liest.In short: references are not a fourth library, they are the knowledge depth of the Persona library. Each buddy carries its own folder of domain knowledge in .claude/skills/<buddy>/references/. The distinction from skills matters: a skill does something (an executable building block), a reference is knowledge the buddy reads.

Sie werden per Progressive Disclosure on demand geladen. Die schlanke Buddy-Persona verlinkt in ihre Referenzen und liest nur das, was der Moment braucht, damit das Kontextfenster klein bleibt. Es ist zugleich das größte Stück kuratierter Substanz im System.They are loaded on demand via progressive disclosure. The lean buddy persona links into its references and reads only what the moment needs, so the context window stays small. It is also the largest body of curated substance in the system.

So ruft eine schlanke Persona eine Referenz nur bei Bedarf, direkt aus der SKILL.md des Dev-Buddys:This is how a lean persona pulls a reference only when needed, straight from the Dev buddy's SKILL.md:

If anything is missing -> run the Setup Wizard.
Read references/setup-wizard.md and walk the user through it step by step.
...
Read references/stack-recommendations.md for which stack to recommend.

Die Buddies und das RoutingThe buddies and the routing

MakerOS liefert ein schlankes, kuratiertes Team. Jeder Buddy ist Spezialist für eine Domäne, teilt aber dasselbe Gedächtnis mit allen anderen. Was der Dev-Buddy über dich lernt, weiß auch der Security-Buddy. Das Routing läuft über Trigger-Phrasen; ist die Absicht unklar, fragt das System nach.MakerOS ships a lean, curated team. Each buddy is a specialist for one domain but shares the same memory with all the others. What the Dev buddy learns about you, the Security buddy knows too. Routing runs on trigger phrases; if intent is unclear, the system asks.

Daneben läuft der Stack-Tracker, der Plattform-Updates passiv verfolgt; er ist bewusst kein eigener Buddy, sondern ein Hintergrund-Mechanismus. Wichtig ist außerdem die Context-Matrix: sie legt pro Buddy fest, welche Kontext-Dateien er liest und wie viel davon, etwa voll, als Zusammenfassung, nur den Ton oder gar nicht. So bekommt jeder Buddy genau den Kontext, den seine Rolle braucht, und nicht mehr.Alongside runs the Stack Tracker, which passively follows platform updates; it is deliberately not a buddy but a background mechanism. Also important is the context matrix: it defines per buddy which context files it reads and how much, for example full, summary, tone-only, or none. So each buddy gets exactly the context its role needs, and no more.

Der PIV-Loop: fünf Gates für jede Code-ÄnderungThe PIV loop: five gates for every code change

Der PIV-Loop ist das Herz der Sicherheit. Jede Code-Änderung läuft durch fünf Pflicht-Gates, und im Build-Modus ist keines davon überspringbar. PIV steht für Plan, Implement, Validate, Security, Commit.The PIV loop is the heart of safety. Every code change runs through five mandatory gates, and in Build mode none of them is skippable. PIV stands for Plan, Implement, Validate, Security, Commit.

Zwei Regeln verdienen Hervorhebung. Erstens: Validate heißt im Browser getestet, nicht "Build läuft durch". Der Buddy muss berichten, was er tatsächlich geprüft hat. Zweitens: die Security-Übergabe ist nach jedem grünen Validate Pflicht. Für neue, nutzersichtbare Features kommt davor noch ein UX-Gate, das Scope und Design absichert, bevor überhaupt Code entsteht.Two rules deserve emphasis. First: Validate means tested in the browser, not "the build passes". The buddy must report what it actually checked. Second: the security handover is mandatory after every green Validate. For new user-facing features there is a UX gate before that, securing scope and design before any code is written.

Die Workflow-Engine: wer wirklich die Schritte taktetThe workflow engine: what actually clocks the steps

Workflows werden nicht von einem Buddy "erzählt", sondern von einer eigenen Workflow-Engine ausgeführt, einem deterministischen Node-Graph-Executor. Die Trennung ist die zentrale Idee: die Engine sequenziert und erzwingt (Gates, Handovers, Cross-LLM, den PIV-Memory-Graph), der Buddy liefert Urteilskraft, Persona und den Dialog mit dem Maker. Der Buddy steuert die Engine, die Engine hält die Regeln.Workflows are not "narrated" by a buddy but executed by a dedicated workflow engine, a deterministic node-graph executor. The split is the central idea: the engine sequences and enforces (gates, handovers, cross-LLM, the PIV memory graph), the buddy supplies judgment, persona, and the dialogue with the Maker. The buddy drives the engine, the engine holds the rules.

Ein Workflow ist eine schlichte Liste von Nodes mit Abhängigkeiten. Jeder Node ist entweder ein skill (Engine führt einen Atom-Skill aus), ein smart_skill (begrenzter Mini-Agent) oder ein delegate (der Schritt geht ans LLM des Werkzeugs). Gates, PIV-Phasen und ergebnisabhängige Verzweigungen sind Attribute am Node. Entscheidend: die Engine besitzt den PIV-Memory-Graph. Wenn eine PIV-Phase abschließt, schreibt die Engine den Anker und die Kind-Einträge selbst; Buddies dürfen keine PIV-Einträge von Hand schreiben, sonst entstünde der Graph doppelt.A workflow is a plain list of nodes with dependencies. Each node is either a skill (the engine runs an atom skill), a smart_skill (a bounded mini-agent), or a delegate (the step goes to the tool's LLM). Gates, PIV phases, and result-based branches are attributes on the node. Crucially, the engine owns the PIV memory graph. When a PIV phase finalizes, the engine writes the anchor and child entries itself; buddies must not write PIV entries by hand, or the graph would be doubled.

So sieht ein echter Node aus, samt Gate, PIV-Phase und ergebnisabhängiger Verzweigung, direkt aus dev-piv-loop.yaml:Here is a real node, with its gate, PIV phase, and result branch, straight from dev-piv-loop.yaml:

- id: validate
  type: delegate
  piv_phase: validate
  depends_on: [code-health]
  gate:
    enforce_in: [build]        # in Prototype faellt dieses Gate weg
  instruction: |
    VALIDATE: Tests + Lint, Performance-Check, dann MANUELL im Browser
    testen (berichte WAS getestet wurde, nicht nur "geht").
  produces:
    all_green: boolean
  on_result:
    - when: "!all_green"
      handover: dev_validate_fails   # -> Debug-Buddy

Die Engine merkt sich jeden Lauf in der Datenbank. Die Tabelle workflow_runs hält den Status (running, waiting, blocked, done, failed), den aktuellen Node und eine etwaige blockierende Übergabe. Scheitert ein Node, wird er bis zu einem Limit erneut versucht; scheitert Validate, geht der Lauf auf waiting, übergibt blockierend an Debug und nimmt nach dem Fix genau dort wieder auf, weil der betroffene Node neu geöffnet wird. Ein Build lässt sich also pausieren und fortsetzen, ohne den Faden zu verlieren.The engine remembers every run in the database. The workflow_runs table holds the status (running, waiting, blocked, done, failed), the current node, and any blocking handover. If a node fails, it is retried up to a limit; if Validate fails, the run goes to waiting, hands off to Debug in a blocking way, and resumes exactly there after the fix, because the affected node is reopened. So a build can be paused and continued without losing the thread.

Die Worker-Engine: asynchrone Arbeit im HintergrundThe worker engine: async work in the background

Kurze Antwort zuerst: Nicht alles läuft synchron, während du wartest. Für gereifte Operationen und Zweitmeinungen startet MakerOS abgekoppelte Hintergrund-Worker. Sie laufen als eigenständige Prozesse, schreiben ihre Befunde ins gemeinsame Gedächtnis und melden sich später, ohne deinen Fluss zu blockieren.Short answer first: not everything runs synchronously while you wait. For matured operations and second opinions, MakerOS spawns detached background workers. They run as independent processes, write their findings into the shared memory, and surface later without blocking your flow.

Der Mechanismus ist bewusst minimal. spawn_background_task() startet einen Fire-and-forget-Prozess, abgekoppelt von der Session (eigene Prozess-Session, Ein- und Ausgabe auf DEVNULL), und legt dessen PID unter .makeros/workers/<task_id>.pid ab. Kein Daemon, keine zentrale Registry in v1.0. Der Worker führt scripts/background_worker.py mit einem Skill-Namen aus; der erste echte ist cross-llm-review.The mechanism is deliberately minimal. spawn_background_task() starts a fire-and-forget process, detached from the session (its own process session, input and output on DEVNULL), and records its PID under .makeros/workers/<task_id>.pid. No daemon, no central registry in v1.0. The worker runs scripts/background_worker.py with a skill name; the first real one is cross-llm-review.

spawn_background_task(
    skill_name="cross-llm-review",
    inputs={"feature_slug": "auth", "code": "..."},
    severity_threshold="warning",
    project_slug="workshop-app",
)
# -> abgekoppelter Prozess, PID in .makeros/workers/<task_id>.pid
# Befunde landen in background_findings:
#   severity (info|warning|critical) · confidence · evaluator_model · suggested_fix
# plus ein Event "background.finding" fuer Cockpit/Buddy

Das ist die Maschinerie hinter "Build / Builder async". Eine Operation, die du oft genug ohne Befund ausgeführt hast, wandert vom synchronen Gate in einen abgekoppelten Worker. Die Sicherheit bleibt an, sie lässt dich nur nicht mehr warten. Die Befunde sammeln sich als offene Einträge und werden dir gezeigt, wenn es relevant wird.This is the machinery behind "Build / Builder async". An operation you have run often enough without a finding moves from a synchronous gate into a detached worker. Safety stays on, it just stops making you wait. Findings collect as open entries and are shown to you when it matters.

Die Handover-Matrix: Übergaben ohne stille MagieThe handover matrix: handovers without silent magic

Buddies dürfen Übergaben nicht vergessen, und sie dürfen sie auch nicht still vollziehen. Beides löst die Handover-Matrix, eine deklarative Routing-Tabelle in .makeros/handover/matrix.yaml. Jeder Eintrag sagt: bei Trigger X übergibt Buddy A automatisch an Buddy B, mit dieser Payload und dieser Nachricht an den Maker. Der Maker sieht jede Übergabe.Buddies must not forget handovers, and they must not perform them silently either. The handover matrix solves both, a declarative routing table in .makeros/handover/matrix.yaml. Each entry says: on trigger X, buddy A automatically hands to buddy B, with this payload and this message to the Maker. The Maker sees every handover.

Der Differenzierungswert steckt im "deklarativ-bedingt-transparent". Andere Systeme haben entweder fest verdrahtetes Routing oder ein LLM, das frei entscheidet. MakerOS legt die Übergaben als lesbare Tabelle offen, macht sie an Bedingungen fest und zeigt sie dem Maker an.The differentiator is the "declarative, conditional, transparent" combination. Other systems either hard-wire routing or let an LLM decide freely. MakerOS exposes handovers as a readable table, ties them to conditions, and shows them to the Maker.

Ein echter Eintrag aus der Tabelle. Die Definitionen leben in der YAML, die konkreten Übergaben als Instanzen im Gedächtnis (maker_handoff). Die Engine lädt das Register, prüft es und schreibt bei Auslösung eine echte Übergabe samt der sichtbaren Nachricht:A real entry from the table. The definitions live in the YAML, the actual handovers as instances in memory (maker_handoff). The engine loads the registry, validates it, and on a trigger writes a real handover with the visible message:

- id: dev_validate_passes
  trigger: piv.gate.closed AND gate_type=validate AND status=passed
  from: dev
  to: security
  payload: [feature_slug, changed_files, validation_report_path]
  user_message: "Security Buddy prueft jetzt die Aenderungen."
  blocking: false

Wie der Prozess erzwungen wirdHow the process is enforced

Die kurze Antwort: Sicherheit bei MakerOS beruht nicht auf gutem Willen, sondern ist strukturell erzwungen. Ein Buddy kann einen Schritt nicht einfach überspringen, weil nicht der Buddy die Schritte taktet, sondern die Engine und die Hooks. Das ist der Grund, warum auch ein Anfänger sicher bauen kann.The short answer: safety in MakerOS does not rest on good will, it is enforced structurally. A buddy cannot just skip a step, because the buddy does not clock the steps, the engine and the hooks do. That is why even a beginner can build safely.

• Gates verlangen deine Zustimmung. Ohne dein OK am Plan-Gate wird nichts gebaut. Du bist der oberste Kontrollpunkt.Gates require your approval. Without your OK at the plan gate, nothing gets built. You are the top checkpoint.
• Die Engine erzwingt, nicht der Buddy. Der deterministische Node-Graph sequenziert die Schritte und lässt eine Phase erst zu, wenn die vorige sauber abgeschlossen ist.The engine enforces, not the buddy. The deterministic node graph sequences the steps and only allows a phase once the previous one finished cleanly.
• Ein git-Hook blockt unsichere Commits. Der Pre-Commit-Hook verweigert jeden Commit, dem eine grüne Security-Phase fehlt. Security ist damit nicht umgehbar.A git hook blocks unsafe commits. The pre-commit hook refuses any commit missing a green security phase. Security cannot be bypassed.
• Anti-Same-Provider. Der Prüfer ist strukturell ein anderes LLM als der Bauer. Wer baut, prüft sich nicht selbst.Anti-same-provider. The evaluator is structurally a different LLM than the builder. Whoever builds does not check their own work.
• Gedächtnis bleibt heil. Migrationen sind additiv, vor jeder läuft ein Backup, gelöscht wird standardmäßig nur weich.Memory stays intact. Migrations are additive, every one is preceded by a backup, and deletes are soft by default.
• .git ist heilig. Es wird nie gelöscht, immer gewarnt, immer gefragt. Du kannst jederzeit zurück..git is sacred. It is never deleted, always warned about, always asked. You can always roll back.

Das ist mit "Slow by Design" gemeint: nicht langsam aus Trägheit, sondern als Verbraucherschutz für den Maker. Mit wachsender Reife wird die Sicherheit leiser und wandert in den Hintergrund, sie verschwindet aber nie.That is what "slow by design" means: not slow out of sluggishness, but as consumer protection for the Maker. As maturity grows, safety gets quieter and moves into the background, but it never disappears.

LLMs wechseln und Cross-LLM-ReviewSwitching LLMs and cross-LLM review

Skills deklarieren eine Rolle, der Broker wählt das Modell. Es gibt drei Rollen: builder baut (Cloud, starkes Modell), evaluator prüft (alternative Cloud, starkes Modell) und background_worker erledigt Hintergrund-Arbeit (möglichst lokal, Cloud-Haiku als Fallback).Skills declare a role, the broker picks the model. There are three roles: builder builds (cloud, strong model), evaluator checks (alternate cloud, strong model), and background_worker does background work (local if possible, cloud Haiku as fallback).

Daraus entsteht ein souveränes Trio, das sich auch EU-konform aufstellen lässt: Builder auf Claude Opus, Evaluator auf Codestral (Mistral, EU-Cloud), und ein lokaler Security-Check auf Codestral-22B. Die Befunde kommen als JSON mit Schweregrad und Konfidenz-Bändern. Genau diese strukturelle Zweitmeinung ist für den EU AI Act relevant.From this comes a sovereign trio that can also be arranged EU-compliant: builder on Claude Opus, evaluator on Codestral (Mistral, EU cloud), and a local security check on Codestral-22B. Findings arrive as JSON with severity and confidence bands. This structural second opinion is exactly what matters for the EU AI Act.

Wie du zwischen LLMs wechselstHow you switch between LLMs

Der Wechsel ist eine Einstellung, kein Umbau. In PREFERENCES.local.yaml legst du pro Rolle fest, welcher Anbieter sie bedient: Claude für den Builder, Codestral für den Evaluator, ein lokales Modell für Hintergrund-Arbeit. Du bringst deinen eigenen API-Key mit (oder ein lokales Modell), und der Broker mappt jede Rolle zur Laufzeit auf das passende Modell. Tauschst du einen Anbieter aus, ändert sich nur die Zuordnung, nicht der Workflow.Switching is a setting, not a rebuild. In PREFERENCES.local.yaml you define per role which provider serves it: Claude for the builder, Codestral for the evaluator, a local model for background work. You bring your own API key (or a local model), and the broker maps each role to the right model at runtime. Swap a provider and only the mapping changes, not the workflow.

provider_roles:
  builder: anthropic
  evaluator: mistral          # nie derselbe Anbieter wie der Builder
  background_worker: local    # lokal (Ollama), Cloud-Haiku als Fallback
cross_llm_review:
  sync_on_commit: true
  confidence_threshold: 0.7

Die Anti-Same-Provider-Regel ist nicht nur Konvention, sondern Code. Jeder LLM-Aufruf wird in llm_call_log protokolliert. Fordert ein Skill die Rolle evaluator an, liest der Resolver den letzten Builder-Anbieter aus diesem Log; wäre er identisch, rotiert er automatisch zum nächsten Cloud-Anbieter. Dasselbe Log ist zugleich der Audit-Trail, der für den EU AI Act zählt. Findet ein Smart-Skill als Prüfer keinen unabhängigen Anbieter, pausiert der Lauf (blocked), statt sich selbst zu prüfen.The anti-same-provider rule is not just convention, it is code. Every LLM call is logged to llm_call_log. When a skill requests the evaluator role, the resolver reads the last builder provider from that log; if it would match, it rotates to the next cloud provider automatically. The same log doubles as the audit trail that matters for the EU AI Act. If a smart skill acting as evaluator finds no independent provider, the run pauses (blocked) rather than reviewing its own work.

Das Memory-System: eine einzige Quelle der WahrheitThe memory system: one single source of truth

Alle Buddies teilen ein Gedächtnis. Es liegt lokal in .makeros/memory.db, einer SQLite-Datenbank mit Volltextsuche (FTS5) und Vektor-Suche, und wird über 24 MCP-Tools mit dem Präfix maker_* angesprochen. Der Grundsatz: Memory ist die einzige Quelle der Wahrheit, kein loser Markdown-Zettel.All buddies share one memory. It lives locally in .makeros/memory.db, a SQLite database with full-text search (FTS5) and vector search, addressed through 24 MCP tools prefixed maker_*. The principle: memory is the single source of truth, not a loose markdown note.

Daraus folgen ein paar harte Disziplinen. Feature-Ideen werden zu maker_task_create, nicht zu einer TODO.md. Migrationen sind streng additiv, es wird nur hinzugefügt, nie gelöscht (kein DROP). Vor jeder Migration läuft ein Backup. Standard ist Soft-Delete; hart gelöscht wird nur im Memory Inspector per Klick-Bestätigung. Die einzige erlaubte Ausnahme von der "kein Markdown für Zustand"-Regel ist OPEN_TASKS.md, und auch das ist nur eine generierte Sicht auf die Datenbank.A few hard disciplines follow. Feature ideas become maker_task_create, not a TODO.md. Migrations are strictly additive, only ever adding, never dropping. Every migration is preceded by a backup. The default is soft-delete; hard delete happens only in the Memory Inspector with a click confirmation. The only allowed exception to the "no markdown for state" rule is OPEN_TASKS.md, and even that is just a generated view of the database.

Lokal: dein Gedächtnis und optionale lokale KILocal: your memory and optional local AI

Die klare Antwort zuerst: Dein Code, dein Gedächtnis, deine Workflows und deine Skills liegen immer lokal auf deinem Rechner. Das gemeinsame Gedächtnis ist eine SQLite-Datei in deinem Projekt, keine Cloud-Datenbank. Was du baust, gehört dir und verlässt deine Maschine nicht von allein.The clear answer first: your code, your memory, your workflows, and your skills always live locally on your machine. The shared memory is a SQLite file in your project, not a cloud database. What you build is yours and does not leave your machine on its own.

Auch beim Reasoning kannst du lokal arbeiten. Über den LLM-Broker lassen sich einzelne Aufgaben an ein lokales Modell geben, etwa Klassifikation, Bulk-Tagging, Embeddings oder sensible Code-Schnipsel, die deinen Rechner nicht verlassen sollen. Solche Hintergrund-Arbeit läuft als background_worker bevorzugt lokal, mit einem schlanken Cloud-Modell als Fallback.You can work locally for reasoning too. Through the LLM broker, single tasks can run on a local model, for example classification, bulk tagging, embeddings, or sensitive code snippets that should not leave your machine. Such background work runs as a background_worker, local by preference, with a lean cloud model as a fallback.

Build- und Prototype-Modus: zwei AchsenBuild and prototype mode: two axes

MakerOS kennt zwei Modi auf der Qualitäts-Achse: Build für Produktion und Prototype für Wegwerf-Demos. Du wählst pro Projekt. Innerhalb von Build kommt eine zweite Achse hinzu, der Reifegrad. Operationen, die du oft genug ohne Befund ausgeführt hast, wandern leise in den Hintergrund.MakerOS knows two modes on the quality axis: Build for production and Prototype for throwaway demos. You choose per project. Within Build a second axis kicks in, maturity. Operations you have run often enough without a finding quietly move into the background.

Wichtig ist die Richtung der Anpassung: Sicherheit wird mit der Reife leiser, nicht weniger. Sie ist nie wegklickbar. Der Wechsel von Prototype zu Build ist normal; der Wechsel von Build zu Prototype verlangt eine Extra-Bestätigung, und Prototype-Branches werden nie direkt nach main gemerged.The direction of adaptation matters: with maturity, safety gets quieter, not weaker. It is never click-away. Switching from Prototype to Build is normal; switching from Build to Prototype requires an extra confirmation, and prototype branches are never merged straight into main.

Die acht Guard-RailsThe eight guard rails

Acht Schutzschichten laufen quer über jede Ebene. Sie sind das Sicherheitsnetz, das das ganze System zusammenhält, unabhängig davon, welcher Buddy gerade aktiv ist. AGENTS.md führt sie als Übersicht der angelegten Architektur. Die Tags zeigen den ehrlichen Stand: live ist im Code umgesetzt, teils nur in Teilen, geplant ist bislang nur deklariert.Eight protection layers run across every level. They are the safety net that holds the whole system together, no matter which buddy is active. AGENTS.md lists them as an overview of the designed architecture. The tags show the honest state: live is implemented in code, partial only in parts, planned is declared so far.

Ein Build von Anfang bis EndeA build end to end

Jetzt der rote Faden zusammengezogen. Stell dir vor, ein Maker will eine kleine App für seine Werkstatt bauen. So greifen die Teile ineinander:Now the thread pulled together. Imagine a Maker wants to build a small app for their workshop. Here is how the parts mesh:

• Onboarding. Beim ersten Start fragt das System fünf Dinge (Name, Hintergrund, Erfahrung, Sprache, was zu bauen ist) und füllt USER.md. Klingt die Idee marktbezogen, gibt der Reality-Buddy einen Hinweis.Onboarding. On first run the system asks five things (name, background, experience, language, what to build) and fills USER.md. If the idea sounds market-bound, the Reality buddy drops a hint.
• Reality-Check. Der Reality-Buddy fährt sein 17-Schritt-Modell, vergibt einen Konfidenz-Score. Bei grün ab 60 Prozent übergibt die Matrix automatisch an UX.Reality check. The Reality buddy runs its 17-step model and assigns a confidence score. On green from 60 percent, the matrix hands off to UX automatically.
• UX-Gate. Der UX-Buddy klärt Scope (MoSCoW, Impact-Risk), schreibt ein Scope-Dokument und übergibt an Dev.UX gate. The UX buddy clears scope (MoSCoW, impact-risk), writes a scope document, and hands off to Dev.
• PIV-Loop. Der Dev-Buddy treibt die Engine durch den dev-piv-loop: Setup-Check, Stack-Snapshot, Plan (du bestätigst), Implement, Code-Health, Validate im Browser.PIV loop. The Dev buddy drives the engine through dev-piv-loop: setup check, stack snapshot, plan (you approve), implement, code health, validate in the browser.
• Security. Nach grünem Validate ist die Übergabe an Security Pflicht. Der Evaluator nutzt einen anderen Anbieter als der Builder. Befunde gehen zur Behebung zurück an Dev.Security. After a green validate, the handover to Security is mandatory. The evaluator uses a different provider than the builder. Findings go back to Dev to fix.
• Commit. Erst wenn jede PIV-Phase grün ist, lässt das Commit-Gate den Commit zu. Der ganze Verlauf liegt als PIV-Memory-Graph im gemeinsamen Gedächtnis.Commit. Only when every PIV phase is green does the commit gate allow the commit. The whole run sits as a PIV memory graph in the shared memory.

Während all das läuft, übersetzt der Tutor-Layer die Erklärungen auf deinen Wissensstand, der Communication-Standard hält die Ausgaben knapp, und der Context-Monitor warnt, bevor das Kontextfenster zu voll wird. Du hast nie eine Zeile Konfiguration geschrieben.While all this runs, the tutor layer translates explanations to your knowledge level, the communication standard keeps outputs short, and the context monitor warns before the context window fills up. You never wrote a line of configuration.

Mehr als das: das CockpitMore than this: the cockpit

Wichtig zur Einordnung: Das Repo, das diesem Bauplan zugrunde liegt, ist der aktuelle Stand des Backends, die Engine, das Regelsystem und das gemeinsame Gedächtnis. Das ist nur ein Teil von MakerOS. Darüber entsteht die Oberfläche, die das Bauen noch einfacher und sicherer macht.For context: the repo behind this blueprint is the current state of the backend, the engine, the rule system, and the shared memory. That is only one part of MakerOS. On top of it sits the surface that makes building even easier and safer.

Diese Oberfläche ist ein Cockpit als Flutter-Desktop-App, und sie launcht Anfang Juli. Sie gibt dir echten, nativen Zugriff auf deine Dateien und macht die unsichtbaren Teile sichtbar: deine Buddies, den Memory-Graph, die Architektur deiner Projekte. Statt im Terminal zu lesen, siehst du Verlauf und Übergaben als ruhige, verständliche Oberfläche, mit weiteren Features für leichteres und besseres Entwickeln, allein oder im Team.That surface is a cockpit as a Flutter desktop app, and it launches in early July. It gives you real, native access to your files and makes the invisible parts visible: your buddies, the memory graph, the architecture of your projects. Instead of reading in a terminal, you see the run and the handovers as a calm, understandable interface, with more features for easier and better development, solo or in a team.

FAQ

Ausblick: wohin sich das entwickeltOutlook: where this is heading

Der aktuelle Stand ist eine Alpha (1.0.0-alpha.1): Architektur und Migrationspaket stehen, die Implementierung läuft. Die Richtung ist klar erkennbar aus dem Aufbau selbst.The current state is an alpha (1.0.0-alpha.1): architecture and migration package are in place, implementation is in progress. The direction is readable from the build itself.

Drei Linien zeichnen sich ab. Erstens wird der Research-Buddy vom Platzhalter zum vollen Buddy, der einen projektspezifischen Knowledge-Speicher füllt. Zweitens reift die Engine weiter als eigenständiger Dienst mit MCP-, CLI- und HTTP-Zugang, sodass mehrere Oberflächen sie ansprechen können. Drittens stärkt das System die Souveränität dort, wo Hardware es erlaubt: mehr lokale Aufgaben über den LLM-Broker, ohne ein voll-lokales Versprechen zu geben, das heutige Rechner nicht halten können. Das Multi-Provider-Setup mit struktureller Zweitmeinung passt zugleich auf die wachsenden Compliance-Anforderungen.Three lines are emerging. First, the Research buddy moves from placeholder to a full buddy that fills a project-specific knowledge store. Second, the engine matures further as a standalone service with MCP, CLI, and HTTP access, so several surfaces can talk to it. Third, the system strengthens sovereignty where hardware allows: more local tasks via the LLM broker, without a fully-local promise that today's machines cannot keep. The multi-provider setup with a structural second opinion also fits the growing compliance requirements.

Bausteine und WeiterlesenBuilding blocks and reading

Die Architektur stützt sich auf wenige, klar benannte Bausteine im Repo. Wer tiefer einsteigen will, findet hier die Ankerpunkte:The architecture rests on a few clearly named building blocks in the repo. For a deeper dive, here are the anchor points:

• AGENTS.md: die kanonische Regel-Quelle, von allen Werkzeug-Wrappern importiert.the canonical rule source, imported by all tool wrappers.
• context/SOUL.md: Identität und Werte, am Anfang jeder Session gelesen.identity and values, read at the start of every session.
• engine/: die Workflow-Engine als MCP-Server, der deterministische Node-Graph-Executor.the workflow engine as an MCP server, the deterministic node-graph executor.
• .makeros/workflows/: die deklarativen YAML-Recipes, etwa dev-piv-loop.yaml.the declarative YAML recipes, such as dev-piv-loop.yaml.
• .makeros/handover/matrix.yaml: die vollständige Handover-Tabelle.the complete handover table.
• .claude/skills/: die Buddy-Personas plus Atom- und Smart-Skills.the buddy personas plus atom and smart skills.

Grundlage: Analyse des MakerOS-Repos, Version 1.0.0-alpha.1. Diese Seite erklärt die Architektur, sie ersetzt keine Installations- oder Rechtsberatung.Basis: analysis of the MakerOS repo, version 1.0.0-alpha.1. This page explains the architecture; it is not installation or legal advice.